Customizing the migration of Rational ClearQuest Test Manager test assets

If the default mapping of Rational® ClearQuest® Test Manager record fields to Rational Quality Manager record fields is insufficient, you can modify the mapping to suit your needs.

The migration mappings file - migration.cfg

The mapping of test assets is controlled via an XML file named migration.cfg. On Rational ClearQuest 7.0.1, this file is typically installed into the following directory path:

CQInstallDir.Rational\ClearQuest\rcp_configuration_701\eclipse\plugins
\com.ibm.rational.clearquest.testmanagement.rqmexport_datestamp\data

On Rational ClearQuest 7.1 and newer, this file is typically installed into the user home directory:

UserHome\.Rational\ClearQuest\rcp_configuration_71\eclipse\plugins
\com.ibm.rational.clearquest.testmanagement.rqmexport_datestamp\data

For example, on a computer running Windows® XP with Rational ClearQuest 7.1, the location could be as follows:

C:\Documents and Settings\myname\.Rational\ClearQuest\rcp_configuration_71\eclipse\plugins
\com.ibm.rational.clearquest.testmanagement.rqmexport_2.0.0.v20091119_1542\data

In the migration.cfg file, the mappings for a particular artifact are contained within the <field _mapping> tags, whereas the individual mappings for each field within the artifact are defined in the <mapping> tags. For example, the following two lines of XML code indicate that the TMTestCase artifact in Rational ClearQuest Test Manager will be mapped to the TestCase artifact in Rational Quality Manager, and that the Headline field within TMTestCase will be mapped to the title field within TestCase.

<field_mapping type="TMTestCase" target="TestCase" task="Test Cases">
<mapping from="Headline" to="dc:title"/> 

To update a field mapping, modify the existing mapping with the appropriate from or to attribute setting. To add a new mapping, duplicate an existing mapping and update as appropriate. After adjusting the field mapping, rerun the migration wizard to utilize the updated mapping file.

The default mappings for a test case in the migration.cfg file are shown below.
<?xml version="1.0" encoding="UTF-8"?>

<config>

<!-- TEST CASE -->

<field_mapping type="TMTestCase" target="TestCase" task="Test Cases">
<mapping from="Headline" to="dc:title"/> 
<mapping from="Description" to="dc:description"/>
<mapping from="owner.login_name" to="jzalm:owner"/>
<mapping from="State" to="jzalm:state"/>
<mapping from="Notes_Log" to="myns:com.ibm.rqm.planning.editor.section.testCaseNotes extensionDisplayName=&quot;Notes&quot;" pre="true"/>
<mapping from="LegacyAcceptanceCriteria" to="myns:com.ibm.rqm.planning.editor.section.testCaseAcceptanceCriteria extensionDisplayName=&quot;Acceptance Criteria&quot;" pre="true"/>
<mapping from="LegacyPreConditions" to="myns:com.ibm.rqm.planning.editor.section.testCasePreCondition extensionDisplayName=&quot;Precondition&quot;" pre="true"/>
<mapping from="LegacyPostConditions" to="myns:com.ibm.rqm.planning.editor.section.testCasePostCondition extensionDisplayName=&quot;Postcondition&quot;" pre="true"/>
<mapping from="LegacyCustom1" to="myns:LegacyCustomField" pre="true"/>
<mapping from="LegacyInputs" to="myns:LegacyInputData" pre="true"/>
<mapping from="LegacyPassPoints" to="myns:LegacyPassPoints" pre="true"/>
<mapping from="LegacyFailPoints" to="myns:LegacyFailPoints" pre="true"/>
<mapping from="LegacyDesign" to="myns:LegacyDesign" pre="true"/>
<mapping from="History" to="myns:History" pre="true"/>
<mapping from="DefaultScript" to="testscript" scripttype="DefaultScriptType"/>
<mapping from="ExternalMotivators" to="attachment" file="true"/>
<mapping from="LegacyTotalPoints" to="weight"/>
<mapping from="ConfiguredTestCases.Script" to="testscript" scripttype="ConfiguredTestCases.TestType"/>

