TN0026: ClearQuest Connector Frequently Asked Questions (FAQ)

Last Updated: November 7, 2012
Build basis: Rational Team Concert 4.0.1
Author: Lorelei Ngooi

Summary

This is a collection of error messages, problems, and questions that have been asked. As a first step, please refer to TN0027: ClearQuest Connector Troubleshooting Guide to confirm that all the necessary configuration steps were taken.

More Information

General Questions

ClearQuest Gateway

JazzInterop Package

Sync Rule Editor

Synchronization

Attachments

Batch Synchronization Tool


General

How do I view or turn on logging?

The ClearQuest Gateway and Batch Synchronization tool generate log files, which contain information to help you troubleshoot problems with the ClearQuest Connector. The ClearQuest Gateway log file (cqgateway.log) is stored in the [install-directory]gatewaytomcatlogs directory. The Batch Synchronization tool log file (synctool.log) is stored in the [install-directory]gateway directory.

By default, the log files contain messages of severity level Warning and higher. You can modify the logging behavior by editing the log4j.properties file in the [install-directory]gateway directory.

If you want to view any incoming or outgoing synchronization logging, modify the log4j.properties file in the [JazzTeamServer-install-directory]server directory by adding the following entry:

log4j.logger.com.ibm.team.interop=DEBUG

Does the ClearQuest Connector support bi-directional create/update/delete between ClearQuest and Jazz?

Create and update are supported between the two repositories. Work items cannot be deleted since they become linked to other objects and reflect the history of a project, so ClearQuest record deletion does not imply work item deletion, just “disconnection” from the work item.


ClearQuest Gateway

How do I run the ClearQuest Gateway as a Windows service?

Follow the instructions on the TN0024: Running the ClearQuest Connector Gateway for Rational Team Concert as a Windows Service technote.

I get the error “Failed shutdown of Apache Portable Runtime” when shutting down the ClearQuest Gateway. Why?

The server.shutdown script in the [install-directory]/gateway directory fails to shut down the ClearQuest Gateway. On Windows, click the Close icon (X) in the Tomcat console window. On Linux, enter the command kill -9 [process-ID].

When viewing the ClearQuest Connector Gateway web page, I don’t see any ClearQuest db info, any Jazz Team Server info, and polling is not enabled. What’s wrong with my setup?

The web page may show this info if there are problems connecting to the Jazz repository using the value specified in the com.ibm.team.uris property in the cqconnector.properties file. Check that the value does not include any nonstandard URL characters, such as the @ or # character, in the username or password parts. In place of a nonstandard URL character, use the appropriate escape characters. For example, use %40 for the @ character and %23 for the # character.

How many external connections should I have?

There should be only one External Connection specified in Rational Team Concert for ClearQuest. This External Connection should contain information on how to connect to the ClearQuest Gateway. This ClearQuest Gateway represents the connection to one ClearQuest user database. It is not currently possible to connect one Rational Team Concert project area to more than one ClearQuest user database.

It is possible to set up a more advanced configuration where more than one Rational Team Concert project area, possibly on more than one Jazz server, is connected to the same ClearQuest Gateway. This configuration enables synchronization between one ClearQuest user database and many Rational Team Concert project areas.

Other configurations are not currently supported, although it might be possible to set them up using the Rational Team Concert client.


JazzInterop Package

Can I enable synchronization of other record types after I have applied the package?

If you’re using Rational Team Concert 1.0, you can apply the JazzInterop package to other stateful record types by running the packageutil enablepackageediting command with the -enable option. Open the ClearQuest Designer and check out the schema. In the navigation pane, expand the Record Types folder. Right-click a record type and select Setup Record Type for Packages. Select the JazzInterop package and click OK. Check in the new version of the schema. Run the packageutil enablepackageediting command with the -disable option. Upgrade the user database with the new version of the schema.

If using Rational Team Concert 2.0 and later, use the ClearQuest Setup wizard.


Sync Rule Editor

In creating a sync rule, the value in the external type field is empty or shows only attachments. Why doesn’t it show my ClearQuest record types?

This could be the case if no ClearQuest record type was enabled for synchronization when the JazzInterop package was applied to your ClearQuest schema. Or the ClearQuest user database was not upgraded after the schema changed.

In addition, make sure the ClearQuest gateway is running. In the sync rule editor, make sure the external repository and the external manager fields are set. The external type field should be populated with the ClearQuest record types that you have enabled for synchronization.

I’m trying to map my ClearQuest state values, but there are no values to select in the external value list.

This is a known bug. The corresponding Jazz work item status values are available, but the ClearQuest state values are not. Until this is fixed, you will need to manually type in the values.

When two project areas use the same sync rules, do I need to duplicate the sync rules?

Yes, you need to duplicate the sync rules in each project area except for the users sync rule. There can be only one user sync rule per Jazz server.


Synchronization

Do I need to create ClearQuest queries in order to sync ClearQuest records?

If you want to sync all records of a particular record type, then no query is required. If this is not the case, then specifying a query would filter the records to sync to include only those records that satisfy the query. For example, you may want to create a query that selects ClearQuest defects that belong to a particular project.

