Page | 1

Using IBM Rational Publishing Engine to Using IBM Rational Publishing Engine to Using IBM Rational Publishing Engine to Using IBM Rational Publishing Engine to

generate compliance relevant reportsgenerate compliance relevant reportsgenerate compliance relevant reportsgenerate compliance relevant reports

AdvancedAdvancedAdvancedAdvanced Reporting for Reporting for Reporting for Reporting for IBM IBM IBM IBM Rational DOORS Next Rational DOORS Next Rational DOORS Next Rational DOORS Next

GenerationGenerationGenerationGeneration

Dr. Einar W. Karlsen

Solution Architect

Draft Version

2015.03.01

Abstract: This article is the sixth in a series of several articles the use of IBM Rational

Publishing Engine to generate compliance relevant reports. This previous article covered

basic reporting using IBM Rational Publishing Engine to generate requirement

management documents for IBM Rational DOORS Next Generation. This article

continues with more advanced concepts such as extraction of diagrams and generating

reports that extract information out of Rational Quality Manager and Rational Design

Manager following OSLC links associated with requirement artifacts.

Page | 2

Introduction The previous article on IBM Rational DOORS Next Generation document generation

using the IBM Rational Publishing Engine basically just considered two kind of artifacts:

headings and text requirements. This is of course an oversimplification. Modules may

reference use case diagrams, UI sketches or process diagrams – just to mention a few –

and this feature sets the scene for creating very rich documents (as shown in the left part

of Figure 1).

However it does not stop here. The fundamental concept of the Jazz platform viewing the

universe of discourse as a set of linked objects makes it possible to link requirement

artifact to other lifecycle artifacts such as design diagrams, design elements or test cases

and test plans. Rational Publishing Engine may therefore use such links to generate cross

tool reports. An archetypical example is a table showing requirements and their associated

test cases and design elements as shown in the right half of Figure 1.

Figure 1. Multi-source and traceability reports

In this second article you shall mainly be introduced to the concepts and techniques

required to generate documentation including diagrams from Rational DOORS Next

Generation as well as cross traceability reports. We shall start with the diagrams first and

then continue with reporting on links next.

Page | 3

Generation of documentation including diagrams Rational DOORS Next Generation offers a number of diagrams that could typically go

into a requirement management document such as use case diagrams, user interface (UI)

sketches or business process modeling diagrams. Such diagrams can be included into a

module and we would then expect the diagrams to appear in the generated document as

well. The article will show you how you can extract user interface sketches as an example,

but extraction of the other diagrams is in principle similar. You will need to import the

associated schema first from the REST service, using an URL on the form:

https://clmserver:9443/rm/publish/uisketches?metadata=schema

The left half of Figure 2 shows you the most import queries for the imported UI sketch,

namely the section aggregatedContent that contains a uisketch/rendering query to

extract the diagram as a bitmap. There are other queries in this section to extract

information about the individual widgets but they are not important for now.

Figure 2. Schema for sketches and module context bindings

When introducing UI sketches you will need to distinguish between the various formats of

the artifacts in the template: the document shall look differently depending on whether the

referenced element is a requirement, UI sketch or use case diagram (say), and different

kind of logic is required for the simple reason that the underlying schemas are different

when it comes to rendering content. The schema for modules shown in the right part of

Figure 2 contains a query named format that delivers exactly this information.

Page | 4

Figure 3. Template fragment for extracting sketches

The template fragment for extracting documentation regarding UI sketches is shown in

Figure 3. Each element in a module is represented by a module context binding. See for

example query $2 in Figure 3 that iterates over all module bindings, and then cases out to

different template fragments depending on whether the artifact format is a sketch or a

text requirement (see the condition in Figure 3). This schema requires however version 5

of Rational DOORS Next Generation). With version 4.0.6 of Rational DOORS Next

Generation) it would be necessary to retrieve the format for the corresponding resource

using an URL on the form:

https://<server>:<port>/rm/publish/resources?resourceURI=<resourceURI>

This in turn would require an additional dynamic data source connection

