Common Problems and Solutions for Office Template (Mail Merge Exports).

Jakob
Jakob
  • Updated

Author: Jakob Khazanovich

Updated: October 2024

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.

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.