Performing a Mail Merge With the Sugar Word Plug-In

Overview

SugarCRM Plug-in for Microsoft Word enables you to merge data, such as names and address in Sugar, to perform mail merges. One of the most common uses of the Sugar Plug-in for Word is mailing letters to your clients and/or creating License Agreements that need to be printed and signed. Once the mail merge template is created via the plug-in, users can initiate the mail merge from within Word.

Use Case

In this example, we will create a template and perform a mail merge for an annual renewal notice for clients.

Prerequisites

You will need to have installed the Sugar Plug-in for Word on your computer in order to perform the mail merge. For information on how to download and install the Word Plug-in, please refer to the Installation Guide.

Steps to Complete

Creating the Mail Merge Template

We will first create a mail merge template using Contacts as the target module as an example.

1. Open up Microsoft Word and click "SugarCRM" on the Add-ins ribbon then select "Define Template".
   
2. In the Select Master Module dialog box, select the target module then click "Next". We will select "Contacts" for our example.
   
3. The fields associated with the target module will be displayed in the "Add fields from" window.
   • Select each field you would like to add to the mail merge template then click "Add to Document". We will select the Primary Address, Contact Name, and Account Name fields for our example.
     
   • Depending on the target module that you select, you may have the option to select fields from the related modules as well by clicking "Next" rather than "Finish". The following window will display the fields for the related modules (Contacts and Opportunities). Select the related module from the bottom left dropdown then choose the desired fields to add to the document.
     
4. Once the appropriate fields have been added to the template, click "Finish".
5. You can move fields around in the word document by highlighting it and dragging it to the new location.
6. The mail merge template is now ready to be used!
   

Performing the Mail Merge

Once the mail merge template is created, the mail merge can be performed. The following steps use contacts as an example:

1. Open the mail merge template in Microsoft Word and click "Log in" in the SugarCRM menu.
   
2. Click the SugarCRM menu again then select "Perform Mail Merge".
   
3. In the popup window, select the appropriate contacts in the Available Contacts list and click the right arrow to move them into the Selected Contacts list. Click "Next" once all the desired contacts are selected.
   
4. The Complete Merge window will display the selected contacts. Click "Complete Merge" to perform the mail merge.
   
5. The merged word document will be generated for each of the selected contacts.
   
   

Creating a Mail Merge for Multiple Module Types

If you wish to include records from the Accounts, Contacts, Leads, and/or Targets module in a single mail merge, you can select "CampaignTargets" when specifying the target module. You will need to build a target list in Sugar by populating its subpanels with all of the desired records from each of these different modules. The mail merge can then be initiated from within Word by selecting the target list record.

Making Fields Available for a Target List Mail Merge

When building a mail merge based on the Target Lists module, the plug-in references the Targets module by default when generating the field list. If there are fields in the other modules (e.g. Accounts, Contacts, or Leads) that need to be populated in the template but which are currently unavailable in the Targets module, there are two options for doing so:

• Adding the necessary custom fields to the Targets module
• Changing the default module that the Word plug-in references for target list templates

Adding the Necessary Custom Fields to the Targets Module

In order for custom field data to populate on the target list mail merge template regardless of the module that the target list record belongs to, the custom fields must have identical database names across the applicable modules (Accounts, Contacts, Leads, and Targets). For example, if you have a custom field in the Contacts and Leads module with the database name 'customer_response_date_c', then you will need to add that field to the Targets module in order to populate the data in the mail merge template.Use the following steps to add custom fields to the Targets module:

1. In SugarCRM, navigate to Admin > Studio > Targets > Fields > Add Field.
2. Create a field with a matching name (not display label), 'customer_response_date_c' for our example. Please note that the field simply needs to be created in the Targets module and does not need to be added to the layout unless desired.
3. In Word, click the SugarCRM toolbar and select "Settings". Select the Advanced tab in the pop-up window then click "Reset" to update the field list cached in the plug-in.
   

Changing the Default Module for Campaign Templates

Depending on the number of custom fields or the possibility that the Targets module is not utilized, it may make sense to change which module the Word plug-in references by default for populating target list mail merge templates. Please note that this change comes with the following precautions:

• This change requires a modification to the code to the core instance files and is not upgrade-safe. It will be your responsibility to ensure this customization is in place and functioning following any upgrades.
• This change will affect how all users use the Word plug-in when composing target list mail merge templates.

Please use the following steps to change the default module:

1. Open the /soap/SoapSugarUsers.php file located on the server running your SugarCRM instance.
2. Search for the function get_module_fields. Inside that function, you should see a block of code similar to the following:

   global $current_user;
   if(!check_modules_access($current_user, $module_name, 'read')){
   	$error->set_error('no_access');
   	return array('module_fields'=>$module_fields, 'error'=>$error->get_soap_array());
   }

3. Modify this code as follows for the Contacts module, as an example:

    global $current_user;
   if($module_name == 'Prospects'){
   	$module_name = 'Contacts';
   }
   if(!check_modules_access($current_user, $module_name, 'read')){
   	$error->set_error('no_access');
   	return array('module_fields'=>$module_fields, 'error'=>$error->get_soap_array());
   }

   Note: You can opt to set $module_name to any module normally associated with target lists.
4. Then in Word, click the SugarCRM toolbar and select "Settings". Select the Advanced tab in the pop-up window then click "Reset" to clear the field cache stored in the plug-in.