Having determined the format, you can then to retrieve documentation for text or UI

sketches. For UI Sketches it is necessary to convert the URL to the user interface into a

reportable URL on the form:

https://<server>:<port>/rm/publish/uisketch?resourceURI=<sketchURI>

Page | 5

The reportable URL is computed in the first Java Script element and assigned to the

variable _ElementURL, which in turn is used to configure the dynamic data source

connection bound to the schema RRC UISketches. At document generation time this will

lead to a request to the REST service to deliver the data for the given UI sketch. Next

follows a query ($48) that iterates over all returned artifacts (there will be exactly one).

For this artifact, the rendering the UI sketch is extracted using the following query:

dataSource/artifact/aggregatedContent/uisketch/rendering

This completes the simple template fragment for extracting UI sketches.

Traceability Reports Requirement management reports are typically in either book format or table format. The

previous reports that we have seen have been all been in book format with headings and

requirement text. Another archetypical report format for requirements is table format, and

according to this style the requirements are simply listed in a table where the columns

typically contain information such as requirement identifier and title followed by e.g.

attributes and links.

Figure 4. Template for traceability table

One template for generating a report in table format is shown in Figure 4. It just iterates

over the module bindings in a module creating one table row for each binding. There are

columns for the identifier, title, associated design elements and associated test cases. The

template follows OSLC links to requirement artifacts, design elements and test cases with

the purpose to extract information about these linked artifacts, i.e. it is essentially a

Page | 6

traceability report. The template is quite simple: it just iterates over all module bindings

($3), computes the URL to be used in order to extract the corresponding text element and

assigns the URL to the variable _ElementURL. Then it configures the dynamic data

source connection that will at runtime cause the details for the text artifact to be fetched

form the REST service. For that artifact ($4) the identifier, title, design elements and test

cases are extracted in different table columns. Figure 4 just shows the first two columns,

but we shall look into the remaining two next, which implies reporting on information

managed by Rational Software Architect Design Manager and Rational Quality Manager.

Schema for traceability links

The left part of Figure 5 shows you the schema for traceability links. There is one section

for each link type. The link type DerivedLink is used to trace to design artifacts, whereas

the link type ValidatedBy (not shown in the figure though) is used to trace to test

artifacts. The section contains the query named relation to determine the target of the

OSLC link, as well as queries that determine the identifier and the title of the target

object. This means that simple traceability reports that need just this information can be

done without querying the target of the link for more information. We shall look into this

simple case first.

Figure 5. Schemas for traceability links

Simple Solution using local traceability link information

The template fragment in Figure 7 shows you the table cell and key logic for retrieving

information related to the derived design artifacts (the 3rd column in the traceability table

in Figure 4).

Page | 7

Figure 6. Template using local traceability link information

It extracts the identifier of the linked design object – be it an UML diagram or element -

followed by the title of the same. The latter is achieved using the query

DerivedLink/content/title.

If you want to report on internal Rational DOORS Next Generation links it is not that

much different. The link will however be of another type (Embeds, References or Link

say) meaning that other queries in the traceability section must be used. However, the base

information can be retrieved as shown above. If more information is needed you should

just use a dynamic data source connection as has already been shown in Figure 3.

Depending on the information needed you can then decide whether you want to connect to

the schema for resources (generic information) or to the individual formats such as text,

UI sketches etc.

Following links to Rational Quality Manager When you want to develop templates following traceability links from requirements to test

artifacts, it is important to know that links from Rational DOORS Next Generation into

Rational Quality Manager are stored as links into the OSLC interface of Rational Quality

Manager – and not as links into the Reportable REST API. The URLs are on the form:

https://clmserver:9443/qm/oslc_qm/contexts/_txayIKw8EeOxT4j25FCN0g/resources/com

.ibm.rqm.planning.VersionedTestCase/_sR7f4aw9EeOxT4j25FCN0g?

There is consequently one technicality involved in reporting into Rational Quality

Manager since the links are URLs into the OSLC interface rather than URLs into the

reportable REST service of Rational Quality Manager. It is therefore necessary to query

