Creating Microsoft Word export templates

To create an export template, you can use a sample template as a starting point or create a new template from scratch.

Modifying a sample template

You may find it easiest to start with a sample template and modify it to contain the information and formatting you want to use. See Sample Microsoft Word export templates for a list of templates you can download to get started.

To decide if a sample template is a good starting point for your template, download it, add it to Helix ALM, and preview it using items in your project. See Previewing Microsoft Word exports. Next, modify it to include the item information and formatting you want to use. For example, you can change the layout, fonts, colors, and more. You can also add a company logo or other images.

Creating a new template

To create a new export template, start with a new Word document or an existing document, such as one that adheres to your company’s style guide.

Note:  Templates must be saved as .docx or .docm files.

If you have never created a template, add tags first and make sure the correct information is exported before working on the formatting. The following steps explain the easiest way to create a new template.

1. Open the field code reference installed with Helix ALM. Click View template field codes in the Configure Word Export Templates dialog box. A list of all field codes in the project is generated.

2. Find the section that contains the field codes for the item type you want to add to the template.

3. Copy and paste the syntax snippet for the item type into the template.

4. Replace the placeholder tags by copying and pasting the field codes for the field values you want to export.

5. Add the template to Helix ALM. Correct any errors.

6. Preview an export with the template.

7. Add any static text and images, and apply any formatting. You can use any Word formatting features, such as styles and tables.

If you are working with an existing document, replace static text you want to replace with exported data with field tags and try to preserve the original formatting.

As you become more familiar with creating templates, you will likely add tags and apply formatting at the same time.

The following example shows a simple template that exports the Summary field value from all selected issues. It tells Helix ALM 'for each issue in the selected list of issues, export the Summary field'.

With issues #1-5 selected, the resulting document contains the following text and formatting.

The foreach tags (first and last lines) that tell Helix ALM what to export are removed. The field tag (middle line) is replaced with the Summary field value. The static 'Summary:' text outside of the field tag remains. This repeats for each selected issue. The formatting set in the template on the static text and field code are applied.

The following sections explain the parts of a template in more detail.

foreach tags

Foreach tags indicate the start and end of a section where exported data is added. During an export, Helix ALM repeats all lines between the starting and ending foreach tags for each selected item.

Use the following syntax for a foreach loop.

