Using IBM Rational Publishing Engine to generate compliance documents

Part 1. Report generation for Rational Quality Manager, introducing REST service URLs, importing schemas, and basic template authoring

Dr. Einar W. Karlsen
Published on February 11, 2014

Users of IBM® Rational® Quality Manager can have different requirements for document generation, depending on local customizations of categories, attributes, and sections, for example. Reporting needs can also be influenced by the specific setup and regulatory requirements or internal standards that need to be fulfilled. Consequently, generating compliance-relevant reports can be nontrivial. This article demonstrates how to use the IBM® Rational® Publishing Engine to generate archetypical test management documents by extracting information from Rational Quality Manager.

Figure 1 shows fragments of a typical test report. The report focuses on a specific test plan and shows information such as:

• Test plan name and corresponding description
• Custom attributes and categories (such as "Product") or sections ("Business Objective" or "Test Equipment") associated with test artifacts
• Test cases associated with the test plan and test case properties
• Associated test requirements from IBM® Rational® DOORS® or IBM® Rational® Requirements Composer (such as requirement id, title, and possibly also other properties)
• Test scripts, including the individual test steps and relevant keywords
• Test execution results for the test case, as well as test results for the individual test steps in the test log
• Associated defects managed by IBM® Rational® Team Concert™ or IBM® Rational® ClearQuest®, together with defect properties

Figure 1. Typical test management report

View image at full size

Part 1 of this series about reporting data in Rational Quality Manager using Rational Publishing Engine focuses on the left part of Figure 1—test plans, test cases, test results, and links to requirements. Part 2 continues with the right half of Figure 1—reporting on test scripts, test logs, and links to defects.

Rational Quality Manager REST service

Rational Quality Manager offers reporting through a Representational Stateless Transfer (REST) API (see Resources). The reportable REST services of Rational Quality Manager are close to the underlying data model shown in Figure 2. The test report shown in Figure 1 traverses the artifacts from test plan, through test case to test case execution record (execution work item) and test case execution result. This article follows all the links highlighted in red to generate the report. See Figure 2:

Figure 2. Rational Quality Manager data model

View image at full size

Rational Quality Manager offers two kinds of resources for reporting:

• Collections (also known as feeds) that contain sets of resources of the same type—for example, test cases, test plans, and test scripts. By default, the data returned in the feed is limited; usually only the name and a URL to the individual resource are delivered.
• Individual resources that contain the details for a single artifact such as a test case, test plan, test script, execution record/work item, or execution result. These resources provide access to the name, description, (custom) attributes, and sections of the resource. They also contain references—but not details—to the linked resources in form of URLs.

To create documents that contain groups of test artifacts, you must use a collection to return the list of artifacts, then link to the individual resource details for each artifact. Developing reports for Rational Quality Manager consequently makes extensive use of dynamic data source connections to navigate from one resource to another.

Two reporting schemas

Rational Quality Manager offers two basic schemas for reporting. The schema for feeds is shown in the left part of Figure 3. Each entry (for example, feed) provides access to the title of the entry — such as a test plan or test case — and the URL through the query id.

The right half of Figure 3 shows the schema for test plan resources. It provides access to all the details of the test plan: the web ID, title description, sections (such as Business Objectives), custom attributes, categories, and links to linked resources such as requirements, child test plans, test suites, and test cases. The same schema (not shown in the figure) also provides access to other resources such as test cases, test scripts, and test execution results.

Figure 3. Schemas for feeds and resources

View image at full size

You can get access to these two basic schemas with these URLs:

https://<server>:<port>/qm/service/com.ibm.rqm.integration.service.IIntegrationService/schema/feed.xsd

https://<server>:<port>/qm/service/com.ibm.rqm.integration.service.IIntegrationService/schema/qm.xsd

To get access to the corresponding resources such as test cases and test plans, you need to know the project area. You can get a list of all project areas here:

https://<server>:<port>/qm/service/com.ibm.rqm.integration.service.IIntegrationService/projects

This URL lists all aliases of the project areas. For example, you can gain access to the test plan feeds and test case feeds for the "JKE Banking Quality Manager" project area with these two URLs:

