![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
IBM® Rational® Publishing Engine supports creation of complex documents perfectly. The concept of document specification allows a document to be composed from several templates that can be developed, tested, deployed and maintained separately.
For example, the screen capture in Figure 1 shows the document specification that was used to generate the software development lifecycle report in Part 1 of this article series. It contains templates for the following sections of the document:
- Title page, table of contents, list of figures (FrontPages.dta template)
- Written introduction (Introduction.dta) from Microsoft Word
- Microsoft Excel-based risk list (ExcelRiskList.dta)
- IBM® Rational® DOORS® stakeholder and system requirements (DOORS.dta) in text format, as well as subsystem requirements (DOORS2.dta) in table format
- IBM® Rational® Rhapsody® use case model and requirements model (UseCaseModel.dta, ReqModel.dta)
- IBM® Rational® Quality Manager test plans and test results (RQMTestPlan.dta)
- IBM Rational Quality Manager work items (RQMWorkItems.dta)
Figure 1. Document specification
IBM Rational Publishing Engine features can help an organization establish publication standards and reduce costs of producing reports by defining a library of highly reusable templates. Most of the templates in the sample document have been made generally applicable by defining information such as document title, project name, section heading, author and date in terms of variables that can be instantiated with actual values as part of the document specification. For example, both the title page and the introduction of the sample report shown in Figure 2 are generally applicable due to use of parameterization, or specifying the parameters.
Figure 2. Reusable title page and introduction
Figure 3 shows an excerpt from the FrontPages.dta template and the use of external variables (Title, Project) to render information such as the document title and project name in Paragraph elements.
Figure 3. Template parameters defined for the title page
The actual values of those variables are provided as part of the document specification by setting the value property, as shown in Figure 4.
Figure 4. Definition of actual values
The next template (Introduction.dta) includes information from a Microsoft Word document. Again, parameters in the template have been used to ensure a high degree of reusability. As Figure 5 shows, the path of the Word document to be included has been defined in terms of the WordDocPath variable in the Include File element of the template as shown in Figure 5.
Figure 5. Inclusion of a Microsoft Word file
The actual path of the Microsoft Word document can then be specified in the document specification, and can vary from one document to another. The template can therefore be used to import any kind of Microsoft Word file, provided that the text from Word is supposed to appear directly following the section title.
Figure 6. Stakeholder and system requirements
The DOORS.dta template is another instance of achieving a high degree of reuse. This template has been used as a basis for generating the stakeholder requirements without rendering the attributes, as well as for the system requirements rendered with attributes, as shown in Figure 6.
Variables, such as PRINT_ATTRS and PRINT_TABLES, have been used to enable or disable printing of Rational DOORS attributes and tables, respectively, as shown in Figure 7. The template uses the PRINT_ATTRS variable in a condition to ensure that information regarding attribute values (in the container named Requirement Attributes) is rendered only if the value of the variable is True.
Figure 7. Using parameters to hide details
Whether this is the case or not is controlled by defining the actual value in the document specification. This way, the template can be used for all Rational DOORS requirements, whether they are stakeholder requirements (no attributes rendered) or system requirements (some attributes rendered). If rendering of attributes is enabled, the template has been defined to iterate over all columns (query $4) and then print the column name and value.
Tip:
Providing metadata, such as the container name (Requirement Attributes), significantly increases the readability, and thus maintainability, of the template.
Figure 8. IBM Rational DOORS view
The set of attributes rendered is controlled by the actual DOORS view being used. For example, the view in Figure 8 shows the Priority and State attributes for the system requirements but not the other attributes available for those requirements. The document specification has been configured to use this view to ensure that only those two attributes are rendered in the report, as shown in Figure 9. The actual view used is determined by the URI property of the DOORS data source. You can use the DOORS Data Source Selection Wizard shown in Figure 9 to configure the data source, including the URI, username, and password properties (among others).
Figure 9. Rational DOORS data source configuration
Organizations that need to generate compliance-relevant documents usually have very specific requirements with respect to the actual layout of the document. For example, typically, the document must be generated with a title page, headers, footers and so forth, all aligned with company standards.
There are basically two ways to achieve this:
- Define styles within a word processor source file, such as a Microsoft Word document
- Define styles within the template
Define styles within a word processor source file
The most straightforward solution is to use a Microsoft Word outline to define the headers, footers and paragraph types according to your company's style guide. This Word outline is then used as stylesheet for generating the report. See Figure 10 where properties are set in the document specification to define the actual path of the Word output file and the stylesheet to use.
Figure 10. Configuration of Microsoft Word output
The relevant styles in the Microsoft Word template must have associated placeholder styles in the Rational Publishing Engine. These styles should then be used and associated with template elements to control the actual formatting of the elements. For example, in Figure 11, the document title has been defined to use the Title style. The actual properties (font, paragraph alignment, and so forth) do not need to be set in the template, but they can be. If they are not defined there, the associated style definitions in the Word outline file will be used.
Figure 11. Use of IBM Rational Publishing Engine styles
Another aspect of generating Microsoft Word as output is the use of macros (see the macro property in Figure 10). Rational Publishing Engine uses macros to post-process the generated document. The standard macro for that purpose is called rpe, and it basically makes sure that the table of contents, the list of figures or tables and such are updated and that referenced documents (such as the introduction) are imported into the generated output file. However, you can develop your own macros to use instead, if you prefer.
Define styles within the template
Another solution for ensuring that the generated output complies with your company's requirements or guidelines is to define the style headers and footers, for example, directly in the template by using master pages (see Figure 12).
Figure 12. Master page that defines headers and footers
This solution will require you to repeat some of the work that you already did in the Word outline, but it has the advantage that the Rational Publishing Engine can more easily take full control over the information rendered (in the headers and the footers, for example), such as displaying data kept in variables or data extracted from the information sources. This is the solution that we adopted in the current set of examples, where the master page (Figure 12) renders the value of variables set in the document specification, such as Title and Section, along with additional elements, such as an image (company logo stored in a JPG file), Author, Page Number, and Total Page Number.
Tip:
A document can contain several master pages, and master page settings can be changed within a single template. For example, the FrontPages.dta template uses the master page called MPT (with no headers and footers) for the title page, but the other pages are set up to use the master page named MPN.
To foster reuse of template fragments and to support organizations in establishing standards in their documentation, it is possible to declare reusable template fragments called snippets. You can declare a snippet simply by invoking the Template > Organize Snippets command. You will then be asked to enter a name, description and template file path for the snippet. After a template file has been defined as a snippet, it can be inserted into a template with a single operation. The snippet will appear as an element in the Palette view, similar to the way that predefined template elements such as paragraphs, tables, and figures do (see Figure 13). To insert the snippet into the current template, simply select the name of the snippet in the Palette view, position your cursor in the document template where you want the snippet to be inserted, and click.
You can declare a library of reusable components to ensure a standard look and feel across the various templates and to reduce the time needed to develop new templates. For this example, we used this feature to declare snippets for insertion of a master page, table and figure. Having done that, it took just a few steps to create the template in Figure 13, simply by inserting Demo Master Page and Demo Table snippets from the (extended) tool palette.
Figure 13. Use of snippets
Note:
This template will be completed in Part 3 of this article series by inserting queries to extract information from DOORS.
This article demonstrated how you can use IBM Rational Publishing Engine to decompose large reports into smaller, more manageable units, ways to design templates for reuse, and to set up templates to be comply with your organization's standards. It covered these topics in particular:
- Document specifications to split a large document into smaller, manageable pieces
- Variables to develop parameterized, reusable templates and to enable or disable rendering of specific details in a report
- File inclusion elements to import written text from Microsoft Word into a report
- Styles in Microsoft Word and Rational Publishing Engine to achieve a specific layout
- Master pages to define headers and footers that adhere to your company's style guide
- Snippets to establish a library of reusable templates that enforce a standardized look and feel and, at the same time, reduce development and maintenance costs
Part 3 of this series shows you how to use the Rational Publishing Engine to create reports by taking information from several information sources, including the ability to follow traces from information in one tool to data managed by another in the same document. The template created by using snippets will be completed by inserting queries to extract information from DOORS. Part 3 also shows you how to report on information managed by other software, such as Microsoft Excel. In addition, you will see how you can use other options, such as JavaScript, to control the color of information rendered in the report.
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.
- Check out Rational Publishing Engine Template library
- For more tips, tutorials and sample templates, visit the Rational Publishing Engine Community wiki on developerWorks and the Rational Publishing Engine Actual blog.
- 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.