Tried to sync a CQ record, but I get the error “Save Work Item Required Properties: Work items must be Filed Against a specific category and a Summary must be provided”. What can I do to resolve this?

Certain fields are required when creating a work item. If they are not set, this error will occur. In this case, both the Filed Against and the Summary fields have not been set and are required.

In general, all required work item fields must have property mappings defined in the sync rule. For the Filed Against property, category mappings must be set up. For more information on setting up category mappings, see Editing sync rules to specify categories.

I created a ClearQuest defect, but incoming synchronization is not working. What do I do?

There could be a number of reasons why you might be experiencing this problem. Make sure the ClearQuest gateway is running. Verify that you have created a ClearQuest query folder whose name is the Jazz project area in the query tree root folder that is specified in the cqconnector.properties file. Set the log level to DEBUG for the ClearQuest gateway log to see if the gateway is picking up your newly-created ClearQuest defect. Also, check the state of the ClearQuest gateway by viewing the ClearQuest gateway status web page, http://[Your_CQ_Gateway_Host]:8081/InteropGateway.

In addition, please look at the TN0027: ClearQuest Connector Troubleshooting Guide technote to verify configuration setup.

I submitted a defect in ClearQuest and its sync status is pending. Its related user and project record, however, have an incoming sync error of java.net.ConnectException: Connection refused. Why?

This error will occur if the external repository connection is incorrect. This is what the Jazz server uses to connect to the ClearQuest gateway. In this situation, the user had changed the gateway port number in the server.xml file, but forgot to change the port number in the external repository connection.

I tried to sync a ClearQuest record, but I get the error “Synchronize with External Objects” failed. Permission denied. The user I use in cqconnector.properties is a super user in ClearQuest and in Rational Team Concert is included in all Repository groups and has all possible Process roles. What am I missing?

You need to enable the Item Connectors -> Synchronize with External Objects (server) permission for some role. Go to the Process Configuration tab page for your project area. Expand the Team Configuration and select Permissions. For the role for the CQ connector account, permit this action.

Incoming sync error: invalid UUID

This problem can occur if the Category (Filed Against) property mapping is not set up properly in the sync rule. The incoming value from CQ must somehow be transformed into a reference to a work item Category object, which is identified by a UUID. The sync rule has a value mapping which defines the value to be “TEST1501”, which is not a UUID.

There are three different techniques for defining a Category mapping – you can map a CQ record to a Category item, or you can identify one or more string-valued fields in the record type that is mapped to a work item that will identify the names of categories, or you can identify one or more string-valued fields in other record types that are referenced by the record type that is mapped to a work item. The techniques are described in Editing sync rules to specify categories to specify categories.

I get the incoming sync error: The uri someCQStateValue does not identify a valid ClearQuest location. What do I do?

This error will occur if the ClearQuest state property mapping is not set up properly in the work item sync rule. In this case, the state property mapping included the WorkflowActionValueTransformer, a reference sync rule, and value mappings that map ClearQuest state values to Jazz work item status values. The problem is resolved by only including the value mappings in the ClearQuest state property mapping in the sync rule.

I’ve already set up my custom sync rules. How do I get a copy of them out of Rational Team Concert?

You can export the sync rules as XML files. Just right-click on them in the Synchronization Rules view and choose Export.

What could cause a “java.net.SocketTimeoutException” error?

This problem can occur as a result of timeouts when connecting to the ClearQuest database.


Attachments

I have the following outgoing sync error: The file name of an attachment is larger than 50 characters: xxx. What does this mean?

Rename the attachment associated with the work item to a name smaller than 50 characters.

I get the following outgoing sync error when I add an attachment to a work item: ClearQuest Error – Reason: CRVAP0332E? An explicit action must be specified when updating records of type “Defect” because this record type defines several modify actions: Modify, AnotherModifyAction. Why?

This is a known bug in Rational Team Concert 1.0. This error will occur if there are more than one Modify type action for the record type. This has been fixed in Rational Team Concert 2.0


Batch Synchronization Tool

Can I use the batch synchronization tool to just import records into Rational Team Concert without modifying my ClearQuest schema?

Yes, it is possible with the batch synchronization tool to import ClearQuest records into Rational Team Concert without applying the JazzInterop package to your schema and upgrading the user database to the new version of that schema. Please see the Importing but not synchronizing records topic in the online help.

I get an “Out of memory” error when running the batch synchronization tool. Why?

The batch synchronization tool is running out of memory when trying to sync a large number of records. It is difficult to quantify how large is large because it all depends on the complexity of the data being synched in terms of the number of fields and any related records that are also being synced over such as users, projects, attachments, etc. It is recommended to modify the query to select a smaller subset of the records and to run the batch synchronization tool multiple times to import a different subset of the data. Also be sure to define the queries so that they select only records that you plan to work on in Jazz. Typically, you would not need to include records in a closed state.

This has been fixed in Rational Team Concert 1.0.1.

References

The following documents provide information related to this topic.

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? Yes No 1 person rated this as helpful.