https://localhost:9443/qm/service/com.ibm.rqm.integration.service.IIntegrationService/resources/JKE+Banking+%28Quality+Management%29/testplan

https://localhost:9443/qm/service/com.ibm.rqm.integration.service.IIntegrationService/resources/JKE+Banking+%28Quality+Management%29/testcase

Feeds provide a field parameter that also can be used to provide direct access to the resources. You may have observed that the schema for feeds in Figure 3 shows sections for test cases, test plans, and test scripts through the query feed/entry/content. By default, no data is returned for these resources. However, if you change the field parameter from its default (?abbreviate=true) to (?abbreviate=false), content is returned.

Importing schemas

Before you can author templates for Rational Quality Manager, you need to import the schemas into IBM Rational Publishing Engine Document Studio. The Rational Quality Manager Reportable REST API does not yet completely adhere to the specification required for a REST or REST v2 data source in Rational Publishing Engine. The Generic XML Data Source is therefore used for reporting.

To import a new data source schema into the template, go to Data > Add Data Source Schema, then enter the URL for the schema and give it a name. Click Next and enter your credentials and OAuth as the authentication mechanism. See Figure 4:

Figure 4. Importing Rational Quality Manager schema

View image at full size

Basic template for test plan reporting

After you import the schema(s), you can start template authoring. Begin with a simple template for test plans that basically extracts the test plan title as section header and retrieves the description. Notice that the template has been defined so that it connects to the feeds for the test plans in a project using the schema RQM Feed. The template therefore starts by iterating over all feeds in the template ($1) until it finds a feed entry with the name matching that of the test plan of interest. The name of this test plan is provided as an external variable called TestPlan. See Figure 5:

Figure 5. Basic template for test plan properties

View image at full size

A dynamic data source connection is used to connect from the feed to the test plan. The schema of the data source connection is RQM TP and the URI property is set to feed/entry/id/_value, which returns the URL of the test plan resource (see Figure 6). The user credentials are inherited from the schema RQM Feed by setting the Inherited data configuration property to RQM Feed. This completes the configuration of the RQM TP data source.

Figure 6. Dynamic data connection for test plans

View image at full size

The most important properties of the corresponding document specification are where the URI and user credentials are set. To avoid exposing the internal data sources (such as RQM TP) used in the template to the document specification, simply select the data source in the outline view in Document Studio and then change the value of the property configuration required from uri to hidden. This way the end user sees only the data sources in the document specification that need to be configured (such as RQM Feed), and data sources like RQM TP remain internal to the template because they are configured in the template. See Figure 7:

Figure 7. Document specification

View image at full size

Always specify the authentication method in the document specification for a data source. If it's left empty, Rational Publishing Engine will try all the authentication methods it supports until it finds one that works. This results in additional requests to the provider, which increases the server load and decreases performance.

Categories and rich text sections

Test artifacts such as test plans and test cases can be extended with custom categories and attributes. The template in Figure 8 demonstrates how straightforward reporting on custom categories is. A query ($242) iterates over all custom categories. The category name (query term) and value (query value) are accessed next. Custom attributes are retrieved in a similar way.

Beyond categories and custom attributes, you can also extend Rational Quality Manager with custom sections that provide client-specific documentation in the form of rich text or grids. To report on rich text sections, define the sections first in Rational Quality Manager, then import the schema into Rational Publishing Engine. Rich text sections will then be directly available in the imported schema as named queries such as Business Objective. See query $244 reporting on Business Objectives in Figure 8:

Figure 8. Template for test plan categories and rich text sections

View image at full size

Custom sections are defined in the schema using uniquely generated names that Rational Quality Manager provides. A user-friendly name such as "Business Objective" is provided as a schema annotation. Rational Publishing Engine uses this annotation in place of the name, but only if you select the default Use schema annotations for display in the preferences.

Test case details

Now that you've retrieved some basic properties for a test plan, you can look into the associated test cases. Figure 9 shows the essential template fragment, which contains a table that lists the test cases for a test plan by number, title, and associated test results:

Figure 9. Template for test case list

