DocExpress Migration Utility for Rational Publishing Engine

Content

---

Overview

Prerequisites

Installation

Usage

Importing Basic Reports




Importing Combined Reports

Limitations

---

Overview

The purpose of this tool is to provide an assisted transition of DocExpress users to Rational Publishing Engine.

This utility converts DocExpress reports to their Rational Publishing Engine equivalents. For each Basic Report, it will generate one Rational Publishing Engine template. The resulting template contains one Container element for each Rule and Exception, with conditional statements. Within this parent Container, various elements with static or dynamic data are being constructed.

For DocExpress View-based Reports, users are encouraged to use the 'view_paragraph.dta' and 'view_table.dta' templates. If a Basic Report contains an Exception with an inserted DOORS view, the resulting Rational Publishing Engine template will have a Dynamic Data Source element, pre-configured for the targeted DOORS module and view.

One Rational Publishing Engine Document Specification .dsx file is constructed for each DocExpress Combined Report. If the Basic Reports that are part of the Combined Report do not exist in the default path, they will be converted as well. The View-based Reports will not be generated every time, instead references to the 'view_paragraph.dta' and 'view_table.dta' templates will be made in the corresponding document specification file.

This utility attempts to mimic the DOORS projects, folders and modules structure, as sub-folders located in a path that can be set using the Preference page of this tool. This makes it easier to identify and to reuse DocExpress reports that have already been generated. The default location is %TEMP%.

In some cases, this utility will result in a Rational Publishing Engine template that will need further editing from the template designer to ensure the data and layout matches the business needs.

There can be differences in the way DocExpres and Rational Publishing Engine results look, due to changes in DOORS filter syntax that are impacting DocExpress. Other DocExpress issues and limitations might cause differences on the resulting document.

Refer to the Limitations section below for information on the features that are not supported.

Note: This utility is an unsupported TechPreview.

---

Prerequisites

The version of the DocExpress Migration utility that is included in Rational Publishing Engine 1.1.1 has been designed to work with reports built with DocExpress 4.3.1 and later. These reports need to be contained within a supported DOORS version.

DocExpress installation is not a requirement. This utility uses report information that has been stored by DocExpress in the DOORS database. The Template Library Location needs to be properly configured to point to where custom templates are located.

---

Installation

This utility consists of a plug-in that can be installed in the Rational Publishing Engine Document Studio by unpacking the file '%RPE_HOME%\utils\import\com.ibm.rational.rpe.migration.docexpress.zip' into the '%RPE_HOME%' folder.

After the DocExpress Migration plug-in has been installed, restart the Document Studio. New menu entries will be available under Import > Telelogic DocExpress, also the plug-in will expose two toolbar icons.

In order to uninstall this plug-in, remove the folder '%RPE_HOME%\studio\features\' and the file '%RPE_HOME%\studio\plugins\com.ibm.rational.rpe.migration.docexpress_1.1.1.200911181309.jar'.

---

Usage

This utility consists of a wizard that gathers the required information and it will generate one or more Rational Publishing Engine document templates and/or document specifications after finishing the wizard.

Importing Basic Reports

1. The first page of this wizard is a welcome dialog:
   
   
   
   
2. Clicking on 'Next' will bring up the 'DOORS Connection Options' wizard page:
   
   
   
   
3. After filling the DOORS connection options, click 'Next' to proceed to the next dialog. A hierarchical view of the DOORS database is shown. Expand this tree and navigate to the module where the desired Basic Reports are kept.
   
   To convert all the Basic Reports from the DOORS database, select the checkbox below. Note that converting all reports can be a time-consuming operation.
   
   
   
   
4. After selecting the module, click 'Next' to show the list of Basic Reports from the selected DOORS module.
   
   This dialog contains the names of the DocExpress Basic Reports, the path where this file will be generated and an entry on the third column for Basic Reports that already have a Rational Publishing Engine template equivalent in the target path.
   
   
   
   Template that have already been generated (as 'test report 1' in the screen capture above) will not be overwritten unless the checkbox underneath the table ('Overwrite Document Template files that already exist') is selected.
   
   Select one or more Basic Reports to be converted to Rational Publishing Engine template files by selecting the corresponding check boxes in the first column and click 'Next'.
   
   
5. The following dialog is shown only if a single Basic Report was selected.
   
   
   
   This screen shows the option to open the resulting Rational Publishing Engine template in Document Studio, which by default this is selected.
   
   
6. Click 'Next' to proceed to this dialog contains the Summary page.
   
   
   
   
7. Click 'Finish' to start the conversion process. Review the Console entries to determine how Rational Publishing Engine Templates are created.
   
   
   
   

Importing Combined Reports

This wizard will create Document Specification files and, if needed, Document Templates as well. It can be launched from the Import > Telelogic DocExpress > Import Combined Reports... menu entry, or from the toolbar.

1. The first page of the wizard is a welcome dialog.
   
   
   
   
2. Clicking 'Next' will bring up the 'DOORS Connection Options' wizard page:
   
   
   
   After filling the DOORS connection options, click 'Next' to proceed to the next dialog. A hierarchical view of the DOORS database is shown. Expand this tree and navigate to the DOORS project where the desired Combined Reports are kept.
   
   
3. To convert all the Combined Reports from the DOORS database, select the checkbox below. Note that this can be a time-consuming operation.
   
   
   
   After selecting a DOORS project, click 'Next' to show the list of Combined Reports from the selected project.
   
   
4. This dialog contains the names of the DocExpress Combined Reports, the path where the corresponding Document Specification file will be generated and an entry on the third column to configure settings for Basic Reports that compose the selected Combined Report.
   
   
   
   Clicking on the '...' (ellipses) button on the third column will show the dialog below, which allows the customization of the destination Rational Publishing Engine template for each Basic Report.
   
   The user can browse to any new or existing Rational Publishing Engine template. If such template already exists, this will be highlighted in the third column and those template files will not be overwritten. Instead, references to these existing Rational Publishing Engine templates will be made in the Document Specification.
   
   
   
   
5. After completing the Basic and Combined Report configuration, proceed to the following wizard page. This contains an option to have the resulting Document Specification file open in Rational Publishing Engine Launcher, once the process completes.
   
   
   
   
6. Click 'Next' to display the Summary page.
   
   
   
   Click 'Finish' to start the conversion process. Review the Console entries to determine how Rational Publishing Engine Templates and Document Specification files are created.

---

Limitations

• Rules defined using filter syntax checks with regular expressions are not supported.
  
  
• The 6 Default Basic Reports that are created by DocExpress for each DOORS module are not being converted, instead they will be offered as pre-generated Rational Publishing Engine Document Templates.
  
  
• The 'Change Orientation' rule format will not be supported.
  
  
• MS Word comments and footnotes support: only the root text or variables will be extracted. The first variable found shall be set for the Rational Publishing Engine comment element. Any Text element shall have the formatting of the first formatted text in the Word comment.
  
  
• The heading numbering is not read from the MS Word templates. The user can select a style-sheet that has numbered headings when publishing the Rational Publishing Engine.
  
  
• The page orientation is set by using Master Pages. The default orientation is set to Portrait, and when a rule contains the Landscape the corresponding Master Page is assigned to the container element. The default orientation can be set to Landscape by assigning the "landscape" value to the "defaultMasterpage" variable, contained by every generated template.
  
  
• Only the page orientation is read from the MS Word templates, other information such as page size, borders, and so forth needs to be set by the user using Master Pages.