Advanced Word Export

Codebeamer (Betty) introduced a new, advanced document export functionality, which gives template developers access to Codebeamer tracker data with the help of cbQL queries. While existing templates continue to work, the new functionality makes it possible to create complex documents from multiple from across multiple trackers.

Basic functionality

Templates can now include cbQL queries at the parameters section of which results can be referenced and iterated through using bookmark loops. To do that, you need to:

1. define a query (as described below at Query parameters)
2. create a bookmark loop as: loop_{queryName}
3. in the loop, reference the attributes of the items returned by the query execution as a merge field: <<{queryName}.{attribute}>>

This will result in listing the {attribute} attribute of all the resulting items of {queryName} query.

Multiple, Interdependent Queries

In case of multiple queries, they need to reference each other and thus be built in a tree of queries, similarly to the multi-level filtering of the Traceability Browser. Once you defined your queries as per the Query parameters table below, you can embed bookmark loops iterating through the results of the related query in other bookmark loops. To do that, the inner loop needs to reference the external loops as well. You can do that in the following way:

1. define your queries (e.g. named epic and userStory)
2. create a bookmark loop referencing the outer query: loop_ {outerQueryName} (e.g. loop_epic)
3. create the inner bookmark loop referencing both the inner and the outer queries: loop_{outerQueryName}_{innerQueryName} (e.g. loop_epic_userStory)
4. reference the attributes of the items returned by the inner query as a merge field as follows: <<{outerQueryName}.{innerQueryNamen.{attribute}>> (e.g. <<epic.userStory.id>> )

Context-Dependent Templates

For context dependent exports, templates can also refer to the items selected on the UI for export as if they were queried by cbQL.

To do that, queries need to be created that are set to depend on a special initial level named item, as per the following example:

<<query.epic.dependson>> = item

Respectively, the results of a similar query can be referred to as follows: <<item.epic.id>>d

The main concept is to use the term item as initial level, instead of the actual initial level.

The Initial level table is unnecessary in the template parameters, and the Depends on value of the first level must refer to it as item.

The bookmarks should also refer to this level as item.

The export has to be started from an item details page.

Template example: template-context-dependent.docx

Example: context-dependent-example.docx

Tracker Item as a Template Configuration Parameter

To make templates more reusable, template developers can also reference an additional tracker item (independent from the items the export was started for) that users can select on the UI dialog when starting the export. The information in the optional tracker item can be used to provide additional parameters for the template.

As an example, a template can be created, which exports selected tasks and their related requirements that were present in a certain release. In this case, the task items can be selected by the UI through any of the tracker views, while the containing release can be provided through the optional parameter field of the export dialog.

The field values of the selected tracker item can be accessed as: ${fieldname} (e.g. ${id} )

Limitation: item field values can be used only in "query.queryName.cbql" template parameters.

Query Parameters

The following parameters can be used to fine-tune the queries of a template.

Template Parameters

Table Rendering

When rendering nested loops inside one common table then following option must be checked. If not, then root items with empty nested loop (e.g. without next level reference) will completely disappear from the resulting table.

checkbox.table.keep.empty.rows

Table cell merge can be switched on and off by below template parameter. Default is off to keep existing behavior.

checkbox.table.merge.cells

See example: template-traceability-tbl-linear.docx

Ignore Tracker Outline-Related Formatting

If the exported tracker supports the outline (parent-child relationship) functionality, the hierarchical position of an item influences the formatting of the corresponding part of the exported word file. For example: each child items will be rendered with a lower level heading to visualize the connection to its parent.

This functionality can be confusing while using multiple queries in the same word file, so we have introduced a checkbox type parameter to turn this off:

checkbox.ignore.outline

Example template snippet: ignore_outline_snippet.docx

Examples

Limitations

• The initial level query cannot be named "item", as it is reserved for accessing the items selected on the UI.
• Only 1 initial level query can be defined, and therefor only one traceability tree can exist in a single export.
• historyDate can only be set on the initial level, which is then passed over to the following levels as well.
• Only 1 tracker item can be selected as a template configuration item.
• Only simple field values can be accessed for the template configuration tracker items (e.g. integer, date, boolean, text, etc). References are not currently supported.
• The field values of the configuration tracker item can only be referenced within the parameter merge fields
• The additional loaders (e.g. history, reviewHub, workflowReview) always accesses the HEAD revision regardless of the version of the related item
• Accessing the related references using the old notation (e.g. {name}.downstream.id ) is not supported with the queried items -- they are recommended to be queried for explicitly if needed. However, they continue to be working for existing, legacy templates.
• The length of the bookmarks is maximized to 40 by Word. In case of high number of query levels, we suggest shortening the name of the queries to be able to fit into this limit.
• Table cell merges do not work in the current release. As a potential workaround, we suggest using nested tables.

Impact on Previously Created Templates

All templates supported by Codebeamer 10.1 continue to work, however the following functionality changes affect their behavior:

• The user is no longer prevented from trying to export an empty selection. This behavior is required to support exporting data sets defined entirely by the templates.
• A new "Configuration item" selector is now present on the export screen, which new templates may rely on, but has no practical use for existing templates, thus can be ignored
• The attachment handling parameters of the Word exports have changed
  • If attachments are included in the export, they are linked to the document by default
  • If embedding the attachments are enabled, all attachments are included into the document itself (as OLE objects)
  • If expanding the attachments are enabled, supported file types (images, text files, etc.) are displayed within the document