Follow these easy steps and it will get you on the road to creating your own Creating Word Templates quickly.
To begin, download a copy of the Default Word Template:
- Within Jama, navigate to a component or set in the explorer tree and click on Export and choose Office Templates
- Right Click on Export to Word Default and choose Download Template
(Alternatively, you can select the report and choose Download Template from the top right)
- Save the file to a name other than boilerplate, such as 'Custom Template' or 'Requirements Template'; this will be your template starter.
- 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. In order to have a clean template that exports exactly what you are adding in, it is advisable to save it as a new template rather than replacing the Export to Word Default.
Now that we have a template to work with, we need to get the reference guide to get the Mail Merge fields as they relate 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 generated guide will reflect only the item types that are enabled for the current project)
Let's open the Word Template reference guide and take a look at what it contains:
Jama exports to Word using Mail Merge fields. You can think of Mail Merge fields as some 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 not exactly what you get. Mail Merge fields contain data that is hidden from view; 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:
- The reason this matters is that if you merely change the wording as you see it without toggling the field code, the code behind will still remain the same.
- After editing the field, just click Update Field and it will save the new field code you've entered.
- Tip: Make sure when copying from the reference guide to a new document that you keep source formatting. This will ensure that the Mail Merge code is kept.
- The identifiers for each item type that you see relate directly to the Field codes that you see from the Item Type configuration screen within the Jama Administration panel. It is important these are reproduced exactly as displayed there. (e.g. «TemplateStart:REQ»)
- The individual field codes similarly relate to the field identifiers in the item type configuration as they are the values that are actually stored on the database. (e.g. «documentKey» «name» «description» etc.)
- Mail Merge is a basic coding, which means that every object must start and end. Therefore with each field you can see a start and an end, and with each table and template you can see a start and an end.
«TemplateStart» tables and fields within «TemplateEnd»
- Additionally, templates are required in order to add tables, and you can have multiple tables contained within each template (such as shown below with the Table:HEADING, within the Template:DEFAULTTEMPLATE). Tables and templates both can contain fields between their start and end tags.
Now let's open the Default export template we downloaded before; this will show you the Mail Merge code that is used for the default export:
As you can see this is pretty basic, but there are several things to take note of:
- Headers and footers can be edited but they will be used throughout the entire document, you cannot format individual page styling.
- There are a few fields shown on the cover page, these are customizable with the use of the Mail Merge fields shown above the Default Fields section in the user guide. These are the only Mail Merge fields that will work for the cover page.
- The table of contents is a TOC field type, which you can see by toggling the field codes; if you edit it, you can set the formatting.
- Note that the Table of contents will only export 3 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 thing to note is that if the table of contents is longer than 1 page, it may incorrectly judge the page numbers and they will need to be manually adjusted (this is a known bug with Word)
Template Fields: You can see that there are only two Templates here, Default Template and a Folder Template; here are some important notes about templates:
It is important to note that the order in which items are exported do not relate to the order in which the template codes are placed, but by the order in which they are shown within Jama. For this reason, you can place the templates themselves in any order to include the item types that you wish to see.
- You can export from a list view or a reading view. As long as the list view displays the necessary items, they will be exported.
- Items are exported by Heading, and will not change order based on how you sort them in your view on Jama.
- Note: The default styling for Rich Text in Word Exports is Times New Roman and cannot be changed before exporting or in the template. 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:
Within the template you can add multiple tables or individual fields from the reference guide in order to get a desired output. For example:
«TemplateStart:DEFAULTTEMPLATE» allows for the item types to be exported
«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» closes the heading
«description» adds the description
«TemplateEnd:DEFAULTTEMPLATE» closes the template
This can be adjusted by item type, so that you can have different fields and headings for each item type that you wish to display in this report.
Different templates have the ability to include different tables, and therefore can have different fields exported, which will be shown in the reference guide.
When you create a customer World template with mail merge, it will export according to the order of the Heading (it will not update to a custom order.) You can specify what item types you want displayed, but it will not export according to the order you put the mail merge tags in the template.
For example, Sets can have the following tables:
Whereas Test Runs can have the following:
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)
This template tells Jama to export all test runs with a heading containing name and ID, a description, and all test steps contained in a table. The main thing to be aware of here is that the start tag is in the first cell before any text and the end tag is in the last cell after all other text.
Finally, If you would like to organize your data by folder hierarchy, then you can 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.
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
To insert line breaks between values, use SHIFT+ENTER so your template looks like this:
Your export will then have separated values, as desired:
For more complex formatting, there are some limitations with Word. For these and more details on report formatting, be sure to visit Introduction to Advanced Reporting.
Here are some more places where you can learn more about Word Templates: