Custom Word Template Easy Start Guide

By Jama posted 01-29-2015 01:54

  

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

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


     
  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. 
     
    • 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:
                          «TemplateStart:DEFAULTTEMPLATE»«TemplateEnd:DEFAULTTEMPLATE»

    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="" br="">«TableStart:HEADING»                            <----signifies that="" everything="" inside="" of="" this="" table="" will="" be="" a="" heading="" br="">«documentKey» «name»                          <----adds a="" unique="" id="" and="" short="" name="" of="" each="" item="" to="" the="" heading="" br="">«TableEnd:HEADING»                              <----closes the="" heading="" br="">«description»                                          <----adds the="" description="" br="">«TemplateEnd:DEFAULTTEMPLATE»         <----closes the="" template="" br="">


 
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.

For example, Sets can have the following tables:
Heading
Synchronized Items
Comments
Versions

Whereas Test Runs can have the following:
Heading
Upstream Relationships
Relationships (downstream)
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)

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

«TemplateEnd:TSTRN»

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:

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







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:

User Guide

28 comments
1417 views

Permalink

Tags

  • Jama features and functionality
  • Office Templates
  • Content Type
  • tutorial

Comments

10-11-2016 17:25

I cannot think of a possible way for Test Runs to have a heading, given they don't live in the Explorer Tree. Both the List View UI and the Admin Configure View options imply that it is possible, but it's not. I think we might need to consider this all a bug.

10-11-2016 17:20

The in ability to export with a font other than Arial has been fixed in Jama 8.7.

10-11-2016 12:30

How can a TESTRUN have a heading?

This refers to the following section:

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

«TemplateEnd:TSTRN»

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.

I created a filter with testruns, added a heading column, column stays empty.

10-11-2016 11:54

Hello, the "Office Templates" are really great. - but because of our CI we need a different font, we cannot use "Times New Roman". - is there any way to change this or will this be changeable in a future version?

06-17-2016 19:31

Depending on the version of Jama you're using, being a user with "create" rights vs "Manage project" vs "admin" rights will make a different difference in if you can upload the template or not. But I'm glad to hear the admin is taking care of it for you.

After you experiment a little more, let me know what particular questions you have about the code vs. the output you are receiving. Word Templates are very tricky when you're first starting to use them!

06-17-2016 18:01

1. First question I have to ask is, where did you get the mail merge code? Did you copy-and-paste these values from the Word Template Reference Guide generated from your own instance? The error makes it seem like one of the values doesn't exist.
Karnala: copied from Word Template Reference Guide generated
2. Another thing to note is that all TemplateStart tags need corresponding TemplateEnd tags, so you'll need to add those.

Karnala: I'll check and let you after.

Hi,

I have added my comments above. A quick update, I did not have admin access may be that causing the error. I asked my admin to upload, and after that I've seen it is not exporting what it suppose to be this means that I'm able to see my merge codes and all content of the other items. As I told you I've less expertise in code.

I'll try to do some more experiments :).

-Karnala

06-16-2016 20:40

It's hard to diagnose that error. (It isn't unique to exports.)
1. First question I have to ask is, where did you get the mail merge code? Did you copy-and-paste these values from the Word Template Reference Guide generated from your own instance? The error makes it seem like one of the values doesn't exist.
2. Another thing to note is that all TemplateStart tags need corresponding TemplateEnd tags, so you'll need to add those.

06-16-2016 18:05

Hello, I'm trying to create sample template. I've added following code(I'm very new to this and very experimental).
Unable to get property 'getValue' of undefined or null reference

###########################################################
 «TemplateStart:RequirementsTemplateSample»

«TableStart:HEADING»

«documentKey» «name»

«TableEnd:HEADING»

«description»

 

«TemplateStart:FRS»

«TableStart:HEADING»

«documentKey» «name»

«TableEnd:HEADING»

«Description»

###########################################################


I told you its very basic and quiet experimental. After that I tried export JAMA then got a warning message "Unable to get property 'getValue' of undefined or null reference"


Can anyone suggest me what kind of error it is? how can I solve this? whether Am I doing any mistake?


thanks in advance.


-Karnala


06-22-2015 21:07

swoo:  Oh the version number is a defect and should say 2014.2?  Now that's funny. 

Kristina: splitting hairs now I guess but I was able to run and upload a template, but not save an uploaded template with "manage project" permissions.  However after I upgraded my perms to organizational administrator I was able to save a new template for our project.   

06-22-2015 20:53

Hi Susan! It sounds like you were running into SOS-BUG-636, which is a bug where users with "Manage Project" permissions can't run the custom Word templates. In theory all users should be able to run the templates, but only "Manage Project" users should be able to save them.

@Swoo thanks for offering to help. I know what you mean about exporting to Word ;)

06-22-2015 20:06

Susan, I forgot about that visual defect. Jama meant to use 2014.2 but someone made a typo. Lol. Glad you are special. If your organization is ready to feel even more special you might consider upgrading to 2015.1. Be aware a number of changes to the UI as several postings have mentioned. Let me know if you have more questions about Word templates management. I have a deep affection--sympathy even--for those Jama users who have to export to Word. Have a great day. :-) Swoo

06-22-2015 19:59

Sorry to hurt your feelings swoo, but my login screen tells me that I have 2015.2 with build date of 2014/11/20 per below so now I feel quite special ;).  But also, i did have the save button enabled and when tried to save it got the error that i sited in my original post.  Since then I have had my perms modified so I'm able to work with the template now.  Still having a few difficulties, but for the most part, I'm getting some good results. 

Thanks for all your help, much appreciated.

Susan :) 

06-22-2015 18:48

Hi Susan,

(Joking start--you must be a super special client of Jama--because as far as I know 2015.2 does not exist either externally hosted or on-premises. 2015.1 is currently deployed. 2015.2 is assume to be the Fall release. My feelings are very hurt because I don't have access to 2015.2. Joking stop :-)

You might consider confirming your version of Jama by looking at the built-date. For example, the hosted version is  
Build date: 2015/06/13 06:11

You do need to be a project admin to save a Word export template. The easiest way to tell is whether "Save Report" icon is visible to you.

I'm sure that @Kristina can help you more directly. Good luck.

By the way, the template file format/extension can be .doc/.docx and .docm (if VBA macros are embedded.) I forgot to mention about the .docx in my earlier reply. Have a good day.

swoo

06-22-2015 18:14

Hi Kristina,  The version is 2015.2 and I have the 'manage project', 'project create/edit', 'project read', 'reuse administrator', and 'review center administrator' permissions.    Do I also need Administrator permission to add a project template? 

06-18-2015 23:37

Hi Susan! Thanks for joining the conversation. Swoo is correct that the uploaded templates need to be .doc. I wanted to answer your other questions.

First, the template tags need to toggle—that's why suggest copying directly off of the Word Template Reference Guide. The mail merge codes need to stay intact.
Second, you wouldn't see that error if your template tags are incorrect; the template would just produce an unexpected output. The error you are seeing usually correlates to a permissions issue. To get to the bottom of this, I have two questions -Do you know what permissions you have to the project that you are uploading this template to? (e.g. read, write, Manage Project) and -What version of Jama are you using? (It's on the login page.)

06-18-2015 20:07

Hi Susan, The template file is doc. Docm if embedded with VBA macro. Good luck. Welcome to the community. Swoo

06-18-2015 20:00

These instructions were very helpful but I have a couple of questions after following the instructions.  
-> When I download a template it is automatically downloading it as a .doc type file, i saved it as a .dot type file and was able to edit, save and toggle the tags.  What file type should this template be?  .dot or .doc.  
-> Should the template tags also toggle?  In my document they are text tags, but I can modify them to toggle tags if needed.  
-> I am seeing an error when I press the 'Save Report' button after selecting my file to upload.  I wonder if it is because the template tags are text (ie:  TemplateStart:DefaultTemplate, etc).  This is the error:   batch.postHooks[i] is not a function.  

04-30-2015 13:17

Thank you for your input, Kristina. It looks like our IT division has already sent the error up to our Jama troubleshooting liason. And my bad - the error was "2fb is undefined"...

04-29-2015 22:50

Darcie, given there is an error occurring, I think the best course of action is to submit a ticket to Support (https://support.jamasoftware.com) with the details in your post. It will be much easier to coordinate as we may need to see log files.

04-29-2015 22:23

Well, Matt is separate from me, but we have groups of "users" and "project admins" that give us separate permissions. As an "admin", I do see that I do have the ability to add permissions under the "configure project" button. We tested the "manage project" permission theory, hoping that would help us work around specific permission issues (i.e. uploading templates for reporting), but it didn't work. They have the "upload template" button, are able to upload the template, and click "Run", but the action errors out (Error: 2fg).

04-29-2015 21:03

If a user has Manage Project permissions they should have the option to upload and save the template, so I don't have an idea why they don't have the options.
In terms of Crowd, that is an interesting consideration. Let's take Matt as an example. In Jama, does his user have Manage Project permissions to this project, or does he belong to a group (managed in Crowd) that has been given Manage Project permissions?

04-29-2015 19:44

We have those that have this permission, but they still don't have this option. Any idea why that would be?They have the "upload template" button, and the "Run" button, but no joy. Could that permission be overruled by Crowd permissions?

04-29-2015 17:35

Matt, sorry for the confusion. The ability to save a report depends on the level of permissions you have. You need to have "Manage Project" permissions to Save a template for use later or by others.

04-29-2015 15:46

When I try to upload a template I can choose the file but can't see the fields that require "Report Name" and "Report Description" or who to share the template with. There is no "Save Report" Option Either. I can get the export to work but it won't save the template I created for future use. 

03-27-2015 21:41

I had an issue with default export template which doesn't export expected result part of test cases. This information will definitely help me in experimenting different layouts. All I need is just little time to play with it. Thanks for sharing. :)

02-04-2015 19:47

I think I mentioned somewhere along the line that for test cases, I'd like to tinker with a "landscape" template, and use a table for the steps.  From a quick glance at the generated Guide, it looks like everything we'd need is there.  Just need to find a few hours to tinker!   :-)

02-04-2015 19:21

Thanks for the positive feedback, Bob! You're right in that there is some overlap with the help, and you'll probably end up stumbling across other instances of that ;) When we set out to improve support documentation we thought all-in-one guides would be the most helpful, particularly to people new to a certain task or new to Jama. I'm glad this was of help.

02-04-2015 18:56

This looks great!  I only read the first part carefully as a colleague asked this morning, if there was a list of all the tags (Mail Merge fields) and was particularly concerned about our customizations.   The "Generate Word Template Reference Guide" is exactly what he was looking for.

Although I see some overlap with the help, I referred him to this page as it covers the topic nicely in a single page.

Thanks!
Bob