SoDA Migration Utility for Rational Publishing Engine

Content

Overview

Installation

Usage

Limitations

SoDA Commands




MicroSoft Word Elements




Paragraph




Other Limitations




Rational Publishing Engine Template Customizations

The purpose of this tool is to provide an assisted transition of SoDA users to Rational Publishing Engine. 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.

The version of the SoDA Migration utility that is included in Rational Publishing Engine 1.1.1 has been tested on RequisitePro SoDA templates only. Although this tool does not contain any RequisitePro-specific features, it might not be appropriate to use in other SoDA domains.

For a single schema used by SoDA multiple Rational Publishing Engine schemas may be required. For example, to cover all the elements in the RequisitePro schema used by SoDA several schemas obtained via the REST API are required: requirements, packages, UC, FEAT and SUP schemas. This makes it impossible to have a fully automated conversion process.

To overcome this problem the tool is designed to "learn" as templates are migrated. Once a template is successfully converted, this utility will remember the actions the user has taken: what SoDA queries were mapped to what Rational Publishing Engine queries. This information will be used in future conversion processes.

The application will get better as the number of converted templates increases. To assist the user, the knowledge can be passed from one tool instance to another. This allows users to share the results of their work. Initially, the tool comes with a small amount of knowledge consisting in a default file, consisting in SoDA-to-Rational Publishing Engine mappings of queries and attributes.

The net result of this approach is that after enough knowledge has been gathered, the intervention of the human operator in the migration process can be close to zero.

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

Note: This utility is an unsupported TechPreview.

The SoDA migration tool consists of a plugin that can be installed in the Rational Publishing Engine Document Studio by unpacking the file '%RPE_HOME%\utils\import\com.ibm.rational.rpe.migration.soda.zip' into the '%RPE_HOME%' folder.

After the SoDA Migration plugin has been installed, restart the Document Studio. A new menu will be available under Import > Rational SoDA, also the plugin will expose a toolbar icon.

In order to uninstall this plugin, remove the folder '%RPE_HOME%\importer' and the file '%RPE_HOME%\studio\plugins\com.ibm.rational.rpe.migration.soda_1.1.1.200911241307.jar'.

This utility consists of a wizard that gathers the required information and it will generate a Rational Publishing Engine document template after finishing the wizard.

1. The first dialog of the wizard simply welcomes you to this utility, click Next:
   
   
   
2. A window opens that collects the path to the input SoDA template file (a MicoSoft Word .doc file) and the path to the destination (output) Rational Publishing Engine document template, a .dta file. then click Next:
   
   
   
   
3. The wizard will read the SoDA template and populate this third dialog with information from that file.
   
   The table in this dialog displays the names of the SoDA data sources present in the SoDA template, along with their domain name. A matching is attempted between SoDA data sources and Rational Publishing Engine schema files.
   
   Shown in this dialog is such matching between the 'RequisitePro_Project' SoDA data source and the 'default/PR_Requirements.xsd' schema file.
   
   
   
   
4. More schema files can be assigned by clicking the '...' ellipsis button in the 'Rational Publishing Engine Schema' table column. This will bring up the 'Schema File Selection' dialog.
   
   This dialog lists the current schema assignments. Add or Remove operations can be performed here:
   
   
   
   
5. Clicking the 'Add Schema...' button, the list of schema files is shown. One or more schema files might need to be added to this mapping to cover the queries from a single SoDA data source:
   
   
   
   These .xsd files are stored in the '%RPE_HOME%\importer\soda\schema\' folder. The current version of the SoDA Migration Utility contains several schemas for the RequisitePro domain. If needed, add more schema files to the '%RPE_HOME%\importer\soda\schema\user' folder to ensure matches of a wider range of SoDA queries.
   
   
6. Once the SoDA - Rational Publishing Engine schema mapping is complete. click 'Next' in the wizard dialog. This wizard page allows the configuration of SoDA queries, Rational Publishing Engine queries and attribute mappings.
   
   The first column in this table displays the SoDA query in a read-only form, as it was read from the SoDA template. The second column allows a selection of a Rational Publishing Engine query that is known to return the same data as the SoDA query:
   
   
   
   A Rational Publishing Engine query can be added or edited by clicking the appropriate row in the 'Rational Publishing Engine Query' column. In the drop-down list that appears, use the '<SELECT NEW...>' entry to configure the Rational Publishing Engine query.
   
   
   
   A dialog is shown, containing several tabs, one for each schema file assigned earlier:
   
   
   
   In the schema file that is appropriate for the corresponding SoDA query, navigate to the schema element that is known to match the same information from the SoDA template. Once this matching has been found, click the 'OK' button to set this assignment to the SoDA query.
   
   
   
   
7. To complete the mapping for a SoDA query, the mapping between SoDA and Rational Publishing Engine attributes needs to be selected as well. Click the '...' ellipses button available on the 'Attribute Mapping' column corresponding to a SoDA query.
   
   This displays a dialog that shows the SoDA to Rational Publishing Engine attribute mapping. Select the appropriate Rational Publishing Engine attribute in the drop-down list available in the second column.
   
   
   
   Once the Rational Publishing Engine query and Attribute mappings have been completed for all SoDA queries, click 'Next' on the wizard page.
   
