Word Reporting using Merge Fields

In codeBeamer 9.3 a completely new Word export functionality has been introduced. Our goal was to make customization as easy as possible by still keeping the flexibility. User can create Word templates using standard Word mechanisms without knowing about codeBeamer internals. Scripting was removed from Word template itself, although it is still possible to use scripting to cover more advanced use cases. Legacy solution was completely rewritten so customization options of legacy solution are not working with the new engine. It was replaced with new mechanisms using Word MergeFields and Bookmarks, see chapters below.

Legacy solution (Word Templates in CB 7.2 - 9.2) is still accessible by using legacy templates.

See: Legacy Word export is disabled ?

Known issues

Known issues of Word Export

Default templates

From codeBeamer 9.3 Word export by default is working with the new export engine. If you do not select any template manually then the default template is applied which triggers the new engine.

In case of tracker item export the basic template contains summary, properties, references, associations, description. User can also choose what kind of extra content is exported for each item: comments, history or last review status.

Previously this additional content was controlled by check boxes. In the new engine the template determines what kind of extra content is included.

Different templates can be selected from the list box on the export dialog.

Templates appearing in the list come from two sources.

• codeBeamer Document Management:
  • for project level templates
  • .codeBeamer/Templates
• From file system:
  • for project independent templates
  • $CB_HOME/tomcat/webapps/cb/exporttemplates

If a template with the same filename can be found both in file system and in project level templates, only the template from filesystem can be selected during export

Each template context has its own sub-folder:

• Trackers
• TestCases
• TestRuns
• Traceability
• Coverage
• Review
• ReleaseNotes
• Wiki

Legacy export solution will only be available if user uploads a legacy template. Legacy templates will not be shipped with 9.3.

codeBeamer detects which kind of template the user selects or uploads (merge field based or legacy).

User interface shows check boxes for extra content only in case of legacy templates.

See more information on template management: Adding and customizing templates for Word and Excel export

Important Word Settings and Shortcuts

Switch to view field code of a particular merge field: SHIFT + F9

Switch to view field codes for all merge fields: ALT + F9

Insert a new merge field:

Insert / Text / Quick parts / Field / Merge field

Manage bookmarks:

Insert / Links / Bookmark

Make bookmarks visible:

File / Options / Advanced / Show document content / Show bookmarks

Make content controls visible:

File / Options / Customize Ribbon / check Developer

Manage content controls:

Developer / Content control

Merge fields

All merge field names are case sensitive. In case of names consisting of multiple words then camel case is used.

Eg.:

• item.closedAt
• item.modifiedBy.name

Merge field notation follows notation of codeBeamer REST API with some extensions. Properties which are available for an item are available here as well. Also there are additional data available for export purpuses. The appendix contains the available field names.

If a tracker field label changes then name on REST API changes with it. As a result Word Export Templare should be updated too or else field will not be exported to the usual place it will remain empty.

There are some exceptions here as well, following fields are not affected by field labels renaming:

priority, comments, staff, closedAt.

Merge fields can be inserted from the ribbon Insert / Text / Quick parts / Field...

Merge fields can be edited using right click context menu. This will show the same window as in case of insert.

In case of insert or delete the following window appears:

Field codes for date / number / currency formatting can be entered when inserting or editing a merge field, by clicking the button Field Codes on the bottom of the window.

Word limitation - When editing an existing merge field, existing field codes are not shown on the user interface. When editing field codes existing ones are overwritten. You can view existing field codes by pressing ALT+F9.

Never edit a merge field manually! Both field name can be changed and field codes can be added after a field inserted. This must be done from Word user interface (Field window, see above.) Do not edit field name or field codes manually.

Formatting fields

By default, formatting defined on merge fields is applied to the replaced content during export. Font, size, color, alignment, styles all received by the content which is rendered into the field.

Wiki fields are an exception from above behaviour. Wiki fields have its own formatting inside codeBeamer and that formatting can not be overwritten by Word template. Content of wiki fields should look like (more or less) the same as on web regardless of formatting of mergefield in the template.

Wiki fields are rendered as html then inserted into the Word document. Currently supported ways of using wiki/html mergefields in templates are:

• put them into a separate line - which should not contain anything else
• put them into a Word table - which would solve the indentation problems too

Formatting date fields using field codes:

Define Date and Numeric Formats for Mail Merge Fields

Formatting Date Fields

Comments

If "item.commentsPlace" is inside the template then item comments are added to the document as Word comments, anchored to this point.

This field should be put into a separate line in the template like it is done in case of default templates.

Hyperlink fields

See: Hyperlink fields

Available merge fields

You can find available merge fields here:

Word Export Placeholder Listing - CB 9.3 and higher

From codeBeamer 9.4 you can generate this listing dynamically which includes all fields including custom fields:

List available fields CB 9.4+

Multi value fields can be printed simply without bookmark loops too. In this case only the names will be shown, separated by comma.

