Doc Merge

Overview

Doc Merge pulls data from Sugar® records into professional-quality documents such as contracts, quotes, NDA agreements, form letters, and labels. Through custom templates that you design according to your needs, Doc Merge has the ability to extract data from all Sugar Sidecar modules and their related modules into individual or multiple digital documents within minutes. This powerful feature will save you time producing common documents natively within Sugar while linking these documents to Sugar records for future reference.

Doc Merge includes the following features:

• Generate DOCX, XLSX, PPTX, and PDF documents without leaving Sugar.
• Merge information from any Sugar module into the document, including related modules.
• Merge multiple records into one document for label generation.
• Template Assistant tool helps you find the fields and data you want to include in your merged documents.
• Merged documents are attached to the Sugar record as a linked document when they are generated from record view.
• Doc Merge Widget is available in the footer to provide links to merged documents and access to the Template Assistant.
• Initiate merges from record view, list view, and subpanel action menus.

Topics

This documentation is organized into the following sections:

• Prerequisites
• Terminology
• Suggested Settings
• Accessing Doc Merge
• Restricting Access to Doc Merge
• Creating a Merged Document
• Using the Doc Merge Widget
• Using the Template Assistant
• Using the Document Templates Module

Prerequisites

To use the Doc Merge feature, you need the following:

• You must be a licensed Sugar Enterprise, Sell, or Serve user with role access to the Documents, Document Merges, and Document Templates modules.
• You must allow pop-ups in your browser settings to use the Doc Merge Template Assistant. 
• You need access to software that produces DOCX, XLSX, and PPTX files to create document templates.

Terminology

The following terms are used in this documentation:

• Doc Merge: The name of the feature that enables the merging of Sugar record data with DOCX, XLSX, and PPTX files.
• Document Merge: The process of merging record data into a DOCX, XLSX, or PPTX template.
• Merged Document: The DOCX, XLSX, PPTX, or PDF document that results from merging record data with the document template. The Merged Document is stored in Sugar in the Documents module.
• Template: The DOCX, XLSX, or PPTX file containing the merge codes that represent the Sugar fields to be merged into the resulting document.
• Widget: The tool that is accessible in the Sugar footer, which contains links to merged documents and access to the Template Assistant.

Suggested Settings

We recommend making the following admin configurations to your Sugar instance to optimize the user experience.

Note: You must be a system administrator to complete the following configurations.

• Unhide the Document Templates module: The Document Templates module is hidden by default. While you can create and select templates without making the module visible, you may want to remove the module from the hidden modules list via Admin > Display Modules and Subpanels for easier template access.
• Add hidden fields to layouts: Add the following fields to layouts for the Document Templates module in Admin > Studio:
  • Add "Extension" to the Record View, List View, and Search layouts.
  • Add "Template Module" to Popup List View layout.
• Create a role for users who will have access to the Doc Merge functionality: Most customers will want users to be able to access each other's templates (team permitting), but only edit or delete their own. To create a role that restricts users from editing or deleting other users' templates, create a new role via Admin > Role Management with the following settings:
  • Role Name: Doc Merge Users
  • Field Permissions: From the fields list for the Document Templates module, set the Extension field to "Read Only". Do not skip this step; it is very important that users do not edit this field.
  • Module Permissions: For the Document Templates module, set the following permissions:
    • Access: Enabled
    • Access Type: Normal
    • Delete: Owner
    • Edit: Owner
    • List: All
    • Record View: All
• Similarly, for users who should not have access to Doc Merge, you can create a role with the Access level for the Document Merges and Document Templates modules set to "Disabled" and all permissions for those modules to "None".

After saving the new role, scroll to the role's Users subpanel and add all users who will have access to Doc Merge. By default, all users in Sugar can access Doc Merge unless they have been restricted by role, as explained in the Restricting Access to Doc Merge section.

Accessing Doc Merge

The Doc Merge feature is accessible in the following locations:

• Sugar Footer: The Doc Merge widget in the footer provides access to merged documents and the Template Assistant.
  
• Actions Menus: "Doc Merge" and "Doc Merge to PDF" options are available in List view, Record View, and Subpanel action menus for supported modules.
  
  
  

Additionally, your administrator may have added Doc Merge action buttons to records. Please refer to the Action Buttons documentation in the Administration Guide for more information on creating action buttons.

Restricting Access to Doc Merge

The administrator may choose to disable access to Doc Merge for some users. To do this, simply create a role with the Access level for both the Document Merges and Document Templates modules set to "Disabled" and then add the restricted users to the role. For more information on creating roles in Sugar, refer to the Role Management documentation in the Administration Guide.

