Using Conditional Statements in Mail Merge Templates

Author: Romer De Los Santos

Date: October 15th, 2024

Audience: Systems Engineers, Quality Engineers, and anyone else responsible for creating and maintaining mail merge templates for export

Products Applicable: Jama Connect®

Use Case

Creating complex reports that contain more than one item type displayed in different tables with different columns is possible through the use of conditional statements also known as "IF" statements. This article will discuss the possiblities and limitations when using conditional statements in mail merge templates.  

This guide assumes basic knowledge of mail merge templates and Jama Connect®. Refer to Custom Word Template Easy Start Guide for the basics.  I also recommend reading the article, Understanding How Mail Merge (Office) Templates Work, before you continue with this article.  This will give you a good foundation with mail merge to understand how you can implement conditional statements in mail merge templates.  

Toggling Field Codes

Conditional statements in mail merge are hidden in Microsoft Word by default.  In order to view hidden mail merge field codes, you'll need to toggle them by pressing Alt+F9.  Alternatively, you can select the entire document, right click to open the context menu, and then click on "Toggle Field Codes" as shown in the figure below.  

Always toggle the mail merge field codes off before you uploading your mail merge template.  If you don't, the resulting report will not display properly.  

Conditional Statement ("IF" statement)

All mail merge statements are encapsulated within curly braces that must be inserted by pressing CTRL+F9.

The format of the IF statement is as follows:

{ IF [Condition]  "[True]" "[False]" }

Syntax Matters

All mail merge statements are case sensitive. Spaces, double quotes, and curly brackets matter when creating your conditional statement so it's best practice to build your conditional statement a piece at a time to catch any syntax or logic problems.  

The statements within and including the square brackets are to be replaced with text and mail merge tags that specify the condition and what to do when the condition is true or false.    

The most common conditional operators that you will use when exporting from Jama Connect®

will be the equal operator ("=") or the not equal operator ("<>"). Most fields, like picklist fields, will be treated as text.  

Here's a basic example of a conditional statement:

where

the [Condition] is "{ MERGEFILED "setKey" \* MERGEFORMAT }" = "UN"

the [True] is This is set of user needs

and the [False] is This is not a set of user needs

For the [Condition], notice that there are no double quotes around the condition.  However, there are double quotes around the field name ("{ MERGEFILED "setKey" \* MERGEFORMAT }") and set of double quotes around the text that the setKey field is being compared to ("UN").   

Notice that that double quotes appear around the [True] statement and another set of double quotes appear around the [False] statement.  Also notice that there is a single space between all three parts of the conditional statement.  

Syntax errors will lead to unexpected results, no results, or errors.

Context Matters

If you read the article, Understanding How Mail Merge (Office) Templates Work, then you should understand how items are processed by the mail merge template. 

Mail merge tags can be used within the conditional statement provided that the mail merge tags makes sense within the context of the TemplateStart/TemplateEnd tags or TableStart:CHILDREN/TableEnd:CHILDREN tags where the conditional statement resides.   

Let's continue with the example above.  The conditional statement is looking at the setKey field which exists a field of the SET item type.  Therefore the conditional statement must live within the TemplateStart/TemplateEnd tags for a set as shown below.  

You cannot refer to item types or fields that are out of the context of the Set item type.  

Multiple Conditions

In the event you have mutliple conditions, you will have to nest your conditional statements. Nested conditional statements are notoriously difficult to debug and maintain so you are advised to avoid multiple conditions if at all possible.

If it is unavoidable, build your conditional statement one part at a time and being very mindful about syntax.  Below is a general example of nested conditional statements.  Even in this simple example, the tags are not easy to decipher.  

{ IF [Condition1]  "{ IF [Condition2]  "[True2]" "[False2]" }" "{ IF [Condition3]  "[True3]" "[False3]" }" }

Handling Multiple Item Types within a Single Document

Let's look at a complex example just to see what you can do with a conditional statement in Jama. 

Suppose you have a document that contains a set of user needs (UN) and a set of user scenarios (US) as shown below:

As part of this export you want to display a table of user needs and a different table for user scenarios.  We need a conditional statement that specfies what to do when a specific item type is encountered.

Remember, that mail merge templates deal with items one at a time.  It only deals with the present.  As such, there are no tags that specify what is coming next. You cannot write a condition that says "If this folder contains >0 items, do this" because there are no tags associated with the folder item that tells you how many items it contains or what the next item will be.  

Knowing this, the best place to put our conditional statement is in the context of a set because the set item type has a set key field which can be used to identify the type of items within the set.  Remember a set is a container that can contain a single child item type (e.g. user needs or user scenarios), folders, and text items.  In this example, set of user needs would have "UN" as the set key and a set of user scenarions would have a set key of "US". 

Below is the mail merge statements used to create the user needs table.  It basically says when a set that has a set key of "UN", any User Needs encountered with this set are to be placed in this specific table format.  

Use of the TableStart/TableEnd:CHILDREN tags are acceptable because User Needs exist within the context of the set.  Refer to the Creating Tables in Mail Merge (Office) Templates for more information on how to create Mail merge tables.  

As mentioned before, you can nest conditional statements within each other. While this type of nesting of statements is allowed, you are strongly encouraged to avoid it whenever possible because it increases the difficulty in debuging your mail merge template. Take a look at the example below of a nested conditional statement.  

Figuring out if you used the appropriate number of double quotes and curly braces will quickly become a nightmare the more nested conditional statements you add.  

Instead of nesting conditional statements, create separate conditional statements. A second conditional statement handles user scenario items as follows:

The empty double quotes for the false statement means do nothing.  By avoiding nesting conditional statements, you can see that the instructions are easier to read and debug.  

Summary

Bear the following in mind when using conditional statements in your mail merge template:

• It is best practice to build your conditional statement a piece at a time to make sure you didn't make any logic or syntax errors. 
• It is best practice to avoid overly complex conditional statements such as nested conditional statements to make it easier to debug your mail merge template.
• A conditional statement can provide alternate formatting instructions for an item based on various conditions, but it cannot be used to format an item more than once.  For example, you cannot display a user need in one section of the document and then have it appear in a summary table at the end of the document.
• The mail merge tags used as part of your conditional statement must make sense within the context of where the conditional statement resides.  
• Toggle mail merge field codes off before uploading your mail merge template to Jama Connect®.
• Finally, consider using a Velocity template when you require a report that needs to have complex logic, pulls information more than 1 level above or below your source item, or if you need to generate an Excel file.  

References

• Custom Word Template Easy Start Guide
• Understanding How Mail Merge (Office) Templates Work
• Creating Tables in Mail Merge (Office) Templates 

Please feel free to leave feedback in the comments below.