Generating compliance documentation using IBM Rational Publishing Engine: Part 4. Testing, review, and deployment

This is the final article in a four-part series about using IBM® Rational® Publishing Engine to generate compliance-relevant reports. Using two IBM® Rational® Quality Manage reports as examples, it shows how to test, check, and deploy the documents and templates that you have developed.

Dr. Einar W. Karlsen (einar.karlsen@de.ibm.com), Solution Architect, North-East Europe, IBM

Author photoDr. Einar Karlsen has more than 25 years of experience in the area of software development tools and methods. He has been with the IBM Rational division for 13 years, supporting customers in the use of Rational software, covering aspects related to demonstrating compliance by using report generation tools, among others. He works in Germany.



29 November 2011

Testing

In this article, you will learn about aspects of testing, review and deployment. The two IBM® Rational® Quality Manager reports as shown in Figure 1 serve as examples. The first report lists test plans, test cases, the associated test inputs (requirements), and test results. The second report shows test plans for which the documentation is incomplete, including hyperlinks to the test plan in Rational Quality Manager.

Figure 1. IBM Rational Quality Manager reports
Sections for test cases, requirements, and resultsSections for test cases, requirements, and results

As mentioned in Part 1 (see the "More content in this series" link), templates should be tested frequently and testing should be interleaved with template creation. Therefore, quick response times are important, so IBM® Rational® Publishing Engine provides several features for speeding up testing.

Testing a complete document specification for a compliance-based report could impose significant overhead if it consists of several templates that extract information from several data sources (such as the software development lifecycle report used as example in this article series). Therefore, it is best to test templates individually, one by one, by defining a dedicated document specification for the template. This specification is then loaded into Document Studio with the template (see Figure 1) so that template creation and testing can be interleaved and at frequent intervals.

If testing is performed by invoking the generate document command, Rational Publishing Engine will extract information from the referenced data sources and generate a report for all of the data within the scope of the template. In there is a large amount of data, such as for a test plan that contains several hundred test cases, this can take considerable time and might generate a large report. You can speed up the report generation process and limit the amount of output generated to fewer pages by using the preview current document command, which limits the number of elements reported in a given collection to a maximum number. You can specify the maximum number in Preferences (the default is 10). For the template in Figure 1, this would mean that the report will include information associated with, at most, 10 test plans or test cases, regardless of the number in the actual data source. However, Rational Publishing Engine will still request all of the data from the data source, because "trimming" of records occurs after the data has been received from the data source.

Figure 2. Document specification for the Rational Quality Manager report
Invoking the command to preview a test document

In addition to the Preview feature, there are other ways to speed up testing:

  • Disable extraction of information from a specific data source in the template by setting the ignored property of the data source to true (see the Properties section in Figure 2). This will cause Rational Publishing Engine to ignore data from that particular data source.
  • Limit the input data coming from the data source.
    • In Rational DOORS, you can do this by defining specific views with a limited number of input requirements.
    • For Rational Quality Manager, this would mean creating a specific test project to be used during testing and then configuring the document specification to use this project.
    • Alternatively, the template could be defined to work with a variable that limits the current scope to a specific test plan, and then you can set this variable to reference a test plan with a few test cases during template development.

During testing, you might discover that a report does not deliver any data. In that situation, the best practice is to use Representational State Transfer (REST) service-based domains to check that the URLs are correct, which requires manually entering the URLs in a web browser. It is also frequently possible to use the ?metadata=schema query to find the schema for the data source, as shown in Figure 3.

Figure 3. Testing of a REST service
XML output, Rational Quality Manager REST service

Larger view of Figure 3.


Checking accuracy, completeness, and consistency

Documents relevant to demonstrating compliance with internal guidelines or external regulations are not generated once, but many times. One frequent need for regenerating a document is when a review shows that information is missing, incomplete, or needs to be revised. For example, an organization might have guidelines that stress the need to provide documentation for each and every requirement, model element, test plan or test case (to mention a few) and to include this information in the generated reports.

