Word export Customization

Since Codebeamer version 7.2 Word export of Issues has been enhanced greatly, so requirements and other kind of issues can be exported to Microsoft Word, changes can be made on this export document, and some time later these changes can be seamlessly re-imported to CodeBeamer.

This is so called Rountrip export that heavily uses Word's capabilities, so this feature requires Microsoft Word 2007 or later. Neither earlier Microsoft Word versions nor open source alternatives like Libre/OpenOffice are supported.

When exporting issues from Word you have several options that are offered by the export dialog. An example of this dialog is seen here:

Managing templates: and how to get the "Default" template as starting point for customizations?

You can create your custom Word export template files for your custom exports.

When you need to create a custom Word template then it is always best to start the customization based on the default templates shipped with codeBeamer.

The carefully customized templates are then can be uploaded and stored in codeBeamer so they can be selected for any exports later when needed.

For more information about managing Templates see: Adding and customizing templates for Word and Excel export

The default and custom templates are both accessible if you click on the "Manage custom templates" link like here:

That opens up the directory in Document Management where the custom templates can be stored. The default template also is downloadable from here:

Customizing Word export's look and content

The content and look of the export can be customized by using a custom Word template. As highlighted on the previous screenshot the export dialog allows you to choose a customized Word template document during export.

The customized templates are managed and stored in a special folder inside the Document Management. This folder can be easily accessed by clicking on the "Manage custom templates" link on the export dialog. You can upload your customized templates to this directory, and use all the benefits of the Document Management. For example you can control who can use the template by setting up the permissions on the files, or access historical versions of templates etc...

As starting point for customizations you should create a copy of the default export template. This file is shipped with Codebeamer and can be downloaded on this export dialog by clicking on the "Download default Word template" link on the bottom right (follow arrows).

Structure of the export document and template

• Header and Footer
• Overview and introduction part
• Exported requirements/issues which contains these sub-parts for each issue:
  • Name part
  • Read-only properties
  • Editable properties
  • Description part

Each of these parts has slightly different customization options which is detailed below:

Customizing Header and Footer

Such fields' can contain any valid Java/Groovy expression and will be automatically filled during export.

Customizing Overview and introduction part

This part works the same way as was described in the Header/Footer part: the fields' name is evaluated as groovy expression during export, and the result of that evaluation is inserted to the result document.

Here you can also insert the rendered Wiki description of the exported objects. For example the exported Project's description is inserted using this field:

Customizing exported issues

• The name of the issue. This part can be edited, and when reimporting the document that will update the appropriate issue's name.
• The read-only properties of the issue. This part is never editable, but can contain rich content.
• Few editable properties of the issue. Some properties of the issue namely the "Priority", "Severity" and "Business Value" can be changed in this part, and such changes can be imported back to Codebeamer.
• The description part of the issue. This is editable, contains rich content like images and optionally the comments made earlier on this issue.

All these parts are somewhat customizable in the template document, which contains blocks of scripts that controls exporting these contents. These scripts are evaluated for each issue, and the result is inserted to the export document.

Customizing the Name part of issues

The Name part is the first part which exports the name of the issue. The content of this is a HTML markup, which is generated by the Velocity template which can be found in the default template document as shown here:

So to customize the content or look of you will need to modify the Velocity template here. The output should be a valid html fragment - without the HTML body or head, that is added automatically.

The Velocity script can access the same variables as other scripts, plus these:

Customizing read-only properties of issues

The next part that will be added for each issue is the read-only properties. The content of this part also is a HTML markup generated by a Velocity template. That template is embedded into the default template document as visible here:

The default Velocity script produces HTML tables for the downstream and upstream associations of the issue, and the downstream and upstream references of the issue.

Customizing editable properties of issues

This is the next part which contains the editable properties of each issue. Unlike other parts this is implemented as a native Word table and using Word's own Content Control elements.

