Why we still generate documents
To adopt modern software development practices, companies need to replace their traditional document-based development workflows with modern engineering applications, such as IBM® Rational® DOORS® or IBM® Rational® RequisitePro®. For this to be successful, it is crucial, that the documents to be shared with other development teams, customers, sub-contractors, and so on can still be created. This is because others may still use document-based approaches or other engineering applications.
This article describes IBM® Rational® Publishing Engine, a new document-generation tool. The first part of this article discusses the key concepts of Rational Publishing Engine. The second part maps the features of DocExpress (a legacy document generation solution) to Rational Publishing Engine. This is done in a way that allows you to systematically define a document generation with Rational Publishing Engine in order to replace an existing DocExpress Configuration. If you do not have experience with DocExpress, this also gives hands-on examples of the power of the Rational Publishing Engine. The templates shown solve typical document generation tasks for Rational DOORS.
Context: Overview of Rational DOORS, as an example
Of course, Rational DOORS and other engineering applications offer interesting views of data, such as the one in Figure 1. You may wonder: Why would anyone use simple document generation, when more advanced tools (such as copy-and-paste operations) are so easy?
Figure 1. You can make this view look better by arranging it vertically, in a document
You can only copy existing views of a tool into a document. It might be necessary, or make the information more easily understandable, to arrange the information in another way in a generated document. For example, you can display the attributes belonging to a requirement vertically below each other, instead of horizontally, as is possible in Rational DOORS. This will look better than the table in Figure 1.
Furthermore, an important reason to introduce modern software engineering applications, such as a requirements management system, is to cope with the changes. However, if your data keeps changing, this means that the documents also need to be updated regularly so that other project members such as subcontractors can keep up to date. Pasting information from tools is a boring and error prone activity, especially when you have to do it regularly. One forgotten update can be the cause for severe damage and costs, especially if it is an important requirement for, as an example, an aircraft or a medical device.
Rational Publishing Engine
Rational Publishing Engine is a small application for generating documents with content that is extracted from the data of other applications. It differs from other solutions by its unique support for IBM Rational software. The first version, launched in December 2008, supported Rational DOORS (a requirements management system), and IBM® Rational® Tau (a UML modeling solution). The latest version adds support for many more applications, namely:
- IBM® Rational® Focal Point™
- Rational Requisite Pro
- IBM® Rational® ClearCase®
- IBM® Rational® ClearQuest®
- IBM® Rational® Test Manager
Future versions of Rational Publishing Engine will add support for even more products.
The key design goals of Rational Publishing Engine were threefold:
- First, Rational Publishing Engine should be able to fulfill the diverse formatting needs of its users. Because no two users will ever agree completely about how their documents should be formatted, Rational Publishing Engine has a very rich set of properties. These properties enable you to give your documents exactly the format and appearance that makes them "look nice" to you. The property set is similar to common HTML editing properties, and even a new user should be able to master them quickly.
- Second, Rational Publishing Engine should generate documents efficiently. This means resource usage is rather small. Resource usage is kept small because Rational Publishing Engine does not load complete data sources from the supported applications into memory. To the contrary, data source extraction, processing, and output generation run in parallel, which also allows for native filtering and sorting, techniques that make document generation yet more efficient. In addition, Rational Publishing Engine generates all of the output formats (Microsoft Word® documents, PDF, HTML, and XML Formatting Objects) directly (without using COM-Automation or the system clipboard).
- Third, Rational Publishing Engine should be easy to use, which design goal is reached through a combination of simple, clearly communicated concepts, and a modern user interface (UI). The core artifacts to define a generated document are document specifications and document templates.
Document specifications are specifications of a concrete document, in one or more of the supported document formats. They reference one or more document templates, which define how the document will look. For each document template and its defined data sources, the document specification contains all of the information necessary to retrieve the actual data from a supported application. Furthermore, they define the desired target format(s), styles to be used in the document templates, document post-processing macros, and other information such as the desired date format. The document specifications are specific for a generated document, and can not be reused to generate another document.
Document templates, on the other hand, are reusable specifications of an output document, or a part of an output document. They define the structure of the input data source and the structure of the output document. Input is related to output by queries. The queries either define the output document content (if they have a textual value), or replicate nodes in the output document as often as they occur in the input document.
Figure 2 shows an example of a document template. The outermost
Container element is associated with the
module.object query. Its contents will be replicated as often as there are such entities in the data source. The content nodes inside of the container produce two paragraphs of text for each of the objects in a Rational DOORS module. These paragraphs contain two textual properties of the nodes, namely
Object Heading and
Object Text, defined by more queries.
Figure 2. Rational Publishing Engine document template for a DOORS data source
The data source to which the query is referring,
A_DOORS_MODULE, is defined with an XML Schema Definition (XSD) inside the document template. Ready-to-use XSDs are available for standard data sources such as a Rational DOORS module, the Rational DOORS database hierarchy, a Rational RequisitePro Project, a Rational Tau UML project, and so on. Additionally, you can generate special-purpose XSDs, for example for access to user-defined attributes and the view-columns of a Rational DOORS module.
A document template also includes several more features:
- You can use style definitions to consistently control the appearance of the whole module. You can assign them to multiple document elements, the same way you do in a normal text processing application.
- Master pages are similar to paragraph styles for pages. You use them to define the properties of the pages of the generated document and also define the content of the header and footer area.
- You can use variables to supply parameters to a document template.
- You can use assignments to move information around (for instance, the name of the author of a DOORS module to the page-header).
- With variables and assignments, you can also perform easy calculations, such as counting the occurrences of a query.
Figure 3 shows the document generated for the Flight Model requirement. It is the result of applying the template depicted in Figure 2 to the DOORS module depicted in Figure 1.
Figure 3. Document generated from the template shown in Figure 2
DocExpress is a legacy solution for document generation. Its main purpose is to generate Microsoft Word documents that contain extracted information from Rational DOORS, but DocExpress also supports some other data sources and target formats. Some of the reasons for developing Rational Publishing Engine are the main shortcomings of DocExpress: it is rather slow and it uses the system clipboard. This creates a certain risk that data from other currently active applications make their way into the generated document without you noticing.
This section describes how to replace DocExpress with Rational Publishing Engine, which can help your team migrate. If you do not use DocExpress, this section also gives hands-on examples of the power of the Rational Publishing Engine: the shown templates solve typical document generation tasks for Rational DOORS.
DocExpress contains two applications to generate documents, which differ in the way that the document generation is configured:
- DocExpress/Word has a user interface within Microsoft Word, and includes dialogs that support the selection of data to be extracted.
- DocExpress/Factory is template-driven, and you configure the data sources in a configuration text file.
Both applications, however, use the same set of data extraction utilities. For Rational DOORS versions up to Version 3.x, two data extractors are most important:
The newer DocExpress (Version 4) includes a new UI useable from within Rational DOORS. It also encapsulates the data extractors of the previous version, and makes them available as different kinds of reports. The view-based reports largely represent the capabilities of the
Get_View extractor, and the basic reports the capabilities of the
Also available is a combined report, which is simply a concatenation of View-based and Basic reports. You can create a combined report using the Rational Publishing Engine document templates for the DocExpress view-based and basic reports together in a document specification.
The following sections show how to define Rational Publishing Engine document templates for the DocExpress data extractors and reports.
View-based reports and the Get_View extractor
The DocExpress View-based report and the
extractor support reproducing a DOORS view (as shown
in Figure 1) into a document. You can format the view either as a table, or as paragraphs. The results look like those shown in Figure 6 and Figure 7.
Some additional formatting options are available for
Get_View and the view-based reports:
- For the table option, the total width of the generated table can be defined
- For the paragraphs option, the indenting level defines the Word heading level for a heading of level 1 in Rational DOORS.
Both options are available in Rational Publishing Engine as well, and you can define parameters for them though Rational Publishing Engine variables. Also, both document generators can apply document generation for the current (or a named older) baseline of a Rational DOORS module.
In Rational Publishing Engine, the data for a data source of the
DOORS Module type contains not only the Rational DOORS module and object attributes, but also a configurable view. The data for this view is automatically extracted, and is available for a document template through the data source. You can use this to build two Rational Publishing Engine templates that resemble the view-based report of DocExpress.
Report templates and generated results
Figure 4 shows the table mode and Figure 5 shows the paragraph mode of the view-based report. The depicted example templates do not give the definitions to reproduce a Rational DOORS table. This does not impose a limitation, however, because Rational Publishing Engine can also reproduce a Rational DOORS table nearly perfectly. The generated results of the templates in Figures 4 and 5 are shown in Figures 6 and 7, respectively.
Figure 4. Rational Publishing Engine template for view-based reports in Table mode
Figure 5. Rational Publishing Engine template for view-based reports in Paragraphs mode
Figure 6. Result of Rational Publishing Engine template for view-based reports in table mode
Figure 7. Result of Rational Publishing Engine template for view-based reports in paragraph mode
There is one automated feature in DocExpress that Rational Publishing Engine does not have: DocExpress reproduces the proportions of the column widths in the generated document, in the table-mode of a View-based report. As a simple workaround in Rational Publishing Engine, you can directly assign the table cell widths in the document template.
Compared with the view-based reports of DocExpress, you have much more influence on the generated documents with Rational Publishing Engine. Examples of things that you can change include, but are not limited, the borders, fonts, and colors of the table headers and data. You could, for instance, decide to give every second row in the table a different background color.
The given templates are only examples, and you can also modify them further in order to implement features that were never before possible in View-based reports. For example, you can switch off the small tables in Figure 7 for heading and information objects with a simple condition, or you can automatically leave out empty table entries.
In addition, suppose you decide that the table in Figure 6 looks awful because it includes heading objects and Rational DOORS tables. That was the way that the document was generated by the view-based reports of DocExpress. However, you can modify the Rational Publishing Engine template to break the table at heading objects, figures, and Rational DOORS tables, and thus create a better looking layout.
Basic reports and Parse_Dps-Extractor
The basic reports and the Parse_Dps extractor in DocExpress offer much broader possibilities to modify the generated documents than the view-based reports. The possibilities compare well with a mail-merge function in a document processing application.
The objects in a Rational DOORS module assume the role of all of the people that you want to write letters to. With the basic report processor, the first actions are that the Rational DOORS objects can be filtered and sorted, because you would maybe not include every address of your database in a mail-merge.
In the basic report processor, you can assign an individual Microsoft Word document template (actually a *.dot file, called an object template) for every Rational DOORS object. The templates can be compared to different letters that you want to send to the addresses. With the basic report, you could assign every object a different object template file, but that would be a lot of work. Normally, you classify the objects (for example, heading objects, information objects, requirement objects, objects with a table, and so on) and assign different Microsoft Word templates to each class. Compared with the mail-merge task, you maybe divide the customers into multiple classes. Some get a personal letter, and others get a more formal letter.
What the basic report then does is create the letters for each address (that is, one document for each Rational DOORS object). Subsequently, all of the generated small documents are concatenated to build one larger result document.
The process of "creating the letters for each address" means that, in the Microsoft Word templates, all of the DocExpress macro references are substituted by their content. Basically, there are macro references for all of the user-defined
Module attributes of a Rational DOORS object. Some other macro references are available that are substituted with the current date and time, module name, project name, and so on. Using these macros, you can create a nice small document for each object. In Figure 8, the left side shows an object template for requirement objects. On the right side, the template is used as part of a basic report, together with other object templates for information and heading objects.
Figure 8. Configuration of a DocExpress basic report with Microsoft Word *.dot template files
The basic reports and the Parse_Dps Extractor have the same features. Their only difference is the way that they are configured. The Parse_Dps Extractor executes a small script (in the scripting language of Rational DOORS) that computes the filename of the Microsoft Word document template file for each object. The basic report, on the other hand, contains a list of Rational DOORS filter expressions, and assigns different templates to the result objects of these filter expressions.
Map basic report features to Rational Publishing Engine
Rational Publishing Engine does not have a single, static template that implements all of the possibilities of the basic reports. But you can map the features very well to Rational Publishing Engine. To map the Rational DOORS object processing with the selection of a template for each Rational DOORS object, you can apply a query that matches all of the Rational DOORS objects of a module to a Container object, as shown in Figure 9. You can apply the initial filter and sorting that is done in the basic report as a Rational Publishing Engine native filter and sort to the query in the outermost container, respectively.
Inside this container, you can add more containers, like the container (c) shown in Figure 9. You must edit each of these containers to hold a Rational Publishing Engine representation of a DocExpress Microsoft Word object template. Because Rational Publishing Engine also has all of the output elements (such as paragraphs, tables, images, lists, and so on), and can access object and module attributes, this should be straightforward.
The containers (a) and (b) in Figure 9, for example, resemble standard DocExpress object templates for regular and heading objects in Rational DOORS. The filter conditions for application of the object templates are translated in Rational Publishing Engine as conditions of the inner containers.
Figure 9. Framework for creating a Rational Publishing Engine template for a basic report
The available information for assigning a translated object template in a Rational Publishing Engine template compares well to the filter-rules used for assignments in the basic scripts. In the Parse_Dps Extractor, however, Rational DOORS DXL-scripts are executed to assign object templates to objects.
This naturally offers broader possibilities for evaluating the condition. In a sample application, for example, the object history is accessed to create different colored bars at the left side of the object text. The object history is not available in Rational Publishing Engine, but there is a simple workaround: assign the filter script of
Parse_Dps in Rational DOORS to a DXL attribute. Next, use the value of this attribute to implement the conditions that choose a container holding the translated object template in a Rational Publishing Engine template.
Three special circumstances
There are three exceptional situations, which you must handle separately:
Parse_Dpsextractor can be used to generate a master page of a document only when it uses only one object template, in which no object attributes occur.
- The basic report can be configured in such a manner that a view-based report is added above or below of an object template.
- The basic report and the
Parse_Dpsextractor can be configured so that they create a table from multiple requirement objects. Figure 10 gives an example: Tables should be generated that resemble the view where data is supplied (in other words, only for requirements).
Figure 10. Challenge: Create tables from multiple Rational DOORS objects, where data is available
You can easily handle the first two situations in Rational Publishing Engine as well. Creating a Rational Publishing Engine template that creates a master page for a document from module attributes only is straightforward. Also, if you want to add a view-based report above or below an object template, use one of the templates shown in Figure 4 or Figure 5. Insert the template above, below, or instead of the object templates that you enter into the template framework in Figure 9 (for example, into (c) container).
For the implementation of the third situation, the straightforward solution has a problem. When multiple objects for which a table must be generated occur below each other, the result of a naive approach would be a table with multiple table header lines. To solve this problem, an important formatting property has been defined for row-objects in a table: The row property
If set to
true, this property produces the specified row only once when it occurs multiple times in a template. It is set for the row containing the table header line in the Rational Publishing Engine template shown in Figure 11. In Figure 12, you can see the result document that Rational Publishing Engine generated with this template.
Figure 11. Template for generating a document for the data of Figure 10
Figure 12. Example result of application of Rational Publishing Engine template from Figure 11
Summary of what you have learned
This article described Rational Publishing Engine, a new, fast and flexible application for generating documents that contain information from a wide variety of IBM Rational software engineering applications. It showed that document generation in Rational Publishing Engine is configured by defining document specifications that reference reusable document templates.
It explained the key concepts of document templates:
- Data source definitions define the structure of the input data
- The output element hierarchy defines the output document structure
- Queries specify how the input data should appear in the output element hierarchy
The other important building blocks of the document templates were also named:
- Master Page Definitions
The examples throughout this article show that Rational Publishing Engine is an extremely flexible document generator.
The second part of this article showed you how to configure Rational Publishing Engine in such a way that it can produce virtually the same documents that you can generate with DocExpress. Using the systematic approach described in this article you can translate DocExpress templates (of the newest Version 4, but also of the older version 3) into templates for Rational Publishing Engine. This allows for migration of DocExpress to Rational Publishing Engine. Rational Publishing Engine is the much more efficient, robust, and stable solution, and it offers a wealth of options for formatting the target documents.
For Version 4 of DocExpress, IBM additionally will offer an automatic migration tool that helps you create the necessary Rational Publishing Engine templates from the object templates that are used in a basic report.
- Learn more in the Rational Publishing Engine product page or developerWorks page.
- Take a course about Efficient Document Production.
- Learn about other applications in the IBM Rational Software Delivery Platform, including collaboration tools for parallel development and geographically dispersed teams, plus specialized software for architecture management, asset management, change and release management, integrated requirements management, process and portfolio management, and quality management.
- Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
- Explore Rational computer-based, Web-based, and instructor-led online courses. Hone your skills and learn more about Rational tools with these courses, which range from introductory to advanced. The courses on this catalog are available for purchase through computer-based training or Web-based training. Additionally, some "Getting Started" courses are available free of charge.
- Subscribe to the Rational Edge newsletter for articles on the concepts behind effective software development.
- Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
- Browse the technology bookstore for books on these and other technical topics.
Get products and technologies
- Download trial versions of IBM Rational software.
- Download these IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Tivoli®, and WebSphere®.