Creating a Merged Document

Creating a merged document includes the following steps:

1. Create a template if it does not already exist.
2. Merge records with the document template.

Creating a Doc Merge Template

Doc Merge templates are DOCX, XLSX, or PPTX documents that include Sugar field references. While you can create templates manually by identifying the system labels for Sugar fields embedded in curly braces (e.g., {first_name}), using the Doc Merge Template Assistant is the easiest method for creating templates. This section explains how to create templates using the Template Assistant.

Note: Doc Merge templates that use Microsoft Word shapes (e.g., text boxes) may appear distorted when using the "Doc Merge to PDF" option as a result of the PDF export engine. If you intend to use shapes in your template, you may need to use the "Doc Merge" option for them to render as expected.

To create a template:

1. Create a blank DOCX, XLSX, or PPTX document in your preferred software application. When records are merged with the template using the "Doc Merge" option, the output will be in the same format. 
2. Leaving the window with the blank document open, launch the Template Assistant by clicking the Doc Merge widget in Sugar's footer. The Template Assistant opens in a new window (not in your current browser tab).
3. One by one, copy the desired fields from the Template Assistant to your clipboard as described in the Working with the Template Assistant section of this page, and then paste the fields into your blank document.
4. Save the document in DOCX, XLSX, or PPTX format. Do NOT save the file in a native template format (e.g., DOTX, XLTX, POTX). 
   

Uploading the Template

After creating the Doc Merge template, you must upload it to Sugar's Document Templates module using one of the following methods:

• Create a new Document Template record in Sugar. Please refer to the Document Templates Module section for more information.
• Alternatively, you may upload the document template when you initiate the merging of a record; refer to Step 3 in the section below.

Sugar will check the file for compatibility when you upload it. Attempting to upload an unsupported file type will produce an error and the Document Template record will not save.

Merging Records with a Document Template

You can either merge individual records or multiple records simultaneously into one document. 

• Merging Individual Records
• Merging Multiple Records

Note: A merge can also be triggered by a SugarBPM process. For more information, refer to the SugarBPM > Process Definitions documentation.

Note: Your data is sent to a secure server for the Doc Merge to be completed. As soon as the Doc Merge is complete, your data is permanently erased from the server. 

Merging Individual Records

Merge individual records with a document template from record view, list view, or a subpanel's Actions menu. You can use DOCX, XLSX, and PPTX file templates when merging individual records.

1. From a record, list view, or subpanel Actions menu, select "Doc Merge" or "Doc Merge to PDF".
2. Select a document template in the Search and Select drawer, or click the Create button to create a new template. Please refer to the Common Actions section for more information. When using the "Doc Merge to PDF" option, you must select a DOCX file template in this step. The merge process begins immediately.
   
   The status of the merge displays in the Doc Merge widget. When complete, a confirmation message displays, and the merged document is added to the document list in the Doc Merge widget and in the Documents module. 
   
3. Click the document icon to download the merged document. For more options, please refer to the Accessing Merged Documents section.

Merging Multiple Records

Merging multiple records allows you to either create a single document with a separate page for each record merged (e.g., mail merge letter), or populate formatted pages (e.g., tables) with fields from multiple records (e.g., shipping labels). To create labels, the Label Merging field must be enabled in the Document Template record. Please refer to the Creating Mailing Labels from Sugar Records article for more information. 

Follow these steps to mass-merge many records at once. Remember, the output's layout will be subject to the state of the template's Label Merging field.

1. Select the records to merge in list view.
2. Expand the Mass Actions menu and select "Doc Merge" or "Doc Merge to PDF". When merging multiple records, if you select "Doc Merge", you will only be permitted to output a DOCX format.
   
3. Select a document template in the Search and Select drawer or click the Create button to create a new template. The merge process begins immediately.
   
4. The status of the merge displays in the Doc Merge widget. When complete, a confirmation message displays, and the merged document is added to the document list in the Doc Merge widget and in the Documents module.  
   
5. Click the document icon to download the merged document. For more options, please refer to the Accessing Merged Documents section.

The field values from the records are merged with the document template:

Accessing Merged Documents

After merging records with a document template, you can access the merged documents using one of the following methods:

• Click the document's link in the Doc Merge Widget to download the document.
• Click the "Document Ready" link in the Doc Merge Widget to open the document's record in the Documents module.
• If you initiated the merge from record view, you can access the document from that record's Documents subpanel.
• Navigate directly to the Documents module to locate the merged document.

Doc Merge Widget

