Support

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 and click on Export and choose Office Templates
   
   
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)
   
   
3. 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:

1. Navigate back to the Office Templates screen in Jama, and click on Upload a Template.
   
   
2. 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 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.

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 That 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:

1. Headers and footers can be edited, but they will be used throughout the entire document -- you cannot format individual page styling.
   
   
2. There are a few fields shown on the cover page, and these are customizable with the use of the Mail Merge fields shown above the Default Fields section in the User Guide.
   
   Note: these are the only Mail Merge fields that will work for the cover page.
   
   
3. 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.
   1. Note that the Table of Contents will only export 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 That There Are Only Two (2) Templates Here: a 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 does not relate to the order in which the template codes are placed, but rather 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 from 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.
  
  
• 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. 

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

• • 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 custom Word 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 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 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 other text, and that the end tag is in the last cell after all other text.

«TemplateStart:TSTRN»
«TableStart:HEADING»
«documentKey» «name»
«TableEnd:HEADING»
«description»

«TemplateEnd:TSTRN»

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:

«TemplateStart:FLD»
«TableStart:HEADING»
«name»
«TableEnd:HEADING»

«TemplateEnd:FLD»

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:



To learn more about Word templates, visit the Office Templates section of the Jama Connect User Guide.



#tutorial#OfficeTemplates #OfficeExports