OSLC API and POX Profile simplifies CLM traceability

Further to OSLC + POXProfile post, RPE 2.1 with CLM 6.0.2 simplifies the data source configuration; especially while configuring dynamic data source for traceability reports.

Use OSLC / Permanent link for configuring the data source URL without having to modify the URL manually or through JavaScript. This simplifies the data source configuration to a great extent as the Permanent / OSLC links are available to the user from the product UI.

Watch video, created by Dragos, on requirement (DNG) to use case design (DM) traceability document generation using Permanent / OSLC links from DNG and DM without having to go through building Rest URL.

No PhD required

CLM 6.0.2 comes with the server side implementation for the Plain Old XML profile or POXProfile. You can test this feature using one of the recent milestone builds.

Based on the name you might think “great, one more reporting “feature” that requires a PhD just to get a PDF of my data” but the Plain Old XML Profile is designed to remove much of the complexity associated with creating traceability documents in RPE.

In essence the POX profile allows a client (RPE, browser addon, curl etc) to request and receive Reportable REST XML from OSLC URLs. The feature is designed for document generation but you can use it whenever you need to access the XML representation of your data.

The image above shows using the POX Profile to get Reportable REST XML from DNG using the FireFox Poster addon. The is URL obtained from DNG’s “Share link” dialog.

For document generation this essentially means that URL manipulation or additional server requests are no longer required for following links. See below for examples. This in turn translates into simpler templates that produce documents faster.

The POX profile complements well using JRS as it simplifies fetching additional data attributes which are not available to JRS such as images and rich text. For such properties you need to request the data from the point product itself starting from the OSLC URLs returned by JRS.

Below are some examples of the document generation flows with and without the POXProfile.  Please note that the client side implementation is not available in the RPE GA but we are working on it.

Three useful QM templates

In the last week it so happened that I spent a lot of time working with RQM. I’ve created a number of templates in the process and I want to share the most interesting three here.

The templates were created and tested using CLM 5.0.2 and are available on the RPE Developer Works Wiki here.

How to print basic test plan information

Prints basic information about the test plan and its test cases. The test cases are retrieved using the efficient QM native filtering which allows RPE  to gets all the test cases associated with the test plan in a single request.

Note that the test plan data source has metadata information that allows the end user to select the test plan from a list rather than typing it.

How do dynamically get state labels for test plans, test cases etc

Prints the test plans and for each their state. The state labels are read from RQM instead of being inferred from the state identifier.

How to print the requirements from a requirement collection associated with a test plan

Prints basic information about a test plan and its linked requirements. The requirements are read from from the requirements collection associated with the testplan.

Traceability with DOORS 9 and RQM

Continuing the series of articles on the topic of creating traceability documents I have arrived at an interesting use case:  traceability from DOORS 9 and RQM.

In this article I will describe how to create a document with requirements from DOORS 9 and their associated test cases from RQM.

More traceability – following links from RQM

Continuing the series of articles on producing traceability documents from IBM CLM I will describe today how to follow links from RQM.

If you examine the RQM schema for testcase for example you will notice entries for workitems and requirements.

Click on the image to enlarge it.

With these properties it should be fairly straightforward to build a template that retrieves CM and RM data associated with the QM artefacts.

However if you run your report on a test case feed URL like https://giediprime:9443/qm/service/com.ibm.rqm.integration.service.IIntegrationService/resources/JKE Banking (Quality Management)/testcase?abbreviate=false there is no requirement or work item data in the document. And if you examine the XML returned by RQM for this request you will see that information is not present there either.

So what is the problem? The answer is in the Rational Quality Manager Reportable REST API Documentation.  For efficiency reasons RQM does not return the link information by default. If you want to create traceability documents you’ll have to explicitly ask for the link information using the calmlinks argument in the request URL.

Which means that the right URL to use in the RPE docspec will look like this https://giediprime:9443/qm/service/com.ibm.rqm.integration.service.IIntegrationService/resources/JKE Banking (Quality Management)/testcase?abbreviate=false&calmlinks=true

Note that the URLs to RTC and DNG are OSLC links and you will need to convert them to Reportable REST API URLs before fetching RM and CCM data.

Examples showing how to follow links from individual testcase or from a test case feed are available in the RPE DevWorks – Cross Domains Templates Wiki.

Accessing individual workitems through RTC’s Reportable REST API

When accessing individual RTC work items through the reportable REST API there are two ways of going about it.

Embed the work item ID in the URL as a filter

https://giediprime:9443/ccm/rpt/repository/workitem?fields=workitem/workItem[id=36]/(description|summary|severity|state)

Embed the work item ID in the URL as  a path segment

https://giediprime:9443/ccm/rpt/repository/workitem/workItem/id/36?fields=workitem/workItem[id=36]/(description|summary|severity|state)

Using the ID in the path segment is especially convenient when following links to RTC as it allows to convert the OSLC URL to Reportable REST without requiring additional variables and native filters as described in Assemble traceability documents from reusable building blocks.

• OSLC URL:  https://giediprime:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/36
• Reportable REST URL:
  https://giediprime:9443/ccm/rpt/repository/workitem/workItem/id/36

Adding Quality Management data to the traceability mix

Continuing the Assemble traceability documents from reusable building blocks I want now to add QM data in the mix. I will be using the same DM model as a starting point and I will follow links to QM Test Cases.

As you read this I  recommend also going through Geoff Rosenthal’s the excellent Rational solution for Collaborative Lifecycle Management Traceability Templates with Rational Publishing Engine tutorial.

The artefacts for this tutorial are available on the Unclassified & Cross Domain Templates section of the RPE Wiki Community at #15  DM to CLM Traceability.

