Common Issues and Solutions for Office Templates (Mail Merge Exports)

Jakob Khazanovich
Jakob Khazanovich
  • Updated

Author: Jakob Khazanovich

Updated: August 2025

Audience: Everyone

Environmental details: Jama Connect Cloud, CVC (all versions),

Self-hosted (all versions)

Summary

This article addresses common issues and questions to help Jama Connect® users develop, troubleshoot, and optimize exports using Office Templates. It supplements the Custom Word Template Easy Start Guide, which should be reviewed before reading this advanced article.

Office Templates can only be exported to Microsoft Word reports. Office Templates do not apply to MS Excel. See Export to Excel 

Observations, Causes, and Solutions

Initial note

When troubleshooting Office Templates, it is essential to take an iterative approach. We recommend the report author make only a few changes at a time before re-uploading the template and testing the export to observe the impact of the changes.

Observation:

Extra header lines in the document.

Cause:
Fields contain hidden rich text formatting. This is often caused by importing content from Word.
Solution:
Verify that the name field in your items does not contain hidden formatting by deleting and manually reentering the data. If this fixes the issue, do this for all affected items.
Observation:

Unexpected line breaks or missing line breaks

Cause:
Carriage returns in incorrect positions.
Solution:

Open your Office template and turn on the Paragraph button in Word.

If you are missing line breaks in your export, add line breaks by pressing Shift+Enter.

You should then see the line break (soft return) symbol. Add line breaks (Shift + Enter) in all locations where new line breaks are needed between exported content.

 

If you see line breaks where you don't want them in your export, delete the line break arrow symbol from your template to remove them.

Observation:

Missing line breaks

Cause:
Extra line breaks are removed by default when exporting data to improve the published document. However, this might cause consecutive tables to be combined.
Solution:
To restore line breaks to your previous exported results, you can apply a new parameter to the Report Parameter field in the template by following the instructions in the help guide here.
Observation:

The title page, header, and footer text are not changing even though Mail Merge field codes have been entered.

Cause:
Dynamic text for headers, footers, and title pages is limited to the report- and context-relevant fields shown at the beginning of the Default Word Template: Report Name, Report Description, Report Context Type, Report Context Name, Report Run By, Report Run On, Project Name, Project Manager, Organization Name, Report Context Tree Path.
Solution:

Any other dynamic text you would like to be in a header, such as document number, document name, and revision number, must be manually entered after export.

Note: A Velocity report would be able to export dynamic headers. 

Observation:

Boilerplate text is not populating after the Jama-exported content

Cause:
The static text from Jama must precede it. You cannot mix boilerplate content with dynamic content or put static content (like a revision table) at the end of an Office template. 
Solution:

A workaround is to incorporate static text as text items in Jama and have them exported as part of the export.

Note: Velocity reports can mix and match static and dynamic sections of the report.

Observation:

Items are not exporting in the desired order

Cause:
The order of content export into Word is per the content order in Jama, not the order of mail merge codes in the template.
Solution:

The content must be reordered within Jama before exporting. You may be able to reorder content by using a filter as the source of the export.

Note: Velocity reports can export content in specified orders other than how they appear within the Jama explorer tree.

Observation:

Exported content is not changing even though mail merge codes were modified in the template.

Cause:

There are two common causes for this issue:

  1. When copying and pasting field codes from the Default Word Template to the Office template, codes are pasted as plain text rather than mail merge field codes.
  2. Report authors type in the desired field code into the Office template incorrectly.
Solution:
  1. Ensure you paste the codes as mail merge codes rather than plain text. Verify that after pasting, the code highlights in gray when you click on it:
  2. To manually modify a field code, one cannot type the desired text between the <<carrots>>. Instead, the author must right-click on the code and select "Toggle Field Codes." Then, edit the text between the quotation marks to match the desired code
  3. Then right-click on the code again and click "Update Field." This will have successfully updated the field code:
Observation:

I want to use additional logic with Office Templates

Cause:
See below
Solution:

The following resources may assist users attempting advanced Office template use cases. They are not created or managed by Jama. Use at your discretion.

Observation:

My exported tables are all merged together

Cause:
Missing report parameters
Solution:

When exporting data, extra line breaks are removed by default to improve the published document. However, this might cause consecutive tables to be combined. To restore line breaks to your previous exported results, you can apply a new parameter to the Report Parameter field in the template.

Follow the steps in this help article.

Observation:

Default exports from single item view do not have the expected fields

Cause:

The fields included in the default exports (i.e. "Export to Word" or "Export to Excel") from the single item view are determined by the visible fields in the list view of the set for that item.

Solution:

To modify the fields shown in the default Export to Word and Export to Excel exports for a single item:

1. Click on the set that contains that item

2. Toggle to List View

3. From the gear icon, make the desired fields visible.

If you navigate back to the single item and export one of the default options, the previously selected fields from step 3 will be visible.

Observation:

Unable to see the navigation Pane in Microsoft Word

Cause:
Mail merge tags do not have heading styles applied.
Solution:

The navigation pane in Microsoft Word is populated automatically by looking at items that have header styles applied. If the navigation pane is empty or does not show up after exporting an item, make sure that a header style has been applied to the header mail merge tags.

Follow the steps in this guide.

Observation:

Unable to create a table of related items as a section of a table of child items

Cause:
It is not possible to put a table in a table - in this case a table of related items within a table of child items.
Solution:

Depending on the desired output, one can use the default line break parameter setting, which removes line breaks in Office Templates, to essentially collapse separate tables into a single table. This gives the look of a single table even though it is configured in the Office Template as separate table per item.

Tradeoff: Table header is in the SET and FLD configuration, which means the Table header row will show up in every SET and FLD.

To create the exact desired output of a table of related items in a table of child items, use a Velocity report.

More Help

Do you need help configuring your Office template, or do you want to learn more advanced options to overcome its limitations? Customers with Success Programs can request consultations or training in Basic Document Exports using Microsoft Word.

Related Articles

 

Please feel free to leave feedback in the comments below.

 

Related to

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.