View image at full size

The important part is the query ($67), which iterates over all test cases and then fills the rows in the table with the test case properties of interest. The schema for test plans offers queries to extract the URI of the associated test cases in form of a query named href. To retrieve more information for a test case, you must connect dynamically to the REST service. A data source configuration associated with the schema RQM TC is therefore used to fetch the data for the test case. The template then iterates over the test cases (query $68) and extracts the test case webId and title in two table cells. A third table cell has been reserved for the test results.

Test results

If you look at the data model for Rational Quality Manager in Figure 2, you see that a test case may have zero or more test case execution records, or execution work items, which in turn may have zero or more test case execution results. You might get the idea looking at the data model for Rational Quality Manager in Figure 2 that retrieving the execution results for a given test case would require two simple queries to read the URLs, combined with two data source connections to retrieve the associated execution records first, then the test results associated with the execution records next.

To some extent this is true. The main problem is that the schema for test cases doesn't offer queries for retrieving the test case execution records. Then, of course, you can decide to iterate over all execution records for a project area, finding the ones that are associated with the current test case. However, this solution doesn't scale with larger amounts of data.

A solution that scales

A more efficient solution is to compute a URL that returns all execution records for a given test case and then continue with this (limited) set of execution work items to retrieve the associated execution results. This solution is shown in Figure 10. It requires two dynamic data connections: the first to retrieve the execution work items (schema RQM EWI) for the test case, the second to retrieve the associated execution results (schema RQM ER). The URL that returns all execution work items for a given test case looks like:

https://<host>:<port>/qm/service/com.ibm.rqm.integration.service.IIntegrationService/resources/<projectarea>/executionworkitem?fields=feed/entry/content/executionworkitem/(*|testcase[@href= '<testcase-uri>'])

In the template, this URL is computed in the second JavaScript code element shown in Figure 10. Basically it computes the base URL for all execution work items given the URL for a test case (lines 1-3) and then appends this URL with a field specification that narrows the search scope to the execution work items for the given test case (lines 4-7).

The URI is used to configure the data source RQM EWI in the template fragment shown in Figure 10. The variable _RQMEWI_I_TestCaseURL is used as a sort of input parameter. The entire template fragment in Figure 10 has been stored as an independent snippet that can be imported into another template for reuse. The only thing that needs to be done in the calling context is to assign the current test case URL to the variable _RQMEWI_I_TestCaseURL. The execution result is returned in the variable _ExecutionVerdict. Finally, the query $360 has a filter that ensures that only the execution work items for the current test plan are considered. See Figure 10:

Figure 10. Template for execution work items and test results

View image at full size

Associated requirements

Test cases are usually linked to the requirements that they test (see Resources). You can also get reports on the requirements associated with a given test case.

Following links from Rational Quality Manager to IBM Rational Requirements Composer involves two key elements: the Rational Requirements Composer schema and the URLs stored in Rational Quality Manager that reference the requirements. The schema for test cases in Rational Quality Manager provide queries for retrieving the requirements associated with a given test case — again in form of the URL of the requirement (query href). See the left half of Figure 11.

The corresponding schema for requirements (text) in Rational Requirements Composer provide information for each requirement artifact such as the identifier and title, amongst others (see right half of Figure 11). The Rational Requirement Composer schema can be imported into the template the same way that Rational Quality Manager schemas are imported; for example, as generic XML using URLs such as:

https://localhost:9443/rm/publish/text?metadata=schema

Figure 11. Schemas for test cases and requirements

View image at full size

Using the template for test requirements

The template is straightforward. First, iterate over all test case requirements ($3). Next, use a dynamic data source connection for the schema RRC Text. Then iterate over the data source artifacts in Rational Requirements Composer ($276), and the identifier and title for this requirement are printed out in two columns, as shown in Figure 12 (each data source connection will have just one requirement):

Figure 12. Template for test requirements

View image at full size

Some URL magic is (again) needed to follow links from Rational Quality Manager to Rational Requirements Composer. The requirements in the Rational Quality Manager REST service are designated by URLs that point to the object in the user interface; for example, the URLs are on the following form:

