You are not logged in. Click here to log in.

codebeamer Application Lifecycle Management (ALM)

Search In Project

Search inClear

Tags:  not added yet

Advanced document export functionality

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


Context dependent templates

For context dependent exports, templates can also reference the items selected on the UI for export as if they were queried by cbQL. To do that, you simply need to create queries that are set to depend on a special initial level named "item" as per the following example: <<query.epic.dependson>> = item


Respectively, you can reference the results of a similar query as follows: <<item.epic.id>>

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} (i.e. ${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.

Content control Required? Value type Default value Used for Example
query.{name}.name Y string
Used for referencing the query. It needs to match the {name} referenced in the mergefield as well. <<query.epic.name>> = epic
query.{name}.description N string
Helps understand the purpose of the query, but not displayed anywhere.
query.{name}.cbql Y string
The heart of the query. It needs to be a valid cbQL. We recommend testing your queries through the Report and Traceability Browser functions of the UI.
query.{name}.dependson N string
Only required for queries that are not on the initial level. There can be only one query without dependson parameter. <<query.userStory.dependson>> = epic
query.{name}.incomingReferences N checkbox N Marks if this query should be connected to the "dependson" query by downstream reference. It is False by default.
query.{name}.outgoingReferences N checkbox N Marks if this query should be connected to the "dependson" query by upstream reference. It is False by default.
query.{name}.incomingAssociations N checkbox N Marks if this query should be connected to the "dependson" query by downstream association. It is False by default.
query.{name}.outgoingAssociations N checkbox N Marks if this query should be connected to the "dependson" query by upstream association. It is False by default.
query.{name}.historyDate N string
Can only be set on the initial query level, in which case it is applied to all levels. By setting an ISO date for this parameter, you can query the version of the resulting tracker items on the given date. <<query.epic.historyDate>> = 2011-12-03T10:15:30+01:00
query.{name}.limit Y integer
The maximum number of items returned by the query. I.e. if there are 3 items on the previous level, and there are 2, 8 and 15 related items for each, and this parameter is set to 5, then the result of this query will contain 2, 3 and 0 items respectively. <<query.userStory.limit>> = 5
query.{name}.limitByPreviousLevel Y integer
The maximum number of items returned for each related item on the previous level. I.e. if there are 3 items on the previous level, and there are 2, 8 and 15 related items for each, and this parameter is set to 10, then the result of this query will contain 2, 8 and 10 items respectively. <<query.userStory.limitByPreviousLevel>> = 10
query.{name}.history N checkbox N Marks if the history entries of the result set should also be queried. Required for being able to reference the related entries in the template. See:
template-items-with-history.docx
query.{name}.reviewHub N checkbox N Marks if the Review Hub entries of the result set should also be queried. Required for being able to reference the related entries in the template. See:
template-items-with-review.docx
query.{name}.workflowReview N checkbox N Marks if the workflow based review entries of the result set should also be queried. Required for being able to reference the related entries in the template. See:
template-items-with-tracker-item-reviews-all.docx
template-items-with-tracker-item-reviews-latest.docx
query.{name}.testCaseRuns N checkbox N Marks if the related test case runs of the result set (along with their results) should also be queried. Required for being able to reference the related entries in the template. See default test run template:
template-test-runs.docx
<<item.testCaseRuns.*>>
query.{name}.testRunStatistics N checkbox N Marks if statistics of queried top level test runs should also be queried. Required for being able to reference the related entries in the template. See default test run template:
template-test-runs.docx
<<item.testRunStat.*>>






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 (eg. 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 is influences the formatting of the corresponding part of the exported word file. For example: the each child items will be rendered with a lower level heading to visualise the connection to it's parent.

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

checkbox.ignore.outline

Example template snippet: ignore_outline_snippet.docx

Examples

Template
Example export documents
template-risk.docx
example-risk.docx
template-risk-nested.docx
example-risk-nested.docx
template-execution.docx
example-execution.docx
template-execution-steps.docx
example-execution-steps.docx

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 (i.e. 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 (i.e. history, reviewHub, workflowReview) always accesses the HEAD revision regardless of the version of the related item
  • Accessing the related references using the old notation (i.e. {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 are 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