You are not logged in. Click here
to log in.
codebeamer Application Lifecycle Management (ALM)
Table of Contents
Word Reporting using Merge Fields
This feature is available starting from codeBeamer 9.3.0. Supported version is Microsoft Word 2016.
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 ( See: Known issues
Default templatesFrom 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, for more information see:
 Adding and customizing templates for Word and Excel export. As for Word Templates, any user's upload can be used for export.
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:
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: Important Word Settings and ShortcutsSwitch 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 fieldsWord export templates are mainly consists of static content and placeholders which will be populated during the export process. For these placeholders a specific Word field type is used - Merge Fields - eg. <<item.name>> 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.
Never edit a MergeField directly in the document! Both field name and code can be changed after a field has been inserted. But this must be done using the Field window, see below. It is accessible from right-click context menu. Do not edit field name or field code inline. (It creates complex markup including change tracking what the export can not process.)
In case of insert or edit 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.
Formatting fieldsBy 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:
Formatting date fields using field codes: Define Date and Numeric Formats for Mail Merge Fields
Available merge fieldsMerge field names are case sensitive. All tracker item fields are accessible by label including custom fields. Labels are expected in the same format how it is returned on REST API. (Labels are converted to a camel case format. First letter is always lowercase. Then starting letter of subsequent words are capital letters. Capital letters inside a specific word are kept.) Examples:
You can verify names on the REST API. Populate certain field on an item then query it through following url: /rest/item/<itemId>Word export Merge Field notation follows notation of codeBeamer REST API with some extensions. Properties which are available there are available here as well. Plus there are additional data available for export purposes. Appendix contains available field names.
If a tracker field label is changed then name on REST API changes with it. As a result Word Export template should be updated as well or else field will remain empty in document.
priority, comments, staff, closedAt
You can find available merge fields here:
From codeBeamer 9.4 you can generate this listing dynamically which includes all fields including custom fields:
Following fields should not be used as tracker field name as it conflicts with export's built-in field names:
author, title, baseline, exportDateTime, project, tracker, release, combinedTopLevelReviewStats, reviewStatsByReviewer, combinedStats
Number of elements in multi-value fields can be accessed by <<*Count>> property. Examples:
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. CommentsIf "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 fieldsSee:
Bookmark blocksWhen 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.
If you define a custom field with label "Related Bugs" then
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
Eg.: Referring onto "item.upstream.name" inside "loop_item_downstream" will result in error.
Limitations:
Rendering table fields of trackersColumns of table fields can be accessed by their index starting from zero:
From codeBeamer version 20.11 columns can be accessed by label as well. Labels are expected in a camel-case format, see explanation above: Table column names can be verified on Swagger API using following url. In the result look for "legacyRestName" /api/v3/trackers/<trackerId>/fields/<fieldId>In test management custom test step fields (columns) can be accessed same way. Examples:
These merge fields must be inside a bookmark called "loop_item_tableName" which will iterate through the rows of the table. Built-in default Test Case template is a good example with a table called "testSteps": template-test-cases-base.docx Another example using custom test step fields as well: template-test-cases-custom-cols.docx
Another example with table called "customTable":
Please note: For table fields to work in Word export "Row numbers" option must be checked on the table field in the tracker configuration.
Links to codeBeamer ResourcesLinks 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.
Heading stylesIf 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.
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 macrosLocation 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:
New merge fields can be defined by creating new velocity macros.
Custom HyperlinksProperties starting with "url" will be a hyperlink
Accessible variables in the Velocity contextItem data is available in the form of a JSON /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.
Conditional formattingConditional 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
Convert to PDF
Available from codeBeamer 9.4.0.
User can select "Convert to PDF" option on export dialog. In this case document is rendered same way in docx format but after that it is converted to PDF.
List available fields
Available from codeBeamer 9.4.0.
The user can obtain a document which contains all merge fields available in a specific export context. This is derived from the current status of the tracker configuration, so it is up-to-date as long as it is unchanged. The available fields depend on the trackers in scope or the current use case (for example, tracker export, traceability export, or review export). The user has to start an export using the following template: template-list-all-fields.docx Resulting document will contain all available fields. Content of the resulting document will be a field name listing. Structure is as follows:
Conditional templates
Available from codeBeamer 9.4.0.
From codeBeamer 9.4.0, Word templates can contain conditional parts based on item properties. These conditional blocks can be defined using bookmarks (similarly to loops). Example template below contains two conditional blocks: "if_folder" and "if_not_folder". In this example, folders will be printed as only a name and an underline. Items of other types will have their properties and description included. Example: template-if-folder.docx
Ignore empty foldersTo ignore empty folders in the exported document, "if_not_empty_folder" can be used instead of "if_folder".
Custom conditionalsConditional template blocks are evaluated using velocity macros which are defined in the same velocity macro library as the merge fields themselves. The location of the velocity macro library is the following: tomcat/webapps/cb/config/templates/export/mergefields.vm New conditional macros can be easily added to this file. The name of the macro can then be used as a name for conditional blocks. The JSON representation of the item is available through the $item variable, which is an instance of com.google.gson.JsonObject. See API documentation here: GSON API 2.3.1 Example: #macro(if_folder)
#set($type = $item.getAsJsonObject("type").get("name").getAsString())
#if ($type == "Folder")
true
#else
false
#end
#endLimitationsNesting conditional blocksConditional blocks can not be nested. They must follow the structure visible on the above image. They must be located directly inside "loop_item" and come sequentially after each other. Creating more complex conditionals is possible by creating more complex velocity macros. See sections below. Bookmark placementIt is not supported to define multiple conditional blocks in a single row. Although one conditional block may span multiple rows.
Conditional and loop blocks should not interfere with each other. If there is no content between two brackets then order of brackets can not be determined. Best practice is to have only one starting or ending bracket in a line. Only exception is when a block ends in the same line in which it starts.
When defining two conditional bookmarks continuously after each another - eg.: "if_folder" followed by "if_not_folder". These must be separated somehow or else the template is not processable. See solution below: When you insert the first bookmark then make sure to have an extra space character at the end of the paragraph. See the dot after <<item.description>>. Then make sure to select the paragraph without this extra space character.
Then define the bookmark on this selection:
This way the ending tag of this bookmark will not interfere with the next bookmark "if_not_folder" Content of conditional blockConditional template blocks must contain at least one item merge field <<item.*>>, can not contain only static text. Otherwise condition can not be evaluated because the engine determines current item based on fields inside the conditional block. If conditional block contains only loops and static text then keep in mind that where loop length is zero then same problem occurs. If adding static text conditionally can not be avoided then this can be done in two ways:
Conditional blocks should not contain merge field <<item.commentsPlace>>. Please add this merge field outside conditional blocks but inside "loop_item" block.
Rendering parameters
Available from codeBeamer 9.4.0.
The template document can contain extra rendering parameters, see below. The user can simply copy this part of the template from an example (template-ignore-html.docx).
Notes:
Parameter values are defined using Word Content Controls. Parameters are identified by the name of the control. (To enable the Content Control user interface in Word, go to: Options / Customize Ribbon / check Developer.)
Rendering parameters can be included in or excluded from the export document based on the option "Remove rendering parameters".
Ignore HTMLFor the specified wiki fields, HTML formatting will be completely ignored and images will be omitted. In the above example, the fields "description" and "preAction" will only have plain text content. Replace empty stringsIt can be specified in the template what a certain value is inserted into the fields which would otherwise be empty. The default value is "--".
Truncate long history entries
Available from codeBeamer version 21.09
Tracker item history can be exported, see built-in template. History values will not be truncated by default although they can be really long depending on content. If it is needed then history entries can be shortened by adding following template parameter to the template: integer.history.entry.max.length If value is greater than zero then this number of characters are kept during truncation. Otherwise no truncation applied. See example template attached: template-items-with-history-maxlen.docx
Export Attachments
Available from codeBeamer 9.4.0.
When exporting items to Word, it is also possible to include attachments of the items. In case attachments are exported, the user will get a zip package not just a single document. Attachment files are packed together with the document in a single archive. When opening the document, make sure that you extract the whole package. The file structure of the package looks like the following: testing - Customer Requirement Specifications ├── attachments │ ├── 22192 │ │ ├── 129144_2007_09_10_miurablueprint.jpg │ │ ├── 129145_cblogo-xl.png │ │ ├── 129149_cbopen.vbs │ │ ├── 129150_kern.log │ │ └── 129151_kern.txt │ ├── 22193 │ │ ├── 129146_egy.bmp │ │ └── 129147_zizi.pdf │ └── readme.txt └── testing - Customer Requirement Specifications.docx The "attachments" directory contains all attachments from the export. This contains a subdir for each item exported, named by the exported item's id. The original file names are kept, but the attachment id is added as a prefix. The attachment id is globally unique in itself, so it clearly identifies the file. The ".docx" file next to the attachments dir is the result docx file: it contains links to the files in the "attachments" as applicable. To enable attachment export, the docx template must contain the merge field <<item.attachmentsList>>. This also defines the place where the links and images will be inserted. There are three different modes for exporting attachments:
The configuration of these options can be done through the docx template. See below: Here is an example template which contains the configuration for the export of attachments: template-items-export-attachments.docx.
System Admin Configuration of Word ExportWord export is implemented as a separate application from codeBeamer. It can run locally on same host as codeBeamer or it can run as separate service on another host.
By default Word export is running as a separate process on the same host where codeBeamer is running. For each export job a new process is started. When a job is started codeBeamer is passing some initial data to export application through file system (like IDs of trackers to export). However most of data is queried from codeBeamer REST and Swagger API-s. For making these calls export application needs to know where codeBeamer is accessible. This is why a callback URL is necessary. codeBeamer tries to calculate this URL automatically however in cases where codeBeamer is behind a frontend (eg. Apache httpd (From codeBeamer version 10.1 Word export can be run as separate service on another host as well however this needs extra installation/configuration. See:
Configuration can be done at System Admin / Application Configuration:
An example configuration: "applicationApi" : {
"callbackUrl" : "http://localhost:8080/cb"
},
"wordExport" : {
"debugLogging" : false,
"jvmArguments" : "-Xmx3G",
"maxParallelProcesses" : 3,
"restLoaderPageSize" : 50,
"timeoutSeconds" : 3600
},
"interactive" : {
"maxAllowedWordExportItemCount" : 5000
}
See relevant documentation of Application Configuration: Accessing logs of Word Export componentWhen word export is running locally then logs can be found under codeBeamer log folder. Before codeBeamer version 21.09:
Starting from codeBeamer version 21.09:
|
codebeamer Overview codebeamer Knowledge Base Services by Intland Software |
This website stores cookies on your computer. These cookies are used to improve your browsing experience, constantly optimize the functionality and content of our website, furthermore helps us to understand your interests and provide more personalized services to you, both on this website and through other media. With your permission we and our partners may use precise geolocation data and identification through device scanning. You may click accept to consent to our and our partners’ processing as described above. Please be aware that some processing of your personal data may not require your consent, but you have a right to object to such processing. By using our website, you acknowledge this notice of our cookie practices. By accepting and continuing to browse this site, you agree to this use. For more information about the cookies we use, please visit our Privacy Policy
.Your preferences will apply to this website only.
anonymous
Although there are some exceptions, following fields are not affected by renaming field labels, they are fixed:
Hotkeys