Let the platform do the work

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:

  1. Analyst
  2. Competitor
  3. Investor
  4. Prospect
  5. Reseller
{test_multi_c format='bullet' order='desc'}

Bullet Desc:

  • Reseller
  • Prospect
  • Investor
  • Competitor
  • Analyst
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

{date_entered format='MMM Do, YYYY'}

Sep 20th, 2021

{date_entered format='MM/DD/YY'}

09/20/21

{date_entered format='M-D-YY'}

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

{date_entered format='dddd, MMMM Do YYYY, hh:mm:ss A'}

Friday, September 20th 2021, 06:10:00 PM

{date_entered format='ddd, MMM Do, YYYY, hh:mm:ss a'}

Fri, Sep 20th, 2021, 06:10:00 pm

{date_entered format='ddd, MM/DD/YY, h:m:ss A'}

Fri, 09/20/21, 6:10:00 PM

{date_entered format='dd, MM-DD-YY, h:m:ss a'}

Fr, 09-20-21, 6:10:00 pm

{date_modified format='dddd, MMMM Do YYYY, hh:mm:ss A'}

Thursday, February 11th 2022, 12:01:00 PM

{date_modified format='ddd, MMM Do, YYYY, hh:mm:ss a'}

Thu, Feb 11th, 2022, 12:01:00 pm

{date_modified format='ddd, MM/DD/YY, h:mm:ss A'}

Thu, 02/11/22, 12:01:00 PM

{date_modified format='dd, MM-DD-YY, h:mm:ss a'}

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}  Wdocs mergeresultsimage
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:
Wdocs formattingurl

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

{department case='upper'}

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'} Wdocs 165
{field_name format='barcode' barcode-format='CODE39'} Wdocs 166
{field_name format='barcode' barcode-width='2' }  Wdocs 167
Wdocs 168
{field_name format='barcode' barcode-height='150' } Wdocs 169
{field_name format='barcode' barcode-height='25' } Wdocs 170
{field_name format='barcode' barcode-text='Hi!' } Wdocs 171
{field_name format='barcode' barcode-font-options='bold/italic/bold italic' } Wdocs 172
{field_name format='barcode' barcode-textAlign='left' } Wdocs 173
{field_name format='barcode' barcode-textPosition='top' } Wdocs 174
{field_name format='barcode' barcode-textMargin='25' } Wdocs 175
 {field_name format='barcode' barcode-fontSize='40'} Wdocs 176
{field_name format='barcode' barcode-background='#ccffff' } Wdocs 177
{field_name format='barcode' barcode-lineColor='#990000' } Wdocs 178
{field_name format='barcode' barcode-margin='30' barcode-background='#dddddd'}

Wdocs 179

{field_name format='barcode' barcode-marginTop='30' barcode-background='#dddddd'}
{field_name format='barcode' barcode-marginLeft='30' barcode-background='#dddddd'}

Wdocs 180

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):

data-subpanel-link

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: 

{if do_not_call==0} {phone_mobile} 

Please call this person:

{name}{endif}

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 value
  • header:  Column names for the table, separated by commas
  • columns: Sugar fields you want to insert into the table, separated by commas
  • bind: Context for the directive; in this example, this is the module you are retrieving data from 
  • sort: Field to sort the table by and the direction of the sort order (i.e., sort='name:asc' or sort='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

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 list
  • bind: The module you are retrieving data from
  • sort: The field to sort the table by and the direction of the sort order (i.e., sort='name:asc' or sort='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
  1. Piedad Chaffin
  2. info28@example.it
  1. Piedad Fleagle
  2. hr92@example.info
  1. Horacio Paulhus
  2. section.dev@example.tv
date

The {!date} directive inserts the current date in the merged document.

Attributes
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 formula
  • format: 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}

{!formula value ='subtract($discount_price,multiply($discount_price,divide($discount_amount, 100)))'

format='currency'}

{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