Doc Merge Appendix
Overview
Doc Merge is a powerful document-generation tool that allows you to pull data from Sugar® records into professional-quality and highly customized documents. This supplemental resource can be used as a reference to understand the different attributes, collections, directives, and more available when building templates, which will help you create specialized documents that suit your organization's needs.
Please review the Doc Merge page for generalized information on building templates. Additionally, refer to the Sample Doc Merge Templates article for document examples.
Topics
This documentation is organized into the following sections:
Doc Merge Terminology
This document uses language specific to Doc Merge. Please review the definitions below as they will help you understand the examples provided.
- Merge Code: A tag you can insert into a document template that will generate content in the final, merged document according to your specifications. For example, a field merge code is used to display the value of a field on the target record. The following are the types of merge codes:
- Field: Insert the value of a field from the target record into the document, such as the name or contact details of an account.
- Collection: Iterate over a list of records, allowing you to display field values from those records in the document, for example in a list or table of sales data. These may sometimes also be called "loops".
- Condition: Print different values in the document based on the state of a condition. For example, you might print a measurement in one unit if the account's country is USA or a different unit if it is Canada.
- Directive: Insert a formatted object into the document, such as a table, a list, the current merge date, or the output of a Sugar Logic calculation.
- Attribute: A setting you can specify on various merge codes to control specific details of what they output. For example, a collection has attributes to control the sort order of the items in the collection and the maximum number of records to display.
Please note that attributes must be written without any blank spaces within the syntax (e.g., max_num='5'
). Having spaces in an attribute's syntax will lead to the template not being processed. Additionally, Doc Merge only supports straight quotes '
inside of attributes. Do not use `
or ‟
. Many modern devices use Smart Quotes, a form of autocorrect, which turns quotes toward the code or comment. You may turn this off or use the Unicode character U+0027
to ensure the quote is straight.
Fields
Field merge codes insert the value of a module's field into the document. For example, you may pull an account's address directly into a letterhead. This can be used to create personalized and robust contracts, quotes, and other documents for your business needs. Additionally, field-level attributes allow customization that can be used in all types of fields.
While merge code examples are presented with stock fields in the below sections, any custom field, relationship, or module may be used with merge codes. You can use the Template Assistant to assist with gathering these items, or you may also use Studio to find the names of custom fields and module relationships.
Field Types
Relationships
Relationship field types allow you to pull data from a related module without creating a collection (loop).
In this example, the assigned_user_name
field is appended to gather further data from the Users module:
Example Merge Syntax |
Merge Results |
Employee {assigned_user_name.name} reports to {assigned_user_name.reports_to_name} . |
Employee Sarah Smith reports to Jane Fitzpatrick. |
Relate Fields
Relate fields are not relationships, and therefore cannot be merged as in the above example. Instead, they are fields and can be merged from the target module using the field's name: {#contacts}{name}{relate_field_c}{/contacts}
.
Multiselect Fields
Multiselect fields are fields within Sugar that can have multiple options chosen. These results can be formatted in Doc Merge in a number of different ways.
Example Merge Syntax |
Merge Results |
{test_multi_c format='number' order='asc'} |
Number Asc:
|
{test_multi_c format='bullet' order='desc'} |
Bullet Desc:
|
Email Fields
Since records can have more than one email address, you must either specify which email address you are referring to or iterate over them using a collection. Use the following two methods to output email addresses:
- Use
{email1}
,{email2}
,{email3}
if you want to generate specific email addresses - Use loops in order to generate all email addresses for a record:
{#email_addresses}{email}{/email_addresses}
Date Fields
Date fields may also be pulled in via Doc Merge and can be formatted to suit your document's needs.
Example Merge Syntax |
Merge Results |
|
Sep 20th, 2021 |
|
09/20/21 |
|
9-20-21 |
Note: You may also use any other format found here: http://momentjs.com
Datetime Fields
Datetime fields, not to be confused with date fields, may be pulled in and formatted within merged documents.
Example Merge Syntax | Merge Results |
|
Friday, September 20th 2021, 06:10:00 PM |
|
Fri, Sep 20th, 2021, 06:10:00 pm |
|
Fri, 09/20/21, 6:10:00 PM |
|
Fr, 09-20-21, 6:10:00 pm |
|
Thursday, February 11th 2022, 12:01:00 PM |
|
Thu, Feb 11th, 2022, 12:01:00 pm |
|
Thu, 02/11/22, 12:01:00 PM |
|
Th, 02-11-22, 12:01:00 pm |
Merged documents display time using the browser's time zone, as opposed to the time zone set on the operating system. You can use the moment()
function in your browser's development tools to get the browser's local time zone.
Checkbox Fields
Checkbox fields may be brought into your document and formatted as a word, number, or symbol.
Example Merge Syntax | Merge Results (Checkbox Checked) | Merge Results (Checkbox Unchecked) |
{checkbox_name format='boolean'} |
true | false |
{checkbox_name format='unicode_symbols'} |
☑ | ☐ |
{checkbox_name format='number'} |
1 | 0 |
Image Fields
Doc Merge supports the following image file types: JPEG, GIF, PNG, BMP.
Example Merge Syntax | Merge Results |
{image_c} |
TinyMCEFieldType Fields
The following formats used inside TinyMCE fields are supported:
- Bold
- Italic
- Underline
- Font color
- Highlight color
- Font size
- Lists: bullets and numbers
The syntax for TinyMCE fields is {TinyMCE_fieldname format='docx'}
.
URL Fields
A URL field can be converted into a hyperlink with your choice of text or a clickable URL:
Example Merge Syntax | Merge Results |
{website format='url' text='Click here!'} |
Click here! |
{website format='url' text='http://www.360vacations.com'} |
http://www.360vacations.com |
Field Attributes
An attribute is a setting you can specify on various merge codes to control specific details of what they output. There are several different attributes, some that apply only to certain field types, such as {checkbox_name format='boolean'}
, while others apply to many different field types, such as {case=''}
or {pad=''}
. For example, a collection has attributes to control the sort order of the items in the collection and the maximum number of records to display. The following field attributes in this section relate to multiple types of fields.
Case and Capitalization
The below table shows some examples of how case and capitalization may be formatted. This example is gathering data from the "Department" field in the Users module. The initial value in Sugar when this merge took place was "sales and SUPPORT".
Example Merge Syntax | Merge Results |
|
SALES AND SUPPORT |
{department case='lower'} |
sales and support |
{department capitalize='true'} |
Sales and SUPPORT Note: Only the first letter of the entire field value is capitalized |
Note: Capitalize set to 'false'
will have no effect on the string. capitalize
is best used for scenarios where you want to assure yourself that the string will start with an uppercase or lowercase letter.
Padding
Padding a field adds a predefined number of leading spaces. This can be useful for formatting fields in a document where you want all fields to be aligned a certain way. If the returned field value is "TEST" and the pad value is 10, the resulting string will be " TEST" (i.e., six spaces will be added so the total number of characters in the merge result becomes 10). If the pad number defined is less than the length of the field value being merged, the merge results will not be padded.
In this example, the email address being merged (test.example@email.com) is 22 characters in length.
Example Merge Syntax | Merge Results |
{email1 pad='35'} |
test.example@email.com (padded 13 spaces) |
{email1 pad='30'} |
test.example@email.com (padded 8 spaces) |
{email1 pad='25'} |
test.example@email.com (padded 3 spaces) |
{email1 pad='20'} |
test.example@email.com (padded 0 spaces) |
Note: The pad
attribute cannot be used with sort,
format
, case
, or capitalize
attributes. This is because padding text gets applied to the code as opposed to the field values.
Pre-Formatted Fields
Sugar has some fields that are already formatted. For these fields, only the field name needs to be placed within the curly braces.
For stock date/time fields, the default formatting is {MM-DD-YYY h:mm a}
.
Example Merge Syntax | Merge Results |
{date_entered} |
09-20-2021, 6:10 pm |
{date_modified} |
02-11-2022, 12:01 pm |
For currency, the format is determined using the user's Preferred Currency setting. The below examples use the Opportunities module and the user's preferred currency is USD $.
Example Merge Syntax | Merge Results |
Likely: {amount} |
Likely: $11,265.00 |
Converted Amount: {amount_usdollar} |
Converted Amount: $11,265.00 |
Best: {best_case} |
Best: $12,154.00 |
Worst: {worst_case} |
Worst: $10,376.00 |
Barcodes
Doc Merge has the ability to format fields as barcodes using the following syntax: {field_name format='barcode'}
.
Example Merge Syntax | Merge Results |
{field_name format='barcode' barcode-format='EAN13'} |
|
{field_name format='barcode' barcode-format='CODE39'} |
|
{field_name format='barcode' barcode-width='2' } |
|
{field_name format='barcode' barcode-height='150' } |
|
{field_name format='barcode' barcode-height='25' } |
|
{field_name format='barcode' barcode-text='Hi!' } |
|
{field_name format='barcode' barcode-font-options='bold/italic/bold italic' } |
|
{field_name format='barcode' barcode-textAlign='left' } |
|
{field_name format='barcode' barcode-textPosition='top' } |
|
{field_name format='barcode' barcode-textMargin='25' } |
|
{field_name format='barcode' barcode-fontSize='40'} |
|
{field_name format='barcode' barcode-background='#ccffff' } |
|
{field_name format='barcode' barcode-lineColor='#990000' } |
|
{field_name format='barcode' barcode-margin='30' barcode-background='#dddddd'} |
|
{field_name format='barcode' barcode-marginTop='30' barcode-background='#dddddd'} {field_name format='barcode' barcode-marginLeft='30' barcode-background='#dddddd'} |
Additional barcode formats
- CODE128 - default
- CODE39
- EAN13, EAN8, EAN5, EAN2
- ITF, ITF-14
- MSI, MSI10, MSI11, MSI1010, MSI1110
- Pharmacode
- Codabar
For further information on barcode formatting, please reference the JsBarcode Guide.
Collections
Collections loop through a list of records, allowing you to display field values from those records in the document, for example in a list or table of sales data. Information merged into a document is not limited to a specific module record's fields. You can extract information from relationships by using loops:
{#contacts}
: opening merge code for Contacts loop{/contacts}
: closing merge code for Contacts loop
Stock module relationships are relatively straightforward. If you want to get information from a contact's opportunities, you would use {opportunities}
in a template that targets the Contacts module. If you do not know the relationship's name, it can be determined in Admin > Studio > {Module Name} > Relationships. If there are multiple relationships for the same module, the relationship name can also be determined from the data-subpanel-link
attribute when inspecting an element using the browser's development tools (F12 in most browsers):
Note: You can only merge up to 40 records in a collection.
Example
This example will create a list of three contact records ordered by first name in descending order. Each record will have specific values for each contact displayed.
{#contacts sort='first_name:desc' max_num='3'}
{salutation} {first_name} {last_name}
{title}
{email1}
{/contacts}
Results
Portia Leatherman
IT Developer
kid69@example.name
Mr. Orlando Bou
Senior Product Manager
im.kid@example.net
Marva Rodes
Director Sales
qa.section@example.co.uk
Inner Collections
An inner collection is another collection generated inside of a parent collection. The syntax is the same:
{#parent_collection}
{parent_collection_field}
{#child_collection}
{child_collection_field}
{/child_collection}
{/parent_collection}
Example
This template will generate all of an account's opportunities and all related contacts for each opportunity. Doc Merge can have as many inner collections as needed.
Account's name: {name}
Opportunities:
{#opportunities}{name}
{#contacts}
{first_name} {last_name}
{/contacts}
{/opportunities}
Results
Account's name: T-Squared Techs
Opportunities:
T-Squared Techs - 175 Units
Love Abelson
T-Squared Techs - 207 Units
Justa Montesino
Guadalupe Schuessler
Conditions
Conditions allow users to print different values in the document based on the state of a condition. This is accomplished by using the if
and else
merge tags codes, in combination with any conditional operator used in JavaScript. You may find more information on JavaScript conditional operators at w3schools.
Example
{if amount>5000}
The amount is greater than $5000{elseif amount<=5000}
The amount is less than or equal to $5000{endif}
Results
This example uses an opportunity with a likely amount of $11,903.70.
Output: The amount is > $5000
Example
{if do_not_call==0}
{phone_mobile}
{endif}
Results
This example uses a contact that does not have "Do Not Call" checked and therefore can have their phone number displayed in the merged document.
Output: (959) 260-3119
Example
This example will show the dp_business_purpose field in the Contacts module if the business purpose contains the word "Marketing". If you do not see this field in your contact's record view, you may need to add it to the layout in Studio.
{if (dp_business_purpose.filter(item=>item.includes("Marketing")).length>0)}
{dp_business_purpose}
{else}
NONE{endif}
Results
In this example, the dp_business_purpose does include the word "Marketing".
Output: Marketing Communications by company
Conditions Inside a Table
When used in tables, conditionals can make an entire row's visibility dependent on if the condition is met. To delete the entire row based on a specific condition, place the {if $condition}
tag in the row's first table cell and the {endif}
in the last table cell of the current row.
If you do not want the entire row deleted if the condition is met, do not place the {if}
in the first table cell. Additionally, if you do not want this, do not place the {endif}
in the last table cell. Having one of these criteria will cause Doc Merge to delete the row.
Example
In this example, if the contact has "Do Not Call" unchecked, they will appear in the table so that only contacts that should be called will be listed:
|
Please call this person: |
|
Results
(959) 260-3119 |
Please call this person: |
Johanne Ellingson |
Directives
Directives insert a formatted object into the document, such as a table, a list, the current date, or the output of a Sugar Logic calculation. They can also change the appearance or behavior of a component.
Directives, like other merge codes, are declared inside curly braces but directives are also preceded by an exclamation point: {!directive_name}
Note: Directives only work for Word and PDF merge. Excel merge is not supported.
table
The {!table}
directive inserts a table in the generated document.
Attributes
header-color
: Any HTML color hex valueheader
: Column names for the table, separated by commascolumns
: Sugar fields you want to insert into the table, separated by commasbind
: Context for the directive; in this example, this is the module you are retrieving data fromsort
: Field to sort the table by and the direction of the sort order (i.e.,sort='name:asc'
orsort='name:desc'
)max_num
: Maximum number of records to retrieve from the collection
Note: Since the lists of values in the columns
and header
attributes refer to the same information (i.e., they represent the data and its display label, respectively), they must both be listed in the same order If there is a mismatch of data, double-check to ensure that the columns match the headers.
Example
{!table header-color='#ff00ff' header='Name,Primary,Email' columns='name,primary_address_city,email1' bind='#contacts' sort='name:asc' max_num='3'}
Results
table_header
The {!table_header}
directive can remove the table header if there is no data in the table.
Attributes
hide_no_data
: A boolean field to remove the table's header if there is no data in the table. The possible values are 'true' or 'false'. A value set to true will hide the table row if it has no data. False will have no effect on the table's row.bind
: The module you are retrieving data from
Example
{!table_header hide_no_data='true' bind='#calls'} |
Date Entered | Assigned User |
{#calls}{name} |
{date_entered} |
{assigned_user_name}{/calls} |
Results
As the criteria for the hide_no_data
were fulfilled, the table is not rendered in the generated document.
list
The {!list}
directive is for quickly creating numbered lists of related module data. This is similar to collections but is formatted with a number for each related record.
Attributes
column
: The Sugar fields you want to insert into the listbind
: The module you are retrieving data fromsort
: The field to sort the table by and the direction of the sort order (i.e.,sort='name:asc'
orsort='name:desc'
)max_num
: The maximum number of records to retrieve from the collection
Example
{!list bind='#contacts' columns='name,email1' sort='name:asc' max_num='3'}
Results
- Piedad Chaffin
- info28@example.it
- Piedad Fleagle
- hr92@example.info
- Horacio Paulhus
- section.dev@example.tv
date
The {!date}
directive inserts the current date in the merged document.
Attributes
format
: Any datetime format. The default is MM-DD-YYYY, h:mm.
Example
{!date}
Results
08-29-2022, 4:53
formula
Sugar Logic functions may be inserted into your document by using calculated fields. To use calculated fields in Doc Merge, you need to input the formula directive {!formula ...}
Attributes
value
: Any Sugar Logic formulaformat
: Any Sugar field type, such as currency or decimal
Example
{!formula value='concat($name, ": ",$quote_stage)}
- TEST DOCUMENT
Product Name | Price | Discounted Price | Quantity | Total Price |
{#products}{name} |
{discount_price} |
|
{quantity} |
{!formula value='multiply($quantity, subtract($discount_price,multiply($discount_price, divide($discount_amount,100))))' format='float'}{/products} |
Results
3 Year Service for Smallville Resources Inc: Draft - TEST DOCUMENT
Product Name |
Price |
Discounted Price |
Quantity |
Total Price |
3 Year Service |
$544.50 |
$544.50 |
10.00 |
5,445.00 |