Updated: July 2024
Audience: Everyone
Products Applicable: Jama Connect®
Use Case
Custom Word Template Easy Start Guide
Follow these easy steps, and it will get you on the road to creating your own Creating Word Templates quickly.
Best Practice
To Begin, Download a Copy Of the Default Word Template:
- Within Jama, navigate to a component or set it in the Explorer Tree, click on Export, and choose Office Templates.
- Right-click on Export to Word Default and choose Download Template (you can also select the report and choose Download Template from the top right).
- Save the file to a name other than boilerplate, such as Customer Template" or "Requirements Template" -- this will be your template started.
NOTE: This file is the base file for the default 'Export to Word' functionality, but we have some additional code on the default 'Export to Word' button that adds more output to the file. To have a clean template that exports precisely what you are adding, it is best to save it as a new template rather than replacing the Export to Word Default.
Implementation
Now that we have a template, we must acquire the reference guide to get the mail merge fields related to our project.
- Navigate back to the Office Templates screen in Jama and click on Upload a Template.
- Now, click on Generate Word Template Reference Guide and save the generated document (note: the guide will reflect only the item types enabled for the current project).
Let's open the Word Template Reference Guide at this point and take a look at what it contains.
Jama exports to Word using Mail Merge fields, which are basically basic code that tells Jama what to look for in the database when writing data into the Word document.
There are a few basic elements to keep in mind when using Mail Merge Fields:
- What you see is different from what you get. Mail Merge fields contain hidden data; to show the true value of a mail merge field, right-click on the field and choose Toggle Field Codes.
-
- The field will change to look something like this:
-
-
- This matters because if you merely change the wording as you see it without toggling the field code, the code behind it will remain the same.
- After editing the field, click Update Field, and it will save the new field code you've entered.
- Tip: When copying from the Reference Guide to a new document, keep the source formatting and ensure the Mail Merge code is maintained.
-
- The identifiers for each item type you see relate directly to the Field codes from the Item Type configuration screen within the Jama Administration panel. These must be reproduced exactly as displayed there. (e.g. «TemplateStart: REQ»)
- The individual field codes relate similarly to the field identifiers in the item type configuration as they are the values that are stored on the database (e.g., «documentKey,» «name,» «description,» etc.).
- Mail Merge is basic coding, meaning every object must have a start and an end. Therefore, you can see a beginning and an end for each field, and for each table and template, you can see a start and an end.
«TemplateStart» tables and fields within «TemplateEnd»
-
- Additionally, templates are required to add tables, and you can have multiple tables within each template (such as shown below with the Table:HEADING, within the Template:DEFAULTTEMPLATE). Tables and templates can both contain fields between their start and end tags.
Now, let's open the default export template we downloaded before. This will display the mail merge code used for the default export.
As you can observe, this is pretty basic, but there are several essential points to consider
- Page-specific formatting cannot be applied to individual pages. Headers and footers can be edited but will be used throughout the entire document.
- You can customize a few fields on the cover page using the Mail Merge fields shown above the Default Fields section in the User Guide. This empowers you to create a cover page that suits your specific needs. These are also the only custom fields that can be used in header or footer.
Note: these are the only Mail Merge fields that will work for the cover page, header, or footer.
-
The Table of Contents is a TOC field type. You can view the field codes to customize the formatting.
- Note that the Table of Contents will only export three levels deep. After that, all items will be added to the same level. To change the level of the headings, you can adjust the "1-2" to "1-3".
-
Another important point to remember is that if the Table of Contents extends beyond one (1) page, Word may incorrectly calculate the page numbers. In such instances, it's crucial to manually adjust the page numbers due to a known bug with Word.
Template Fields: Only two (2) templates are available: a default template and a folder template. Here are some essential notes about templates.
-
It is important to note that the order in which items are exported does not relate to the order in which the template codes are placed but rather to the order in which they are shown within Jama.
- For this reason, you can place the templates in any order to include the item types you wish to see.
-
You can export from a ListView or a Reading View.
-
The ListView will export the required items as long as they are displayed.
-
- Items are exported by heading and will not change order based on how you sort them in your view on Jama.
-
Remember that the default styling for Rich Text in Word Exports is Times New Roman and cannot be altered before export or in the template itself.
-
You can, however, edit the styling after the fact by adjusting the 'Normal' style.
-
-
The DEFAULTTEMPLATE must be in all Word templates; it will show information for all item types.
- If you wish to include only specific item types, leave the template start and end tags on their own, as shown:
«TemplateStart:DEFAULTTEMPLATE»«TemplateEnd:DEFAULTTEMPLATE»
- You can add multiple tables or individual fields from the Reference Guide to get the desired output within the template.
«TemplateStart:DEFAULTTEMPLATE» -- Enables the export of item types.
«TableStart:HEADING» -- Signifies that everything in the table will be a heading
«documentKey» -- Adds the unique ID of the item
«name» -- Adds the name of the item
«TableEnd:HEADING» -- Loses the heading
«description» -- Adds the description
«TemplateEnd:DEFAULTTEMPLATE» -- Closes the template
-
- This report allows for customization by item type, enabling the display of different fields and headings for each type.
- The Reference Guide shows that different templates can include different tables and export different fields.
When you create a custom Word template with Mail Merge, you have full control over the export order. It will export according to the heading's order, not updating to a custom order. You can specify what item types you want displayed, but it will not export according to the order in which you put the Mail Merge tags into the template.
For example,
-
Sets can have the following tables:
- Heading
- Synchronized Items
- Comments
- Versions
Whereas
-
Test Runs can have the following:
- Heading
- Upstream Relationships
- Downstream Relationships
- Comments
- Steps
- Versions
You can also add the fields to cells in an informational table.
*Remember that you cannot copy from here -- copy from the Reference Guide, and use Keep Source Formatting*
The following template tells Jama to export all test runs with a heading containing a name and ID, a description, and all test steps in a table. The main thing to be aware of here is that the start tag is in the first cell before any other text and that the end tag is in the last cell after all other text.
Finally, If you would like to organize your data by folder hierarchy, use the CHILDREN tag. This is useful for the FLD template and specifically for organizing your items in tables. Here is an example of this:
Reminder: the font used by the export is Times New Roman.
Formatting
When building your custom Word template, there can be situations where you will want to insert a line break between field values for viewing purposes. You may have noticed that inserting a simple carriage return will not produce this line break. Here are some examples depicting the action and result:
Simple Carriage Return
Result:
To insert line breaks between values, use SHIFT+ENTER so your template looks like this:
Your export will then have separated values, as desired:
References
- To learn more about Word templates, visit the Office Templates section of the Jama Connect® User Guide.
Please feel free to leave feedback in the comments below.
Related to
Comments
0 comments
Please sign in to leave a comment.