Technical Desk - Creating Letters and Mail Merges

Our customers tell us that one of the most used features and biggest benefits of their CRM System is the ability to quickly produce a series of personalised letters using the mail merge facility. Yet we sometimes get questions which indicate the process of creating mail merge documents is not fully understood.

This article provides a procedural tutorial on how to create and run a mail merge in Commence. This may be particularly useful to long-time Commence users, as it shows how to get the best results out of the new Word merge macros.

The procedures for sending letters with Commence can be broken into three steps:

Step 1: Create a letter template

Step 2: Edit the letter template in Word

Step 3: Run a mail-merge

Once you have created a letter template, you can use it over and over again. You do not have to create a letter template every time you want to send a letter.

What is a letter template?

Letter templates are the basis for letters that are created with Commence. They consist of special symbols which are called field codes. When a field code is detected, the required data is read from Commence and entered into the document. For example, you could create a letter template to be used as your letterhead. The template could include your company logo and field codes to get the recipient's Name, Company Name, and Address from Commence. 

Letter templates are often used to create form letters. Once the template is set up, a mail merge can be run to produce multiple copies of the letter, personalised with the selected contact's information from Commence.

Commence includes several pre-defined letter templates which can be edited to meet specific needs. Additional templates can be added (or deleted) as needed. 

What types of letter templates are there?

Commence offers two types of letter templates: 

Text letter templates (TXT)

Text letter templates are text only files that contain no formatting information. This means they can't have fonts, bold, italics, or indents, etc. 

Formatted letter templates (DOC)

Formatted letter templates are word processor documents that are specific to the word processor in use. Formatted letter templates are usually created with Microsoft Word. 

When a formatted letter template is created, Commence uses a macro to communicate with Word. This means you will need to enable macros when prompted, when you open Word. 

In this article, we will mainly be looking at creating formatted letter templates in Word 2000, Word XP or Word 2003.

Inserting Field Codes

Microsoft Word 97 or WordPerfect

Letter templates created using Microsoft Word 97 or WordPerfect use a special syntax for inserting field codes into the template. This syntax is also used for email merged html documents sent from Commence Connect for E-Mail. 

The field code is a special way of representing a field from a category. The format for a field code is (%Field Name%), where Field Name is a valid field name in a particular category. For example, to represent the First Name field from the Person/Company category, the proper field code would be (%First Name%). 

Field Codes can also be used to represent fields from a connected category. A field code that represents a connected field has the format (%Connection Name%%Connected Category Name%%Field Name%). 

When a letter is created, the field code gets replaced with data from the item in Commence. In the example above, if we had a field code called (%First Name%), it would actually get replaced by the person's first name from Commence, before printing out the letter.

Field codes can be typed in directly if you know the field names within the categories. If you do not know the field names, then there is an Insert Field button which will insert the appropriate field code into the letter template for you. 

Microsoft Word 2000, XP or 2003:

Templates created with Microsoft Word 2000 and later versions do not use this field code format. Instead they use the standard Microsoft Office merge field format. Full details are available in the Microsoft Office Integration Guide. The remainder of this article refers to the techniques to use with Microsoft Word 2000, Word XP or Word 2003.

Step 1: Create a letter template

1. In Commence, go to the Customise > Database... and then click on the Letter Templates tab.

2. The Customize Database - Letter Template Dialog Box will be displayed. Select the correct Commence category that the letters will be extracting the data from.
   
   
   
   
   
   
   
   

3. Click on the Add Formatted button and a new Formatted Letter Template dialog will open.
   

4. Enter a name for the template that will easily distinguish it from the other  templates. 

5. There is a checkbox called Shared. If you  tick it, the letter template will be made available to all the Commence users/clients, if you do not tick the Shared box, then the letter template will only be available to the person who created it (if the checkbox is greyed out, you may not have permissions to make the template shared). 

6. Click on the Create Template button and Word will open up with the Select Template Type dialog box visible. 

7. Select Letter and click on the Create Template button.

Step 2: Edit the template in Word

1. Once the letter template is open, format it as you would for any Word document.

2. You will notice a floating Commence Fields bar. If this is not visible go to the Commence menu and select Insert Commence Fields.

You can use this bar to add any Commence fields into the Word template. An example of a letter template with Field codes inserted is shown on the right.

You don't need to worry about trying to edit these codes manually, just use the Insert Commence Field button, and it will insert the correct code for you.

3. When you have entered in some field codes, you can see what they would look like with data in them by clicking the View Field Codes button. Click the View Field Codes button again to toggle back to show the Field Codes.

4. When you have finished creating the template you have to go to File > Save Commence Template (or Commence > Save Commence Template if you prefer).  Simply selecting File > Save won't work.

5. Close the document. 

Editing an existing letter template 

Once you have created a letter template, you may need to come back to it at a later stage to add some more fields or change the layout. You can quickly modify a letter template by:

1. In Commence, go to the Customise > Database... and then click on the Letter Template tab.

2. All the letter templates for the selected Commence category will be displayed, so make sure you have the correct category selected. 