8. This dialog provides the options to save the current selections to the mappings file. If the option 'Overwrite the mappings file' is checked, the mappings for the queries and attributes will be saved so that the next time the user goes through the wizard, the tool will remember these selections. This helps the tool learn so it minimizes the work required for subsequent runs.
   
   Check the 'Open RPE Template in Document Studio' to have the resulting template shown, once the migration process completes, then click Next:
   
   
   
   
9. The Summary page appears:
   
   The conversion process starts once the 'Finish' button is clicked.
   
   
   
   
10. All the information regarding the SoDA - Rational Publishing Engine queries and attributes mappings is stored in a mapping file, located in '%RPE_HOME%\importer\soda\mapping\user\mappings.xml'.
    
    This file can be shared with other users, other mapping files can be added to the 'SoDA Mapping Files Location' preference page. All mapping files listed in the preference page are being considered when query and attribute mappings are being looked-up during the wizard.
    
    

The current implementation of this migration utility has several limitations that are described in this section.

SoDA Commands

1. OPEN
   
   OPEN commands that that have multiple arguments are not supported in this version of the tool.
   
   
2. REPEAT
   
   The following sections of a REPEAT command are not supported:
• Predicate
• Ordering
• Recursive replicator
  
  
3. LIMIT
   
   The following sections of a LIMIT command are not supported:
• Transform
• Predicate
  
  For LIMIT command Rational Publishing Engine will create a container and will add a condition on this element. The condition body will be "SoDA LIMIT Predicate". After template generation the user should edit this condition in accordance with the LIMIT predicate.
  
  LIMIT OMIT and LIMIT OTHERWISE are treated identical with the simple LIMIT command.
  
  
4. DISPLAY
   
   The 'filter' feature is not supported.

MicroSoft Word Elements

Only the following properties are being read from the SoDA template and set in the resulting Rational Publishing Engine template for the generated elements. If a property is not set in the SoDA template, or if it matches the default value, it will not be set.

• inherited style name (only if the style is a heading type one)
• paragraph alignment
• top border style
• top border width
• top border color
• right border style
• right border width
• right border color
• bottom border style
• bottom border width
• bottom border color
• left border style
• left border width
• left border color
• before spacing
• after spacing
• multiple line spacing
• first line indent
• hanging indent
• left indent
• right indent
• level number
• numbering style

• font color
• font size
• font family
• bold
• italic
• underline
• strikethrough
• character spacing
• subscript
• superscript
• all borders style
• all borders color
• all borders width
• text background color

• font color
• font size
• font family
• bold
• italic
• underline

• cell spacing
• table alignment
• top border style
• top border width
• top border color
• right border style
• right border width
• right border color
• bottom border style
• bottom border width
• bottom border color
• left border style
• left border width
• left border color

• top border style
• top border width
• top border color
• right border style
• right border width
• right border color
• bottom border style
• bottom border width
• bottom border color
• left border style
• left border width
• left border color
• cell text top padding
• cell text right padding
• cell text bottom padding
• cell text left padding
• cell background color

• image width
• image height
• image alignment

• font color
• font size
• font family
• bold
• italic
• underline
• underline color
• strikethrough
• character spacing
• subscript
• superscript
• text background color

• font color
• font size
• font family
• bold
• italic
• underline
• strikethrough
• character spacing
• subscript
• superscript
• text background color
• footnote type

• font color
• font size
• font family
• bold
• italic
• underline
• strikethrough
• character spacing
• subscript
• superscript
• text background color

• row height
• row repeat at page beginning

• numbering style

• font color
• font size
• font family
• bold
• italic
• underline
• strikethrough
• character spacing
• subscript
• superscript
• all borders style
• all borders color
• all borders width
• text background color

• field code

• page orientation
• paper size
• paper height
• paper width

• header from top

• footer from bottom

Other Limitations

Certain SoDA data sources can map to multiple Rational Publishing Engine schemas and operations such as 'Join' cannot be performed in these scenarios. This means that the data sources will be added to the Rational Publishing Engine resulting template, with the user having to manually add a condition on the desired template elements to perform the Join operation.

Rational Publishing Engine Template Customizations

• Due to the command limitations highlighted above, the resulting Rational Publishing Engine template will not have any conditions set. Template designers can add conditions in appropriate locations in the template.
  
  
• Because of the SoDA template structure, empty Paragraph elements can appear in the resulting template. These can be removed if no longer needed.
  
  
• If there are lists elements in the SoDA template, it is possible in Rational Publishing Engine template to have a list element with one or more paragraphs inside. Please remove all paragraphs from the list element, to obtain a better output.
  
  
• For each OPEN commands with calculated values, the resulting Rational Publishing Engine template will contains a Dynamic Data Source Configuration element. The user should configure this element with a specific value as needed.
  
  
• The REPEAT commands that have the Heading style, in the resulting template a Paragraph element with that Heading style will be created. Inside such Paragraph elements there will be a Container element having the Repeat query. The user should remove the Heading style from the parent Container element.