Creating Tables in Mail Merge (Office) Templates

Author: Romer De Los Santos

Updated: 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

Provide best practices and techniques for organizing documents and creating tables in mail merge templates (also known as Word or Office templates) in Jama Connect®. 

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

Organizing Data for Export

How you organized your data in Jama affects how your export will work.  Consider the following best practices.  

• It is best practice to organize your items into folders to help you navigate through them in Jama, but it also allows for the creation of separate tables by folder.  
• If your document contains only one set of items (e.g., User Needs), you can use a Set item type to contain everything that represents your document, as shown below.    

• However, if you need a document to contain one or more different sets of Jama items, use a component as the container for your document.   

Implementation 1: Creating Tables Containing Multiple Items of a Single Item Type

The most common type of table is a table that contains a single type of item like the one shown below.  

If you want to generate a table that contains multiple items of the same type, use the TableStart/TableEnd:CHILDREN tags to define a row of data in your table.

Below is an example of mail merge tags used to generate the User Needs table above. 

The look and feel of a table is based on the table style applied in the mail merge template in Microsoft Word.  

Notice how "UN" (User Need) is used to designate the item type to display.  You can use any UN field within the TableStart/TableEnd:CHILDREN tags.

The image below shows how the data is organized within Jama.  Notice that the user needs must be children of a folder item.  In order to use TableStart/TableEnd:CHILDREN tags, the item type must live within the parent container.  In this case it is a folder but it can also be a set or component.    

Things to Keep in Mind

Unfortunately, table tags within table tags will not work in Mail Merge templates.  Since upstream and downstream item are accessed through table tags, you will not be able to include related items if you are using TableStart/TableEnd:CHILDREN tags.  

Implementation 2: Creating Tables with Relationships

A mail merge template is able to pull relationships one level above and below the source item.  Upstream items are retrieved using TableStart/TableEnd:UPSTREAMRELATIONSHIPS.  Downstream items are retrieved using TableStart/TableEnd:RELATIONSHIPS.  

To get around the problem where table tags are not allowed within table tags, this example uses the TemplateStart/TemplateEnd tags to define a single row as its own table.  Since these individual tables are generated right after each other, they get "stitched" together to form a complete multi-item table with a trace.  

This is an example of the kind of table we want to generate:

The mail merge tags used to generate the output are below:

Notice that the table header is defined before the TemplateStart:UN tag.  If the header appeared after the tag, it would be repeated with each UN encountered during the export.  However, because of this, the header will be printed even if there are no user needs under the folder.  

Implementation 3: Creating Complex Single Item Tables

Since TemplateStart/TemplateEnd tags can be used to create an individual table per item, it is possible to create complex tables.  Below is the output from a mail merge template for a verification test protocol.  

The snippet below shows the mail merge tags used to generate this table.  

References

• Custom Word Template Easy Start Guide
• Common Problems and Solutions for Office Templates
• Understanding How Mail Merge (Office) Templates Work

Please feel free to leave feedback in the comments below.