https://localhost:9443/rm/resources/_07780a4170d04db3a152657b1387244b

However, the reportable REST service of Rational Requirements Composer expects the URL to be on the following form to return XML data for the requirements that are suitable for reporting:

https://localhost:9443/rm/publish/text?resourceURI=_07780a4170d04db3a152657b13b87244b

By using the replace function with a JavaScript expression, you can convert this URL by substituting the string resources/ with publish/text?resourceURI=:

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

Reporting on requirements coming from IBM Rational RequisitePro is different than reporting on requirements from Rational Requirements Composer. Reporting on requirements with Rational RequisitePro is no different than retrieving, say, test scripts associated with the test case: a dynamic data source is associated with the schema for test artifact resources. The URI of the data source is defined using the query testcase/requirement/href. A section is defined for requirements in the test artifact resource schema. These queries can be used to retrieve elements such as the requirement tag and requirement title.

Conclusion

This first part of this article series addresses Rational Quality Manager reporting with Rational Publishing Engine. It introduces basic concepts such as the Rational Quality Manager data model, Reportable REST service URLs, importing schemas, and basic template authoring for test plans, test cases, test results, and test requirements (fetching information from Rational Requirements Composer). Document design and layout Part 2 shows how to retrieve information related to test scripts and test logs, as well as cross-domain reporting by retrieving information with IBM Rational Team Concert following Open Services for Lifecycle Collaboration (OSLC) links.>

Acknowledgement

Thanks to Dragos Cojocari, Peter Staubrandt, Abish Mathew Zachariah, and Gerd Schiering for providing valuable input to the two articles on using Rational Publishing Engine for reporting over data in Rational Quality Manager.

Downloadable resources

• PDF of this content
• Quick demonstration (RPEQuickDemo.zip | 3,242KB)

Related topics

• Learn more about Rational Publishing Engine features and benefits:
  • Check the overview, get installation help, and read the documentation in the information center.
  • Watch the demo to see how you can use Rational Publishing Engine, including how to configure templates.
• Read other articles in this series.
• Read "Rational Solution for Collaborative Lifecycle Management Traceability Templates with Rational Publishing Engine" (Geoff Rosenthal, Jazz.net, October 2012)
• For additional tips and tricks, visit Rational Publishing Engine Actual.
• Gather more information for the Reporting Area Web Publisher.
• For more help with templates and schemas:
  • For more tips, tutorials and sample templates, visit the Rational Publishing Engine Community wiki and check the Rational Publishing Engine Template library.
  • If part of what you want to include in your reports is in Microsoft Office documents, here's where you can find help: Go to either 2007 Office System: XML Schema Reference to download XSD schemas for Microsoft Office products. Navigate to Microsoft Office Project 2007 XML Data Interchange Schema to download the XSD schema required to report on Microsoft Project data. Read the Microsoft article titled Create an XML data file and XML schema file from worksheet data to learn more about how to create appropriate schemas for reporting Excel data.
• Check the Rational Quality Manager pages on developerWorks for links to product documentation, articles, tutorials, courses, downloads, and other useful areas.
• Explore the Rational Quality Manager Information Center for technical details, check the Rational Quality Manager Roadmap for links to more resources.
• For how-to tips, read these developerWorks articles by Michael Kelly:
  • Lab Management using IBM Rational Test Lab Manager: Extending IBM Rational Quality Manager for collaborative, comprehensive test planning and test asset management (developerWorks, October 2008)
  • Getting started with IBM Rational Quality Manager (developerWorks, December 2008)
  • Managing your first project with IBM Rational Quality Manager (developerWorks, October 2008)
• Try building and deploying your next project on the IBM Bluemix cloud platform, where you can take advantage of pre-built services, runtimes, frameworks, application lifecycle management, and continuous integration.
• Go to Jazz.net to find out more about Rational Quality Manager Reportable REST API.
• Improve your skills. Check the Rational training and certification catalog, which includes many types of courses on a wide range of topics. You can take some of them anywhere, anytime, and many of the Getting Started ones are free.
• Download the free trial version of Rational Quality Manager.