<<foreach [in ##_LIST]>>

(Field tags or nested foreach tags here)

<</foreach>>

List codes

The [in ##_LIST] parameter in the starting foreach tag contains a list code, which tells Helix ALM the item type to export. For example, the list code for issues is IS_LIST. The list code provides the context for all other tags inside the foreach loop. Helix ALM uses this list code to determine which templates are valid when exporting. For example, if you are exporting from the Issues list, only templates with IS_LIST as the list code in the top-level foreach loop are available to use.

List codes start with one of the following identifiers to indicate the item type. Field codes also start with these identifiers.

Item type	Context identifier
Folders	FD_
Issues	IS_
Requirement documents	RD_
Requirements	RQ_
Test cases	TC_
Test runs	TR_

Nested foreach loops

A foreach loop can contain nested foreach loops. These let you use another list code to define a different context and drill down into an item to export specific fields. For example, in a foreach loop for issues, you can use a nested foreach loop to export fields from workflow events associated with each issue. The following example exports the workflow event name from all selected issues.

<<foreach [in IS_LIST]>>

<<[IS_WORKFLOW_EVENT_NAME]>>

<</foreach>>

Remember that the top-level foreach loop defines the context for everything in the loop. If you need to export a field that belongs to a different context, you need to use a separate foreach loop.

Note:  A foreach loop can also include nested conditional statements to perform advanced actions. For example, you can use an if statement to format exported information differently based on the field value. See Using advanced logic in Microsoft Word templates.

Field tags

A field tag contains a field code, which represents a specific field in an item. During an export, field codes are replaced with a specific field value from a selected item. For example, the field code for the issue Summary field is IS_SUMM.

Field tags must be inside a foreach loop and in the same context as the list code. For example, you cannot use requirement field codes starting with RQ_ if the list code is for issues (IS_LIST). Requirement field codes are only valid in the context of a requirements list (RQ_LIST).

The following example shows a field tag for the issue Summary field in a foreach loop.

<<foreach [in IS_LIST]>>

<<[IS_SUMM]>>

<</foreach>>

To view a list of all field codes for the project, click View template field codes in the Configure Word Export Templates dialog box. You can easily copy and paste field codes from this page. The required context list code is also displayed to help you use field codes inside the correct foreach loop.

Note:  If you want to format the exported field value, apply any Word formatting to the field code. You can change the font, size, color, etc.

Syntax rules

• All tags must start with << and end with >>. Any text outside of a tag is static text that is always exported to the resulting document. This includes paragraph marks. To exclude extra paragraph marks, set the properties of the character as hidden in the template. See the Word help for information.
• A starting foreach tag must contain a list code. The list code must be enclosed in square brackets and follow 'in'. For example, <<foreach [in IS_LIST]>>. The list code must be in all capital letters. The 'foreach' and 'in' must be lowercase.
• Each starting foreach tag must also close with ending tag: <</foreach>>.
• Field codes must be enclosed in angle and square brackets. They must be in all capital letters. For example, <<[IS_SUMM]>>.

You can use any Word formatting features in a template. Any formatting applied to static text and field codes is exported to the resulting document. For example, you may want to add field labels to identify values. Field labels and values can have different formatting.

If exported images are not displayed correctly or at the resolution you expect, see Troubleshooting Microsoft Word export image issues.

You can add any static text and images to templates. Text and images can be inside or outside a foreach loop. Any formatting applied to text or images is exported to the resulting document.

Following are some tips to help you successfully create export templates.

Copy and paste tags and field codes

To easily create a template and avoid any errors, copy tags and field codes from the reference installed with Helix ALM. This page includes syntax snippets for all item types and all field codes in the project.

To open the reference, click View template field codes in the Configure Word Export Templates dialog box.

Display paragraph marks

Display paragraph marks when working in Word so you can add tags in the correct locations. To show paragraph marks, click the Show/Hide button on the Word toolbar.

Use hidden text for foreach tags and comments

When you are working on a template, the tags can make it difficult to see how the resulting document will look. You can upload and preview the template in Helix ALM to test it, but if you want to see how the resulting document will look as you work in Word, you can use Word's hidden text on tags and other text not displayed in the resulting document. You can toggle to show or hide hidden text to preview the text and field codes without the tags.

The easiest way to use hidden text is to create a Word style with the Hidden effect selected in the font properties. You may want to also make this style gray or another color that helps differentiate it from other text in the template. Apply this style to all foreach tags or other statements in the template. Do not apply it to field tags. You can also add comments in the document body, such as instructions, and apply this style so they are not included in the exported document.

Tip:  You may also need to apply hidden text to any extra paragraph marks in the template that add extra lines in the resulting document.

Hidden text has a dotted line under it. To hide all hidden text in the template, click the Show/Hide button on the Word toolbar.

Use Word styles

If you are familiar with Word styles, we recommend using them in export templates. This ensures consistent formatting in the document and makes it easier to apply global formatting changes. If you use a sample template, you can modify any of the styles to change the text properties, such as font, color, size, and spacing.

Working with tables

When adding tags in tables, make sure the foreach loop starts inside the table or the resulting document will contain a table for each exported item.

A foreach loop must start either in the first column of a row or in the same cell as a field tag. They must close in the same cell as a field tag or last column in the row.

The following examples show valid placement of tags in tables.

Simple foreach loop example

<<foreach [in IS_LIST]>>

<<[field_code]>>

<</foreach>>

Nested foreach loop example

<<foreach [in IS_LIST]>>
<<foreach [in IS_REPORTED_BY_LIST]>>
	<<[field_code]>>	<</foreach>>
		<</foreach>>

Conditional statement examples

Follow the same rules when using conditional statements inside foreach loops.

<<foreach [in IS_LIST]>>
<<if [condition]>>	<<[field_code]>>
<<elseif [condition]>>	<<[field_code]>>
<<else>>	<<[field_code]>>	<</if>>
		<</foreach>>

 

<<foreach [in IS_LIST]>>
	<<if [condition]>> <<[field_code]>> <<elseif [condition]>> <<[field_code]>> <<else>> <<[field_code]>> <</if>>
		<</foreach>>

Keep the following limitations in mind when creating Word templates.

• You cannot insert page or section breaks in foreach loops. To add a page break within a loop, select the line where you want the break and select Page break before in the paragraph properties.
• You cannot use a field code in a header or footer if the foreach loop is outside of it.
• Tabs and spaces used for indenting text in formatted text fields are not exported. You can indent text manually in Word.

As you work on a template, upload it to make sure it does not contain any errors. Make sure you select Draft so other users cannot use the template for exports. See Adding Microsoft Word export templates to Helix ALM.

When you upload a template, Helix ALM checks for valid syntax and field codes, field codes in the correct context, and any other problems. If the template contains errors, you are prompted to view and correct them. Helix ALM creates a copy of the template with comments that tell you about each problem to fix. See Correcting Microsoft Word export template errors.

When the template works correctly and contains all information, make sure you add the final version to Helix ALM and make it available to the security groups who need to use it. Make sure to clear the Draft option if you selected it.