![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
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
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
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
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.
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
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
Figure 6 shows what the corresponding output fragment produced by the template looks like.
Figure 6. Rendering of issues with hyperlinks
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
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
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
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.
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 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
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
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.
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
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.
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.
Learn
- Learn more about Rational Publishing Engine features and
benefits:
- Check the product page and the overview, plus the many resources on the developerWorks page and the documentation in the information center.
- Watch the demo to see how you can use Rational Publishing Engine, including how to configure templates.
- Investigate the Rational Publishing Engine web service option.
- 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 or Office 2003: XML Reference Schemas 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 Reporting Arena Web
Publisher website for more information on this Rational Publishing Engine
extension (not from IBM Rational software but validated as Ready for
Rational).
- Visit the Rational software area on
developerWorks for technical resources and best practices for Rational
Software Delivery Platform products.
- Stay current with developerWorks technical events and webcasts focused on a variety of IBM
products and IT industry topics.
- Attend a free developerWorks Live! briefing to get up-to-speed quickly on IBM products and tools, as well as IT industry trends.
- Watch developerWorks on-demand demos, ranging from product installation and setup demos for beginners to advanced functionality for experienced developers.
- 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, any time, and many of the "Getting
Started" ones are free.
Get products and technologies
- Download trial versions of IBM Rational software.
- Evaluate other IBM
software in the way that suits you best: Download it for a trial, try it
online, use it in a cloud environment, or spend a few hours in the SOA
Sandbox learning how to implement service-oriented architecture
efficiently.
Discuss
- Ask questions, give answers, and get involved in
the Rational Publishing Engine communities: forums, user groups, blogs and
wikis
- Rate or review Rational software. It’s quick and easy. Really.
- Share your knowledge and help others who use
Rational software by writing a developerWorks article. Find out what makes a good developerWorks article and how to proceed.
- Follow Rational software on Facebook, Twitter (@ibmrational), and
YouTube, and add your
comments and requests.
- Ask and answer questions and increase your
expertise when you get involved in the Rational
forums, cafés, and wikis.
- Get social about thought leadership. Join the Rational community to share your
Rational software expertise and get connected with your peers.
Dr. 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.