<!-- TM "properties" RAProject and Requirements_List are placeholders and can not be renamed -->
<!-- <mapping from="RAProject" to="RAProject"/> -->
<mapping from="Requirements_List" to="requirement"/>
<mapping from="Notes_Log" to="myns:com.ibm.rqm.planning.editor.section.testCaseNotes extensionDisplayName=&quot;Notes&quot;" pre="true"/>
<mapping from="custom2" to="LegacyCustom2"/>
<mapping from="custom3" to="LegacyCustom3"/>
</field_mapping>

The following table describes some additional directives that can be included within a mapping.

Table 1.
Directive Description
pre="true" Pre-formatted. Wraps the data so that it will not be reformatted.
file=”true” Specifies that the field references an external file in Rational ClearQuest Test Manager.
scripttype Only used for associated scripts.

Example 1 - Mapping a user-defined field

This example shows the simple case where a user-defined field in Rational ClearQuest Test Manager is mapped to an existing field in Rational Quality Manager.

<mapping from="InternalName" to="dc:title"/>

In this example, a user-defined field named InternalName is mapped to the title field in Rational Quality Manager.

Example 2 - Referencing a field from a referenced artifact

This example shows how a field in a referenced artifact is mapped to a field in Rational Quality Manager.

<mapping from="ParentPlan.Headline" to="dc:description"/>

In this example, the Headine field in the ParentPlan artifact is mapped to the description field in Rational Quality Manager.

Example 3 - Mapping a user-defined field into a user-defined section

This example shows how a user-defined field in Rational ClearQuest Test Manager is mapped to a user-defined section in Rational Quality Manager.

<mapping from="InternalName" to="myns:InternalName extensionDisplayName=&quot;Internal Name&quot;">

In this example, the mapping still references the custom InternalName field in Rational ClearQuest Test Manager, but now it maps to a user-defined section in Rational Quality Manager, also called InternalName.

The name of the user-defined section in Rational Quality Manager can be any name without spaces and must be prefaced with myns:.

The last part of this example - extensionDisplayName=&quot;Internal Name&quot;" - specifies how the section name will appear in Rational Quality Manager.

Here, the user-defined section name, InternalName, will be displayed as Internal Name. Internal Name must be enclosed in quotes, but because it is to be included within an XML file, the quotes must be replaced with the escaped version of the quotes, that is, &quot;.

Example 4 - Replacing values in Rational ClearQuest Test Manager

This example shows how values in Rational ClearQuest Test Manager are replaced with values in Rational Quality Manager.

<enum_mapping name="jzalm:state">
<mapping from="pass" to="com.ibm.rqm.execution.common.state.passed"/>
<mapping from="fail" to="com.ibm.rqm.execution.common.state.failed"/>
<mapping from="inconclusive" to="com.ibm.rqm.execution.common.state.inconclusive"/>
<mapping from="error" to="com.ibm.rqm.execution.common.state.inconclusive"/>
<mapping from="Draft" to="com.ibm.rqm.planning.common.new"/>
<mapping from="Approved" to="com.ibm.rqm.planning.common.approved"/>
<mapping from="ForReview" to="com.ibm.rqm.planning.common.underreview"/>
<mapping from="Blocked" to="com.ibm.rqm.planning.common.new"/>
<mapping from="Implemented" to="com.ibm.rqm.planning.common.new"/>
</enum_mapping>

In this example, the enumerated tag starts with the keyword enum_mapping, and the name attribute specifies the field in Rational ClearQuest Test Manager whose values are to be replaced. In the first row, the pass attribute is to be replaced with com.ibm.rqm.execution.common.state.passed in Rational Quality Manager. On the other hand, if you wanted all inconclusive test results mapped to failures in Rational Quality Manager, you would change that row to <mapping from="inconclusive" to="com.ibm.rqm.execution.common.state.failed"/>.

Example 5 - Defining categories in the migration.cfg file

You can map fields and their values in Rational ClearQuest Test Manage to categories and values in Rational Quality Manager. If the category does not exist, it will be created.

<attribute from="State" to="category term=&quot;Test&quot; " value="value"/>          

In this example, the State field and its values will be mapped to a category named Test. The values in the State field will be migrated also.


Feedback