This Wiki page describes outdated Word Export customization, which has been completely reworked in CodeBeamer 7.2. For customization of Word templates look at Customizing Word Export of Issues for Round-trip (CB 7.2+)

Customizing Word Export of Issues

Format of the exported file

The file that is actually exported for Word is not a native Word document, but an MHTML file that Word fully understands.

It consists of multiple so-called parts:

• The main part in the MHTML is a regular HTML document, this is the actual document body.
• The images referenced by the main HTML part are saved into additional parts, one part for each image.

Customizing the content: HTML and CSS

The content of the document body, the document header and the document footer are rendered from regular Velocity templates for easy customizability. Making modifications on the templates is totally similar to customizing the notification emails sent by codeBeamer. (Thus we strongly suggest that article, as well.)

It's important to understand that what you actually do is modifying an HTML template. You can use most of the HTML formatting capabilities (like colors, font weight, and borders), most of the HTML text constructs (like lists or tables), but not everything. For instance, floating <div>'s will not be understood by Word, as a floating block doesn't make much sense in a word processor.

You can also use CSS, with the same restrictions: exotic visualization, like drop shadows, will be ignored by Word.

The template files are located in the CB_HOME//tomcat/webapps/cb/config/templates/html directory:

Modify them, save them and export a new document. codeBeamer will pick up your changes immediately.

Word-specific fields

Another interesting feature is that you can use special, non-standard HTML fragments in the templates, which generate fields managed by Word.

You can, for instance, add this snippet to have an intelligent Word-managed TOC in your document:

<p class=MsoToc1>
<!--[if supportFields]>
<span style='mso-element:field-begin'></span>
TOC \o "1-3" \u
<span style='mso-element:field-separator'></span>
<![endif]-->
<span style='mso-no-proof:yes'>Please right-click and choose "Update Field" to initialize this field.</span>
<!--[if supportFields]>
<span style='mso-element:field-end'></span>
<![endif]-->
</p>

Or, you can insert this to have a "17 of 82" style page number (fully managed and recomputed by Word!):

Page <!--[if supportFields]>
<span class=MsoPageNumber><span style='mso-element:field-begin'></span>
PAGE
<span style='mso-element:field-separator'></span></span>
<![endif]-->
<span class=MsoPageNumber><span style='mso-no-proof:yes'>1</span></span>
<!--[if supportFields]>
<span class=MsoPageNumber><span style='mso-element:field-end'></span></span>
<![endif]-->&nbsp;of <!--[if supportFields]>
<span class=MsoPageNumber><span style='mso-element:field-begin'></span>
NUMPAGES
<span style='mso-element:field-separator'></span></span>
<![endif]-->
<span class=MsoPageNumber><span style='mso-no-proof:yes'>1</span></span>
<!--[if supportFields]>
<span class=MsoPageNumber><span style='mso-element:field-end'></span></span>
<![endif]-->

Examples

Modifying the page header and adding your company logo

Modify the "h1" paragraph in requirement-document-export-headerfooter.vm and add a new <img> element where it fits.

Adding further attributes to requirements

Modify this table in requirement-document-export-body.vm and add the fields you want to see in the exported document:

<table class="requirement-props">
	<tr><td class="field">Revision:</td><td class="value">3</td></tr>
	<tr><td class="field">Priority:</td><td class="value">${requirement.namedPriority.name}</td></tr>
	#if(${requirement.status})<tr><td class="field">Status:</td><td class="value">${requirement.status.name}</td></tr>#end
</table>

List of Objects/Entities available in the export context

This table lists the objects available in the velocity script above:

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.

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