Understanding How Mail Merge (Office) Templates Work

Author: Romer De Los Santos 

DUpdatedate: November 2024

Audience: System engineers, test engineers, quality engineers, and anyone responsible for creating and maintaining mail merge templates.

Products Applicable: Jama Connect®

Use Case

This article aims to give the reader a deeper understanding of how a mail merge template processes Jama items.

This guide assumes basic knowledge of mail merge templates and Jama Connect®. Refer to basics of the Custom Word Template Easy Start Guide.

Overview

At its core, a mail merge template is simply a list of instructions for handling different item types.

Concept 1: Items are processed one at a time and in order. 

For demonstration purposes, consider what happens when you initiate the export from the User Needs Document Component, as shown below.  

The first item to be processed is the User Needs Document component, followed by the Purpose text item, followed by the Scope text item, and so on until we reach the Revision History Item.  

Microsoft Word will take the Jama item being processed and look for instructions regarding what to do with the item type.  These instructions generally begin with TemplateStart/TemplateEnd tags but can also be surrounded by TableStart/TableEnd:CHILDREN tags which specify formatting instructions for item types in tables (refer to Creating Tables in Mail Merge (Office) Templates). 

Concept 2: Only one set of instructions per item type.

A mail merge template cannot have more than one set of instructions per item type.  For example, you cannot create a mail merge template that places data from the same item in two tables in the same document.  

If no formatting instructions are found for a given item type, Microsoft Word will insert a default set of fields that will look like junk in your report. To avoid this scenario, insert TemplateStart/End tags for the Default Template at the end of your mail merge template. You are instructing the software to do nothing when it encounters an unexpected item type.  

Concept 3: Header and footers can only contain a specific set of mail merge tags.    

The only tags that can be used in the header or footer come from item that can only exist once per report.  This includes things like the project, report, or the container (context) that contains the items being exported.  This keeps everything consistent with concept 3.  

For your convenience, a list of header and footer compatible tags are listed above the default fields in the Word Template Field Reference Guide that you can download from Jama Connect®.

Imagine that you initiate the export from the User Needs Document Component shown below.  

The User Needs Document Component in this example is known as the context item. In this example, the Report Context Type would be component (CMP), and the Report Context Name would be "User Needs Document." Since these tags can be used in the header and footer, many customers use the context to store things that they need in the header or footer, like the document number or title.  

Concept 4: Mail merge tags specify data, not style.

The look and feel of a document are not just aesthetic; they also improve readability and offer an opportunity to add branding.  

To change things like the header numbering, page layout, font size, color, etc., you must apply a Microsoft Word Style to the mail merge tag that represents the data you want to format.  Similarly, table styles can be applied to your mail merge template tables.  

Some customers may have noticed that tables or sections run together.  The mail merge tags do not cause this and must be corrected by editing the paragraph spacing in the template. 

Concept 5: Numbering is based on style and context.  

The numbering of items in your template are based on the position of the item relative to the context item.  Let's continue with the User Needs Document example.  Purpose would be 1, Scope would be 2, and so on.  

References

• Microsoft: Customize or Create New Styles
• Microsoft: Format a Table
• Creating Tables in Mail Merge (Office) Templates
• Custom Word Template Easy Start Guide
• Request a Solution Offering or Training from the Success Catalog

Please feel free to leave feedback in the comments below.