Beruflich Dokumente
Kultur Dokumente
SYSTEMS
LLC
Last Updated:9/2012
S-Docs CookBook
WELCOME
If youve been searching for a native document generator for Salesforce.com, we have good
news: Your search is over - S-Docs for Salesforce is the solution!
Since youre already using Salesforce.com, you understand the benefits of cloud computing. SDocs extends your existing salesforce investment even further by leveraging the
Salesforce.com platform to create documents. There are countless things you can do with SDocs to improve your business we provide a few here along with some best practices.
What you wont find are instructions on how to install connectors or plug-ins; S-Docs doesnt
use any. You also wont find any information related to network configurations or setting
trusted server IPs; S-Docs runs entirely within your existing Salesforce platform. Your users
wont need to download and install special client software like Silverlight and you wont need
to provision anything outside of salesforce. Creating and emailing documents using S-Docs is
simple, smart and secure.
Once you start working with S-Docs, we think youll agree that S-Docs is quite novel and
incredibly flexible. You will often find multiple solutions and discover clever ways to meet
requirements (usually by leveraging existing Salesforce.com features).
Were excited about this product and welcome your questions, suggestions and feedback.
-TJ
TJMcLoughlin@mesystemsllc.com
INTENDED AUDIENCE
This guide provides solutions and ideas to help organizations get the most from S-Docs. It is
intended for users already familiar with Salesforce administration and configuration
techniques. Knowledge of HTML is also useful in creating the highest quality documents. We
encourage you to visit our website: http://www.mesystemsllc.com for template samples and
help.
S-Docs CookBook
TABLE OF CONTENTS
GENERAL SOLUTIONS
S-Docs CookBook
1. Conditionally show a field value on a document
Solution. Perhaps you have a sales quote where you would like to waive charges for
a particular product. This is a common request and there are several options.
Option 1: Use a Salesforce Formula Field: To accomplish this you should simply create
a formula field on the Salesforce object that does all the work for you. You then drop
that formula field into your S-Docs template.
For example, you could create the following salesforce formula field on your base
object:
IF( Tier__c=Gold, 'No Charge', Fee__c)
If the Customers Tier is Gold, then the text No Charge would appear, otherwise the
Fee would be displayed. You would then just insert this new formula field into you SDocs Template using the template editors Insert Field button.
Alternatively, if your output format is MS Excel, you have the option of using an Excel
Formula. Using Excel formulas within your S-Doc template is described in more detail
in Solution #13 of this documentation.
Option 2: Leverage S-Docs RENDER feature. S-Docs provides a RENDER feature
that will evaluate an expression, and if it is true, will display all of the content until
the ENDRENDER tag is found. The example below shows how to meet the same
requirement above. No Charge will be displayed for Gold tier, and the Fee will be
displayed for all other Tiers. Note the use of two equals (==) vs not equals (!=) as the
comparator.
<!--RENDER={{!CustomObject__c.Tier__c}}==Gold -->
No Charge
<!--ENDRENDER-->
<!--RENDER={{!CustomObject__c.Tier__c}}!=Gold -->
{{! CustomObject__c.Fee__c}}
<!--ENDRENDER-->
S-Docs CookBook
There are some important considerations when using the RENDER feature:
1. It currently supports ==,!=, > and < for the comparison operator
2. It does not support multiple conditions such as &&, OR
3. The right hand side can contain a field value or a hard-coded value: e.g.
<!--RENDER={{!Contact.Language__c}}==French-->
Bonjour {{!Contact.firstname}},
<!--ENDRENDER-->
Or,
<!--RENDER={{!Account.Owner.name}}=={{!Username}}-->
You own this account.
<!ENDRENDER-->
4. You can use a check box field (Boolean) without an operator if you are checking
if it is checked (true). e.g.
<!--RENDER={{!Account.IsGoldCheckBox__c}}-->
Contact me at {{!Account.owner.phone}} if you have questions
<!ENDRENDER-->
But, if you want to check if its unchecked (false) you need to specify an operator
<!--RENDER={{!CustomObject__c.IsGoldCheckBox__c}} == false-->
Contact us at service@mesystemsllc.com if you have questions
<!ENDRENDER-->
S-Docs CookBook
2. Use S-Docs with your custom object
Solution. Yes, S-Docs works great with your custom objects, but there are a few
configuration steps you will need to take. Detailed step-by-step instructions on how to
configure S-Docs with your custom object is available on our website at:
http://www.mesystemsllc.com/documentation?p=custom. Below, you will find an
overview of the configuration steps.
First, you will need to add your custom object to the picklist value Related to
Type field in the SDOC Template object. When adding your object, be sure to use
your objects API name (e.g. myObject__c) as the new picklist value. This step is a
critical step, as it allows S-Docs templates to be associated to your custom object.
Second, you need to create an S-Docs button and place it on your custom objects detail
page. Weve found that a Detail Page Button displayed in the existing window with
sidebar works great.
You should create a button link using a URL similar to the following, but replacing
myObject__c with your Custom Object API name:
/apex/SDOC__SDCreate1?id={!myObject__c.Id}&Object=myObject__c
Lastly, this step allows generated S-Docs to be associated to your custom object and
further allows you to place an S-Docs related list on your custom objects detail page
layout. You simply need to add a look-up field to the SDOC Relationship object that
points to your custom object. Note: The Field Name of this new lookup field must
match the name of your object (e.g. myObject) without the __c.
Discussion. When using S-Docs with custom objects, the field template designer will
automatically correct and append your related object fields with a __r. If you are
comfortable creating your templates in the source code, be sure to use the standard
Salesforce conventions and dot notation and be mindful of capitalization differences.
S-Docs CookBook
relate one S-Doc to multiple records of the same object type (e.g. one S-Docs Contract
to two Salesforce Accounts), the user simply clicks on the New SDoc Relationship
button from the S-Doc related list on the record and then relates it to the S-Doc. One
additional SDoc_Relationship__c record is needed for each records of the same
object type you want to relate to the same S-Doc.
Discussion. The SDoc relationship junction object provides more power and
flexibility in relating S-Docs to your Salesforce objects rather than just linking them
directly. When a document is first generated, one SDoc relationship record is
automatically created and will be linked to up to two objects. This automated
association is driven by the Related to Type and Additional Relationship fields on
the template setup. The Additional Relationship field needs to be a related object
field on the base object. For example, you can relate a document to an Opportunity
and an Account (as an Additional Relationship), because there is an Account lookup
field on the Opportunity record. Likewise, you can link an S-Docs to a Contact and the
Account, since there is an Account lookup field on Opportunity. However, you could
not, for example, automatically link an S-Docs to an Account (base object) and an
Opportunity (additional Relationship) because this is a one-to-many relationship.
You may also notice that comments field and status field are conveniently located on
the SDocs_Relationship object. S-Docs will automatically synchronize these fields
among all relationships that point to the same generated document. For example, if
you update the status of a Contract that is related to two different Accounts, the
status will be consistent across all views.
4. Saving S-Docs as attachments
Solution. To create attachments, update each template record and check on the Auto
Create Attachment checkbox. When you enable this, attachments will be created in
addition to the S-Doc record for each document that uses that template going forward.
It will not create attachments for previously created documents.
Discussion. There are advantages and disadvantages to using attachments. On one
hand, attachments are more permanent, are faster to view, and can be exported for
archiving or for legal/compliance purposes. Attachments are also not affected by
future template changes, whereas S-Docs use the template record each time they are
viewed. On the other hand, the attachment record itself cannot be easily related to
multiple records (you should leverage the S-Docs Relationship for this) and
attachments can consume a significant amount of file storage space within Salesforce.
You also cannot easily report on data located within an attachment. S-Docs lets you
choose whether you want enable attachments or not on a per-template basis. We
typically recommend you use the Create Attachment feature.
S-Docs CookBook
7. Change page size and orientation (landscape, A4, legal, mailing label)
Solution. Most CSS2 compliant browsers will accept the @page style class. There are
some workarounds for older Internet Explorer versions that can be found on-line.
S-Docs CookBook
Working in the template source mode, you can include something similar to the
following at start of your page:
<style>
@page
{
/* use landscape orientation */
size: landscape;
}
</style>
Discussion: Since S-Docs uses standard HTML and CSS, youll find countless online
resources to help resolve any formatting questions. This is a key differentiator that
makes developing S-Docs templates easier and quicker than using a proprietary
design tool.
S-Docs CookBook
LineItems tag as shown below as you would normally use a <tr> element. When
rendered, this code will replaced as a table rows <tr> within the table, and include the
related list field values you specified for columns.
The following snippet will render as a <tr> element. It should therefore be placed
within your <table> element:
<!--{{! <LineItems>
<class>style8</class>
<ListName>OpportunityLineItems</ListName>
<column>PriceBookEntry.product2.Name</column>
<column>PriceBookEntry.product2.Description</column>
<column>UnitPrice</column>
<column>Quantity</column>
<column>TotalPrice</column>
</LineItems> }}-->
Be sure to use include the HTML comment tags (<!-- and -->) exactly as shown in the
snippet above. While the line items wont appear on the template editors WYSIWYG
view, they will render when the document is generated.
NOTE: Since S-Docs is a Native Force.com app, it is subject to Salesforces governor
limits. The complexity of your objects will determine the maximum number of related
lists and the maximum number of line items that you can include in your document
before reaching these limits. We are continually working on improving this limit. For
more information visit
http://www.salesforce.com/us/developer/docs/apexcode/Content/apex_gov_limits.htm.
S-Docs CookBook
<style type="text/css">
table.table1 {border:solid black 1px;border-collapse: collapse;borderspacing:0px;font-family: verdana; font-size: 10pt; width:100% }
.table1header {text-align:center;font-weight:bold;border:solid black
1px;}
.table1footer {text-align:right;font-weight:bold;border:solid black
0px;}
.table1col0 {font-weight:bold;text-align:left; border:solid black 1px;}
.table1col1 {text-align:left; width:20%;border:solid black 1px;}
.table1col2{text-align:left; width:40%;border:solid black 1px;}
.table1col3{text-align:right;width:10%;border:solid black 1px;}
.table1col4,.table1col5{text-align:right;width:15%;border:solid black
1px;}
.table1RowEven{ background-color:#fff; }
.table1RowOdd{ background-color:#eee; }
</style>
... your template HTML here...
<table class="table1">
<!--{{!
<LineItems>
<class>table1</class>
<ListName>opportunitylineitems</ListName>
<column>PricebookEntry.Product2.family</column>
<column>PricebookEntry.name</column>
<column>PricebookEntry.product2id</column>
<column format-number="#,###" postfix="/Per Unit">quantity</column>
<column format-number="#.###,##" postfix="">unitprice</column>
<column format-number="#,###.##" prefix="$">totalprice</column>
<where>PricebookEntry.name != null</where>
<orderby>PricebookEntry.Product2.family</orderby>
<groupby type="newtable">PricebookEntry.Product2.family</groupby>
<groupbyheader position="after-group">Product Name,Product
Description,Qty,Unit Price,Total Price</groupbyheader>
<groupbysum position="footer" format-number="#,###" prefix="
Subtotal $">totalprice</groupbysum>
<limit>100</limit>
</LineItems>
}}-->
</table>
S-Docs CookBook
The following are use cases where Direct SOQL may useful:
1. The related list you want to include is not related to (no linked relationships exist)
to your underlying record. The underlying record is the value in the "related to
type" field on the template record. For example, if you wanted to include a related
list of similar Accounts (perhaps in the same industry) in your Account document.
2. You have has more than 100 records in the related list that you want to merge into
your document. Direct SOQL is able to work with more records before hitting any
governor limits.
3. You want your related list to refresh with the latest data every time the S-Doc is
VIEWED from the S-Docs related list. This is a critical distinction, as the document
can change over time without being regenerated. If you want a point-in-time
snapshot, you should also use the additionally save an attachment feature.
4. You want to use very specific or advanced SOQL statements they may include
features such as aggregates
5. You want to include the same related object multiple times in your template and
but have each occurrence use a different filter criteria or display different columns.
While you can use the groupby in the standard related list feature to break a table
by a data column, you have more control with Direct SOQL.
Direct SOQL key differences:
1. Uses <LineItemsSOQL> instead of <LineItems>
2. The <listname> should be set to the object API name not the relationship name.
This means that your should use Opportunity not Opportunities, or
OpportunityLineItem not OpportunityLineItems, or for custom objects you should
use CustomObj__c not CustomObj__r.
3. Direct SOQL data is not saved with the S-Doc snapshot record. This means that
each time the s-doc is viewed within salesforce, it is regenerated and therefore it
executes the query and retrieves the latest data. If you email your document, or
save it as an attachment, then that document is unaltered because it is saved as a
physical pdf or Word file. However, if you click on the view button with the S-Docs
related list, the related list data is queried again, and may have changed since the
document was originally generated. Therefore, we strongly recommend you check
"also create attachment" in the template editor in order to keep a hard copy of your
document.
To use Direct SOQL:
Open your template in the editor and then click on the "Source" button. You will need
to add a section similar to the example below. Place it where you want the related list
table of data to be inserted.
S-Docs CookBook
<table>
<tr><td>stage</td><td>name</td><td>Acct</td><td>amount</td></tr>
<!--{{! <LineItemsSOQL>
<class>table1</class>
<ListName>Opportunity</ListName>
<column>stagename</column>
<column>name</column>
<column>account.name</column>
<column format-number="##,###" prefix="$">amount</column>
<where>stagename in ('Prospecting','Closed') and amount>90000 </where>
<groupby>stagename</groupby>
<orderby>stagename, amount desc</orderby>
</LineItemsSOQL> }}-->
</table>
You can use this snippet above with any template because it runs as an independent
SOQL query that returns the same data set regardless of the template used. The
example above shows how you could select all opportunities that match a particular
criteria (opportunity stage name and amount) and would include the retrieved records
into a 4-column table within your document.
In this example, the query runs irrespective of your base record (that you used to
generate the S-Doc from) or whether your base record is linked to these opportunities
returned in the query or not. The SOQL query also runs under the users permissions
and therefore does not violate any sharing rules.
If you want to limit the related list items to only those records linked to your specific
record, then you would need to expand the <where> condition and specify the those
line items have a lookup value equal to your specific record ID. For example, if you
want to include only opportunities linked to your account record you would need to
include a condition to filter Opportunity.AccountID value equal to your record
Account.ID. Obviously, there needs to be some linked relationship field for this to
work. To do this in the template, you need to specifically use the syntax '{!ObjectID}'
that is dynamically replace the records salesforce id value. In our example, you would
add the following: <where>AccountId='{!ObjectID15}'</where>
Advanced SOQL: If you want even more control, you can type the exact SOQL
statement you want executed by adding a <SOQL> tag.
S-Docs CookBook
Adding the following into your template source ( it assumes your base object is
opportunity) will sum your quantity and totals per product and return just one line by
leveraging SOQL aggregate functionality to remove duplicates. You will note how the
<SOQL> statement is used with an alias, and then matched to the columns.
<table border="0" class="table1" width="100%">
<tbody>
<tr>
<td class="table1header">
Product</td>
<td class="table1header">
Quantity</td>
<td align="right" class="table1header">
Total Price</td>
</tr>
<!--{{! <LineItemsSOQL>
<class>table1</class>
<ListName>quotelineitem</ListName>
<soql>Select PricebookEntry.product2.name, sum(o.TotalPrice)tp,
sum(o.Quantity)tq, o.PricebookEntryId From OpportunityLineItem o where
opportunityid='{!ObjectID15}' group by pricebookentryid,
PricebookEntry.product2.name</soql>
<column>Name</column>
<column format-number="#,###" prefix="$">tq</column>
The
resultsformat-number="#,###.##"
from the soql query will be prefix="$">tp</column>
matched to the column names. Here we used
<column
aliases
tp and tq that}}-->
mapped to columns. You don't need to map all columns. If you
</LineItemsSOQL>
</tbody>
use
this option, you need to correctly create the soql query to include required where,
</table>
group
by and order by syntax.
Final note: All SOQL runs as the running user. This prevents any user from viewing
any information that they are not entitled to through salesforce permissions (object
level, record level and field level).
11. Access other fields not visible from the Insert Field Picker button
Solution. The Insert Field button in the template editor will allow you to easily
insert fields from related object. However, S-Docs can access related fields using
standard dot notation that can reach fields up to 4 relationships removed if you
manually edit the template source. For example, you could include the following in
you template:
{{!Opportunity.Account.ParentAccount.Owner.Name}}
Note: Due to Salesforces governor limits, S-Docs may not validate after the second
dot. This means users will not receive any warning messages (during document
creation) that a referenced field is invalid. If you find yourself needing to extend to
S-Docs CookBook
this level, be sure to use the correct relationship name and notation. If you choose to
map fields manually and do not correctly specify objects and fields, the user may
receive an system error during document creation.
Discussion: If you find yourself needing to extend to a far removed field value, we
recommend creating a formula field on the base object. In the example above, you
could easily add a formula field on the Opportunity labeled PAowner_name__c and set
its value to the field referenced above. Then, you could use this field in your S-Docs
template.
If you include the above snippet in your S-Docs template, the user will be prompted to
choose a billing and shipping contact following the document selection step. The
available Contact picklist is populated from the Contact Roles so, you need to
associate Contacts to the Account or Opportunity in order to use this template.
Optionally, you can include a generic contact record by using the syntax below. This
may be more appropriate for Custom Objects. If you include the following, it will look
for any link from your object to the Contact object and include those matching records.
Record Contact:
Record Email:
{{!picklist.recordcontact.name}}
{{!picklist.recordcontact.email}}
S-Docs CookBook
BEST PRACTICES
13. Updating templates without affecting previously created documents
Solution. It is important to understand that once a template has been used to create
the first real document you should refrain from making ANY updates to the
template. This is because the S-Docs template record is used both during document
creation AND during each subsequent view of an S-Doc. Each S-Doc stores the
template used to create it. If you attempt to open an S-Doc where the template used to
create it has been deleted, you will receive an error. The diagram below illustrates
this relationship.
S-Docs CookBook
If you want to make changes after you have completed your design work, it will affect
how PREVIOUSLY generated documents are rendered. Therefore, if you need to
make changes, you should CLONE the template and make modifications to the newly
cloned record. You then uncheck Active on the original template to ensure no new
document can be created using it. Previously generated documents will continue to
use the original template (therefore rendering unchanged), and new documents will
use the newly activated template.
Discussion. To maintain flexibility during the iterative process of template design,
and to allow for mass changes to previously created documents, it is advantageous for
some to be able to edit templates after first use. However, for many organizations, it is
equally important that documents are not changed once created. For example, a
contract created a year ago, should not be affected if you updated the Terms section of
the S-Docs template record. If you follow the technique described above, you can
ensure that your documents maintain an unalterable point-in-time record.
S-Docs CookBook
Alternatively, you can also use the Additionally Create Attachment option (see
Solution #4). This is particularly useful for orgs that are restricted to 5 templates,
have a need to change templates often, and still requiring past documents to remain
unaffected by future template changes. Attachments allow you to store a copy of the
document that cannot be affected by template changes and do not require the S-Docs
template record to view.
S-Docs CookBook
Typically, customers will want to track just the Status and Comment fields, as
these are the fields that are most meaningful to track. If you integrate S-Docs with a
electronic signature solution, users could be notified, via the Chatter feed, that
documents have been executed by the customer.
Now that you have Chatter enabled and Feed Tracking set, you will need to make one
additional change. You will need to create a hyperlink on the S-Docs related list that
can take the user to the S-Docs Relationship record detail page. This is the only page
where users can click on the Follow button located on the Chatter toolbar.
Background: By default, there is no such hyperlink on the S-Docs related list, and this was done
intentionally. While S-Docs related list includes a column labeled Document Number, this field is
a plain text field (not a hyperlink). If this field were a hyperlink, the user might expect this to open
the S-Doc itself not the S-Doc Relationship record. To eliminate any confusion, the hyperlink was
intentionally removed.
However, for Chatter, we do need to get to the S-Docs Relationship record in order to allow users to
click on the Chatter Follow button. Unfortunately, the first column in the related list (Edit link)
wont work either. While this link does take the user to the S-Docs Relationships page, it is
rendered in edit-mode, and the Chatter toolbar does not render for records in edit mode.
So, you will need to add a new column to your S-Docs related list view that will take the user to the
S-Docs Relationships record detail page. While you might first consider using the Relationship ID
field as an easier approach, this ID value would display the S-Doc Relationship ID, not the S-Doc
ID, which again, may confuse users. A formula field rendered as a hyperlink is the best solution.
Since each org will have its own preference on how this related list column should appear, we have
not included this formula field in the core S-Docs package, but rather leave it to the Salesforce
Admins to implement.
You will need to create this hyperlink using a custom formula field on the
SDOC_Relationship__c object. You will then add this field to the related list view.
By using the formula below, you could include a new column that replaces Document
Number with the same value but that is a hyperlink to the S-Doc Relationship
record. (For comparison only, both columns are included in the related list shown
below)
HYPERLINK('/'+
Id ,
SDOC__SDoc__r.SDOC__Document_Number__c, "_self" )
S-Docs CookBook
Id ,
Once youve added the link to the relationship object, the user simple opens the record
and then clicks on the follow icon.
S-Docs CookBook
S-Docs CookBook
However, rendering in PDF does have some design considerations. Specifically, not all
fonts are supported, nor are all CSS styles. To get the desired result, you may need
additional editing time or are afforded some leeway on the final output.
If you have existing company PDFs that you would like to use with S-Docs, you will
need to first convert the PDF to HTML, so that it can be saved as an S-Docs template.
Adobe provides free automatic conversion tools that can be found here:
http://www.adobe.com/products/acrobat/access_onlinetools.html. Again, you may need
to edit the template after conversion in order to make it appear as the original.
MS Word
This is often the best choice for rendering form letters, especially when the message
needs to be tailored for each document, such as customer service letters or meeting
follow-ups. You can still embed company logos, rep signature images and
automatically insert needed Salesforce.com data fields. This format is often used when
there is a need to uniquely edit or personalize each document after it has been
created.
When you select MS Word as the template output type, you will see a Set advanced
Microsoft Properties button. You can use this feature to set margins, headers and
footers. The following special S-Docs syntax can be used in your template:
##TERMS## - can be used to insert a terms and conditions section elsewhere than end of document
##PAGEBREAK## - a manual page break is forced
##TOCSTART## and ##TOCEND## - used to insert a table of content
You dont need to configure a connector, plug-in or any macros. S-Docs uses the
template definition you provide and creates a new MS Word file. This means you
cannot use an existing MS Word template (.dot file). After generating the document,
the user can then leverage all the features of MS Word to further tailor the content of
each message.
MS Excel
For large related lists, you may want to render you document using MS Excel. After a
user creates the S-Doc, they can update the spreadsheet as usual.
Note: Similar to how S-Docs generates an MS Word document, S-Docs does not
populate an existing .xls file with data, but rather generates a new .xls file. This
means that you do not need to create and share a template .xls file. All definitions and
formulas should be defined in either Salesforce formula fields, or alternatively, using
the S-Docs template editor. If you have existing xls documents you want to use with SDocs, you will need to save them as HTML and use the HTML output as the basis for
your S-Docs template. You may need to remove some special formatting Microsoft
S-Docs CookBook
automatically adds to the document that prevents non-Microsoft browsers from
rendering the document correctly. There are also tools available online for converting
Excel to HTML.
Tip: Since it is often difficult to predict a particular cell location that your S-Docs field
will render to in MS Excel, and since many formulas require cell locations, it is often
easier to create formulas using a two step process. First, you create your fields and
render the document without any formulas. Then, once you have identified all your
target cell locations, you can add your excel formulas using the S-Docs Template
Editor.
For example, typing the following text into the S-Docs template editor that will sum
the values of the values of rows 4 through 8 in Column A.
=SUM(A4:A8)
You can also use a VLookup function to help locate values you want to update with
Salesforce data. Here is a useful resource for creating Excel formulas:
http://www.mrexcel.com/archive/Formulas/index.html
HTML
HTML is the most flexible of the output formats. HTML docs can even contain editable text areas.
This is the format of choice if you wish to send an in-line document via email. However, you
should note that images are retrieved when the document is viewed. For this reason, we do not
consider the document self-contained. This means users need to not only be connected to the
internet to view your document appropriately, but also have access to the embedded images. While
embedded images can be useful for tracking, rendering consistent HTML on a variety of devices,
browsers and email clients can also be challenging.
Note: If a user emails an HTML S-Doc during the last step of generation, S-Docs will
automatically include the document in-line as HTML in the email body.
USING IMAGES
If you are looking to embed images into your S-Doc, you have several options; each
offers some advantage. Please also see Solution #13 - Based on the document format
(e.g. PDF, MS Word) you want to produce, one of the options may be better suited.
S-Docs CookBook
16. Embedding static images into your document
Solution. For static images, like a company logo, you can simply use an image tag
similar to the following in your S-Docs template source.
<image src=http://publicsite/imagename.png />
This may be the simplest approach if you are emailing HTML content or wish to
embed an image pixel for email tracking. But, keep in mind that if this image is not
stored in your Salesforce org or if the host server is not under your control, the linked
image may change and therefore is not guaranteed to work.
You can also embed images that are stored as Salesforce documents. You can use the
Add Image button on the template editor toolbar to search and add the desired
image from your Salesforce documents folder.
If you intend to send a document externally that requires access to the image at viewtime (e.g. HTML S-Doc), be sure that the Salesforce document record, which contains
the image, is set for public visibility. Checking this box will make the image visible on
the public internet.
S-Docs CookBook
If you want this image to be visible externally (such as including it in an email sent to
your customers), you must use the full path when referencing the image in your SDocs template. To do this, use the source button in the template editor toolbar to
toggle to source view, find the image, and then edit the image src value with the full
url path (adding the underlined portion shown below that corresponds to your
Salesforce instance):
<image
src="https://na1.salesforce.com/servlet/servlet.ImageServer?id=..."/>
S-Docs CookBook
PRODUCT IMAGE:<br><img scr=/host/Product123Image.png />
Then, using the S-Docs template editor, click on the Insert Field button, select the
field, and then be sure to click on the Contains Rich Text checkbox.
This is a simple approach but has limited usage. It is useful for images such as
representative signatures, where they are centrally controlled by an administrator,
they do not change frequently and the user would not normally need to view them in
the Salesforce user interface along with the record. Since this is a text field, if you
were to include this field on a page layout, it would not render as an image users
would only see the text shown above when viewing the record detail in the Salesforce
UI. Therefore, it would not be appropriate for end-users who upload their own images
frequently (e.g. scanned photograph of a damage claim) or wanted to view the actual
image in Salesforce within the record detail page.
Option 3 Use a formula field to display an image.
Building on option 2, you can leverage a Salesforce formula field to create the image
path and also display the image within the Salesforce record detail. You would then
drop the formula field into your S-Docs template with the Contains Rich Text option
checked (as described in the previous option). The formula field would contain
something similar to the following:
IMAGE("/CompanyIntranet/Products+ myObject__c.ProductID__c + .png")
This option requires some planning so that the image field name can be
programmatically derived.
Option 4 Build an image URL within the S-Docs template
This is a combination of option 2 and 3, but would not require a formula field. You can
use a records existing field value to help build the correct image path but you create
the full path value within the S-Docs template, not in the salesforce field.
For example, to include a dynamic product image or agents signature, you can use
something similar to the following in your document template source:
lt#img src=quot#http://intranet/{{!Product2.ProductPath__c}}.png quot#
/gt#
S-Docs CookBook
The field value should be a URL that points to either an image in your Salesforce documents
folder or an external image hosted on the public internet. In the second example, the field
should contain the entire path including the http:// prefix.
Since the image path is text (not markup) it should only be surrounded by double brackets, as
shown above. The special notation for <, >, and quotes, using lt#, gt#, quot# respectively, is
used to instruct S-Docs that this markup needs to be evaluated rather than rendered literally.
Having this flexibility gives you total control of how you want a field interpreted within the SDocs template.
The extra pair of brackets instructs S-Docs to interpret this field rather than just
displaying the stored value. Without this, S-Docs would not know whether a field
containing the value <img src=//host/Product123Image.png /> should be displayed
as the text quoted or substituted with the actual image when rendered. Whenever you
add a field using the template editor and click on the Contains Rich Text checkbox,
S-Docs will evaluate the value regardless of the actual Salesforce field type (Rich Text
or otherwise).
18. Embedding Google Charts into your document
Solution. Leveraging Google Charts API provides a great way to include dynamic
charts in your S-Docs.
You can find more information here on Google charts here:
http://code.google.com/apis/chart/
S-Docs CookBook
Here are a few examples of Google charts:
The charts work by passing the Salesforce data to the Google API, which in turn
dynamically builds and returns the chart as a PNG image.
Security Note. Unlike S-Docs, which works entirely within the Salesforce.com
platform, Google Google charts are hosted remotely. Depending on the chart, your
data is passed from Salesforce to Google. Your security team would need to determine
if this is an acceptable practice.
Images are rendered by using one URL request per chart. For example, you can
manipulate the values in the following URL to render a different pie chart:
http://chart.apis.google.com/chart?cht=p3&chd=t:60,40&chs=250x100&chl=Jan|Feb
S-Docs CookBook
As you may begin to see, using Google Charts API is all about creating these URLs
where you pass in the data points, legends and chart options. Depending on the chart,
some of these URLs can be long and a bit complex.
Rather than building complex logic within S-Docs to create these URLs, we again
leverage Salesforce formula fields to do the heavy lifting.
Here is a great tutorial from Salesforce on how to create Google Charts using a
formula field:
http://wiki.developerforce.com/index.php/Using_Formulas_and_Google_Charts_to_Vis
ualize_Data
The above tutorial will walk through how to build the following formula field to
display a Won/Loss pie chart:
IMAGE("http://chart.apis.google.com/chart?cht=p3&chd=t:" &
Text(Won__c/(Won__c + Lost__c)) & "," &
Text(Lost__c/(Won__c + Lost__c)) &
"&chs=275x100&chf=bg,s,F3F3EC&chl=Won|Lost&chco=5555ff",
"chart text")
Then, we simply drop this formula field into our S-Doc template (be sure to check
Contains Rich Text box).
While more complex, another approach is to build the Google Chart API URL in your
S-Doc Template and then mix in field values. This may offer you greater control.
Using syntax similar to the following, you could add the image, where
ChartLegend__c would just contain the value Jan|Feb.
lt#img src=
quot#http://chart.apis.google.com/chart?cht=p3&chd=t:60,40&chs=250x100&chl=
{{!MyObject__c.ChartLegend__c}}quot# /gt#
S-Docs CookBook
If the date field is located in a related list column use the following, you would need to
edit the template source. Click the source button, and then locate the date column
within your template.
<column format-date="MM/dd/yyyy">createddate</column>
The format-date can accept a wide range of values. You can add minutes, timezones
etc. Pay attention to caps as mm in minute, where as MM is month.
Use this reference to view all date formatting options:
http://download.oracle.com/javase/1.4.2/docs/api/java/text/SimpleDateFormat.html
S-Docs CookBook
If this does not meet your requirements, you have another option to format dates by
leveraging Salesforce formula fields. By adding the following formula field to your
object, you can leverage Salesforce functionality. You would need to substitute your
field name. You do not need to add these fields to any page layout. If you are working
with a Date Field (not a DateTime field), see the next example for slight modifications
needed.
CASE( MONTH( DATEVALUE(LastModifiedDate) ), 1, "January", 2,
"February", 3, "March", 4, "April", 5, "May", 6, "June", 7, "July", 8,
"August", 9, "September", 10, "October", 11, "November", 12, "December",
"-" )
+ ' ' + TEXT(DAY( DATEVALUE(LastModifiedDate))) + ', ' + TEXT(YEAR(
DATEVALUE(LastModifiedDate)))
Similarly, you could use the pattern below to modify a Date field for differing Locales.
This formula returns European date formatting (DD/MM/YYYY)
TEXT(DAY( CloseDate)) +'/'+ TEXT(MONTH( CloseDate)) +'/'+ TEXT(YEAR(
CloseDate))
If the number/currency field is located in a related list column, you would need to edit
the template source. Click the source button, and then locate the number/currency
field within your template. You then need to replace the syntax to match the
following:
<column format-number="#,###">quantity</column>
<column format-number="#,###.##" prefix="$">unitprice</column>
<column format-number="#.###,##" postfix="">euro_price__c</column>
S-Docs CookBook
The example above shows the three supported formatting options. For others, you can
use a formula field described below.
The following section outlines how to leverage a salesforce formula field to format
currency data within your document.
AUTHOR CREDIT: By searching the internet, you can find many other solutions. This
particular solution was found online at: http://techblog.appirio.com/2010/02/displaying-currencies-insfdc-email.html
By adding the following formula field to your object, you leverage built-in Salesforce
functionality. You would need to substitute your field name into the formula below (in
place of Amount), and then drop the formula field into your S-Docs template. You do
not need to add any of these fields to any page layout. You can add the dollar sign ($)
to either the start of the formula or within the template design document proceeding
your field.
IF(
Amount >= 1000000,
TEXT(FLOOR(Amount / 1000000)) & ",",
"") &
IF(
Amount >= 1000,
RIGHT(TEXT(FLOOR(Amount / 1000)), 3) & ",",
"") &
RIGHT(TEXT(FLOOR(Amount)), 3) & "." &
IF(
MOD(Amount , 1) * 100 < 10,
"0" & TEXT(ROUND(MOD(Amount , 1), 2) * 100),
TEXT(MIN(ROUND(MOD(Amount , 1), 2) * 100, 99))
)
NOTE: This solution formats only the given value, it does not consider currency
exchange rates. In such cases, you could use a combination of formulas. One to convert
the currency based on the exchange rate, and another to format it correctly for your
document.