Rational solution for Collaborative Lifecycle Management Traceability Templates with Rational Publishing Engine
This article and the accompanying Rational Publishing Engine templates describe at a high level the required template elements and the configuration of those elements for traversing Collaborative Lifecycle Management (CLM) traceability links in a report document produced by Rational Publishing Engine. The point of this asset is to describe the basic pattern to print the related CLM artifacts of a requirement in Rational Requirements Composer, a work item in Rational Team Concert, and a test case in Rational Quality Manager. This document does not cover formatting; instead, it focuses on how to extract the data.
Note that this document assumes that the reader has working knowledge of Rational Publishing Engine and the IBM Rational Collaborative Lifecycle Management tools as well as their APIs. For more information on using the CLM tools with Rational Publishing Engine reporting, see the following resources:
- Rational Requirements Composer wiki on Jazz.net
- Rational Team Concert wiki on Jazz.net
- Rational Quality Manager wiki on Jazz.net
Samples are provided for each of the three CLM tools. The sample labeled “RRC_CLM_traceability” was created for iterating over all requirements in Rational Requirements Composer and printing each the linked work items (WIs) and test cases (TCs) for each requirement. The sample labeled “RTC_CLM_traceability” was created for iterating over all work items in Rational Team Concert and printing each the linked requirements and test cases associated with each work item. The sample labeled “RQM_CLM_traceability” was created for iterating over all test cases in Rational Quality Manager and printing each the linked requirements and work items associated with each test case.
Comparing releases of the Rational solution for Collaborative Lifecycle Management
The June 2011 release of the Rational solution for Collaborative Lifecycle Management (CLM) included the 3.0.1 versions of Rational Requirements Composer, Rational Team Concert, and Rational Quality Manager. The June 2012 CLM release provided the 4.0 versions of these same CLM products.
These templates were originally created with the products that shipped in the June 2011 CLM release, but in this most recent release of the samples, the templates were validated against the June 2012 CLM release, including the 4.0 versions of the CLM products. This document and the accompanying templates are expected to work with the 3.0.1 versions of the CLM products. The only difference between the 3.0.1 and 4.0 versions of the products that would affect these templates is the security authentication updates that were made to Rational Requirements Composer 4.0. You can read more details about the updates in the following FAQ document: https://jazz.net/wiki/bin/view/Main/RRCReportServiceFAQ#Why_I_can_not_generate_reports_f
If you are using Rational Requirements Composer 3.0.1, remove the “OAuth1a” authentication type from the various Rational Requirements Composer data sources in the accompanying templates to address the security change.
General dynamic data source configuration setup
All of the provided samples have been set up so that each template has one top-level data source and all of the subsequent data sources inherit the credentials of that first data source. Thus, for each template, as long as the provided Jazz Team Server credentials have access to all three tools, the end user only needs to provide the URI, user ID, and password in the top-level data source. The top-level data sources are as follows:
- RRC_CLM_traceability – “Text_rm”
- RTC_CLM_traceability – “WorkItem_ccm”
- RQM_CLM_traceability – “TestPlan_feed”
These samples are based on the JKE Banking sample projects; however, the templates were created to work in any CLM project as long as they have the appropriate links. The URIs for the data sources are as follows:
- RRC_CLM_traceability – Any Rational Requirements Composer resources URI that returns resource-based or text-based artifacts
- RTC_CLM_traceability – Any Rational Team Concert work item URI that returns artifacts based on work items
- RQM_CLM_traceability – Any Rational Quality Manager test plan URI that returns a test plan feed
Generating an output document
Once you have set up your document specification with the appropriate URI and credentials as explained in the previous section, you can generate your output documents by using the Generate Document button or menu selection. Since you only need to provide a URI and credentials for the top-level data source, the other data sources in the specification will remain in red-colored text. When you generate, you will get a warning message that looks like the following screen capture:
Click Yes to ignore the warning and continue with the document generation. The properties in the template have been set dynamically, so it is likely that not all of the data sources will have the configuration properties filled in under the document specification. Thus, you can ignore this warning message.
CLM traceability from a Rational Requirements Composer requirement to a Rational Team Concert work item
In the provided sample, CLM traceability is shown from the basic Rational Requirements Composer “text” artifact schema. In Rational Requirements Composer, a link to a Rational Team Concert work item is stored in the dataSource/artifact/traceability/links/ImplementedBy/relation query.
Traversing the work item link “ImplementedBy”
The desired attribute is the “relation” attribute. This attribute returns an href to the related work item artifact in Rational Team Concert. The href is not stored in a format to return the artifact from the Rational Team Concert Reportable REST API, and so the href must be parsed.
In the provided sample, the URI in the document specification for the “Text_rm” data source is the resource query for a specific project. The resource query will return resource-based artifacts, such as requirements of all types, actors, use cases, and requirements collections. It is possible for the ImplementedBy attribute to store hrefs in different formats for different relationships, thus your template must account for these differences by either filtering your URI in the document specification or, as in the provided sample, first checking to make sure that the relationship is the desired href that can be used in the rest of your template (noted in the following screen capture as the container in the black box).
In the sample, in the variable assignment on the “Print WI links” container, the relation attribute is parsed with JavaScript to the proper Rational Team Concert REST API query format for a work item and assigned to the template variable “WI_href”. If the href is not a work item href, the variable is assigned to the exit value of “-1”. If the href is to a work item, the dynamic data source (DDSC) configuration element is used to traverse to the related work item. The DDSC element uses the work item schema from Rational Team Concert and the href in the template variable is assigned to the dynamic URI property.
For more information on the script that was used to parse the Rational Team Concert href returned by Rational Requirements Composer, see the later section for traversing from a Rational Quality Manager artifact to a Rational Team Concert artifact. A similar script was used in that sample.
CLM traceability from a Rational Requirements Composer or Rational Team Concert artifact to a Rational Quality Manager artifact
Note: An explanation of how to find the appropriate links in the Rational Team Concert auditableLinks node is provided in a later section. In the Rational Team Concert references in this section, the assumption is that you have already traversed the auditableLinks node and you have the appropriate Rational Quality Manager Open Services for Lifecycle Collaboration (OSLC) v2 href.
To traverse from either a Rational Requirements Composer artifact or a Rational Team Concert artifact to the related Rational Quality Manager artifact requires use of both the Rational Quality Manager OSLC v2 API as well as the Rational Quality Manager Reportable REST API. As you might infer, Rational Publishing Engine usually connects to the Rational Quality Manager Reportable REST API (this is what Rational Publishing Engine typically supports with Rational Quality Manager). However, the href that is stored in Rational Requirements Composer and Rational Team Concert from an artifact to a Rational Quality Manager artifact is the OSLC v2-based href. The OSLC v2 API is not as fully functional as the Reportable REST API, so we must convert from the OSLC v2 API to the Reportable REST API to get at most Rational Quality Manager artifact attributes.
Note: Feel free to explore the Rational Quality Manager OSLC v2 API in greater detail. If the attributes that you want to print are actually in the Rational Quality Manager OSLC v2 API, then simply use those attribute queries as opposed to having to traverse over to the Reportable REST API.
The solution is to first traverse to the OSLC v2 API using a discovered schema, then traverse from the OSLC API to the Reportable REST API using the Rational Quality Manager standard “qm” schema so that the template can print any required details of the Rational Quality Manager artifact.
Discover an OSLC v2 schema
We can use the RPE REST v2 Schema Discovery wizard to create a schema in our template. We will choose to add only the attribute queries that we are interested in, such as the “relation” attribute that stores the Reportable REST URI of a given artifact.f
Note: This documentation will create a schema with only the “relation” query because that is the query that must be used to complete this exercise. Feel free to explore the various queries that are included in the OSLC v2 API. Note that the more queries that are added to a schema, the more data that will be pulled from the API in a request. Thus, the number of queries that are selected will impact performance.
- To start the Schema Discovery wizard, click Data->Schema Discovery->REST v2 Schema Discovery.
- Enter the base URL to your OSLC v2 API resource shapes (for example, discoverable Rational Quality Manager artifact schemas) on your Rational Quality Manager server. The base URL will be of the following format:
https://<server></server><port>/<QM context="" root="">/oslc_qm/catalog</QM></port> - You will also need to provide the authentication type and credentials to your Rational Quality Manager server. Consult your Rational Quality Manager administrator if you don’t know what these settings should be. Click
Next.
- On the REST v2 Service Provider Selection page, select the Rational Quality Manager project that you will be publishing documents from. It is possible for different projects to have different catalogs. For example, different Rational Quality Manager projects could have different custom attributes.
- Select a service provider and click Next.
- On the REST v2 Service Selection page, expand the various nodes and select the Rational Quality Manager artifact type that you want to print from. In the rest of these steps, we will use the “TestCase” service because the sample covers artifacts linked to test cases, but the other artifact types could just as easily be selected.
- Select the Default query capability for TestCase capability and click Next.
- On the REST v2 Properties Selection page, select any attributes that you want to be included in the schema that will be created. In this example, we are only interested in the “dcterms:relation” query, so check that query. We also included the “dcterms:identifier” query for debugging purposes, but this query is not required. As previously mentioned, this is the page of the wizard where you could choose to add more queries to the schema that is being created.
- Select the Support oslc.select and Support oslc.properties check boxes because Rational Quality Manager does support both of those properties. If you click the Test button next to either of those properties, expect a pop-up window with valid XML returned from your Rational Quality Manager server. Click Next.
Note: For more information on the various OSLC v2 query parameters, see: http://open-services.net/bin/view/Main/OSLCCoreSpecQuery#Query_Parameters
- Leave the default settings on the rest of the various wizard pages and complete the wizard by clicking Next and then Finish.
You should now have a schema in your template for the OSLC v2 artifact type with the attributes that you selected.
Switch over to the Launcher and select the REST v2 data source that you just added. Delete the data source URI and credentials that were filled in. We will dynamically configure those properties later on. Leave the rest of the settings for that data source unchanged.
Print Rational Quality Manager artifact details
To print the details of a Rational Quality Manager artifact, the template must use two DDSC elements. The first traversal is from the OSLC href stored in either Rational Requirements Composer or Rational Team Concert to the Rational Quality Manager OSLC API. The second traversal is from the OSLC implementation of the artifact in Rational Quality Manager to the Reportable REST href that is stored in the OSLC version of the artifact. Once the template locates the Reportable REST URI, you can use the standard Rational Quality Manager “qm” schema to print the details of the artifact as you would in any Rational Quality Manager template for Rational Publishing Engine. Note that no href parsing is required (as is done for work item hrefs) because the OSLC or Reportable REST hrefs that are stored in the tools can be used unchanged.
The next screen capture is from the RRC_traceability sample. In Rational Requirements Composer, a link to a Rational Quality Manager test case is stored in the dataSource/artifact/traceability/links/ValidatedBy/relation query. In Rational Team Concert, a link to a Rational Quality Manager test case is stored in the workitem/auditableLink/targetRef/uri query (see the later section for more information on using auditableLinks in the Rational Team Concert schema).
In your template, under the context of the Rational Quality Manager OSLC test case query (such as “ValidatedBy” in Rational Requirements Composer or “targetRef” in Rational Team Concert), add a DDSC element and set the dynamic configuration properties to the appropriate Data Expression. Also, set the inherited data configuration property to the top-level data source so that the end user does not have to provide credentials for this data source in the document specification. In the provided examples, the OSLC v2 schema for test cases is called “VersionedTC”.
Important: You must set the “oslc” properties as shown below and the correct authentication type or your document generation will fail.
Once the template has traversed to the discovered OSLC v2 schema, add another DDSC element and traverse to a “qm” schema as you normally would in any Rational Publishing Engine template for Rational Quality Manager. The DDSC element URI should be set to the Data Expression query of testcase/relation/resource. Finally, add template elements as needed from the test case node of the qm schema as you normally would.
CLM traceability from a Rational Quality Manager artifact to a Rational Team Concert work item
In several Rational Quality Manager artifacts, there are a number of places where a link to a related artifact in Rational Team Concert is stored. For example in the QM schema, the “testcase” node has a subsection for “workitem” and the “executionresult” node has a subsection for “defect”. The “href” query in these subsections store a link to the related Rational Team Concert artifact; however, the href format is such that it returns the artifact in the Rational Team Concert web client.
For the purposes of a Rational Publishing Engine template, we need to use JavaScript to convert the returned href into a format that returns the artifact by way of the Rational Team Concert REST API. The JavaScript code that you use should be “generic” enough that it would work for any installation of a Jazz Team Server. In other words, do not set a static base Jazz Team Server URL such as “https://clm.jkebanking.net:9443. Instead, use a script that would account for any base URL.
In the provided “RQM_CLM_Traceability” sample, the template traverses from the Rational Quality Manager test case to the related Rational Team Concert work item that implemented the test case. In the QM schema, the test case node has a subsection for work item. A container was added with the query context of testcase/workitem. Then, a dynamic data source configuration (DDSC) element was used to traverse the link. Remember to set the inherited data configuration property to the top-level data source so that the end user does not have to provide credentials for this data source in the document specification.
The href that is returned is of the following format:
https://clm.jkebanking.net:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/57
The script that is used in the DDSC element parses the returned href to first find the work item ID at the very end of the href and the Jazz Team Server base URL (the server and port information with the context root to Rational Team Concert). The base URL and work item ID is then concatenated with the rest of a URI that includes field parameters to return the work item with the desired attributes. For more information on querying the Rational Team Concert Reportable REST API and using field arguments, see the Rational Team Concert Reportable REST API wiki on Jazz.net.
CLM traceability from a Rational Quality Manager or Rational Team Concert artifact to a Rational Requirements Composer requirement
The href that is stored in either Rational Team Concert or Rational Quality Manager to a related Rational Requirements Composer artifact is a link that opens that specific artifact in a web browser. You can add simple JavaScript code to your template to transpose the stored href into a URI that will return the artifact from the Rational Requirements Composer Reportable REST API. See the documentation on the Jazz.net wiki page for the Rational Requirements Composer API for more information on what an artifact URI to the REST API should look like.
The link stored in either Rational Team Concert or Rational Quality Manager to a Rational Requirements Composer artifact is in the following format:
https://clm.jkebanking.net:9443/rm/resources/_grHou5dFEeCPof-VFPWRJQ
The URI for this same artifact to be returned from the Reportable REST API would be in the following format:
https://clm.jkebanking.net:9443/rm/publish/text?resourceURI=_grHou5dFEeCPof-VFPWRJQ
The provided JavaScript examples essentially replace “resources/” with “publish/text?resourcesURI=”.
In Rational Quality Manager, the test case node of the QM schema has a subsection for “requirement,” which includes an “href” query to the related Rational Requirements Composer artifact. See the later section for traversing the Rational Team Concert auditableLinks node to find hrefs for related requirements to a Rational Team Concert work item.
In a template under the correct requirement query context for either Rational Team Concert or Rational Quality Manager, add a data source configuration element and fill in the appropriate properties. Be sure to set the inheritance property for this DDSC element to inherit the credentials of the top-level data source. For the URI of the DDSC element, use the JavaScript code as explained earlier.
Traversing the Rational Team Concert auditableLinks node
Traversing the auditableLinks node can seem very complex, particularly when you compare where Rational Requirements Composer and Rational Quality Manager store CLM traceability links in their schemas with the location where Rational Team Concert stores CLM traceability links in its schemas. Today, Rational Team Concert has implemented links per schema type as one table of source and target pairs for that schema type. For example, if you iterate over the auditableLinks node in the work item schema, you can print all source-target link pairs for all work items.
As a result, two Rational Team Concert schemas of the same type must be used (the work item schema is used in the provided example). In a template, use the first schema to iterate over and print each Rational Team Concert artifact. Then, using the second schema, use a dynamic data source configuration (DDSC) element with the second schema to find the links for each artifact. For the URI, use field parameters to return only the link pairs of the current artifact (where the “sourceRef” ID is the current Rational Team Concert artifact that you are printing). For more information on querying the Rational Team Concert Reportable REST API and using field arguments, see the Rational Team Concert Reportable REST API wiki on Jazz.net.
Once the template is iterating over and returning the targetRef items for the current artifact, use a couple of conditional statements to filter on whether you are searching for Rational Requirements Composer links or Rational Quality Manager links. The auditableLink node has a “name” attribute. The name attribute is set to “com.ibm.team.workitem.linktype.implementsRequirement” for Rational Requirements Composer requirement links and “com.ibm.team.workitem.linktype.testedByTestCase” for Rational Quality Manager test case links.
About the author
Geoff Rosenthal came to IBM Rational Software via the Telelogic acquisition. During the past 5 plus years he has worked extensively with cross tool usage scenarios for Software and Systems Delivery. In particular he has focused on cross domain reporting use cases with both the Rational Publishing Engine and the Rational Insight technologies. Geoff is at the forefront of the Rational Reporting Strategy which has the end goal of crossing Rational tools in a concise, uniform manner. With an integrated Application Lifecycle Management environment, organizations will be able to show objective and tangible business benefits with industry proven reporting technologies. Geoff specializes in helping customers turn their development data into insights and those insights into competitive advantage in the market.
You can contact Geoff at grosenth@us.ibm.com.
Copyright © 2013 IBM Corporation