3. Highlight the name of the template from the list of available templates, and click on the Edit button.

4. The Edit Formatted Letter Template dialog box will display and you will be able to see the following info: the Filename, the Template Name, the Category and the Shared checkbox. 

Technical Note: Each Commence client saves letter templates into the <databasepath>\tmplts folder on the local harddrive. Since you can create Shared and Local letter templates, the same Letter template can have a different filename on each Commence client. The filename it uses is displayed in step 4 above, it will look like File Name: PIM00012.doc. 

5. Click the View button to proceed with editing in Word. 

6. When you have finished editing, remember to save the template correctly using  File > Save Commence Template.

7. Close the template in Word.

Step 3: Run the mail-merge

Sending letters to one or more recipients using a letter template 

1. Open a view containing the contact(s) who should receive the letter.

2. If you want the letter to go to more than one contact, but not everyone in the list, then filter the view accordingly. You must remember to save the view before you do the mail merge, for the filter settings to work. There are two options for saving views either from the menu bar or by right clicking in the view:

• Views > Save View (don't use this option)

• Views > Save View As ...

You should use Views > Save View As ... and give the View a new name, so you don't overwrite Views used by others in the Workgroup. If available, leave the Shared checkbox unchecked. 

Note: this step is only required if you want to merge the letter for all items.

3. Select the contact you want to create a letter for, by clicking on them once in the view. If you want to create a letter for everyone in the view, just select anyone in the view.

4. Select the Send Letter button on the tool bar or Tools > Send Letter 
   
   
   
   
   
   

5. The Send Letter dialog box is displayed, highlight the letter template you want to use (i.e. the one you just created).

6. By default, a single letter will be sent to the Selected Item in your view. To perform a mail merge for all contacts in the view, choose All Items from the Send Letter To: Combo-box at the top of the dialog.

7. Ticking the box to Include merged document with log item will add a reference to the document with your log history. It is a good idea to Include the Merged Document, because you then have a record of exactly what the document contained. 

8. Custom Document Filename lets you specify a custom path and filename to store the merged document instead of using the auto-generated filename.

9. Click on the Merge button to begin the merge process and send the finished documents to the selected destination.

10. If Preview checkbox is ticked, the merged document will open in Word. This enables you to preview the letter before completing the merge. When sending a letter to multiple contacts, your changes will be applied to the merged document for all contacts.

11. The letter will open up in Word and the field codes will have been replaced with the data from Commence.

An example of a mail-merge to the selected item in the view:

An example of a mail-merge to all items in the view:

The number in the box (circled in red above) indicates the record number in the merge. It is useful to go to the last record by clicking the button - this provides a quick sanity check to ensure that the merge proceeded as expected. The record number now displayed should match the number of items in the View used for the Merge.

You can step backwards or forwards in the merge with the and buttons.

Technical Note: This illustrates one of the advantages of re-creating old templates with the new macros. Using the old tools, a separate document and print job was required for each data item. This created a massive overhead on the computing resources and resulted in poor performance. With the new macros, one document is created and only the data that is changing (i.e. contact details) are inserted into the page. 

12. Press Continue with Merge to complete the letter and send it to the destination you selected (Printer, FAX, E-Mail or Draft). Press Cancel to discard the letter.

13. A log entry is automatically created and linked to the contact record(s) to whom the letter was sent. The date and time the letter was produced is automatically recorded. 

Adding Commence Views to your Word Templates

It is often useful to have a Commence View included in a document, retrieving the latest data direct from the database. For example, you might want to send out a letter which includes current pricing information. Including views into a Template has been covered in a previous CRMtimes article:  http://crmtimes.aus.com.au/0604/technical.htm.

Creating Label Templates in Word

Word can also be used to efficiently create templates for envelope labels. This has also been covered in a previous CRMtimes article: http://crmtimes.aus.com.au/0604/mailing_labels.htm.

New Word Merge Features in Commence RM2.1 and Commence RM3.0

The Old style templates using the (%<field_name>%) syntax still work with the latest versions of Word. You don't have to re-create these templates.

However, the new macros introduced use the standard Word merge features and are significantly better, especially for large merges. It is recommended that legacy letter templates in regular use should be recreated using the new macros.

Letters logging is always performed. If you do not want letters logged you set the preferences through Customise > Preferences  Event Logs tab

• set the Log letters category to (none); or

• create a dummy category for logging letters. The category should have at minimum, a selection field with 'Letter Log'. An agent can be used to regularly remove these items.

Common Questions

Sending letters to all items but it does not replace the field codes with data. 

This is usually caused by the letter template not being saved correctly.  You must use File > Save Commence Template to ensure that the template is properly saved.

Error message "Compile error in hidden module: Commence"

This may indicate an installation problem and you should contact Advanced User Systems support for further assistance.

Error message "Microsoft Visual Basic Runtime error 438"

This problem is generally to do with permissions. Make a copy of the currently installed macro file (CmcMerge.dot) and place it into the Office\Startup directory. Reboot the PC, start Commence and re-run the mail-merge. Contact Advanced User Systems support if you require further assistance.