eg.: "item.assignedTo"

When there is a need for more complex look, then bookmark loops can be used with specific fields/properties. Please see next chapter.

Bookmark blocks

When you are exporting a multi value field like a choice list then using only merge fields is not enough. A loop must be defined in the template by adding bookmarks.

When you are editing the template in Word select Insert / Links / Bookmark on the ribbon. This will show you a small window where you can view and manage existing bookmarks in the document.

By entering a name and clicking Add you can create a new bookmark on the current selection. In the below example the bookmark "loop_item_upstream" is created on the table row which is selected.

By selecting a block of document and creating a bookmark on it you are defining which part of document should be the body of the respective loop.

Squared brackets show the begin and end of the bookmarked block. This is not visible by default, you can switch it on at File / Options / Advanced / Show document content / Show bookmarks.

Name of bookmark blocks must match to respective merge field names.

• eg. merge field name "item.downstream.name"
• respective bookmark name "loop_item_downstream"

If you define a custom field with label "Related Bugs" then

• merge field name: "item.relatedBugs.name"
• bookmark name: "loop_item_relatedBugs"
• Note: In case of custom choice lists only "id", "name" and "urlName" merge fields are available.

All bookmark names are case sensitive like merge field names.

Currently bookmark loop detection is relying on the location of the bookmarkStart tag.

If bookmark starts inside a table then particular table row will be looped (referred as table row loop from now).

If bookmark start outside a table then included paragraphs/tables will be looped (referred as paragraph loop from now).

When copying content which includes bookmarks then bookmarks will not be copied because of duplication.

Bookmark names have to be unique in the document. User has to create a new bookmark by altering the name of the original bookmark.

When using the same loop multiple times in a document, then user has to add some postfix to alter the name of bookmark.

eg.: loop_item_downstream2, loop_item_downstreamPostfix

Underscore used to determine levels, so it cannot be used in the postfix.

eg.: loop_item_downstream_postfix => will not work

In a "loop_item_downstream" you can refer only onto the array "item.downstream". For referring another arrays you have to specify loops for each of them respecitively.

Eg.: Referring onto "item.upstream.name" inside "loop_item_downstream" will result in error.

Limitations:

• loops in tables
  • only loops one row, the first row inside bookmark
  • single cell can not be repeated only the whole row
• loops outside tables
  • when user wants to create a paragraph loop starting with a table then bookmark has to start in a line before the table (not in the same line)
    • otherwise it will be detected as a table row loop
  • if a paragraph loop is followed by a table then there must be an empty new line between the end of the bookmark and the table

Rendering table fields of trackers

Columns of table fields can be accessed by their index eg.:

• item.tableName.col0
• item.tableName.col1
• item.tableName.col2
• ...

Above fields must be inside a bookmark called "loop_item_tableName". See example below.

See also default Test Case template for an example table "testSteps": template-test-cases-base.docx

Links to codeBeamer Resources

Links to codeBeamer resources can appear in Word export documents in two different ways. If you check "Generate absolute links" then all link will point to the codeBeamer instance where export was initiated. See screen below.

If above checkbox is left unchecked, then those links which point onto items present in the currently exported document will become internal links pointing onto bookmarks inside the document. This is a feature which helps in offline work, when codeBeamer instance is not accessible.

Internal links are used only for items selected for export, links to item references are still using absolute links to codeBeamer. Technically where <<item.name>> merge field is present, a bookmark is inserted. In case a link found onto that item, then it is replaced to point to this bookmark instead.

Heading styles

If a line is formatted with a heading style in the template then the exported document will also use this heading style. You can see this in case of headings in standard template.

Usage of heading levels in case of item hierarchies start from the level defined in template (starting from version codeBeamer 9.5). Eg. if <<item.name>> is formatted with Heading 2 then top-level items will have Heading 2 and their children will have Heading 3 and their children Heading 4 etc. Heading styles will follow as the hierarchy goes deeper.

In codeBeamer 9.3 and 9.4 item hierarchies always started from fixed level "Heading 3".

If you want to change the numbering and start at a different level eg. at 1.1. instead of 1.1.1. then in Word you can adjust which heading belongs to which list level.

Right click on number / Adjust List Indents... / More >>

Velocity macros

Location of velocity macro library:

tomcat/webapps/cb/config/templates/export/mergefields.vm

Velocity macro names are all lower case as the examples show:

eg.: field_item_downstream_name

eg.: property_name

To evaluate value of a field a velocity macro is called based on the field name. This provides an extra customization option for the user where some kind of text transformation can be implemented.

There are two type of macros:

• Field macros
  • using a prefix "field_"
  • matching on specific merge fields, eg.: "field_item_downstream_id" will match on field "item.downstream.id"
• Property macros
  • matching on the property name of a field, eg.: "property_result" matches to all merge fields ending with "result", like "item.testCaseRuns.result"
  • This means user can define a unified behavior for all fields referring the property "result".