What happens during the export here that the exporter will look for any Content Control elements inside this table. The "Tag" property of the found Content Control elements are then used as an groovy expression, and evaluated on the current issue, and the result is inserted to the table. If the property is not available on the issue (for example the Tracker of that issue does not contain it) then the whole row of the table is removed.

If a "Drop-down" Content Control elements is found then the exporter will also insert the possible choice-values, so the export document will correctly show the options. As an example this screenshot shows how is the Priority of issues can be configured. First click on the "Priority" Content Control inside Word, and then the "Properties" button on the "Developer" tab, which opens up the dialog to customize this field. The "Tag" value of this drop-down now contains "editable:Priority". The "editable:" prefix makes this field editable in the export, and the "Priority" is the field name on the "issue" being exported:

(Hint: the "Developer" tab is not visible in Word by default, but can be turned on as described here)

Customizing description of issues

List of Objects/Entities available in the export scripts

This table lists the objects available in the Velocity/Groovy scripts above:

variable name	type	description
baseline	com.intland.codebeamer.persistence.util.Baseline	The current baseline object if any (can be null)
request	HttpServletRequest	The http request being processed
user	com.intland.codebeamer.persistence.dto.UserDto	The requesting CodeBeamer user
currentDate	java.util.Date	Current date-timestamp
project	com.intland.codebeamer.persistence.dto.ProjectDto	The current project where the tracker being exported is
requirementTracker	com.intland.codebeamer.persistence.dto.TrackerDto	The requirement tracker
tracker	com.intland.codebeamer.persistence.dto.TrackerDto	The requirement tracker (same as requirementTracker)
requirements	SortedMap<ReleaseId,TrackerItemDto>	requirements as TrackerItemDtos grouped by release-ids
items	Collection<TrackerItemDto>	The exported Word items collection. Available since CB7.9: allows export script to filter Work Items: an practical example is here
issueReferences	com.intland.codebeamer.controller.importexport.IssueReferencesBuilder	Class to fetch downstream and upstream references of an issue Use getIncomingReferences() and getOutgoingRefrences() methods to fetch the downstream/upstream references of an issue
incomingAssocationsByIssue, outgoingAssociationsByIssue	Map<Integer, Map<String, List<IdentifiableDto>>>	Map contains for each requirement's id the downstream or upstream associations from/to that requirement. Important: these are not the referenced issues via reference fields, but the associations between other issues in the system.
exporter	com.intland.codebeamer.controller.importexport.DocxRoundtripExporter	The Docx exporter class. Added for including an HTML description of the issues or other kind of DescribableDtos using the exporter.renderAsMhtml(describable) method
urlLink	String	The context-relative url of the current entity (Work item). Use this instead of {No variable {describable.urlLink defined. if you want a link which keeps baseline and version information: the link will open the same version/baselined version which was originally exported.
interwikiLink	String	The interwiki-link of the current entity (Work item). Use this instead of {No variable {describable.interwikiLink defined. if you want a link which keeps baseline and version information: the link will open the same version/baselined version which was originally exported.
fields	com.intland.codebeamer.text.excel.FieldAccessor	Use {No variable fields.getByLabel($entity, "Description") defined.} to access value of any field on the current entity by its label. Available from CB 7.10+

Using properties of Objects/Entities available in the export scripts

About figuring out what properties are available on of these CodeBeamer objects: please look at the remote-api documentation and the javadoc found in. As you may already know CodeBeamer provides a rich API for querying and manipulating CodeBeamer objects programmatically using an RPC protocol. This API is documented here: You must login to see this link. Register now, if you have no user account yet.

The Javadoc of the remote-api is available here

So the remote-api contains the Javadoc of most internal CodeBeamer objects I've listed above, and is shipped with the CodeBeamer distribution. You can find it below your CodeBeamer installation directory on a path like: $CB_HOME/tomcat/webapps/cb/codebeamer-api-{version}.zip. If you unzip this zip file somewhere then you will see a "docs/api/" directory where the generated Javadoc resides. Open the index.html here and you will find the Javadoc and properties of the objects (like our TrackerItemDto).

Be warned however that the signature of these objects, the export scripts may and practically will change between any new CodeBeamer releases in the future. I would strongly recommend that you try to keep your customizations as isolated as possible, and using a git repository for tracking such changes is recommended. This will make your life much easier if you plan to upgrade CodeBeamer in the future...

Using Microsoft Office specific HTML/XML tags

Customizing the look/style of the export document

This is possible however you will have to play with customizing the original templates and may have to adjust some HTML/CSS files as well. The default export templates and CSS files are set up to produce the look which is closest to the original CodeBeamer web-page's look. This is what you may want to adjust.

Customizing header/footer and using your company logo

For customizing header/footer and company logo simply make a copy of the original template documents, and in Word edit the header/footer and replace the texts, fields and the logo image as needed. An example screenshot shows this:

Customizing styles in Word template

First when you try to customize the look of an element in the export document you should try to do it using Word's styling. For that open your customized copy of the template docx document, and adjust the styles there. That is done using Word's style dialogs. For example the following screenshots shows how to adjust the look of the "Heading 3" style in word. This is the style used when exporting the issue names and headings from CodeBeamer. So in this example we're changing the color of the Heading 3 to orange:

The result when using this template will look like:

Now the question arise: how can I find which style to adjust in the template? This is can be found out by opening an exported_ document, and then:

1. click on the little style button to open styles
2. click on open style inspector button on the styles dialog. Then the style inspector should appear.
3. Keep the style inspector open, and inside the document click on the part you want to find out which Word style is being used. The style inspector will show the Word style used there.

The next screenshot shows this, and from that it turns out the HTML links are appearing using the Hyperlink style. This is the style should be adjusted in the template if you want a different look for these elements.

Customizing look of html element using CSS

While many elements in the export Word document is customizable in the export Word documents, several others are not. The Word export in CodeBeamer is primarily producing some HTML content -this is the HTML content you have learnt to customize previously in the document-, and that HTML content is merged into a the docx templates.

When the export document is opened Word converts all embedded HTML (and CSS) contents to native Word content. During that conversion Word does a mapping between the exported HTML and the Word styles in the provided templates, however not all the HTML elements and CSS selectors get an appropriate style. Unfortunately it is not possible to assign any style to such HTML elements.

So in this cases the best option is to adjust the CSS that is being used in export to get the desired look. Here is how to do this:

Adjusting default HTML and CSS templates

In CodeBeamer there are the following customizable Velocity templates available:

Both files are located in the $CB_HOME/tomcat/webapps/cb/config/templates/html directory. These files are plain text files, so for customizing them just open them in your favourite text editor. As soon as the changes saved they will be immediately applied without need of CodeBeamer restart.

An example: if we want to change the look of the tables in our export result, like change the color and font-type then edit the mhtml-export-css.vm and add this to the end of it:

table td {
   color: red !important;
   font-family: 'courier' !important;
}

As result table will appear as this in the export:

Customizing HTML and CSS in the docx template documents

From the latest CodeBeamer 7.3.0.1 it is also possible to embed the customized HTML/CSS templates inside the template. This means that you can have a different HTML/CSS look in each docx template, instead of having only one customization globally.

So instead of editing the "mhtml-decoration.vm" and "mhtml-export-css.vm" files now you can put the same customizations into the docx template. These customizations are stored in blue boxes with title "Custom HTML" and "Custom CSS" title appearing when you click on them. The customized content can be a Velocity template. If you want to only extend - and not replace- the default template then keep the ${defaultTemplate} variable/placeholder, which will be replaced by the original content from the "mhtml-decoration.vm" or "mhtml-export-css.vm".

Following screenshot shows how to perform the same customization of the HTML tables inside the template:

Advanced styling and HTML rewriting

Advanced Word reporting: customizing Table-of-content and assigning Word style to wiki elements

Customizing the proofing language of the export documents

For example if you want to export content in German, then:

• Create a copy of the default template
• Open the copy template in Word, select all text, and change the proofing language as documented here
• Save the template and use it for German language exports