View
239
Download
1
Category
Preview:
Citation preview
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.
Recommended