New merge fields can be defined by creating new velocity macros.

Custom Hyperlinks

Properties starting with "url" will be a hyperlink

• macro name eg.: "property_urlName"
• display text can be defined by creating / using velocity macros like "property_urlName", "property_urlKeyId"
  • see existing macros in velocity library
• hyperlink will point onto {codebeamer_url} / uri-of-item
  • eg.: in case of "item.submittedBy.urlName" will point to the user page who is in the submittedBy field
• if macro not available for field or for property then displayed text will be simply "Link"

Accessible variables in the Velocity context

Item data is available in the form of a JSON data tree. You can see an example of a tree by issuing a simple GET request to the codeBeamer REST API eg.:

/cb/rest/item/<item-id>

Name of a particular merge field selects a specific path in this tree. This path consists of a couple of nodes or objects. All of these selected objects are accessible from the velocity context.

• ${leaf}
  • The leaf in the JSON tree selected by the actual mergefield (the last object in the selected path).
  • eg. "item.priority.name" => "priority" object
  • eg. "item.history.changes.newValue" => "change" object
• All levels along the path selected by the particular merge field is accessible through a "lower camel-case" naming convention.
  • Name of each node is converted to lower case, then these lowercase names are joined together so that each node starts with a capital letter except the first one.
    • See examples below: field name => context variable name
    • aaa.bbb.ccc => aaaBbbCcc
    • aaA.bBb.Ccc => aaaBbbCcc
  • eg. in case of merge field "item.history.changes.newValue"
    • ${item}
    • ${itemHistory}
    • ${itemHistoryChanges}
      • this is the same as ${leaf}
  • eg. in case of merge field "item.testCases.name"
    • ${item}
    • ${itemTestcases}
      • Please note: node "testCases" became "Testcases" becauseof the above mentioned camel-case notation

Conditional formatting

Conditional formatting can be achieved by using multiple merge fields each of which matching to appropriate result of a condition. The default test run template contains a good example:

"item.testCaseRuns.result.name" is formatted/colored differently depending on the value of it.

To make this work you have to introduce new merge fields by creating velocity macros. During rendering only one of the merge fields will have value, the others will be rendered empty.

See example merge fields below:

#macro(field_item_testcaseruns_result_namepassed)
    #set($result = $leaf.get("name").getAsString())
    #if($result == "Passed")
        $result.toUpperCase()
    #end
#end

#macro(field_item_testcaseruns_result_namefailed)
    #set($result = $leaf.get("name").getAsString())
    #if($result == "Failed")
        $result.toUpperCase()
    #end
#end

#macro(field_item_testcaseruns_result_nameelse)
    #set($result = $leaf.get("name").getAsString())
    #if($result != "Passed" && $result != "Failed")
        $result.toUpperCase()
    #end
#end

#macro(field_item_testcaseruns_notrunyet)
    #set($result = $leaf.get("result"))
    ##  if result is null
    #if("$!result" == "")
        NOT RUN YET
    #end
#end

By default empty fields receive a "--" value so this would be a problem if "--" would appear for all merge fields. This can be avoided by adding new entries to existing macro called "not_available". This provides the value which is shown for empty fields.

## empty fields are populated with some n/a value to clearly show something is not available
## if a merge field result remains empty during merging then this macro is run to populate some value

#macro(not_available)

##    Some specific merge fields don't need n/a value but should be actually empty.

##    - A notification is present or not, it is never missing.
##    - Chapter number is also not missing, but it is present or not.
##    - Conditional fields also use this behaviour.
##      From multiple fields only one will get value, others remain empty.

    #if(   $fieldName != "item_changenotif"
        && $fieldName != "item_chapter"
        && $fieldName != "item_testcaseruns_result_namepassed"
        && $fieldName != "item_testcaseruns_result_namefailed"
        && $fieldName != "item_testcaseruns_result_nameelse"
        && $fieldName != "item_testcaseruns_notrunyet"
        && $fieldName != "item_assocout_to_urlkeyid"
        && $fieldName != "item_assocout_urlurl")
    $!naValueFromTemplateParameters
    #end

System Admin Configuration of Word Export

Each Word export job runs as a new process separate from codeBeamer. This process can be configured as below.

Callback URL

The callback URL is where codeBeamer application is accessible for external export application process.

This is detected automatically by default. If server is behind Apache then it must be configured manually.

Configuration can be done at System Admin / Application Configuration:

You can see relevant entries below:

"applicationApi" : {
  "callbackUrl" : "http://localhost:8080/cb"
},
"wordExport" : {
  "debugLogging" : false,
  "jvmArguments" : "-Xmx3G",
  "maxParallelProcesses" : 3,
  "restLoaderPageSize" : 50,
  "timeoutSeconds" : 3600
},
"interactive" : {
  "maxAllowedWordExportItemCount" : 5000
}