1. Prerequisites and Scope

This tool mentor was written with the following tools:

• IBM Rational Publishing Engine (RPE) v1.1.2.2
• IBM Rational DOORS v9.4
• IBM Rational Quality Manager (RQM) v4.0
• IBM Rational Team Concert (RTC) v4.0

This tool mentor assumes that the reader has a basic understanding of the above mentioned tools. This tool mentor should not be used as tool training by itself, rather, this tool mentor should be used as supplementation information and guidance.

The RPE templates provided by the IBM Rational Systems Accelerator are provided as-is. These templates should be considered to be examples of functionality that can be produced for output document reports and not necessarily complete/finalized document templates. Use these templates as examples and functionality to build off of and to extend for your own organization's report use cases.

2. Introduction

RPE's Launcher client is used to generate document(s) based upon report template(s) that are already created. You create a document specification (.dsx file) with the Launcher. A document specification can consist of one or more document templates (.dta file) and it can produce any one or all of the document output types (.doc, .pdf, .html, .fo) in a single document generation.

In a document specification, for each included template you must specify any required data source URI and login credentials and any required run-time parameter values. You must also specify the output document information including which output types you wish to produce and the path where you wish the output documents to be placed. In the case of a Microsoft Word output document you can also specify a Word style sheet and/or Word macro to be used.

This perspective of RPE is for an end user who just wishes to generate documents based upon templates that have already been created for him. RPE separates the document generator role from the template author role, thus one doesn't need to know anything about how the template was created in order to use the template. The document generator role typically only has access to RPE's Launcher client and should not need access to the Document Studio client for any reason.

3. Included Templates in the Systems Solution

For a detailed description see RPE Systems Solution Templates.

4. Understanding a Document Specification in the RPE Launcher Client

The following section describes how to use the Launcher to generate reports. The Launcher creates/uses a Document Specification. A document specification is a saved configuration of a document generation including what template(s) to use, configuration properties of the data sources in those templates, and the desired output document types to produce during the generation.

1. Open the RPE Launcher client from a document specification file

a. Right-click on any document specification file (.dsx file) and choose Open with Rational Publishing Engine.

b. If the RPE "Welcome" screen appears, close it by pushing the "x" button on the Welcome tab in the upper left corner of the screen.

2. Explore the RPE Launcher

a. The RPE Launcher has only 3 very simple to use panes:

i. The "Document Specification" pane shows your output documents to be created and the templates that the generation process will use. Each template has data sources which are either defined by you, or dynamically configured in the template. Each template also has "Variables" which are run-time parameters that can be defined by you, the document generator.

Note - Red vs. black nodes: The various nodes of the Document Specification pane are colored in either black or red. A node is red when it has a property where you can specify a value, but no value has been specified yet. A node turns black when a value has been specified for that property. Note that it is not necessarily a problem if a node is red for example if you have a defined dynamic data source you would not need to specify a URI and/or credentials for that data source.

ii. The "Properties" pane shows you the properties of the currently selected element in the Document Specification pane. Select any of the elements to see its properties. Certain properties have fields that you can modify by selecting the row in the Value column of the pane.

iii. The "Console" pane displays messages at run time as well as when you're performing other operations like saving the Specification.

4.1 Define Output Document Types

The "Output" node in the document specification pane allows you to define the output file types that you wish to generate. You can choose to add or remove any one or all of the output formats for a single generation. The below instructions explain how to add a Word output document. You can follow the same steps for any output type, but select the desired output driver.

1. To add a Word output document

a. Find the "Output" node at the top of the Document Specification pane.

b. Right-click on the Output node and choose Add Output>Word>Telelogic.Word.Driver

c. A new "Target:Word" node will be added to your Document Specification.

d. Right-click on this node and choose "Configure Output..."

e. Specify an appropriate Path to your output document i.e. the Output folder as described above, and give your output document a descriptive name.

Note - Word stylesheets and macros: Notice that you can also specify a Word style sheet for your Word output as well as a Word macro to automatically execute post-generation. Note that the style sheet and macro will only be applied to your Word output document. Also note that the macro will only run if you have Word installed on the same machine where the generation process is taking place (post generation, RPE will open Word in the background and apply the specified macro).

Note - Word 2003 and 2007 support: RPE supports both Word 2003 and Word 2007 output formats. RPE defaults to Word 2003. To specify Word 2007, simply add ".docx" or ".docm" to the path of your Word output document. Note that you can also use Word 2007 stylesheets (.dotm or .dotx) with Word 2007 output.

f. Click the "OK" button.

g. Select the Word output node and notice that the properties pane is updated with the values that you just specified. Note that you can also manipulate the values that you just provided in the Properties pane.

Note - Simultaneous generation of 4 output types: RPE can generate any or all of the 4 output types simultaneously during any given generation process. The output drivers are built into RPE and thus no other application is required to be installed to generate any of the 4 output types (except for Word macros as described in the information box above).

2. You can follow these same/similar steps to add any of the other 3 output types to your generation. Try adding a PDF output to your generation by following the same steps, but select the PDF output driver.

4.2 Document templates under the Templates node

The "Templates" node shows you the templates that will be included in a generation of this document specification. Templates will generate in sequential order starting at the top of the list. You can add a template by right-clicking on the "Templates" node. You can right-click on a template to move it up or down in the order.

It is a best practice to create modular/reusable building blocks. The provided Systems Accelerator examples include a cover page template. This template contains only the cover page information. This template is reused in all of the document specifications provided by the Accelerator.

1. Explore the parts of the cover page template. 

a. Notice the "...\rational_cover_page.dta" template. This template can define your company's standard cover page, and includes a table of contents, headers and footers.

