Custom Word Template Easy Start Guide

Amanda Jennewein
Amanda Jennewein
  • Updated

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:

1. Within Jama, navigate to a component or set in the Explorer Tree, click on Export, and choose Office Templates.

1.png

2. 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). 

2.png

3. Save the file to a name other than the boilerplate, such as 'Customer 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. To have a clean template that exports exactly what you are adding, save it as a new template rather than replace 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:

1. You can navigate to the Office Templates screen in Jama and click Upload a Template.

3.png

2. Now, click on Generate Work Template Reference Guide and save the generated document (note: the guide will reflect only the item types enabled for the current project).

4.png

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; 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. 

  • What you see is not exactly what you get. Mail Merge fields contain hidden data; to show the actual value of a mail merge field, right-click on the field and choose Toggle Field Codes.

5.png

    • The fields will change to look something like this:

6.png

      • 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, you keep source formatting, ensuring that the Mail Merge code is maintained.
  • The identifiers for each item type you see relate directly to the Fields code from the Item Type configuration screen within the Jama Administration panel. These must be reproduced exactly as displayed (e.g., «TemplateStart: REQ»). 
 
  •  

7.png

  • The individual field codes similarly relate 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.).

8.png

  • Mail Mere is an introductory coding, meaning 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 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 both can contain fields between their start and end tags. 

9.png

Now, Let's open the Default Export Template we downloaded before -- This will show you the mail Merge code used for the default export.

As you can see, this is pretty basic, but there are several things to take note of:

1. Headers and footers can be edited, but they will be used throughout the entire document -- you cannot format individual page styling.

2. A few fields are shown on the cover page, which are customizable using the Mail Merge fields above the Default Fields section in the User Guide.

Note: These are the only Mail Merge fields that will work for the cover page.

10.png

3. The Table of Contents is a TOC field type, which you can see by toggling the field codes. If you edit, you can set the formatting.

11.png

1. Note that the Table of Contents will only expire three (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"). 

2. Another thing to note is that if the Table of Contents is longer than one (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 there are only two (2) templates: a default template and a folder template. Here are some essential notes about templates:

  • 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. 

12.png

  • You can export from a ListView or a Reading View.
    • As long as the ListView 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. 
  • The default styling for Rich Text in Word Exports is Times New Roman and cannot be changed before export or in the template itself.
    • You can, however, edit the styling after the fact by adjusting the 'Normal' style.

13.png

  • The DEFAULTTEMPLATE must be in all Word templates; it will show information for the 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. For example:

14.png

    • This can be adjusted by item type so that you can have different fields and headings for each type you wish to display in this report.
  • Different templates can include different tables and, therefore, can have different fields exported, which will be shown in the Reference Guide. 

When you create a customer Word template with Mail Merge, it will export accordingly 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 in which you put the Mail Merge page 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 the 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.

15.png

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:

16.png

Reminder: The font used by the export is Times New Roman

Formatting 

When building your custom Word template, there can be situations when 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:


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

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.