SugarCRM SupportProduct GuidesSugar Versions11.2 Sugar11.2 Sugar ServeSugar Serve 11.2 Application GuideUser InterfaceDoc Merge
This release is only available for SugarCloud customers.

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 is available out-of-the-box with Sugar Sell and Serve licenses. 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.
  • 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

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

  • You must be a licensed Sugar Sell or Sugar 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.

In addition, 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.
  • Create a role for users who will have access to the Doc Merge functionality:
    • 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 so that users can see each other's templates (team permitting) but only edit or delete their own:
      • Access: Enabled
      • Access Type: Normal
      • Delete: Owner
      • Edit: Owner
      • List: All
      • Record View: All
    • After saving the new role, scroll to the role's Users subpanel and add all users who should have access to Doc Merge. 
    • Separately, for users who should not have access to Doc Merge, set their roles' access to the Document Merges and Document Templates modules to "None".
  • Finally, add the following fields to layouts for the Document Templates module in Studio:
    • Add "Extension" to the Record View, List View, and Search layouts.
    • Add "Extension" and "Template Module" to PopUp List View layout.

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.

Accessing Doc Merge

The Doc Merge feature is accessible in the following locations:

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.

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.

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 "Merge to Doc" 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). 
    docmerge sampletemplate

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.

Merging Records with a Document Template

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

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 "Merge to Doc" or "Merge to PDF".
  2. Select a document template in the search and select drawer, or click the Create button to create a new template. When using the "Merge to PDF" option, you must select a DOCX file template in this step. The merge process begins immediately.
    docmerge listviewactions2
    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. 
    Docmerge mergedone
  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 "Merge to Doc" or "Merge PDF". When merging multiple records, if you select "Merge to Doc", you will only be permitted to output a DOCX format.
    docmerge massactionsmenu
  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.
    docmerge selecttemplate
  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.  
    docmerge mergecomplete
  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:
docmerge samplemergedletter

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 a single record, 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.
docmerge documentlist

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.
docmerge documentlist

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
docmerge docready 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.
docmerge filetypes Downloads the merged document from the Document List.
docmerge emaillink 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. 
docmerge notificationlink 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. 
docmerge remove 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:

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

  • Fields: Copy data from your Sugar records
  • Directives: Insert lists, tables, and dates
  • Formula Builder: Produce custom content using Sugar Logic.

TA-tabs

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.
    TA-fieldstab
  3. Scroll through the list or use the Search field to locate the desired field.
    docmerge searchfields
  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.
    docmerge copyfields

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 will have different field settings, which are described in detail in the Field Settings section of this page.
    docmerge config fields
  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'} 
    docmerge copyconfiguredfield
  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

docmerge fieldsettings1

 

  • 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

docmerge fieldsettings2

  • 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
docmerge fieldsettings5
  • 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
docmerge fieldsettings3
  • Padding: Number of space characters to add around the value.
  • Image
docmerge fieldsettings6
  • 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
docmerge fieldsettings4
  • 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:
    docmerge barcode
  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 
docmerge barcode2  docmerge mergedbarcode

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

  1. Navigate to the Directives tab in the Template Assistant.
    docmerge directives
  2. Select the module containing the records you want to show.
  3. From the "Select Directive" 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'}

    docmerge addlist

To add related record field values to your template in a table format:

  1. Navigate to the Directives tab in the Template Assistant.
    docmerge directives
  2. Select the module containing the records you want to show.
  3. From the "Select Directive" 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: 

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

Adding Date Stamps to Document Templates

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

  1. Navigate to the Directives tab in the Template Assistant.
    docmerge directives
  2. From the "Select Directive" dropdown, select "Date". Selecting a module is not required when "Date" is the selected directive.
  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.
    docmerge addtable

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 Formula Builder tab in the Template Assistant.
    docmerge formulabuilder
  2. Select a module from the list.
  3. Build your formula by select 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.
    docmerge formula

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 Studio documentation in the Administration Guide.

Field Description
Name Descriptive name for the document template. This name will be appended to the name of merged documents and will identify each merged document in the Doc Merge Widget.
Template Name of the source template file. Click the Browse button to locate the file on your computer, and then click the Open button. 
Template Module The module with which the template is associated. The template is only available for use in document merging from the selected module.
Use Revisions

When enabled, each occurrence of a record being merged with this template is added to the Document Revisions subpanel in the record. If this option is disabled, then only the most recent occurrence of the merged document is maintained in the record's Documents subpanel; however, all revisions are still maintained in the Documents module. 

Label Merging

When enabled, the template can be used for mass merging records into label format. Templates with Label Merging enabled can only be used for merging multiple records; you cannot merge a label template with an individual record.

Prefix

Optional text to be included at the beginning of the merged document name.

Postfix

Optional text to be included at the end of the merged document name.

Assigned to Owner of the document template. The value defaults to the current user, but you can select any other user to be the owner of the template. Templates are available to all users regardless of ownership.
Teams The Sugar team(s) assigned to the record.
Extension The source template file format extension.

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.
Documents ModuleTabMenus

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

Menu Item Description
Create Document Template Opens the record view layout to create a new document template.
View Document Templates Opens the list view layout to search and display document templates.

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.

docmerge massactions

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

Menu Item Description
Mass Update Mass update one or more document templates at a time.
Merge Merge two or more duplicate document templates.
Delete

Delete one or more document templates at a time.

Note: All document revisions related to the parent document template record will be deleted when the document template is deleted.

Export Export one or more document templates to a CSV file.
Merge to Doc Select or create a DOCX template to merge record data into documents that will be accessible in the Doc Merge widget.
Merge to PDF Select or create a DOCX, XLSX, or PPTX template to merge record data into PDF documents that will be accessible in the Doc Merge widget.
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.
Documents LV RecordActionsMenu

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

Menu Item Description
Preview (Eye icon) Preview this document template in the intelligence pane.
Edit Edit this document template.
Delete

Delete this document template.

Note: All document revisions related to the parent document template record will be deleted when the document template is deleted.

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.
Documents RV ActionsMenu

The Actions menu allows you to perform the following operations:

Menu Item Description
Edit Edit this document template.

Share

Share a link to this document template via email.

Copy

Duplicate this document template.

Note: Only the last document revision record related to the original document template will copy over to the new document template, and the "Change Log" will display "Document Created". 

View Audit Log View a sequence of changes made to this record.
Delete

Delete this document template.

Note: All document revisions related to the current document template will be deleted when the document template record is deleted.

Merge to Doc

Select or create a DOCX, XLSX, or PPTX template to merge record data into documents that will be accessible in the Doc Merge widget.

Merge to PDF

Select or create a DOCX, XLSX, or PPTX template to merge record data into PDF documents that will be accessible in the Doc Merge widget.

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.

General Instructions for Working With Sugar Modules Document Templates-Specific Instructions
Use the links below to navigate to the User Interface page which covers topics generic to many Sugar modules. When Documents-specific help exists for each topic, use the links below to navigate to sections of the current page.
Creating Records  
Viewing Records  
Searching for Records  
List View List View Mass Actions Menu
List View Record Actions Menu
Record View Record View Actions Menu
Intelligence Pane  
Editing Records  
Deleting Records  
Exporting Records  
Recalculating Calculated Values  
Finding Duplicate Records  
Merging Records  
Favoriting Records  
Following Records  
Sharing Records  

Last modified: 2021-10-26 15:38:54