Rational Publishing Engine

It is available from codeBeamer 9.3.0 version.

Rational Publishing Engine Integration

IBM Rational Publishing Engine is an IBM tool for generating formatted documents.

RPE contains:

• Document Studio
• Document Builder

The following diagram shows the concept:

There are three components in this concept:

• Document Studio
• Document Builder
• codeBeamer

Document Studio

Document Studio is an IBM tool to create formatted document templates.

We can design, preview and generate documents in several formats. It supports the following output formats:

• PDF
• HTML
• Word
• XSL

How can we use codeBeamer in Document Studio?

Schema

First of all, codeBeamer provides the result schema to Document Studio. This schema can be added as data source in Document Studio.

With this schema we can create queries to obtain data from codeBeamer result.

For example: on the screenshot we can see how we can iterate over work items attributes:

Schema can be available for reports and tracker types and these can be downloaded from codeBeamer REST endpoints:

• Report schema URL - http://<codeBeamer-host>/cb/rest/rpe/schema/report.spr
• Tracker schema URL - http://<codeBeamer-host>/cb/rest/rpe/schema/item.spr?trackerId=<tracker-id>

It is available from codeBeamer 9.4.0 version.

• Reports schema URL - http://<codeBeamer-host>/cb/rest/rpe/schema/reports.spr

The schema is in JSON format.

Report Result

codeBeamer use reports to provide data to RPE. We should create a report and the report result contains the selected data.

codeBeamer provides REST endpoint to download report result. The result is in JSON format and the schema is the Report schema.

Reports Result

It is available from codeBeamer 9.4.0 version.

If we want to generate a document from more than one report result we can use the reports data source.

With this datasource we can iterate over reports. We can use the url attribute in a dynamic data source to obtain report results.

Tracker Item Result

In templates we can use dynamic data sources. With these we can add additional data to our document. For example: we can add a tracker schema as data source with link attribute of report schema. With this data source we can obtain all field values of an item.

Requirement tracker schema:

Dynamic data source:

We should create a template (.DTA file) with Document Studio and this will be used to generate documents. This file should be available for codeBeamer, so we can upload it to documents folder or share it on the network.

Document Builder

Document Builder is an IBM tool to generate documents with templates.

Document Builder contains the following applications:

• DGaaS web application
• RPENG web application

How can we use Document Builder?

To generate documents with codeBeamer we need DGaaS web application is available on network and configured in codeBeamer.

DGaaS endpoints are used by codeBeamer to generate documents. codeBeamer create document specification which contains the provided templates and send it to DGaaS. If the generation process is finished codeBeamer downloads the generated documents and provides these as attachments.

codeBeamer

codeBeamer provides a new RPE tracker type to support document generation with IBM RPE. This tracker contains the report items. Each report item contains the template, the selected report and additional information for generation. The report items can be grouped by folders and the result will be one generated document.

The tracker uses predefined fields to provide additional information for generation. These fields are set in templates as variables. We can add new fields to this tracker and these fields will be set in the selected template also.

If we want to generate documents from codeBeamer we should:

• create an RPE tracker
• create a report item
• set item fields, for example.: template, report and other custom fields
• start the generation by right click on a report item and select the Generate selected RPE report menu item from the context menu.

If the generation is started the status of the report item is updated to in Progress.

codeBeamer check the status of the generation process. If the generation is finished then the status of the report item is updated to Finished and the generated documents are added as attachment to this item.

Installation Guide

Use this step by step guide to configure RPE in codeBeamer.

Prerequisites

Rational Publishing Engine is installed on codeBeamer server or on different server. If we use different server the two servers must connect to each other.

DGaaS is installed on RPE server and it runs.

We can check DGaaS application with this URL: http://<dgaas-server>:<dgaas-port>/dgaas/debug

DGaaS debug screen:

RPE Home Directory

If RPE is installed on codeBeamer server then we can skip this step.

If we use a different server then we should copy home directory from RPE server to codeBeamer server.

The directory can be found at <RPE-installation-directory>\lib\api\examples\com.ibm.rational.rpe.examples\src\home.

Copy this folder to codeBeamer server.

Environment Variable

We need to create an environmental variable. Name of this is RPE_HOME. This variable should contain the IBM RPE installation path. If we use different server then this variable should contain the path of the RPE home directory which is copied from RPE installation.

Libraries

We need the following IBM JARs:

• com.ibm.icu_52.1.1.v201501240615.jar
• com.ibm.rational.rpe.core_6.0.6.v20180425_2102.jar
• com.ibm.rational.rrdg.core_6.0.6.v20180529_1851.jar
• org.eclipse.emf.common_2.10.1.v20150123-0348.jar
• org.eclipse.emf.ecore_2.10.2.v20150123-0348.jar
• org.eclipse.xsd_2.10.0.v20150123-0452.jar
• rcl_telelogic.jar
• Since codebeamer 22.04 (FELICITY) release, the org.mozilla:rhino.jar is also needed which can be downloaded from the Maven Repository. For RPE6, the usage of version 1.7.14 is advised.

Find these JARs at: <RPE-installation-directory>\lib

The com.ibm.rational.rrdg.core_6.0.6.v20180529_1851.jar file can be found at: <IMShared-installation-directory>\plugins

Copy the JAR files to codebeamer tomcat: CB\tomacat\webapps\cb\WEB-INF\lib

General XML Configuration

Configure the following RPE settings in Application Configuration

• DGaaS application URL and credentials
• checker job

A configuration example:

  "rpe" : {
    "checkerjob" : {
      "timeInSec" : 60
    },
    "dgaas" : {
      "authenticationMethod" : "",
      "url" : "http://<dgaas-host>:<dgaas-port>/dgaas",
      "username" : ""
    }
  }

Old general.xml configuration example:

<rpe>
    <dgaas url="http://<dgaas-host>:<dgaas-port>/dgaas" username="<user-name>" password="<password>" authenticationMethod="<auth-method>" />
    <checkerjob timeInSec="<seconds>" />
</rpe>

How to use RPE in codeBeamer

If RPE is configured in codeBeamer then we can start to work with RPE.

RPE Report Tracker

First of all, we need to create an RPE tracker.

Steps:

1. Go to trackers page
2. Click on the plus sign
3. Select RPE Report in Type field
4. Fill the name field
5. Fill the key (short name) field
6. Fill the description field
7. Click to save

Report Items

Now we can create report items.

Steps:

1. Click on the plus sign
2. Fill name field
3. Fill description
4. Click on the Save icon
5. On details panel on the right side fill the following fields:
   • Report - click into the field and select a report with artifact selector
   • Template - click into the field and select document template or paste template file URL
   • other fields - set custom fields, these fields are set in templates as variables

It is available from codeBeamer 9.4.0 version.

• Word Sytle Sheet - click into the field and select a word template file
• Generated At - click into the field and set the generation time
• Output - click into the field and select the generated output types

Click on the Save button

Note:

We can create folders and folders can contain one or more report items. If we want to use two or more templates for document generation just use folders as report items container.

Example for report folder:

It is available from codeBeamer 9.4.0 version.

The folder field values are the default values for the generation, so if we do not set the fields on the report items then these values will be used. (except: report field)

Start Document Generation

To start generation process just click on the selected report item or folder, right click on it and select the Generate Selected RPE Report menu item from context menu.

If generation is started we get an info message about it and the selected item status is updated to in Progress.

Download Result

Refresh the page and if the status of the selected item is updated to Finish then the generation is finished.

Now we can find the generated documents as attachments at the report item.

Just click on the documents.zip file and the download is started.