You are not logged in. Click here to log in.

codeBeamer ALM

Search In Project

Search inClear

Tags:  not added yet
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:

requirement-document-export-body.vm Specifies the body content for the document.
requirement-document-export-headerfooter.vm Specifies the document header and footer. The header and the footer
requirement-document-export.vm Specifies the "skeleton" of MHTML. It's very unlikely that you will ever modify it.

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

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>
<span style='mso-element:field-separator'></span></span>
<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>
<span style='mso-element:field-separator'></span></span>
<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>


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">${}</td></tr>
	#if(${requirement.status})<tr><td class="field">Status:</td><td class="value">${}</td></tr>#end

List of Objects/Entities available in the export context

This table lists the objects available in the velocity script 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
requirements SortedMap<ReleaseId,TrackerItemDto> requirements as TrackerItemDtos grouped by release-ids
incomingReferencesByIssue, outgoingReferencesByIssue Map<Integer, Map<String, List<IdentifiableDto>>> Map contains for each requirement's id the incoming or outgoing associations from/to that requirement. Important: these are not the referenced issues via reference fields, but the associations between other issues in the system.

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