Although is usually possible to customize development tools to perform consistency checks, you can also use Rational Publishing Engine to detect whether information is missing and then print out a warning in the generated document if this situation occurs. The advantage of using the tool for this purpose is that it can be done without any programming required and without involving people in other roles in the organization, such as Rational Quality Manager, DOORS or Rhapsody specialists.

Using regions

The following subsection demonstrates how you can use Rational Publishing Engine to notify you of issues related to missing test plans and test case descriptions at the end of the generated document (rather than interleaved with the extracted information), without having to traverse the information source a second time. Examples of the results are shown in Figure 1 and Figure 6. It would not be optimal if the error messages occurred interleaved in the generated output, because this could require a reviewer to read the entire report to find the issues. However, by using the concept of regions, you can specify that the generated warnings are put into a region of text that might be located somewhere else in the template, rather than in the current context. Notice that the region element is available in the Document Studio palette and needs to be inserted in the relevant position of the template (for example, at the end of a template). Figure 4 shows the definition of such a region.

Figure 4. Region for rendering issues
Container with condition: PRINT_ISSUES == true

Using containers

The region named Issues appears at the end of the template and contains, beyond the region element itself, a preceding page break and subsection header titled Document Issues. Notice that a PRINT_ISSUES variable has been used to enable or disable rendering of the warnings, so that the entire section of warnings can be disabled when the final document is generated for approval.

The elements that define the warnings are found in other locations, in the parts of the template where the test plan details are rendered. Figure 5 shows a basic template for extracting information for a test plan, together with its associated title and description. In the template, a container named Output Issues has been defined with a condition that checks whether the test plan description is empty or set to TBD. In this case, the template will issue a warning, as well as two hyperlinks. To direct the output of the warnings to the region named Issues (rather than having them appear in the current context), the target region property of the container has been set to Issues. This will trigger Rational Publishing Engine to put all output generated in the Output Issues container to the Issues region at the end of the template.

Figure 5. Template with completeness checks
Output Issues Container with condition to generate issues

Larger view of Figure 5.

Using links

Figure 6 shows what the corresponding output fragment produced by the template looks like.

Figure 6. Rendering of issues with hyperlinks
No description for test plan (plus link)

Notice that the template defines two hyperlinks:

  • The first link, which displays the name of the test plan (HybridSUV), is an internal hyperlink that will navigate from the location of the warning to the location in the generated report where the test plan is defined. This location has been defined by the Bookmark element in the template (in the paragraph immediately preceding the Output Issues container). Both the Bookmark and the internal hyperlink use the testplan/identifier property to provide the connection between the hyperlink and the target of the hyperlink.
  • The second link is an external one that, when you click the Rational Quality Manager URI, takes you directly to the test plan in that software (see Figure 7). You can use Rational Publishing Engine to navigation directly from a piece of information in a report to the appropriate definition in a data source, provided that the data source supports links that allow such navigation. This solution minimizes the work required for starting another tool, locating the source of the violation, and fixing it. Simply click the link, log in to the Rational Quality Manager (if you are not already logged in), and either fix the problem by providing a proper description or delegate the work by creating a work item for another team member.
Figure 7. Navigation to the test plan from the generated report
Hybrid SUV tab in Quality Manager, test plan view

Larger view of Figure 7.

Defining properties

The properties of the external and internal hyperlinks that allow navigation into the Rational Quality Manager source, as well as navigation within the document, have been defined in Figure 8. Basically, the internal hyperlink has been defined to display the title of the test plan and navigate to the bookmark identified by the testplan/identifier property. The external hyperlink is defined to display the Rational Quality Manager URL (testplan/identifier query) and to use the same value as the target of the hyperlink (Content property).

Figure 8. Hyperlink properties for external and internal links
Key properties for defining hyperlinksKey properties for defining hyperlinks

Identification of reusable components

After developing a template, it is a best practice to identify reusable components in the template and then register them as snippets or entire templates before deploying the template. Suppose that you would like to use the techniques presented in the previous section notices about issues in future templates, as well. In that case, it would make sense to register the container named Issues and the container named Output Issues as reusable snippets (palette elements).