the OSLC interface first to get the URL link to the reportable REST interface, and once

this is done to retrieve the linked test artifact using this URL. Two dynamic data source

connections are therefore required.

The template fragment in Figure 7 is significantly more complex than the template in

Figure 6 and shows the key logic in following OSLC links from Rational DOORS Next

Generation to Rational Quality Manager. The template starts by iterating over all

validatedBy links ($13) of the text artifact. It then uses two dynamic data source

connections to get hold on the test case. The first data source connection uses the relation

query to get hold on some OSLC related data for the test case using the schema named

OSLC REST v2.1.

Page | 8

Figure 7. Following OSLC links to Rational Quality Manager

Next a query RDF/TestCase/Relation is used to determine the URL of the reportable

REST service for the test case ($10). This URL is in turn used to configure the second

dynamic data source connection for the Schema RQM TC. Using this schema it is

possible to retrieve the details of the test case ($11) such as the webId and the title

(amongst others).

You can find more information on how to report into Rational Quality Manager in the

article by Geoff Rosenthal. This article also describes how to get hold on the OSLC

schema using the wizard. Basically, you can use the schema discovery wizard for REST2

schemas as shown in Figure 8. The steps are:

• Define Base URL, select Form authentication and provide user credentials

• Select REST v2 service provider project area

• Select query capability, i.e. test case, test plan etc.

• Select properties to be available in the schema (identifier and relation)

The Base URL is https://<server>:<port>/qm/oslc_qm/catalog.

Page | 9

Figure 8. Retrieving the OSLC schema

Following links to Rational Design Manager Suppose that the information directly available in Rational DOORS Next Generation for

traceability links to Rational Design Manager would not be enough, but the template

would require more information about the design elements such as the diagrams or the

properties of the design elements. In this case, you would need to navigate links from

requirements to model elements.

Technically, this means that you will need to analyze the links provided by Rational

DOORS Next Generation and make sure that they are brought on a form where they can

be used for reporting. The URLs that Rational DOORS Next Generation maintains to

reference design elements are links into the user interface, i.e. they are on the form:

https://clmserver:9443/dm/models/1711

URLs needed for reporting on design elements are however more rich: they contain

information about the type of the UML element as well as the current context in form of

project and workspace, for example the URL for a diagram:

Page | 10

https://clmserver:9443/dm/reporting/uml/UMLDiagram?name=<name>&id=<UI

URL>&project=<project>&workspace=<workspace>&rmps.context=<context>

It is therefore not possible to link directly from Rational DOORS Next Generation into

Rational Design Manager when developing reports. Fortunately, this does not pose a real

problem. The issue can be solved by defining an additional data source in the template that

connects to a Rational Design Manager project and workspace. This data source will then

define the missing context.

In a next step you will need to deal with the schemas that Rational Design Manager

provides for reporting on links related to an object. Rational Design Manager keeps

separate data resource providing information about incoming and outgoing links and all

that needs to be done is to query this data source for the design elements linked to a

specific requirement. The resource has the base URL on the form:

https://clmserver:9443/dm/reporting/collaboration/Link?project=<project>....

Figure 9. Rational Design Manager schemas

The corresponding schema for collaboration links is shown in the left part of Figure 2.

Conceptually it can be viewed as a binary relationship with one part designating the

requirement artifact (the object) and another part designating the UML element (the

subject). The proper URL for the UML element can then be retrieved by the query

subject.href. From there one can use a dynamic data source connection bound to the

Page | 11

schema DM UMLDiagram to get hold on the image and other properties of the diagram

such as the title or Description (see right part of Figure 9).

There is one missing step now: to determine the links that are relevant for a specific

object. In theory that could be done by iterating over all links until a link is found where

object.href matches the requirement artifacts about property. However, such a solution

would not scale in context of large amount of data. Fortunately, Rational Design Manager

offers a query that would allow us to filter on those links that are relevant for a specific

requirement artifact. The filter has the form:

&fields=dm/LinkList/Link[object/resourceID=’<resourceURL’]/*/*

It should be noted that other filters may be defined as well taking other parameters as

scope such as e.g. link type or subject.

Figure 10. Following OSLC links to Rational Design Manager

Figure 10 shows how to extract diagrams from Rational Design Manager for a

requirement artifact. First, it is checked if the artifact has derived links at all ($66). If this

Page | 12

is the case (HasElements is true), the base context for collaboration links is determined

next ($71) and assigned to the variable _BaseContextURL. A second JavaScript code

element has been defined to compute the URL that will retrieve all collaboration links of

the current requirement artifact. This URL is assigned to the variable _LinkURL and the

data source DM CollaborationLinks is configured next using _LinkURL as the URI.

For each link returned ($72), the subject is retrieved ($73). A condition has been defined

to ensure that only UML diagrams are further processed by checking if

“dm/reporting/UMLDiagram” is part of the URL (href) of the design object. If this is

the case, a dynamic data source connection bound to the schema DM UMLDiagram will

be used to retrieve the UML diagram at runtime. Finally the image is extracted.

Defining proficient documents Modules can be used very efficiently to generate a compliance relevant document exactly

up to the point with the required subsection and artifact formats and types – provided of

course that the right usage model has been established in Rational DOORS Next

Generation first. You can define specific kind of requirement types and then use Rational

Publishing Engine to control the exact layout and content on a per type basis.

Suppose that you would like to include document references at the end of each module.

You could of course define the document references as text artifacts with a table in the

rich text body defining the title, edition, year etc of the document reference. With such a

solution it is however difficult to introduce a standard layout within a large community of

users: each user would have free hands to change the layout. Moreover, it would be

difficult to let Rational Publishing Engine take over the responsibility for ensuring a

uniform appearance of the tables in the document since the data would be embodied in

XHTML.

A better solution would be to have custom attributes such as Author, Edition and Date

defined for the document reference. The Id and the Title of the document references are

represented by the corresponding standard properties of the requirement artifact.

The template in Figure 11 shows how these two standard attributes are extracted into a

table where the titles are in the first column and the values in the second. The extraction of

the custom attributes for the artifact follows the same solution pattern as described in the

previous article. Notice that with the appearance of document references we have

introduced a new text requirement type named “DocumentRef” with a different

presentation in the document. The template must therefore distinguish between regular

text requirements such as e.g. use case requirements and document references. A simple

condition using the artifact type query has been used to achieve this.

Page | 13

Figure 11. Template for extracting document references

Conclusion The article has covered fundamental concepts of reporting for Rational DOORS Next

Generation like the schemas, the URLs and basic reporting for modules, including

extraction of headlines, requirement text and requirement attributes. It has also

demonstrated how Rational Publishing Engine can be used to pass information from

Rational DOORS Next Generation to Microsoft Word using Word document properties,

which in turn can be used in company specific headers and footers.

Acknowledgement I would like to thank Geoff Rosenthal for pioneering some basic techniques for

Collaborative Lifecycle Management reporting.

Resources

• G. Rosenthal: Rational Solution for Collaborative Lifecycle Management

Traceability Templates with Rational Publishing Engine, Jazz.net Article 1241,

www.jazz.net/library/article/1241, October 2012.

• K. Cornell: Tutorial: Design Management Reports, Jazz.net

https://jazz.net/wiki/bin/view/Main/DMReportTutorial, September 2012.

• Creating and configuring Rational Publishing Engine reports in the Requirements

Management (RM) application, Jazz.net,

https://jazz.net/wiki/bin/view/Main/RRCCustomRRDGReportsWalkthrough

• Find an entry point to more information at the developerWorks main page for the

“IBM Rational Publishing Engine”.

Page | 14

• To learn more about the IBM Rational Publishing Engine, visit the “IBM Rational

Publishing Engine Infocenter”.

• For tips, tricks and sample templates, visit the “Rational Publishing Engine

Community Wiki” at developer Works.

• For additional tips and tricks, visit “Rational Publishing Engine Actual”.

• Gather more information for the Reporting Area Web Publisher.