The Doc Merge widget in the footer provides access to your merged documents through the widget's Document List and the Template Assistant, where you can select Sugar record fields and other data to build your template.

Widget Document List

The widget's Document List stores a list of merged documents and those still in progress, with status indicators and links to completed documents. Documents are only displayed for the user who initiated the merge, and they persist in the Document List until manually removed, even across multiple sessions. If an error is encountered while processing a document merge, errors are displayed below the name in the Document List and it is identified by a red bar.

Note: If a user's session ends while a merge is in progress, the merge will continue to process and the status will be updated in the widget in the user's next session.

The Document List provides the following functions: 

• A list of all merged documents for the current user
• Links to each merged document in Sugar
• Links to download each merged document to your local computer in its native format (DOCX, XLSX, PPTX, PDF)
• Send a link to an assignment notification
• Quick access to email the document
• Delete documents from the list

Document List Elements

Element	Function
	Opens the merged document in the Documents module. To locate a document that you have removed from your Document List, navigate to the Documents module or, if it was a single-record merge, to the record's Documents subpanel.
	Downloads the merged document from the Document List.
	Emails a merged document from the Document List as an attachment. The configured email client opens with the document attached. After sending the email, it is added to the record's Emails subpanel.
	Adds a notification record with a link to the merged document in the Notifications module. In the Search and Select drawer, select the names of recipients for the notification and then click the Select button.
	Removes the document from the Document List. This does not delete the document from Sugar, it only removes it from the Document List in the Doc Merge widget. To fully delete a merged document from Sugar, you must delete it from the Documents module. Removing a document from the list while a merge is in progress does not stop the merge processing, it only removes it from the list.

Template Assistant

The Template Assistant, accessed from the top of the Doc Merge Widget, facilitates creating Document Templates by allowing you to select module fields from Sugar and copy them to your system clipboard for use in a DOCX, XLSX, or PPTX file. Once open, the Template Assistant window is intended to be left open next to a window with the document template file in its native editing environment so you can easily copy and paste the field codes into the document template.

The Template Assistant helps you complete the following tasks:

• Find and select fields to copy into your template document file.
• Insert lists or tables of data from related Sugar records.
• Place a custom-formatted date stamp in your template. 
• Use Sugar Logic to apply calculations, logic checks, and formatting to your data, or copy data from one field to another. 

These tasks are completed within the tabs of the Doc Merge Template Assistant:

• Fields: Copy data from your Sugar records
• Dynamic Elements: Insert lists, tables, and dates
• Sugar Logic: Produce custom content using Sugar Logic

Copying Fields from the Template Assistant

The Fields tab of the Template Assistant allows you to copy the merge codes for Sugar module fields to your system clipboard, including custom fields, from which you can paste into a file to create a document template:

To copy fields:

1. Navigate to the Fields tab in the Template Assistant.
2. Select a module from the dropdown list. The fields in the selected module display as a list with the associated field merge code.
   
3. Scroll through the list or use the Search field to locate the desired field.
   
4. Click the name of the field to copy the field merge code to your system clipboard.
5. In your document template file, paste the field in the desired location.
6. Repeat for all desired fields.
   

Configuring Fields

You can configure how field values will populate the merged document by setting options before you copy the field merge code (e.g., capitalizing).

To configure fields:

1. Follow steps 1 - 3 in the Copying Fields from the Template Assistant section.
2. Click the settings icon to the right of the field to configure or the link icon for fields that have relate fields. Different field types have different field settings, which are described in detail in the Field Settings section of this page.
   
3. Set the desired options, and then click the Copy to Clipboard button. In the example pictured here, we are configuring the Name field to output on our template with a capital first letter. The appropriate merge code for your configuration is produced and stored in your clipboard: {name capitalize='true'} 
   
4. Paste the code from your clipboard into the desired location In your document template file.
5. Return to the Template Assistant and click the Back button to return to your previous location.

Field Settings

Field Types	Settings
ActionButton Dropdown Email Iframe Parent Radio TextArea TextField URL		Capitalize: When selected, the first letter of the value will be capitalized. Only the first word will be capitalized for multi-word values.  Case: Converts the value to all uppercase or all lowercase. Padding: Number of spaces to add after the value when it is placed inside a table cell in the template. Barcode: Select this field to include a scannable barcode in the document template. Please refer to the Barcodes section for more information.
Date Datetime		Date format: Select a standard format for the date field. Custom date: Select this option to identify a custom date format. Click the Help link to navigate to a page with information on acceptable date formats.
Checkbox		Format Type: Select the format that you would like to use to output the boolean value (true/false, checked/unchecked, 1/0, yes/no, on/off). Custom: Select this option to define custom output for the boolean values. Custom States: Displayed when the Custom option is selected, identify the custom true and false boolean values in these text boxes (e.g., "Enrolled"/"Not Enrolled").
Phone Currency Integer		Padding: Number of space characters to add around the value.
Image		Scale: Resize the image when it is merged into a document by the value identified in this field. Use a value between 0 and 1, where 1 is 100% (e.g., enter 0.5 for 50%).
Multiselect		Format Type: Display the multi-select field values as a bulleted or numbered list. Sort direction: Display the values in ascending or descending order.

