1. Prerequisites and Scope

This tool mentor was written with the following tools:

• IBM Rational Publishing Engine (RPE) v1.1.2.2
• IBM Rational DOORS v9.4
• IBM Rational Quality Manager (RQM) v4.0
• IBM Rational Team Concert (RTC) v4.0

This tool mentor assumes that the reader has a basic understanding of the above mentioned tools. This tool mentor should not be used as tool training by itself, rather, this tool mentor should be used as supplementation information and guidance.

The RPE templates provided by the IBM Rational Systems Solutions are provided as-is. These templates should be considered to be examples of functionality that can be produced for output document reports and not necessarily complete/finalized document templates. Use these templates as examples and functionality to build off of and to extend for your own organization's report use cases. For more details see: RPE Systems Solution Templates.

2. Introduction

The Systems Solution provides several RPE example templates. These templates were meant to show variety of the types of document report use cases that can be accomplished using RPE. The templates include data sources from DOORS, RQM, and RTC. For information on how to configure the data sources in these templates to generate documents, see the tool mentor Using the RPE Report Templates.

These examples were built off of a generic DOORS requirements module schema, the standard RTC work item schema, and the standard RQM "Feed" and "QM" schemas. These templates leverage the default attributes for each artifact. You can/should tailor these templates to include any additional or custom attributes that you have in your environment that you need to print in your report use cases.

For more information about the RTC REST API and schemas, see: https://jazz.net/wiki/bin/view/Main/ReportsRESTAPI.

For more information about the RQM REST API and schemas, see: https://jazz.net/wiki/bin/view/Main/RqmApi. 

3. Customizing the Templates

3.1 Substituting Your DOORS Module Schema

With DOORS ever module has a standard set of attributes i.e. the module attributes such as "Name", "Description", "Baseline", etc. and the object attributes such as "Object Heading", "Object Identifier", "Object Text", etc. In the provided Accelerator templates, only these standard attributes were used. More than likely you will want to add your own customer DOORS module attributes to this template. Thus, you must edit the provided DOORS schema to include the desired attributes in your DOORS module(s).

• In the RPE Outline pane navigate to and expand the Data Source Schemas node.
• Find the "DOORS_SRS" schema

            Figure 1: DOORS_SRS schema

• Right-click on the "DOORS_SRS" schema and choose Edit Using Schema Discover...

           Figure 2: Edit schema wizard

• In the "Edit DOORS Schema Wizard" dialogue box that pops up, push the Next button on the Welcome screen
• In the "DOORS Connection Options" dialogue box, fill in the appropriate DOORS database connection details and push the Next button
• In the "Select the Attributes Type" dialogue box, leave the default radio button for "Module and object attributes" selected and push the Next button
• In the "DOORS Module Selection" dialogue box, expand your DOORS folder hierarchy to find the module that you are interested in, select that module and push the Next button
• In the "DOORS Baseline" dialogue box, select the appropriate baseline for the module that you are interested in
• In the "DOORS Attributes" dialogue box, check the attributes that you wish to add or remove to your schema and push the Next button
• In the "DOORS Views and Columns" dialogue box, navigate to any appropriate view and check any appropriate column name that you wish to add to the schema, then push the Next button
• Complete the wizard by pushing the Next and Finish buttons in the subsequent dialogue boxes
• The DOORS_SRS schema should now include the attributes that you selected in this wizard

3.2 Tailoring the DOORS Section of the Template

Now that you've updated the template's DOORS schema with the attributes in your DOORS module that you are interested in, you can tailor the DOORS section of the template to better meet your needs for your report use cases.

3.2.1 Module Information

If the provided template prints module information that you wish to update or modify, find the container in the template with the $# Module query.

                                                                            Figure 3: Module section of template

Within this container and at the desired location, remove the existing elements or add additional elements. As an example, if you have a custom module attribute that you wish to print:

• In the Palette pane, select a paragraph element and drop it into the module container as desired

Figure 4: DOORS module attributes in schema

• Drag and drop the query for the desired module attribute (Module/I <attribute> ) onto this paragraph
• A text box should automatically appear with the appropriate query to print the module attribute
• Now, when you generate a document from this template, it will include the module attribute that you just added

3.2.2 Requirement Information

If the provided template prints requirement object information that you wish to update or modify, find the container in the template with the $# Module/Object query.

                                                            Figure 5: Requirement section of template

Within this container and at the desired location, remove the existing elements or add additional elements. As an example, if you have custom object attributes that you wish to print in a table:

• Determine the table layout that is appropriate for your report use case i.e. number of rows and number of columns
• In the Palette pane, select the table element and drop it into the object iterator container as desired
• Drag and drop the queries for the desired object attributes (Module/Object/I<attribute> ) onto the desired table cells

Figure 6: DOORS object attributes in schema

