Advanced Word Export Features

In codeBeamer 9.4 a set of new features has been introduced on top of new Word export solution introduced in 9.3.

See: Word Templates in CB 9.3 and higher

List available fields

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 and the resulting document will contain all available fields.

Content of the resulting document will be a field name listing. Structure is as follows:

• Meta data fields
  • eg. project.id
  • eg. tracker.keyName
• Fields by tracker
  • item.*
  • eg.: item.name
  • eg.: item.(array).assignedTo.name
    • above example shows a field name which includes ".(array)". This part shows that the next element ("assignedTo") is an array of elements, not a single element. This ".(array)" is only a meta information it is not part of the actual merge field name. Merge field name will be "item.assignedTo.name" and you will need a bookmark loop around it. Name of the bookmark loop has to be "loop_item_assignedTo".

A field is included in the list only if it has value in at least one exported item. If there is no item in the exported file which has that value filled in, then that particular field will not be included in the exported document.

Conditional templates

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 folders

To ignore empty folders in the exported document, "if_not_empty_folder" can be used instead of "if_folder".

Custom conditionals

Conditional 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
#end

Limitations

• Conditional blocks cannot be nested. They must follow the structure visible on the above image. They must be located inside "loop_item" and come sequentially after each other. Creating more complex conditionals is possible by creating more complex velocity macros. See sections below.
• 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.
• Conditional template blocks must contain at least one item merge field <<item.*>>, can not contain a simple static text. If adding static text conditionally is a must then this can be done in two ways:
  • By adding a custom placeholder as Velocity macro and implement condition inside it. Eg. it renders text only in case condition evaluates to true.
  • By adding a custom item.* placeholder as Velocity macro which renders nothing.
• Conditional blocks should not contain merge field <<item.commentsPlace>>. Please add this merge field outside conditional blocks but inside "loop_item" block.

Rendering parameters

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).

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.)

Plain Text Content Controls have to contain at least a space to be empty, otherwise, they will contain the message "Click or tap here to enter text."

Rendering parameters can be included in or excluded from the export document based on the option "Remove rendering parameters".

Ignore HTML

For 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 strings

It can be specified in the template what a certain value is inserted into the fields which would otherwise be empty. The default value is "--".

Export Attachments

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:

1. Expand means that the attachment will be inlined into the document as an image. The user can specify extensions which will end up in the document as images. The supported file types are: gif, png, bmp, jpg, jpeg, txt, log, and pdf.
   • If no extensions are specified, then all supported attachments will be expanded.
   • The maximum size can be defined for inlined images.
   • In case of expanding "pdf" files, a rendered thumbnail image is inserted into the document, which shows the first page of the pdf document. This thumbnail is also a link which opens the full document.
   • Pdf rendering is done using GhostScript, which must be installed on the host running codeBeamer.
2. Embedmeans that the attachment will be available in the embedded package and the document will contain a link to it. Extensions can be specified the same way as in the case of the previous mode, but there is no limitation regarding extensions.
   • If no extension is specified, then all attachments which are not expanded will be embedded.
   • If an extension is defined for both expand and embed, then it will be expanded.
   • See example below:
   • 
3. Export- the rest of the attachments - which are not expanded or embedded - will be added to the zip package but the document will not refer to those attachments.
   • For technical reasons, if only "export" is checked and none of the other two options above, <<item.attachmentsList>> is still needed in the template. Although in this case no attachments will be rendered into the document and this merge field will be empty.

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.

Values inside the parameter table are given inside content control blocks. When editing values, make sure that you enter values inside those controls. Parameters are identified using the name of these content controls.

The result of expanding a "txt" or "log" file is shown below. The file name is a link in the header: when you ctrl-click on that link, it will open the full-text file in the Windows' registered appropriate/text editor. The text below only shows the first 1000 characters with an "..." at the end if the text is shortened. Note the red warning which reminds the user that this is NOT the full text, only the beginning of it.