The first template fragment holding the "issues" region can be reused without much additional work, because it simply defines a couple of elements. Before doing so, however, clean up the template by deleting styles, master pages, and variables not needed in the snippet. After doing this, you can save the template and publish it as a snippet using the Publish Snippet wizard, as shown in Figure 9. After it is published, the name of the snippet will be in the palette view.

Figure 9. Publishing snippets
Organize and Publish windows to register snippets

Larger view of Figure 9.

More work would need to be done to turn the container named Output Issues into a reusable component, because there are queries, bookmark references, fixed text and such in this part of the template. Therefore, it would make sense to simplify and clean up its definition before it is published. Variables should be introduced to define warnings to be rendered, text to be displayed for the hyperlinks, and the target of the internal or the external hyperlink. Moreover, it would make sense to define a new style for the hyperlink, setting the color to blue (4080) and the line.underline property to single.

Note:

This rework is nothing specific to Rational Publishing Engine. It is a fundamental truth that going from a specific solution to a more general solution might require changes.


Deployment

There are several ways to deploy templates and document specifications for final use in an organization. Deployment usually boils down to storing templates and document specification in some designated folder or subfolder of a central file server, as well as defining means for generating the reports. This section focuses solely on the last aspect of deployment.

Using the launcher

Using the Rational Publishing Engine launcher is, of course, one possibility for generating a report. That adds to overhead, because several steps are involved (start the launcher, load the document step, invoke report generation). Alternatively, it is possible to generate documents interactively simply by using the Microsoft Windows Explorer without having to start the launcher explicitly, as shown in Figure 10.

Figure 10. Generation using Windows Explorer
Generating a report using the Publish command

Using the command line interface

Frequently, organizations want to automate generation of documents so that they are generated daily, weekly, or monthly. For these purposes, you can invoke document generation using rpe-launcher.exe in a command line interface, as shown in Figure 11. Notice that the -noresult switch is used to inhibit showing a results box at the end, thereby allowing the end user to open generated output (generation is more silent).

Figure 11. Generation using the command shell
Generating a report using the launcher.exe command

Using a scheduler or build process

Invocation of the document generation can be triggered by a scheduler or, for example, by incorporating document generation as part of a build in IBM® Rational® Build Forge® or other build management systems.

Using template libraries

A fourth possibility, shown in Figure 12, is to register the location of the templates with the IBM Rational Publishing Engine in the preferences of the tool. A DOORS user can then invoke the Publish > Generate Document command from within DOORS and get access to templates in any of the registered libraries.

Figure 12. Registration and use of template libraries
Specifying a new location for storing templatesSpecifying a new location for storing templates

There are several other ways in which templates and documents can be deployed for final use:

  • The web service option for Rational Publishing Engine (see Resources) can be deployed on a remote server, thus allowing report generation to take place on the server rather than on the local desktop. This can speed up document generation for complex reports by running it on a remote server located close to the data sources to minimize the need for transferring a large amount of data over the network.
  • Rational Publishing Engine offers a comprehensive API so that organizations can write their own automation routines for generating reports.
  • Reporting Arena, an IBM partner, provides an extension called Reporting Arena Web Publisher to generate reports using a web browser (thin client). See the Resources section for a link to their website.

Summary

This part of the series covered tips for developing, testing, reviewing and deploying IBM Rational Publishing Engine templates and document specification. This part demonstrated these concepts in particular:

  • Ways to speed up testing by using dedicated document specification, plus disabling resources and document preview
  • Use of regions to add document issues, such as missing descriptions, at the end of a report
  • Use of external hyperlinks to navigate from a generated report to the external source (IBM Rational Quality Manager, for example) to speed up the revision process
  • Use of internal hyperlinks to navigate from an applied to a defining occurrence of a given element
  • Interactive generation of a report using Microsoft Windows Explorer
  • Automated generation of a report using the command shell interface

Be sure to review the Resources section for where to find additional helpful information.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=776231
ArticleTitle=Generating compliance documentation using IBM Rational Publishing Engine: Part 4. Testing, review, and deployment
publish-date=11292011