b. There are no Data Sources for this template as it simply prints static pages.

c. Note that this template has Variables for "Author" and "Title".

Note - Reusable and modular templates: This simple example shows the power of creating modular and reusable templates. You can ensure document consistency within your organization by creating a library of reusable templates.

i. Select the Author variable.

ii. In the properties pane, change the Value of the "value" property to your name. When you next generate this document, the printed author will be your name that you just specified for this variable.

d. You can also manipulate the Author vairable.

e. Save your Document Specification by clicking the save button in the upper left corner of the Launcher.

2. The second template in the provided document specification has several data sources defined to produce the final output. Depending on whether the data source is a DOORS, RTC, or RQM data source and depending on whether it has been dynamically configured, you will need to provide a URI and/or login credentials to that data source. Section 3 above provides information on configuration properties need to be defined for each example template. Section 4 below describes how to configure each type of data source.

4.3 Configuring a Data Source

With the provided examples, either a DOORS data source or an RQM data source will need to be configured. Note that the RTC data source in the provided templates is always dynamically configured.

4.3.1 DOORS Data Source

Notice the DOORS data source in the "...\SSE_Traceability_traceability_example v2.0.dta" template. This template will iterate over all objects in the starting requirements module and, for each object, it will follow the external link relationship to print the details of that related object. In this case, our data has links from the requirement to either work items in RTC or test cases in RQM.

Note - Show traceability automatically and in real-time: With RPE you can create documents that show traceability across objects in your development tools within just a few seconds or minutes. RPE will allow you to pass your audits quickly and accurately by removing the human element from creating cross tool reports.

To configure a DOORS data source:

a. In the Document Specification pane, select the DOORS data source denoted by "- DOORS". In the provided example, the data source is named "Data Source: DOORS_SRS - DOORS".

b. Notice the properties of this node in the properties pane:

i. The URI property specifies the location of the data that will be pulled to populate the end document. In this case, the data source is a particular DOORS module.

ii. A username or password has not been specified and the new_instance property has been set to "false." Thus, this specification has been set to use a instance of the DOORS client that is already running. You could change this so specify RPE to open an instance of the DOORS client in the background with specific DOORS credentials.

c. RPE includes easy to use wizards for configuring data sources. Right-click on the same DOORS data source and choose "Configure Data Source...".

i. Browse through the welcome wizard dialogues by clicking the "Next" button.

ii. You will then be presented with a tree view of your DOORS database explorer. Exapnd through the tree to find your appropriate project and folder where the module that you wish to use is located. For the module, you can even expand to choose a specific baseline and view within that baseline if you choose.

iii. Select "Finish" when you have found the appropriate module, baseline, and view that you wish to report against.

4.3.2 RQM Data Source

It is fairly simple to configure an RQM data source in the provided examples. Check Section 3 above to understand in each provided example which data source configuration properties need to be specified. Select the appropriate data source. Then, in the "Properties" pane type in the appropriate URI, username and/or password.

4.3.3 Dynamically Configured Data Sources

Notice that there can be red colored data sources in your document specification. As discussed in section 3 above, these data sources are all dynamically configured in the template, thus the URI property does not need to be specified for any of these data sources.

Note - Tool login credentials in RPE templates: Login credentials for various data sources are completely configurable in RPE templates based upon your tool authentication in your environment. The template could have been configured to assume that the DOORS user also has RTC and/or RQM access. There is no "extra" security involved with RPE. RPE uses the credentials and permissions that have been configured in the point tool(s). For example, if you login to DOORS with user "Joe", you can generate documents with RPE using your same "Joe" credential. Thus, an RPE document generation will only report on data that the specified credentials have access to in any given tool.

4.4 Generate a Document with the Launcher Client

Note - Ensure that the DOORS database explorer is open: RPE can be configured to either use an instance of the DOORS rich client (NOT DOORS Web Access) that is already open, or it can be configured to open a new instance of the DOORS client in the background as long as you provide appropriate DOORS credentials. The templates that you are using has been configured to use a currently opened instance of the DOORS client. Thus, if a DOORS client is not currently open, please open a DOORS client now. Use any credentials that you've already used which have access to the "Water Reader" project in DOORS (i.e. id/password - kavita/kavita).

1. To generate the current document:

a. In the middle of the lower menu bar, push the "Generate Current Document" button.

b. You will get a warning message that not all of the data sources have been configured. Remember that this is not an issue since these data sources have been dynamically configured in the template. Push the "Yes" button to continue with the generation.

c. You will see the progress dialogue just as you did in the exercise at the beginning of this lab. You will also see progress messages displayed in the console.

d. Once the generation is complete, you will be presented with the "Rational Publishing Engine - Results" dialogue. You can then click on the link to open the report. Note that this report is actually stored in the folder that you specified earlier. In this dialogue RPE gives you a convenient link to the output document in the specified folder.

2. When you are finished looking through the report, close the report and close the RPE results dialogue. If you are finished with RPE, you can also close the Launcher.

4.5 Generate a document with a right-click on the specification

You can implement a generation process without having to open the Launcher client. A simple right-click on a specification file will give you the option to generate your documents.

a. Navigate to any document specification.

b. Right-click on the specification (.dsx file) and choose Publish with Rational Publishing Engine.

c. You will see the RPE Launcher splash screen. Then, while the document is generating, you will see the "Publishing Document" status dialogue.

d. Once the generation is complete, you will be presented with the "Rational Publishing Engine - Results" dialogue. You can then click on the link to open the report. Note that this report is actually stored in the folder that you specified earlier. In this dialogue RPE gives you a convenient link to the output document in the specified folder.