On Premise & Cloud
© Copyright 2013 Sage Technologies Limited, publisher of this work. All rights reserved.
No part of this documentation may be copied, photocopied, reproduced, translated, microfilmed, or otherwise duplicated on any medium without prior written consent of Sage Technologies Limited.
Use of the software programs described herein and this documentation is subject to the End User Licence Agreement enclosed in the software package, or accepted during system sign-up.
Sage, and the Sage logo are registered trademarks or trademarks of The Sage Group PLC. All other marks are trademarks or registered trademarks of their respective owners.
This Sage CRM Mail Merge Support Guide aims to provide additional knowledge about Mail Merge and other related features.
This guide is specifically aimed at CRM Professional Services and Support Engineers. It applies to:
• Sage CRM On Premise from 7.1 SP2 onwards.
• Sage CRM Cloud from 2012 R2 onwards.
Note: An updated version of this document will be released for future versions.
This document provides a general introduction of the Mail Merge feature, as well as practical troubleshooting cases. It describes how this feature currently works and provides implementing techniques. This document will review common configuration errors, and detail their resolution as well as providing techniques for capturing error details.
This document will also provide best practices guidelines when carrying out an implementation, and information on supporting/troubleshooting the Mail Merge functionality effectively. It should be viewed as a supplemental guide to the Sage CRM version 7.1 Administrator Guide.
Mail Merge is designed to produce multiple documents from a single template form and a structured data source.
We listened to customers’ feedback about the difficulties of creating Mail Merge templates using Microsoft Word's native Mail Merge feature, and our aim was to remove that complexity and shift the focus to being able to create simple Mail Merge templates from within Sage CRM.
A number of sample templates are included in a standard install. To check the templates in your install, go to Administration | E-mail And Documents | Document Templates
Mail Merge is a server-side process. You do not need Microsoft Word on your client machine in order to perform a Mail Merge. However, you will require Microsoft Word or another program that opens .DOC and .DOCX files in order to view and print merged documents.
CRM Merge fields
1. Mail Merge templates contain Sage CRM merge fields, which are placeholders for information from the CRM database that are inserted during a merge. For example, the merge field <<comp_name>> is replaced by an actual Company name when the merge between the template and the database data is executed.
2. The merge fields that are available to you depend on the context you are in, so make sure that you start the merge in the correct context. For example, if you want to include merge fields from the opportunity table, start the merge process from within the context of an opportunity.
3. You should only enter merge fields from one primary entity when creating a new template in Microsoft Word. For example, when creating a template for use with case records, you can enter case, person, company, address and user merge fields, but not quote merge fields.
Mail Merge templates
1. Mail Merge templates are available to you only in the context with which they are associated. For example, only case templates are available in the case context. If you attempt to use a template outside of its context - for example a quotation Mail Merge template in the case context the merge fields will not be converted successfully.
2. You can create new Microsoft Word templates and upload them for your users to work with.
3. You can continue to work with existing Microsoft Word templates (And for those Word documents that contain nested items, see point 7 below). However, you cannot edit them on the fly in Sage CRM.
4. In Cloud 2012 R2, there is a new Edit Attachment option in the final step of a Mail Merge if you are working in IE and merging with an MS Word document template. This allows you to edit a merged document after the merge has completed. The Allow ActiveX Document Drop (in Administration | E-mail and Documents | Documents & Reports Configuration) option must be set to Yes for this option to be available.
5. If you have existing Word templates that you want to edit on the fly during the merge process, these templates must be converted to HTML.
6. Any old quote or order Word templates will need to be reconfigured. Any template that merges child items now needs to include special <<TableStart>> and <<TableEnd>> tags. For example if you are creating a quote template, you would need to include a <<TableStart:Quotes>> tag at the beginning of the template and a <<TableEnd:Quotes>> tag at the end. Any child items to be merged would need to be wrapped with <<TableStart:QuoteItems>> and TableEnd:QuoteItems tags. For more information refer to the in-product documentation.
7. You can create new templates using Sage CRM's rich text editor. Any new templates you create will be saved in HTML format. You can add images to these templates, but any of these images must be uploaded first via the rich text editor.
8. The Mail Merge feature can also be used with Custom Entities. Please keep in mind that the ‘Has Communications’ and ‘Has Library’ options must be selected when creating a new entity. Otherwise, this new functionality will not be available.
Performing a Mail Merge
To merge an existing template with company and person details:
1. Find the prospect you want to perform the Mail Merge to.
2. Click on the hyperlink of the person so that their name appears in the context area of the screen.
3. Right-click on the New menu button, and select Mail Merge
To create your own template, you can:
• Select any existing HTML or Word template stored locally in CRM or,
• Create your own template or,
• Add an existing template you have on your local drive.
Opens a blank HTML template. You can create a new local template using this blank template and save it locally so that you can reuse it when you need it.
Add Local Template
You can add an existing HTML or Word template from your local drive. These should include all the standard merge fields used in your customer correspondence.
4. Click on an existing template.
5. You can Preview Merge at this stage or perform Merge and Continue which will do the actual merge for you.
6. After the Mail Merge has been processed, you can also Create Communication. This will allow you to view a copy of the merged document from the communication record. Untick the box if you do not wish to, and you can click to View Merged Document or Edit Merged Document which can be saved to your local drive at this stage. Select Continue to go to the current communication record.
7. The communication will include your merged document with a default ‘Letter Out’ action. Add a title in the Subject area and a brief description in the Details area of the communication.
8. Select the Save button. A communication record is created to record that a letter was sent out, forming part of the customer's interaction history. The merged document can be viewed as an attachment on the communication record. It can also be viewed and edited from the Documents tab.
Performing a Mail Merge to Multiple Contacts
You can create a merged document for all contacts contained in a search list, saved search, or a group. To carry out a Mail Merge to multiple contacts:
1. Return a search list by either performing a standard search or selecting a saved search from the Saved Search drop-down list at the top of the screen.
2. You can then Start Mail Merge for this group of contacts and simply follow through the steps mentioned in the former section.
Changing a Mail Merge View
In some cases, you may need to include some additional/customised fields in a merged template. The Mail Merge view must be modified in order to do that. For example, if you want to add the field case_description to the Case Mail Merge view, and it is not yet available in the case Mail Merge view.:
1. Open Administration | Customization, and select Cases from the Customization home page.
2. Select the Views tab. A list of views associated with the Case context is displayed.
3. Select the hypertext link of the view you want to edit. In this example, the view you want to edit is
4. Select the Change button. The view is displayed in edit mode. The View Script field contains the SQL used to create the view.
5. Make the changes you require. In this example, find the Case_CaseId. Add the new field after the Case_CaseId. This section of the script changes from:
Case_CaseId, Case_Description, Comp_CompanyId
Note: If you make a syntax mistake, then you will not be allowed to save the changes.
6. Select the Save button. Once you have included the case_description field in the view, you can repeat the Mail Merge process, and add the new merge field into the template.
Available Mail Merge Views
The table below outlines which view is used according to the area from where the Mail Merge is running.
Note: It is not possible to add a field to a document template from the Mail Merge dialog box in Word unless you add it into the associated the view first.
Note: When carrying out a Solution Mail Merge using vMailMergeSolution, the Solution must be linked to a Case for the merge to work.
Creating a Microsoft Word Label Template
You can use Microsoft Word to create a label template. Please note, when creating label templates you must:
• Insert Sage CRM merge fields manually.
• Wrap the template in TableStart:Labels and TableEnd:Labels tags.
• Ensure the template contains a minimum of two label placeholders, the second of which must contain a Next field.
To create a label template in Microsoft Word:
1. Create a new blank document and insert a one row table with as many columns you need for the labels you want to print onto. Make sure that the cells are sized to the dimensions of the labels you are using, and add any required margins to align your selected labels.
2. Insert a TableStart:Labels tag in the top left cell. To do this, select Quick Parts from the Text part of the Insert tab, then select the Field option. The Field dialog box is displayed.
3. Select the MergeField option from the Field Names drop-down in the Please Choose a Field panel.
4. Type TableStart:Labels in the Field Name field of the Field Properties panel.
5. Use the same method to insert any Sage CRM merge fields you want to include after the TableStart:Labels tag, this time typing the name of the Sage CRM merge field in the Field Name field of the Field Properties panel.
6. In each subsequent cell, insert a Next field. To do this, open the Field dialog box once more and select Next from the Field Names list. After the Next field, copy the Sage CRM merge fields from the label placeholder you created earlier.
Note: You will not see the Next field unless you have the Show Field Codes Instead Of Their Values option selected in Word Advanced Options. Alternatively you can see the field codes by pressing ALT+F9.
7. Insert a TableEnd:Labels tag after the Sage CRM merge fields you entered in the rightmost cell.
Sample label template
8. Save and upload the template. You can save it in .DOC or .DOCX format.
9. To test the merge document, navigate to a customer record.
10. In the Documents tab, select Start Mail Merge. Click the hyperlink of your new template, preview the merge, and check that the customer data is merged.
Editing an Existing Microsoft Word Mail Merge Template in Sage CRM
Sage CRM Administrators can edit existing Microsoft Word Mail Merge templates from the Document Templates area in Administration | E-mail and Documents.
To do this, the document's status must be set to Draft. To set a template's status to Draft, click the document's hyperlink and on the details panel select Draft from the Status drop-down, then click Save. When you click on the document's hyperlink again, an Edit Attachment button will be available in the Details panel.
Edit Attachment button available when document Status is set to Draft
Click the Edit Attachment button to begin editing the document. The document will open in Microsoft Word, or whatever program you use to open .doc or .docx files.
If your edits include adding new merge fields, you must add them by clicking Insert | Quick Parts | Field, then selecting MergeField from the Field Names drop-down and typing the merge field name in the Field Name field on the Field Properties panel.
You must remove any column, section, or line breaks.
Save the document then close it. Then click Save on the Document Details screen back in Sage CRM.
If you perform a Mail Merge with the newly updated document, the changes you have made will be reflected in any resulting merged output.
The same process can be followed for HTML, again provided the template's status is set to Draft and the default program you use to open .htm and .html files is set to a text editor program such as Notepad.
Editing HTML templates using this method is recommended only for people with HTML experience. Incorrect changes to the HTML code can result in templates no longer working properly.
The new Mail Merge process and the move to the Cloud environment have highlighted a number of areas that are causing some confusion. In this section, we will try to highlight the changes to alleviate some of that confusion.
Converting a Quote Template to work in 2014 R1
Pre Cloud 2012 R2 Templates that contain nested (child) items, such as those for Quotes or Orders, will no longer work and will need to be converted using some special rules.
Converting a Quote Template to work in 7.1 SP2
To display nested items in a quote (or order) template in SP2, a specific structure is required - If you want to include a table with nested (child) item merge fields, you need to insert start and end tags for both the main table (Quotes) and the child table (Quote Items). You must also include a TableStart and TableEnd tag in the same template section, table row or table cell. For example, if you want a row of quote item data to display, the first column in that row must include a TableStart:QuoteItems tag, and the final column must include a TableEnd:QuoteItems tag.
Any Mail Merge fields included in the document must be genuine Mail Merge fields, i.e. by going to Insert | Quick Parts | Field then selecting MergeField from the Field Names drop-down list in the Please Choose A Field panel of the Field dialog box, then entering the name of the CRM merge field (e.g. comp_name) in the Field Name field on the Field Properties panel.
In addition, any column, section, or page breaks must be removed.
A basic example would be something like:
«orde_createddate» Reference: «orde_reference»
«pers_firstname»«pers_lastname» «comp_name» «addr_address1»
Please find enclosed the requested quote. Please call me with any questions you may have.
A new Mail Merge video (www.youtube.com/watch?v=MJFsdVuxGU0) was created in response to the influx of Support issues related to migrating pre-7.1 SP2/2012 R2 MS Word quote/order templates.
For more information on creating new templates in Microsoft Word and creating new quote or order templates, please refer to the following Help files:
• https://community.Sage CRM.com/adminhelp/Content/Administrator/DT_CreateQuoteOrder.htm
• https://community.Sage CRM.com/adminhelp/Content/Administrator/DT_CreateNewWordTemplate.htm