Getting the DM link information is already covered in  Assemble traceability documents from reusable building blocks so I will skip it here. This article starts from the point where you have your DM and DM link data in place in your template.

How QM linking works

But before I go there I want to explain how QM linking works and what are the various schemas you will encounter in the process.

QM, just like all the other CLM products has an OSLC API that is used for linking. A QM Test Case will be referenced from another product using a URL that looks like this:

https://giediprime:9443/qm/oslc_qm/contexts/_cmIwsHceEeW6EPQMMno5Bw/resources/com.ibm.rqm.planning.VersionedTestCase/_sF1Y4XceEeW6EPQMMno5Bw

For the example I am presenting you can get these URLs from the link page of the DM artifact.  And if you access these URLs from a tool like Poster and specify “application/xml” for the “accept” header you can see the data available. One thing you will notice is that even though the data is not in the form you are used to when reporting on QM with RPE which is the QM’s Reportable REST API.

Unlike DNG there is no way to convert from the RQM OSLC v2 URL to the Reportable REST URL but for QM the OSLC representation of the QM artifact contains the link to the RQM Reportable REST URL.

So to get from the OSLC URL to the Reportable REST URL you firsy need to access the OSLC resource, read the Reportable REST URL and then accesses the data there.

How QM linking works – TL;DR version

When you want to access linked QM data you need to:

1. access the OSLC representation of the artifact
   • you need to use RPE’s Reportate REST v2 schema discovery to find the schema form QM’s OSLC representation. The starting point for the schema discovery process is https://server:port/qm/oslc_qm/catalog
2. read the URL to the Reportable REST representation of the QM artefact
3. access the Reportable representation of the artefact
   • you need to add the QM schema which is available at https://%5Bhost%5D:%5Bport%5D/qm/service/com.ibm.rqm.integration.service.IIntegrationService/schema/qm.xsd
4. Use the data as needed

Suggested reading:

1. RQM OSLC v2 REST API – for linking data
2. RQM Reportable REST API – for document generation

Get linked QM Data from DM

1. Insert the QM_TC_Snippet.dta in the indicated position
2. Edit the condition on the QM Container such that you are only processing QM Data. I have used the “link type” property  to only accept “Validated By” links
   
3. Connect the QM snippet to your template by specifying
   1. A data source to have the QM_OSLC_TC inherit from
      
   2. The data property that holds the OSLC QM URL
      
4. Make a test run to verify all the pieces fit together. Just like with the RTC example you only need to specify the entry point and credentials for accessing the DM UML project.
   

NOTE: You will need to replace the QM schema from my snippet with your particular QM schema so that you can use the custom attributes defined in your particular QM instance.

Conclusion

You now have 2 RPE snippets for accessing RTC and QM linked data that you can reuse in your traceability documents. I recommend evaluating your existing templates to identify other sections in your templates that you use on a regular basis and transform them in reusable snippets.

Assemble traceability documents from reusable building blocks

When building a template you can take advantage of the reuse capabilities that RPE Template and Document Studio provide.  You can use this for any documents and traceability documents are a great candidates since they usually involve the same steps over and over again:

1. Read the data from Product A and print the details you need
2. In the data of Product A find the links to data in Product B
3. Read the data from Product B and render it
4. …

The above is the outline of any 2 source traceability report and steps 2 and 3 are almost identical for all reports so they can be packaged as blocks to be reused as needed.

To show this I have created a document with DM and RTC data. The artifacts I use in my example are available on the Unclassified & Cross Domain Templates section of the RPE Wiki Community at #15  DM to CLM Traceability.

How to follow links from DM to DNG

In this article I describe how to generate a document with RPE that contains DM resources and their linked DNG requirements. While the example uses DNG as a target the technique is applicable to other CLM sources or even DOORS 9 with slight changes.

Credit: thanks to Kevin Cornell for his excellent DM Reporting Tutorial .

How it works

Unlike other Rational data sources links are not stored in the representation of a DM resource. This means that if you request the Reportable REST representation of a Package there will be no links inside it. The links are stored separately and access via the the “collaboration/links” Reportable REST URI.

So in order to build a document that contains DM resources and linked requirements you have to perform these 3 steps:

1. retrieve the DM resource.
2. retrieve the links for the DM resource
3. access the linked artifacts

The anatomy of the template reflects these 3 steps:

I will skip step 1 and describe step 2 and 3

#2 Retrieve the links for a DM resource

The links for a DM resource are retrieved from the the collaboration/Link service. The dmResourceID and the dmContextID properties are available in the resource you’ve got at step 1.

https://server:port/dm/reporting/collaboration/Link?referencingId=<dmResourceID>&rmps.context=<dmContextID>

#3 Access the linked artifacts

Now that you have the link href all you need to do is access the information. Assuming all the links are for DNG text artifacts all you need is to convert the OSLC URL stored in DM to a Reportable REST form using a script like this and then access the DNG data through a Dynamic Data Source.

href.replace("resources/","publish/text?resourceURI=")

Reusing the template

The template is available on the Modelling Templates Page of the RPE DevWorks Wiki and is provided also as a reusable snippet. See the attachments section for:

• DM Links for Package Diagrams Example
• DM Links Snippet

Once imported in your template you connect your code to the snippet by adding code to set the baseURL, dmResourceID and dmContextID in the “add code here” Java Script block.

Creating traceability documents with RPE and JRS

If you have ever had to generate a document that contains Requirements, the Test Cases that validate them and the related work items you’ve most likely ended up using (at least) 3 different data sources and you’ve had to use Java Script to switch between APIs.

Aside from a complex design, the performance of the report wasn’t that great as RPE had to crawl over all the data sources to fetch the required data.