Rational Publishing Engine introduction for DocExpress users

A comparison of features

IBM Rational Publishing Engine is a new, fast, and flexible application for generating documents from a wide variety of software engineering applications. This article explains its key concepts and compares them to DocExpress, so that you can systematically replace that tool.

Matthias T Jung (matthias.jung@de.ibm.com), IT Specialist, IBM Deutschland GmbH

Matthias JungDr. Matthias Jung is a consultant at IBM Software Services, Rational. He came to IBM through the acquisition of Telelogic, where he helped companies generate documents for rolling out their requirements management processes.



15 October 2009

Also available in Chinese

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
Columns of system requirements, comments, etc

Larger view of Figure 1.

Rational DOORS terms

In Rational DOORS, single requirement specifications are represented by Modules, which are organized in the Rational DOORS database in Projects and Folders. This is much like files in a file system. Each module holds a set of requirement objects.

Within Rational DOORS, you use the module browser for editing such a module, as shown in Figure 1. The module browser looks like a combination of Microsoft® Word and Microsoft® Excel. The rows store the different objects from the module, and the columns show the values of different attributes. The most important attributes are the object text and the object heading, both shown together in the main column (column 2 of Figure 1), and the object identifier. You can define other attributes.

In the module browser, you can save an arrangement of the attributes into columns, together with a filter condition for the objects, as a view.

Also important in Rational DOORS are the links between the objects that document, for instance, how requirements are derived from each other.

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.

Managing change

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.

Design goals

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 format

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
Nested boxes represent the referenced elements

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.

Additional features

To further control the appearance of the output document, the paragraph nodes can have conditions and properties. The conditions are noted in JavaScript®, and in this case will produce only the paragraphs, if the text in them is not empty. They are necessary, because a Rational DOORS object will normally contain either a value for the object heading attribute, or for the object text attribute. The properties control the appearance of the paragraphs. The paragraph holding the object heading will thus generate a heading paragraph following the level of the requirement object, whereas the object text will generate a normal text paragraph (these properties are not depicted in Figure 2.

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
1.1 Overview, 1.2 Environment

DocExpress

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: Get_View and Parse_Dps.

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 Parse_Dps extractor.

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 Get_View data 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
Container, with table, row, cell, and text inside
Figure 5. Rational Publishing Engine template for view-based reports in Paragraphs mode
Container, paragraph, and text
Figure 6. Result of Rational Publishing Engine template for view-based reports in table mode
Table with ID, system reqs , prio , and risk cols
Figure 7. Result of Rational Publishing Engine template for view-based reports in paragraph mode
Paragraphs with ID, Priority, and Risk rows

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.

Additional customization

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 Object and 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
Design window on left, result text and table right

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
heading is marked (a), text (b), and container (c)

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:

  • The Parse_Dps extractor 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_Dps extractor 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
Functional requirements table

Larger view of Figure 10.

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 only once.

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
Template shows table generation

Larger view of Figure 11.

Figure 12. Example result of application of Rational Publishing Engine template from Figure 11
Header, text, and generated tables

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:

  • Conditions
  • Master Page Definitions
  • Variables
  • Assignments

    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.

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. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. 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=431896
ArticleTitle=Rational Publishing Engine introduction for DocExpress users
publish-date=10152009