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

Convert to PDF

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

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

Nesting conditional blocks

Conditional 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 placement

It 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 block

Conditional 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:

• By creating a custom field as Velocity macro and implement condition inside it. Eg. it renders text only in case condition evaluates to true.
• By creating a custom field eg. "item.forceConditionEvaluation" as Velocity macro which renders nothing. Then add this practically empty field to body of conditional block inside the template. To make sure the new custom field will not render "--" add "item_forceconditionevaluation" to macro called "not_available".
• From cB 10.0 there is an existing <<item.empty>> merge field for above reason.

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

Notes:

• The parameters section should be contained in a bookmark named template_parameters.
• There must be an empty new line just before the the template_parameters bookmark, otherwise export may fail.

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 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 thumbnail creation is using GhostScript, which must be installed on the host running codeBeamer. Tested following versions of GhostScript: 9.07, 9.27.
     • "bin" folder of GhostScript installation must be added to PATH environment variable
     • On Windows machines it is needed to restart codeBeamer to make sure that updated PATH variable is being used. Command prompt have to be restarted as well.
2. Embed means 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
   • 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.