TN0027: ClearQuest Connector Troubleshooting Guide

Summary

This guide provides some assistance in verifying that your ClearQuest Connector environment was properly configured. It assumes that the prerequisites have been satisfied. These instructions are written assuming Rational ClearQuest 7.1 is installed. If ClearQuest 7.0.1 is installed, some file paths shown below might be slightly different.

The CQ Connector Setup Wizard is a new feature in Rational Team Concert 2.0. It was intended to replace many error-prone manual steps that were needed to setup the CQ Connector in 1.0. Therefore, many of the troubleshooting suggestions below are less likely to be the source of any problems you are encountering.

The help topic Integrating > Rational Team Concert and Rational ClearQuest > Configuring and using the Rational ClearQuest Connector > Using the ClearQuest Connector Setup Wizard describes how to use the wizard.

Things to check after Configuring CQ, step 2 of the wizard

In the ClearQuest Designer

• In the ClearQuest Designer, open the schema that you just applied the JazzInterop package to (navigate to the appropriate version using the Repository Explorer view). Right click Record Types – Stateless. The record types: JazzConnectorQueryInfo, JazzConnectorSyncHistory, and JazzConnectorChangeEvents must be present.
• In step 2.5 of the wizard, you were presented with a list of record types which you could apply the package to. Right-click Record Types, or Record Types – Stateless, and then right-click one of those record types. Click States and Actions > Actions. The action Change_History must be present.

In a ClearQuest Client

• Using a ClearQuest client, log in as the user you just created or specified for ClearQuest Connector in step 2.4 of the wizard.
• Using the ClearQuest User Administration tool, make sure that this same user has SQL editor permission, and that it is subscribed to by the user database selected in step 2.2.
• Check to see that the query tree root specified in step 2.6 was created by navigating to it in the ClearQuest workspace.

Things to check after Configuring Jazz, step 3 of the wizard

In the Rational Team Concert Client

• Try to log in with the user you just created or specified in RTC. If successful, bring up the User Editor to this user by right-clicking Repository Connections > your repository connection > Open My User Editor. In the Client Access License pane, make sure that Rational Team Concert – Clear Quest Connector is checked (a Developer CAL is also acceptable).
• Click in the All Project and Team Area view, Repository Connections > your repository connection > Administer > Synchronization Rules. In the Synchronization Rules view, check for the following conditions:
  • Make sure that the external repository connection specified in step 3.5 is correct.
  • Make sure any project area specified in step 3.4 of the wizard contain a set of synchronization rules that correspond to the record types chosen in step 2.5 of the wizard. A sync rule for users should only exist in one project area, since users in RTC are not specific to any project area.

In a ClearQuest Client

• Check to see that for each project areas specified in step 3.4, a folder was created under the query root tree (by navigating to it in the ClearQuest workspace).

In the cqconnector.properties file

• Verify that the Jazz server URL as entered in the com.ibm.team.uris property is correct. Open a Web browser and enter the Jazz server uri without the user and password information. If correct, this should display the Jazz Team Server login page. If the login page does not appear, verify that the Jazz server is running and that the URL is correct. Verify that the values for the user ID is as expected. Since the password will probably be encrypted, it is not possible to verify it.
• Verify that the CQ connection information as entered in the fields cq.dbSetDbName and cq.userId are correct. Since the password will probably be encrypted, it is not possible to verify it.
• Verify that the value in the cq.queryTreeRoot property is as expected.

Testing the ClearQuest Connector

Topic path: Integration > Rational Team Concert and Rational ClearQuest > Configuring and using the ClearQuest Connector > Testing the ClearQuest Connector

What should you do if the test indicated in this topic does not succeed?

1. Check to see that the query tree that was specified in the wizard was correctly processed by the ClearQuest Connector.
   1. Open a ClearQuest client.
   2. Create a new query. Name it “Query Info”. Select JazzConnectorQueryInfo as the record type of the query. Do not add any filters. Select the display fields: entityRecordType, jazz_ProjectArea_id, and query_dbid.
   3. Run the query. If the table is empty, then you probably did not specify a query tree correctly. Consult the Integrating > Rational Team Concert and Rational ClearQuest > Configuring and using the Rational ClearQuest Connector > Using the ClearQuest Connector Setup Wizard, step 7 help topic.
   4. If there are records in the table:
      1. Make sure that there are as many different jazz_ProjectArea_ids, as Project Areas you specified in the query tree.
      2. Make sure there are is only one entry for the user record type.
      3. Make sure that there is an entry for each query you explicitly specified.
      4. Make sure that there is an entry for each record type for which you did NOT explicitly specify a query – those for which you want all records of that type synchronized.
2. Check to see if change events are being created for the changes made in ClearQuest.
   1. Shut down the ClearQuest Gateway.
   2. Open a ClearQuest client.
   3. Create a new query. Name it “Change Events”. Select JazzConnectorChangeEvents as the record type of the query. Do not add any filters. Minimally, select the display fields: entity_dbid, entity_display_name, entity_record_type, version_number.
   4. Create a record that you expect to be synchronized with RTC. If the creation of that record is successful, run the query you just created. A “change event” record should be returned. If there isn’t one, the JazzInterop package might not have been applied correctly, or the ClearQuest user database might not have been upgraded to the new version of the schema.

Verify the external repository connection

Open a Web browser and enter the CQ Gateway URL as entered in the External Repository Connection Info field. If correct, this should display the CQ Connector Gateway status page. If this is not displayed, verify that the CQ Gateway has been started or that the URL is correct.

Simplify new synchronization rules

To ensure synchronization is not failing due to field mapping errors, you may want to simplify your synchronization rule as much as possible. To do this, map only the fields which are required fields in CQ or Rational Team Concert. Once synchronization works with these fields, you may add more field mappings to your synchronization rules, testing synchronization along the way.

Attachments

Attachments require their own synchronization rule in order to be synced. See the Creating a synchronization rule for attachments topic for more information.