Introduction
This guide will provide links to resources you can use to troubleshoot issues with the IBM Rational ClearQuest Synchronizer (a.k.a. ClearQuest Connector). Below are categories for most types of problems and this diagram shows the basic components of the integration. This diagram also shows the logs for each component. In general, you will need to consult the logs when issues arise. Later in the Guide, there is information on how to control the logging levels.
1. Configuration
Configuration issues occur if you have not met the prerequisites or something has changed in the system which can include: user accounts, permissions, licenses, schema changes, and hook code.
Use this checklist to identify areas that you may need to re-configure if you are setting it up for the first time, or areas you need to check for changes if the Sychronizer was formerly working:
Configuration checklist
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.
2. Synchronization Rules
Synchronization Rules map fields between the external object (for example, CQ record) and a Jazz item (for example, work item) and describe the transformations.
Steps for how to test rules in the RTC Client.
Consult RTC logs for errors.
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.
3. Outgoing Sync - RTC WIs --> CQ records
Verify the Jazz Server can reach the CQ Gateway by opening a synchronization rule in the RTC Client. If you see the error "CRRTC4690E: The "External type" filed could not be populated. Name: BAD RULE" then the Jazz server can't reach the gateway.
Gateway logs show it contacting CQ but records are not making it in to CQ. Search for ClearQuest Web "MustGather" technotes for information on location of the logs for your ClearQuest version and consult the CQ logs. Need hooks tracing.
4. Inbound - CQ records --> RTC WIs
CQ Gateway log, RTC or RQM log
5. Conflicts
Conflicts can occur when two users make nearly simultaneous changes to a ClearQuest record and its corresponding work item. Sometimes, you may manually resolve the conflict by selecting the appropriate value.
Check Synchronization status in the RTC Client.
Steps for how to resolve conflicts using the RTC Client.
External links: