Migrating Rational ClearQuest records to work items

You can use the ClearQuest Import Wizard to import records from a ClearQuest user database into a project area. The imported records are stored as work items in the Jazz™ Team Server repository. The new work items are not synchronized with the ClearQuest records upon which they are based. You can also use the ClearQuest Import Wizard to export ClearQuest records to a comma-separated value (CSV) file. You can then use the Work Items CSV Import Wizard to create work items from the CSV file.

Before you begin

Rational® ClearQuest® 7.1.2 or higher must be installed on the computer where the IBM® Engineering Workflow Management (EWM) Eclipse client and the ClearQuest Synchronizer are installed. You can use the ClearQuest Import Wizard only on a Windows computer. You must have at least a Contributor Client Access License (CAL) to run the wizard to create work items. If creating work items involves creating categories, iterations, or releases, then you need a Developer CAL. You must be assigned adequate process permissions. If the import operation will create Jazz user accounts, you must be a member of the JazzAdmins group.
Important: The ClearQuest Import Wizard works only with the 32-bit version of the EWM client for Eclipse IDE. Starting in version 6.0.6, no 32-bit EWM Eclipse client is available to download in the form of compressed zip file. To work around this problem, install a 32-bit version of the Eclipse client. Then, download the EWM client p2 Install Repository and install it in the 32-bit Eclipse client.

For information about limitations of the ClearQuest Import Wizard, see ClearQuest Import Wizard limitations and known problems.

About this task

Tip: An easy way to experiment with the ClearQuest Import Wizard before you use it in your production environment is to create a project area based on the Scrum process template, and create a ClearQuest user database based on the DefectTracking schema. You can then use the default mapping file. In your ClearQuest query, list the following fields to display:
  • id
  • Headline
  • Project
  • State
  • Resolution
  • Severity
  • Description
  • Attachments
  • Notes_log

Procedure

To import ClearQuest records:

  1. In the EWM Eclipse client, click File > Import. Expand Team and select ClearQuest Records. Click Next.
  2. The first time through, select Connect to ClearQuest.
  3. Select the schema repository for the ClearQuest user database that contains the records you want to import. Enter a user name and password for the wizard to use to login to the ClearQuest user database. Select the user database.
  4. In the Query section, click Browse and navigate to a query in the Personal Queries or Public Queries folder that selects the records that you want to import.
  5. In the Destination section select:
    • Save to a file (default format is zip file of XML data) to save the query results in XML format. Click Browse and navigate to a directory where you want to store the .zip file that contains the XML-formatted query results. Enter a name for the .zip file.
    • Save as CSV file to save the query results in a CSV-formatted file. Click Browse and navigate to a directory where you want to store the CSV file. Enter a name for the .csv file.
      Note: You cannot use the ClearQuest Import Wizard to create work items from a CSV file. Select the Save as CSV data option only if you intend to use the Work Items CSV Import Wizard to create work items. See Importing work items from a .CSV file in the Eclipse client for details.
      Note: When you save to a CSV file, work item attachments are not included in the CSV file. The XML save option supports attachments. If a ClearQuest record contains multiple attachments or history entries, the ClearQuest Import Wizard still creates just one work item for that record.
      Note: If a ClearQuest record has multiple attachment fields, and an attachment with the same file name appears in more than one of those attachment fields, you receive an error, and the record is not exported. To work around this limitation, select the Import to Project Area option, which imports the records directly into EWM.
  6. Click Finish to create the .zip file or the .csv file.
  7. Open the ClearQuest Import Wizard.
  8. In the Source section, select Zip File. Click Browse and navigate to the .zip file that you created previously.
  9. In the Destination section, select Import to Project Area and select a project area.
  10. In the Mapping section, click Generate a sample data mapping file and save as, and specify the name of a file that will contain the information that maps ClearQuest record fields to work item attributes and attribute types. The wizard creates a sample mapping file with the name that you specify. You then customize the mapping file.
  11. Open the mapping file and modify it to map the ClearQuest record fields to work item attributes and attribute types. See Customizing the mapping file for details. Save the modified mapping file.
  12. Before you import the records into your production Jazz Team Server repository, verify that the mapping file works as expected against a test repository. Open the ClearQuest Import Wizard. Select Zip File. Click Browse and navigate to the .zip file that you created previously. Select Import to Project Area, and select a test project area. In the Mapping section, click Browse and navigate to the mapping file. If this is the first time that you are importing this set of ClearQuest records, select Create a new work item for each ClearQuest record to be imported. If you previously imported these ClearQuest records and want to update the work items that were created from that earlier import operation, select Update work items which have previously been imported.
    Note: When you select Update work items which have previously been imported, the wizard finds the work items to update by querying on the Imported from work item field. Do not edit the Imported from field. If the Imported from field of multiple work items specifies the same ClearQuest record ID, none of those work items is updated. The update operation does not update the following fields:
    • Attachments
    • Discussion
    • Subscribers List
    Note: The update operation updates work item links by first removing the existing links and then creating the links from the ClearQuest record. The update operation adds comments to the Discussion field indicating that it has removed and added links. For links between work items to be created, all of the linked records must be included in the file that you import. For example, if Record A is a duplicate of Record B, but Record B is not imported, the duplicate link is not created. Instead, a custom attribute that contains the duplicate information is created. If you update existing work items, be sure to import the full set of records that you imported originally.
  13. Click Finish. Examine the results of the import operation. If necessary, make corrections to the mapping file.
  14. When you are ready to import records into the production repository, open the ClearQuest Import Wizard. Select Connect to ClearQuest and complete the corresponding ClearQuest information fields. Select Import to Project Area, and select the production project area. In the Mapping section, select the mapping file. Click Finish.
    Note: Because the ClearQuest Import Wizard internally uses the Bugzilla Import Wizard, the History tab of the imported work items displays Origin (Bugzilla) Bugzilla identifier. The identifier is a ClearQuest record identifier.

video icon Video

Jazz.net channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community

Jazz.net
Jazz.net forums
Jazz.net library

support icon Support

IBM Support Community
Deployment wiki