ClearQuest Synchronizer limitations and known problems

This release of the ClearQuest® Synchronizer contains several limitations and known problems.

This release contains the following limitations and known problems:

  • To use the ClearQuest Synchronizer, you must be running IBM® Rational® ClearQuest 7.1.2 or higher.
  • The ClearQuest Synchronizer Setup Wizard runs on Windows only. If you are deploying the ClearQuest Synchronizer on Linux®, you can run the ClearQuest Synchronizer Setup Wizard on Windows. The wizard generates the file, which the Gateway uses. You can copy the generated properties file to a Linux computer, edit it, and then start the Gateway on that computer.
  • In the Jazz® Server Configuration part of the ClearQuest Synchronizer Setup Wizard, the Create New Account option fails if the Jazz user registry is read-only, which is true if the Jazz Team Server is running on a WebSphere® Application Server or is configured to use Lightweight Directory Access Protocol (LDAP).
  • If work item comments contain text that looks like the special syntax that is used to format comments when synchronizing with an external object, then errors occur during synchronization. For example, the following text in comments causes synchronization errors:
    "user==_1a_VoPYJEdqU64Cr2VV0dQ!FIELD!text==This bug has been marked as a duplicate of work item 28624.!NOTE_ENTRY!"
    Notes_Log=user==CQ%3Acq.repo.cq-record%3Ausers%2F33554434%40sample_schema_repo%2FSAMPL!FIELD!text==Added: attachment 8 (attach23956txt)!NOTE_ENTRY!
  • When mapping state values between a ClearQuest record type and an Engineering Workflow Management item, you cannot map the transition from a ClearQuest Closed state to an Opened state.
  • A Jazz repository can contain character data for multiple national languages because it stores the data in Unicode format, but a ClearQuest user database can hold data for only one character set at any time. If the character set for the ClearQuest user database does not support the character data in work items, synchronization operations fail with errors such as, "The field "Description" contains characters that are not supported by the data code page, "1252 (MS Windows Latin 1)"."
  • In a ClearQuest user database, the UnDuplicate action changes the state of the record to its state prior to the Duplicate action. In some cases, the Engineering Workflow Management work item cannot make the same state transition because its state transition model does not support it.
  • When you define keywords in ClearQuest record types that are synchronized with Engineering Workflow Management items, use lowercase and do not include spaces.
  • Although a ClearQuest record can have multiple attachments list fields, an Engineering Workflow Management item can have only one. Within the Synchronization Rule editor, you can select one ClearQuest attachment field to synchronize. After you update the attachment field selection in the mapping, reset the ClearQuest Gateway so that it uses the new version of the synchronization rule.
  • Do not add a mapping for the Description property to an attachment synchronization rule; it is not supported and causes synchronization to fail with the error, "Invalid Attachment property name: Description."
  • Although Engineering Workflow Management allows users to attach multiple files with the same file name to a work item, ClearQuest does not allow multiple attachments with the same file name. If a work item contains multiple attachments with the same file name, the attachments do not synchronize with ClearQuest, and you receive an outgoing synchronization error.
  • If you use the ClearQuest Synchronizer with a Db2® user database and schema repository, you might encounter database deadlocks in certain circumstances. To avoid this problem, set the Db2 MAXAPPLS parameter to 200 for the user database and the schema repository.
  • When specifying the Jazz server Uniform Resource Identifier (URI) with the parameter in the file, do not include nonstandard URL characters, such as the @ character, in the user name or password parts. In place of a nonstandard URL character, use the appropriate escape characters. For example, use %40 for the @ character.
  • When specifying the jazzServer parameter for the synctool command, do not include nonstandard URL characters, such as the @ character, in the user name or password parts. In place of a nonstandard URL character, use the appropriate escape characters. For example, use %40 for the @ character.
  • If you use the ClearQuest Synchronizer in a nonASCII environment, you must use Unicode escape characters for any nonASCII characters in the file. A Java™ utility, native2ascii, converts characters in other formats to Unicode escape format.
    1. In a text editor that supports UTF-8 encoding, such as Notepad, create and save a file that contains the nonASCII characters from the file.
    2. On a computer running Windows, open a DOS Command Prompt console and navigate to the Java-installation-directory/bin directory.
    3. Enter native2ascii.exe –encoding source-file to-be-generated-unicode-escape-file where source-file is the file that you created in Step 1.
    4. Open the generated file and copy the Unicode escape characters. Open the file. Paste the Unicode escape characters into the file where needed. Save the modified file.
  • When you apply the JazzInterop package to a schema, you select the record type or types to which to apply the package. If you decide later that you want to apply the package to one of the stateful record types that you did not select when you first applied the package, you can do so. However, if the default scripting language for the schema is Visual Basic, you cannot apply the package to a stateless record type that you did not select when your first applied the package to the schema.
  • If you have JazzAdmins repository group permissions, you can delete comments from work items by using the Empty option. ClearQuest does not let you delete part of a Notes entry. Therefore, the comment that you delete from a work item is brought back to that work item the next time the corresponding ClearQuest record is synchronized with that work item. To prevent the deleted comment from being restored, perform the following steps:
    1. Stop synchronization between the work item and the ClearQuest record. Do this by creating a conflict so that you have an entry in Status view. Then right-click the entry and select Stop Synchronizing.
    2. Make a change in the work item to force an outgoing synchronization operation to a new ClearQuest record. This new ClearQuest record is a clone of the synchronized work item without the emptied comments.
    3. Update the new ClearQuest record with any new changes from the original ClearQuest record, then delete the original ClearQuest record.
  • If the Jazz Team Server is configured to use LDAP for storing user accounts, but the ClearQuest user database does not use LDAP, you might see synchronization conflicts because the ClearQuest Gateway cannot create or edit LDAP users.
  • Even if you do not have synchronization rules configured to synchronize attachments, the ClearQuest Gateway retrieves attachments (but does not synchronize them) and makes corresponding entries in the ClearQuest Gateway log file. To prevent this behavior, perform the following steps:
    1. Enable package editing for the JazzInterop package by entering the following command in a Windows command prompt window: packageutil enablepackageediting –dbset schema-repository-name username password –enable username
    2. In the ClearQuest Designer, check out the schema and locate the WriteChangeHistoryRecord method. You can use the Find in Hook option to find the method.
    3. In the WriteChangeHistoryRecord method, add the # sign to comment out the following line: # $xml .= addAttachmentsRecords($entity->GetAttachmentFields());.
    4. Save your change, check in the schema, and then upgrade the user database.
    5. To verify that any attachment-related operations (such as adding or deleting attachments) do not generate Change Events, create a ClearQuest query against the JazzConnectorChangeEvents record type with entity_dbid and field_values as display fields, and monitor the result set.
  • In certain circumstances, the ClearQuest Synchronizer uses the default ADMIN Jazz user account when it synchronizes ClearQuest records with Engineering Workflow Management work items, even if the ADMIN account has been deactivated. If the ADMIN user does not have permission to perform synchronization operations for the project area, synchronization operations might fail and you can see permission denied errors in the ClearQuest Gateway log file and the Synchronization Status page. To correct this problem, add the ADMIN user as a member to your project area and assign it a role that has permission to perform Item Connectors > Synchronize with External Objects operations:
    1. Open the project area in the web client.
    2. In the Members section of the Overview page, click Add.
    3. In the Add New Members wizard, enter ADMIN in the search field. Select ADMIN from the Matching users list and move it to the Selected users list. Click Next.
    4. Select a role that has Item Connectors > Synchronize with External Objects operation permission.
    5. Click Finish.
    6. Save your changes to the project area.
    7. Re-run any blocked synchronization operations that you see on the Synchronization Status page.
  • If the ClearQuest notes log has dates in one of the following formats, the ClearQuest Synchronizer treats the first two digits as the month and the second two digits as the day, which might not be appropriate for all locales:
    • nn/nn/yyyy
    • nnnnyyyy
    • nn.nn.yyyy
    To change this behavior on Windows, perform the following steps:
    1. Open the jazz-team-server-install-directory/server/server.startup.bat file in an editor.
    2. Before the line LOCAL_CLASSPATH=%CLASSPATH%, insert this line: set
    3. Find the following line and append the part in bold: set CATALINA_OPTS=-Dcq.home="%CQ_HOME%" %CQPACKAGEDIR% %CONFIG_PROP% %LOG_PROP% "%TIME_PROP%".
    To change the behavior on Linux, edit the server.startup script by adding the property shown in bold to this line: export CATALINA_OPTS="-Dcq.home=$CQ_HOME/cqweb/lib"\ `pwd`"/ -Dlog4j.configuration=file://"`pwd`"/".
    Examples of date formats include the following:
    • dd MMM yyyy HH:mm:ss
    • dd/M/yyyy HH:mm
    • dd.M.yyyy HH:mm
    • M/dd/yyyy hh:mm:ss a
    • M/dd/yyyy HH:mm
    • dd/M/yyyy HH:mm a
  • The timestamps from ClearQuest notes log entries are saved with the time and time zone of the Jazz Team Server.