• A text box should automatically appear with the appropriate query to print the module attribute
• Now, when you generate a document from this template, it will include the object attributes in the table that you just added

3.3 Dynamically Traversing Links

The templates use data source configuration elements (the orange boxes) to dynamically re-configure a data source based upon a link i.e. to automatically traverse a link from one object to another object. Within the context of a link (the External Link object in the case of DOORS), a dynamic data source configuration (DDSC) element is used. The appropriate schema (TC_qm or WI_ccm as shown in the figure) is applied to the DDSC element. The dynamic link properties are set for the properties of the DDSC element.

                                                          Figure 7: Following external links

             Figure 8: DDSC element properties

3.3.1 Traversing to an RQM Test Case

To traverse from a DOORS requirement to the related RQM test case requires a customized solution. Today, RQM has been implemented with 2 separate APIs. There is an OSLC based API and a separate Reportable REST API. As you might assume, RPE connects to the Reportable REST API and cannot use the OSLC based API as currently that API is not fully reportable. However, the href that is stored in DOORS from a requirement to the RQM test case is the OSLC based href. The custom solution is to first traverse to the OSLC API using a custom schema, then traverse from the OSLC API to the Reportable REST API using the RQM standard "qm" schema so that the template can print any desired details of the test case artifact.

In the provided "Templates" folder there is a sub-folder called "RQM OSLC Schema" that contains the custom RQM OSLC schema for a test case. This schema was created from scratch specifically for the purposes of these templates. If you wish to use this schema, simply use the RPE wizard to add a data source to your template, choose a generic XML schema, navigate to this folder and select the root node of the schema " versionedTestCase.xsd".

To print the details of a TC, the template must use two DDSC elements. The first traversal is from the OSLC href stored in DOORS to the RQM OSLC API. The second traversal is from the OSLC implementation of the test case in RQM 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 RQM "qm" schema to print the details of the test case as you would in any RQM template for RPE. Note that the good news is that no href parsing is required (like what is done for WI hrefs) as the OSLC or Reportable REST hrefs that are stored in the tools can be used as-is.

The below screen shot is from the SSE_traceability_example template. In DOORS, a link to an RQM test case is stored under the Module/Object/External Link query. The template first checks to ensure that the external link is a link to a test case (as opposed to any other external link).

                                                        Figure 9: Traversing an href to an RQM TC

In the template, under the context of the DOORS external link query, a DDSC element was added and the properties were set to the appropriate Data Expression. It is also crucial that the accept header of this data source is set to "application/xml" in the template.

Note: You MUST set the accept header for the Versioned TC schema to "application/xml" or a document generation will fail.

   Figure 10: Versional TC DDSC configuration properties

Once the template has traversed to the custom OSLC schema, another DDSC element was added to traverse to a "qm" schema as you normally would in any RPE template for RQM. The DDSC element URI was set to the Data Expression query of testcase/relation/resource. Finally, template elements are added as desired from the test case node of the qm schema.

3.4 Using Regions to Re-Direct Output Location

The SSE_traceability_example.dta template uses an advanced feature of RPE called a Region. A region allows you to re-direct the output that is created in one section of the template to another section of the final output document. Most box elements (container, paragraph, text, table) have a property under Formatting->Common called target region. You can specify a region element in the template with a name. Then on any other supported box element you can fill in the case sensitive name of the region. In the generated document, the output of the box element will be directed to print in the location of the region.

                                                                    Figure 11: Region elements

       Figure 12: Target region property

3.5 Tailoring the Quality Manager Section of the Template

The RQM artifact schemas are not modifiable by the end user. This means that unlike DOORS, the schema provided in the template does not need to be modified. You can choose to add or remove test case attributes as you wish. Follow the same method as you did for the DOORS section above, but use the queries from the RQM test case schema (TC_qm).

                                                       Figure 13: Test case section of template

In the provided templates, only the RQM "qm" schema is included. This schema provides the details of the RQM artifacts. Furthermore, the examples have been setup to only traverse to or print from the test case artifacts. You could certainly add more schemas to print more types of RQM artifacts if you wish. In the provided example templates, if you wish to print more details of the test case artifacts you must use the queries located in the testcase node of the qm schema.

Figure 14: Test case section of TC_qm schema

3.6 Tailoring the Team Concert Section of the Template

The RTC artifact schemas are not modifiable by the end user. This means that unlike DOORS, the schema provided in the template does not need to be modified. You can choose to add or remove work item attributes as you wish. Follow the same method as you did for the DOORS section above, but use the queries from the RTC work item schema (WI_ccm).

                                                    Figure 15: Work item section of template

In the provided templates, only the RTC work item schema is included. This schema can be used to provide more details of the RTC work item artifacts. Be sure to use the queries under the workItem node of the schema.

Figure 16: Work item section of WI_ccm schema