Upgrading ClearQuest Synchronizer

Several steps are required to upgrade ClearQuest Synchronizer from an earlier release to the current release. You start the process by disabling outgoing synchronization for both the client and the server.

1. Disable outgoing synchronization for the external repository connection:
   1. In the Engineering Workflow Management for Eclipse IDE client, in the Synchronization Rules view, expand the External Repository Connections node.
   2. Double-click the external repository connection to open it.
   3. Select Disable automatic outgoing synchronization and click OK.
2. Disable outgoing synchronization for Jazz® Team Server:
   1. In the web client, on the administration page, click Advanced Properties and scroll to the Item Interoperation component.
   2. For com.ibm.team.interop.service.internal.InteropService, click Edit.
   3. For Outgoing Synchronization Enabled, select false from the list.
   4. Click Save.
3. Stop the ClearQuest Gateway.
4. Stop Jazz Team Server.
5. Note: The system administrator typically performs this step.
   Upgrade Jazz Team Server and the IBM Engineering Lifecycle Management applications. For more information about upgrading, see the Interactive upgrade guide.
6. Start Jazz Team Server and the Engineering Workflow Management for Eclipse IDE client. In the client, verify the following conditions:
   • You can log in to Jazz Team Server with the Jazz user account that the ClearQuest Connector uses.
   • You can connect to the project area.
   • The external repository connection exists in the Synchronization Rules view.
   • The synchronization rules exist in the Synchronization Rules view.
   • The work items that you previously created and synchronized with ClearQuest records exist.
   • Jazz Team Server is still set to disable outgoing synchronization.
7. Install the new version of the ClearQuest Synchronizer. See Installing IBM Engineering Workflow Management ClearQuest Synchronizer by using Installation Manager.
   Note: If you are upgrading from a version 3 release or later, you can use the Update option in IBM Installation Manager. If you are upgrading from a version 2 release, you must first uninstall the version 2 release and then use the Install option in IBM Installation Manager (see step 17). Beginning in version 3.0, the default installation directory is named ClearQuestSynchronizer instead of ClearQuestConnector.
8. Navigate to the installation_directory/ClearQuestSynchronizer/gateway directory and start the ClearQuest Gateway.
9. Stop the ClearQuest Gateway.
   Starting and stopping the ClearQuest Gateway creates the installation_directory/ClearQuestSynchronizer/gateway/tomcat/webapps/cqconnector directory.
10. If you are upgrading from a version 2 release, copy any user-configurable files that were modified from the ClearQuestConnector installation directory to the ClearQuestSynchronizer installation directory. Specifically, copy these files to these locations:
    • The cqconnector.properties file from the installational_directory/ClearQuestConnector/gateway directory to the installation_directory/ClearQuestSynchronizer/gateway directory
    • The log4j2.xml file from the installation_directory/ClearQuestConnector/gateway directory to the installation_directory/ClearQuestSynchronizer/gateway directory
    • The tomcat-users.xml file from the installation_directory/ClearQuestConnector/gateway/tomcat/conf directory to the installation_directory/ClearQuestSynchronizer/gateway/tomcat/conf directory
    • The web.xml file from the installation_directory/ClearQuestConnector/gateway/tomcat/webapps/cqconnector/WEB-INF directory to the installation_directory/ClearQuestSynchronizer/gateway/tomcat/webapps/cqconnector/WEB-INF directory

    If you are upgrading from version 3 or later and you choose the Update option in IBM Installation Manager, your modified configuration files are stored in a backup directory. Copy the modified configuration files from the backup directory to the new installation directory.

    Note: The server.xml file in releases earlier than 4.0 is not compatible with version 4 or later releases. Therefore, you cannot copy that file from the installation_directory/ClearQuestConnector/gateway/tomcat/conf directory or from the backup directory to the installation_directory/ClearQuestSynchronizer/gateway/tomcat/conf directory. Instead, edit the version 4 or later server.xml file in the new installation directory (installation_directory/ClearQuestSynchronizer/gateway/tomcat/conf) so that it contains any changes you made to the earlier version.
11. Optional: Apply the latest version of the JazzInterop package to your ClearQuest schema, and then upgrade the ClearQuest user database with the new schema version. For more information, see Upgrading the user database with a new version of the JazzInterop package.
12. Start the ClearQuest Gateway.
13. Check the status of the gateway by going to the status page at http://host_name.example.com:8081/cqconnector/gateway. The page should show that the gateway is accepting all requests.
14. Enable outgoing synchronization for the external repository connection.
15. Enable outgoing synchronization for the server.
16. Verify that synchronization works by completing the following steps:
    • Create several records in the ClearQuest user database. Verify that corresponding work items are created in the Engineering Workflow Management project area.
    • Create several work items in the project area. Verify that corresponding records are created in the ClearQuest user database.
    • Edit several work items that were synchronized in the previous release. Verify that the changes are propagated to the corresponding ClearQuest records.
    • Edit several ClearQuest records that were synchronized in the previous release. Verify that the changes are propagated to the corresponding work items.
17. If you are upgrading from a version 2 release, or you did not choose the Update option in IBM Installation Manager, uninstall the previous release of the ClearQuest Connector.
    The uninstall operation should create a directory named backup-config-timestamp in the installation_directory/ClearQuestConnector directory. Verify that this directory contains the following directories and files:

    • gateway/cqconnector.properties
    • gateway/log4j2.xml
    • gateway/tomcat/conf (this directory contains several files and a Catalina directory)
    • gateway/tomcat/webapps/cqconnector/WEB-INF/web.xml