Barcodes

You can include scannable barcodes in merged documents for the following field types:

• ActionButton
• Dropdown
• Email
• Iframe
• Parent
• Radio
• TextArea
• TextField
• URL

To include a barcode on your template:

1. Select the Barcode checkbox when configuring the field. The following fields display:
   
2. Complete the settings using the guidance text in each field and the reference material provided on the jsBarcode wiki page.
3. Click the Copy to Clipboard button and paste the copied code into your external template.

The following example shows the settings used and the resulting barcode in the merged document:

Barcode Configuration	Barcode Result

Adding Lists of Related-Module Data to Document Templates

To add a bulleted list of related record field values to your template:

1. Navigate to the Dynamic Elements tab in the Template Assistant.
   
2. Select the module containing the records you want to show.
3. From the "Select Dynamic Element" dropdown, select "List". 
4. From the "Select Relationship" dropdown list, select the name of the related module.
5. From the "Select Relationship Fields" list, select all fields to be included in the list.
6. From the Sort dropdown list, select the name of the field on which to sort the list.
7. In the remaining dropdown list, select "asc" to sort the list in ascending order or "desc" to sort the list in descending order.
8. In the Max Records field, optionally identify the maximum number of records to return. If you do not identify a limit, then all matching records will be returned.
9. Click the Copy to Clipboard button to copy the set of merge codes to your document template. The example shown below produces the following merge code:

   {!list bind='#members' sort='name:asc' columns='name,created_by,description'}

   

Adding Tables of Related-Module Data to Document Templates

There are two methods for adding related record field values to your template:

• Formatted table: Select related module fields on the Template Assistant Fields tab to copy and paste a formatted table to your Document Template.
• Merge code: Select related module fields on the Template Assistant Dynamic Elements tab to copy and paste a merge code that produces a table in the merged document.

Related-Module Data Formatted Tables

To insert field values from related records as formatted tables in your template:

1. Navigate to the Fields tab of the Template Assistant.
2. Select a module from the dropdown list. The fields in the selected module display as a list with the associated field merge code.
3. From the "Select Relationship" dropdown, select the name of the related module.
4. Click the settings icon to the right of the selected module.
   
5. In the Max Records field, optionally identify the maximum number of related records to include in the table.
6. From the "Select a field" dropdown, select the fields you want to show in the table. Selections are shown in the Fields box below.
7. In the Sort Direction field, select the order in which the records will be displayed: alphabetically ascending or descending.
8. Click the "Copy as table" button to copy the set of merge codes to your clipboard so that you can paste the code into your document template. On merge, the data from related records will be listed as the rows of a formatted table. 
   

Related-Record Data Merge Codes

To add related record field values with merge codes:

1. Navigate to the Dynamic Elements tab of the Template Assistant.
2. Select the module containing the records you want to show.
3. From the "Select Dynamic Element" dropdown, select "Table". 
4. From the "Select Relationship" dropdown list, select the name of the related module.
5. From the "Select Relationship Fields" list, select all fields to be included in the list.
6. In the Header Color field, either type the name of a color for the table's header row or click into the field to use the color picker which adds the corresponding hex code.
7. From the Sort dropdown list, select the name of the field on which to sort the list.
8. In the remaining dropdown list, select "asc" to sort the list in ascending order or "desc" to sort the list in descending order.
9. In the Max Records field, optionally identify the maximum number of records to return. If you do not identify a limit, then all matching records will be returned.
10. Click the Copy to Clipboard button to copy the set of merge codes to your document template. The example shown below produces the following merge code, which produces a table with the field values in the merged documents: 

    {!table header-color='gray' bind='#contacts' columns='name,phone_mobile,email_and_name1' header='Name,Mobile,Name' sort='name:asc'}
    

Adding Date Stamps to Document Templates

To add a date stamp that will populate with the current date upon merge:

1. Navigate to the Dynamic Elements tab in the Template Assistant.
   
