Importing a batch of ClearQuest records

The ClearQuest® Connector includes an Import tool that lets you create corresponding items in a Jazz™ repository for a batch of ClearQuest records.

About this task

For example, you can use the Import tool to create Rational Team Concert™ work items that correspond to a batch of defects in a ClearQuest user database. The new work items are synchronized with the defects. Changes that you make to a work item are propagated to the corresponding defect, and changes that you make to a defect are propagated to the corresponding work item.

The Import tool uses the parameters set in the cqconnector.properties file. The ClearQuest Connector Setup Wizard updates the cqconnector.properties file based on the choices that you make. You can also edit the cqconnector.properties file directly to set the parameters. See Modifying Connector service parameters for descriptions of the parameters. Run the Import tool multiple times, once for each record type. This approach allows you to verify that the synchronization of one record type is successful before you proceed to the next record type.

Some record types might have a dependency on other record types. You should run the Import tool on the record types that other record types depend on first. For example, in the sample DefectTrackingInterop schema, synchronization of the Defect record type depends on successful synchronization of the Project and users record types. Therefore, use the Import tool on Project and users record types first. After you verify that synchronization of those record types succeeds, run the Import tool on the Defect record type.

The Import tool syntax is as follows:

synctool recordType=record-type-name jazzServer=url projectArea=project-area-name 

To import records:

Procedure

  1. Navigate to the install-directory\gateway directory.
  2. Run the synctool command. The Import tool searches the query folder that the cq.queryTreeRoot parameter names in the cqconnector.properties file. If it finds a query in the project area folder for the record type specified, it uses that query to select the records to be imported. If no query exists, the Import tool selects all records of that record type. If you have a very large number of records of the record type to import, consider running the Import tool multiple times, changing the query each time, so that each invocation selects a subset of the total number. For example, you might adjust the query to select records based on creation date. Also be sure to define the queries so that they select only records that you plan to work on in Rational Team Concert. Typically, you would not need to include records in a closed state.

    Anytime you add or remove a query, or add a synchronization rule, you must stop and restart the ClearQuest Gateway so that the ClearQuest Connector uses the new synchronization criteria.

    Example, on Windows®:

    synctool recordType="users" jazzServer="https://cqconnector:cqconnector@localhost:9443/jazz" projectArea="Reporting"

    On Linux®, use ./synctool to start the command line.

  3. Open the Rational Team Concert client and verify that the Import tool created user records for the ClearQuest records selected by the query. In the Team Artifacts view, expand the My Team Areas folder. Double-click a team area to open it. In the Members area click Add to add the new users to the team area. To assign roles to the users, select each user in the Members table and click Process Roles.
  4. Run the synctool command specifying a different record type. For example, the Project record type.
  5. In the Rational Team Concert client verify that the Import tool created corresponding category items for the ClearQuest project records selected by the query. In the Team Artifacts view, right-click the project area and select Open. In the Project Area editor, click the Work Item Categories tab. Select the category that corresponds to the ClearQuest project record. Select the team area that you want to associate with the category. Click Associate. Repeat this step for each category that the Import tool created to correspond with the ClearQuest project records. Click Save to save the change to the project area. After you associate a category with a team area, work items with that category property are associated with the appropriate team.
  6. Run the synctool command specifying a different record type. For example, the Defect record type.
  7. In the Rational Team Concert client verify that the Import tool created corresponding work items for the ClearQuest defects selected by the query.

Results

If the Import tool selects a record that is currently synchronized to a different project area on the same Jazz Team Server, it disconnects that record from that project area so that it can synchronize the record with the project area that you specify on the command line.

Feedback

Did this help? You can provide feedback at Jazz.net (registration required): Comment in the forums or submit a bug