Additional guidance and a workshop on importing ClearQuest records in to Rational Team Concert

Jennie Brown, Steven Cotugno, John Liu, Smita Gupta, Paul Bahrs, Yuhong Yin and Lorelei Ngooi
Last updated: January 10, 2013
Build basis: Rational Team Concert 4.0.1

Table of Contents
Summary
Use the ClearQuest Importer
Limitations
Import ClearQuest Records of Different Types
Import ClearQuest Records of Complicated Relationship
Update Imported Work Items with Additional Information in ClearQuest
An Alternate and More Generic Approach to Import ClearQuest Records to RTC
Workshop
More Information
About the Authors

Summary

This document provides guidance of using the ClearQuest Importer to import ClearQuest records of different record types into Rational Team Concert (RTC) as work items of different types, to preserve ClearQuest record relationships (such as the parent/child relationship and duplicate relationship, and to update imported work items with additional information in ClearQuest. It is a follow up of Guide to migrating defects from Rational ClearQuest to Rational Team Concert 2.0.

This document also introduces an alternate and more generic approach to import ClearQuest records to Rational Team Concert. A workshop that details the steps and procedures of this approach is included.

Use the ClearQuest Importer

Rational Team Concert provides the capability to import ClearQuest records into Rational Team Concert as work items. This is accomplished using the ClearQuest Importer function of the Team Concert client. The CQ Importer is accessed from the client by selecting File > Import > Team > ClearQuest Records.

Limitations

There are some limitations of the ClearQuest Importer.

The first limitation is the mapping file by default only deals with one ClearQuest record type. This constrains the scenario where you want to import multiple ClearQuest record types using one mapping file. From work flow mapping point of view, the ClearQuest Importer doesn’t adequately handle the case of importing to a different work item type with a different work flow. Moreover, the problem becomes more complicated when the ClearQuest state values are identical across the different ClearQuest record types, which is not uncommon. For example, “Submitted” is typically the initial state of a ClearQuest record whether that ClearQuest record type is a defect, task, etc. The importer will not be able to differentiate between a ClearQuest submitted defect from a ClearQuest submitted task, and assign both work items the same target state, which is correct for one, but invalid for the other.

The second limitation is that it doesn’t update work items when re-running the Importer. That means that everything that needs to be imported, must be imported together in one shot. This comes into play if you plan to run the ClearQuest Importer separately for each ClearQuest record type and there are relationships to maintain across the record types. For example, first run the ClearQuest importer to import the ClearQuest defects, and then run it to import the tasks, etc. In the case where the ClearQuest defects are parents to ClearQuest tasks, when the ClearQuest tasks are imported, it would be nice if the already imported RTC defect work items are updated with the parent/child link. Unfortunately, the ClearQuest Importer doesn’t currently support updates, so the parent/child link will not be created.

Given the current limitations of the ClearQuest Importer, it can be considered if the data can be imported into RTC in a single import pass, or you may need to use other tools such as the CSV Importer in conjunction to accomplish a more complicated importing task.

Import ClearQuest Records of Different Types

Let’s assume that you want import ClearQuest records of type “ChangeRequest” to work items of type “Defect”, and ClearQuest records of type “Task” to work items of type “Task”. You also want to preserve the reference relationship between the two record types.

The idea is that you run the ClearQuest Importer separately for each ClearQuest record type, but don’t import the contents into the RTC repository, but into separate files. Next, you combine the files and tweak the mapping file. You will then take the combined file with the modified mapping file to import to Rational Team Concert project area.

Here is a walkthrough with our example.

Define two queries in ClearQuest, one against the “ChangeRequest” record type, another one against the “Task” record type.
Run the ClearQuest Importer separately for the “ChangeRequest” record type and for the “Task” record type. This will create two XML files.
To deal with the workflow mapping issue, it’s crucial that the CQ state and resolution values are distinct across all CQ record types. Modify the mapping file so that the sourceId values for the state and resolution fields are prefixed with the CQ record type and that the targetId values are correct.
For example,
```
	<value sourceId="Submitted" targetId="1"/> 
```
becomes
```
	<value sourceId="Defect_Submitted" targetId="1"/>
	<value sourceId="Task_Submitted" targetId="12"/>
```
For each file created in step 1, modify the state and resolution values by prefixing them with the CQ record type name.
Combine the content of all the modified files into one large file.
Run the CQ Importer using the contents of the large, combined file and the modified mapping file to import into the RTC project area.

Import ClearQuest Records of Complicated Relationship

In this section, we discuss solutions to import ClearQuest records of complicated relationship.

Parent-Child Relationship

ClearQuest has several reference capabilities. For instance, one to one reference via the Reference field, one to many references via the Reference List field, many to one reference via the Back Reference capability, and many to many via the Reference and Back Reference capabilities. In general, ClearQuest schemas can be programmed to have any number of references or reference lists for a given record type. The various reference capabilities are often presented as “Parent” and “Children” relationships, but they are really references among records as opposed the strict parent-children relationship Rational Team Concert supported. When you import ClearQuest records into Rational Team Concert work items, you may consider importing in these references as “Related” instead of “Parent-Child”.

Duplicate Relationship

ClearQuest has a built-in capability to mark a record as a duplicate of another record. You need to make sure that the ClearQuest “Parents”, “Children” and “is_duplicate” fields are part of the query displays.

The mapping file should have the following lines besides other entries

<attribute sourceId="Duplicate_Of" 
 targetId="com.ibm.team.workitem.rcp.core.is_dup_of"/>
<attribute sourceId="Duplicated_By" 
 targetId="com.ibm.team.workitem.rcp.core.duplicates"/>

Update Imported Work Items with Additional ClearQuest Information

There are situations you want to modify the imported Rational Team Concert work items because there are additional changes happened to the ClearQuest records, or because you want to bring in additional ClearQuest information (extra fields, or relationships).

The procedure of an update often involves the following steps:

Exporting the imported work items out to a CSV file using the Rational Team Concert Client “Export Work Item…” feature.
Exporting ClearQuest records with additional information out as another CSV file.

To export the ClearQuest records as CSV format, you can either use the ClearQuest Eclipse client, or use the new “Save as CSV data” optional added to the ClearQuest Importer Wizard in Rational Team Concert v4.0.1 release. (See the Rational Team Concert 4.0.1 infoCenter for more information about this feature.).
Manipulating and combining the two CSV files to correlate the work item IDs in the first CSV file with the ClearQuest records IDs in the second file, and prepare for updating the work items with additional information from ClearQuest.
Importing the combined CSV file using the Rational Team Concert “Import Work Items from CSV” feature. Please make sure that you check the “Update matched Work Item” option.

An Alternate and More Generic Approach to Import ClearQuest Records to Rational Team Concert

In this section, we introduce an alternate and more generic appraoch to import ClearQuest records to Rational Team Concert. It does not use the ClearQuest Importer, but rather use the CSV Importer through a multiple-pass approach.

This approach should be considered when update to imported work items are required to preserve the record topology (i.e parent/child and/or related work item relationships). This method should also be considered for importing LDAP and/or sub-field data. A set of customized mapping files (one map file for each ClearQuest record type) are created that maps the record type to work item type, including the work item’s state flow. The import process for this method is illustrated in the graph below.

Figure 1: Import process for preserving Record Taxonomy

This process includes the following steps:

Define the data for export from ClearQuest and map to the target RTC configuration. Identify the link types and any LDAP related attributes that will be used for the update import. Perform an export of the data set(s) representing each record type. Include the ClearQuest record ID as a hidden attribute of the created RTC work item.
Transform the CSV files into a format that can be consumed by RTC and import into RTC to create the individual work items. In the first pass all records are imported into RTC as unlinked records.
Export linked data sets for each query of records that includes the ClearQuest record ID and any related record(s) and any additional attributes not retrieved by the original export (for example LDAP recognizable user names or any sub-field data).
Export a data set for each work item type that will need to be updated to add the links or additional attributes. Include the RTC ID and ClearQuest ID for each work item type.
Merge the data sets into a common .csv file. Create a new table for each link type that contains the RTC ID of one of the pairs linked.
Create a mapping function that transforms the ClearQuest ID of the linked record for each RTC work item into the RTC ID for the same linked record. (eg: For a Task, transform the parent ClearQuest ID to corresponding RTC Story ID. Repeat this for each link type and data set needed.
Import the transformed data sets to update the existing RTC records. Use each resulting data set to import and “update” the RTC database. The second pass updates the relationship links for related records, LDAP owners, LDAP creators, etc, resulting in a record hierarchy in RTC that mirrors the original ClearQuest organization including LDAP data.

Please note that the CSV Importer does not support the direct import of ClearQuest attachment to Work Item attachments (The ClearQuest Importer does support direct import of the attachments). However, attachments can be imported from ClearQuest to RTC as Related Artifact links. This is done by exporting the ClearQuest attachments from ClearQuest to an ftp directory (or Share point directory) and then updating the imported work items with their associated attachment URL’s using the Related Artifact link.

The workshop material in the next chapter demonstrates this process.

Workshop

This workshop documents detailed procedure for migrating records from an IBM Rational ClearQuest database into an IBM Rational Team Concern repository. It is generalized from a real world migration project and uses a ClearQuest ALM schema as the sample database.

Click here to download the workshop PDF file.

If you have any questions regarding the workshop material, please contact any of the following folks, Jennie Brown, Steve Cotugno, John Liu, Smita Gupta or Paul Bahrs.

For more information

Please refer to the Rational Team Concert infoCenter contents on the ClearQuest->RTC Importer.

The following are some enhancements against the ClearQuest->RTC Importer.

About the authors

Jennie Brown is an IT specialist at IBM. She can be contacted at jennieb@us.ibm.com.

Steven Cotugno has been with IBM/Rational since 2001. He is a Certified Agile Scrum Master and Certified IT Specialist. Before joining Rational, Steve spent 16 year developing and managing software development projects in the CAD and factory automation markets. Since joining IBM Rational, he has worked in other industries as well, in both the software engineering space and the IT Application space. In the last 4 years, he has been leading engagements in the IBM/Rational CLM solution for clients. He can be contacted at steve.cotugno@us.ibm.com.

John Liu has been with IBM/Rational for 12 years. He lives in Denver, Colorado. Before joining Rational, he had spent 12 years developing software systems ranging from the first two way paging system in the US to a commodity trading system for a major energy company. He’s intimately familiar with every role in the software development life cycle. For the past few years, he has been leading engagements in deploying the IBM/Rational CLM solution for customers. He’s also a technical lead in DevOps, architecture modeling and asset management. He won the Outstanding Innovation Award for his role in the development of DOP workbench in 2012. He can be contacted at johnliu@us.ibm.com.

Smita Gupta is a software test engineer at IBM Rational Software. She has supported IBM Rational ClearQuest and IBM Rational Team Concert (RTC)/Jazz as a technical support engineer for 6+ years before moving to her current role. Within the support role, Smita has developed expertise with Rational ClearQuest’s schema design, databases, migration, integrations with RTC, and web applications. Smita holds a Masters of Science in Management Information Systems from Florida International University. She can be contacted at guptasm@us.ibm.com.

Paul Bahrs is an IBM Executive Architect specializing in IT solutions for government, insurance and financial services industries, world wide. Paul is a thought leader on IBM Rational’s world-wide Solution Delivery Team and supports IBM clients in the planning, adoption and migration to IBM solutions. He can be contacted at pbahrs@us.ibm.com.

Yuhong Yin is a senior development manager at IBM. She is responsible for the ClearCase, ClearQuest-RTC/CLM connectors and integrations. She had previous worked on various components of ClearCase and ClearQuest, and integrations. She can be contacted at yyin@us.ibm.com.

Lorelei Ngooi is a software developer at IBM. She currently works on the Rational Requirement Composer(RRC). Before joining RRC, she had worked on the RTC ClearQuest Connector for a number of years. She can be contacted at lngooi@us.ibm.com.

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.

Feedback

Was this information helpful?

1 person rated this as helpful.