2. From the "Select Dynamic Element" dropdown, select "Date". Selecting a module is not required when "Date" is the selected element. 
3. Either select a format from the Date Format dropdown list or select the Custom Date option.
4. For custom dates, identify the desired format in the text field. Click the Help link for an external resource to custom date formats.
5. Click the Copy to Clipboard button to copy the merge code to your document template. The example shown below produces the following merge code: 

   {!date format='YYYY MMM'} which adds the date when the document merge is initiated to the merged document in YYYY MMM format.
   

Using Sugar Logic in Document Templates

Example functions include counting the related records (count), returning the sum of several values (rollupConditionalSum) or the difference between two values (subtract), and even converting a non-string value to a string (toString).

To use Sugar Logic formulas in document templates:

1. Navigate to the Sugar Logic tab in the Template Assistant.
   
2. Select a module from the list.
3. Build your formula by selecting functions and fields from the dropdown lists. Please refer to the Sugar Logic documentation for more information.
4. Click the Copy to Clipboard button to copy the formula to your document template. The example shown below produces the following merge code: {!formula value='concat($name,$industry)'} which returns the account's name with the industry appended.
   

Using Condition-Based Logic in Document Templates

In addition to the ability to use Sugar Logic formulas in documents templates, you can use condition-based logic by manually constructing IF/ELSE IF statements. Please refer to the Filtering with Conditionals in Doc Merge article for more information.

Document Templates Module

The Document Templates module was added to Sugar to support the Doc Merge feature. The Document Templates module is where you can upload new document templates and manage existing document templates. This section provides information specific to the Document Templates module. For information on views and actions that are common across all Sugar modules, such as creating, editing, and deleting document templates, please refer to the Working with Sugar Modules section of this page.

Note: The Document Templates module is hidden by default. If you do not see the Document Templates module, please check the Layout Options in the Advanced tab of your user profile or ask your Administrator to unhide the module via Admin > Display Modules and Subpanels.

Document Template Fields

The Documents module contains a number of stock fields that come out-of-the-box with Sugar. For information on using and editing various field types, refer to the User Interface documentation. The definitions below are suggested meanings for the fields, but the fields can be leveraged differently to best meet your organization's needs. Administrators or users with developer-level role access have the ability to alter, add, or remove fields via Admin > Studio. For more information on configuring fields, please refer to the Fields documentation in the Administration Guide.

Working With Sugar Modules

While the Document Templates module has some features that only apply to document templates, it also uses the Sidecar user interface that most Sugar modules are based on. The following sections detail menus, views, and actions common to Sidecar modules and contain links to additional information within the page or links to the User Interface documentation.

Document Template Menus

The Document Templates module contains various options and functionality that are available via menus in the module tab, list view, and record view. The following sections present each menu and its options with links to more information about each option in the User Interface documentation or, for Document Templates-specific functionality, within this page.

Module Tab Menus

The Document Templates module tab is typically located on the navigation bar at the top of any Sugar screen. Click the tab to access the Document Templates list view. You may also click the triangle in the Document Templates tab to display the Actions, Recently Viewed, and Favorites menus. The Actions menu allows you to perform important operations within the module. The Recently Viewed menu displays the list of document templates you most recently viewed. The Favorites menu displays the list of document templates you most recently marked as favorites.

The module tab's Actions menu allows you to perform the following operations:

For more information on module tab menus including reasons a module may not be included in the menu, see the User Interface documentation.

List View Menus

The Document Templates list view displays all document records and allows for searching and filtering to locate specific documents. You can view the basic details of each record within the field columns of the list view or click a document's name to open the record view. To access a module's list view, simply click the module's tab in the navigation bar at the top of any Sugar page.

List View Mass Actions Menu

The Mass Actions menu to the right of the checkbox option in the list header allows you to perform mass actions on all currently selected records. You can use the checkbox on each record's row to select individual document records or click the checkbox in the list header to select all records displayed on the current set of list view results.

The Mass Actions menu allows you to perform the following operations:

List View Record Actions Menu

The Record Actions menu to the far right of each record's row allows you to perform actions on the individual document directly from the list view.

The list view's Record Actions menu allows you to perform the following operations:

Record View Actions Menu

The Document Templates record view displays a single document template in full detail including its fields and subpanels of related records. To access a document template's record view, click a hyperlinked document name from anywhere within Sugar. The record view's Actions menu appears on the top right of the page and allows you to perform various operations on the current record.

The Actions menu allows you to perform the following operations:

Common Views and Actions

In the table below, the left column contains links to the User Interface page covering topics that are applicable to all Sidecar modules. The right column has links to sections of the current page that cover topics specific to documents.