Performing post-server rename actions for the ClearQuest Synchronizer – production scenarios

After you perform a server rename operation, you need to perform additional steps to ensure that the ClearQuest® Synchronizer behaves as expected.

About this task

This topic describes the post-server rename steps to perform for the pilot deployment to production scenario and the production to production scenario. You need to edit the file so that it identifies the URI of the renamed server. Then restart the ClearQuest Gateway and enable outgoing synchronization for the server.

The server rename operation updates explicit URLs in work items for the new server URL; however the new URLs are not automatically synchronized with Rational® ClearQuest records. You must force outgoing synchronization of work items to propagate the change to ClearQuest.


  1. Run the Server Rename Verification wizard to confirm that the URL for the ClearQuest Gateway has been changed. See Verifying URLs with the server rename verification wizard for details.
  2. Navigate to the install-directory\gateway folder. Make a copy of the file.
  3. Open the file and edit the parameter value to specify the URI of the renamed server. Save the modified file.
  4. Start the ClearQuest Gateway by navigating to the install-dir\gateway directory and running the server.startup.bat (Windows) or server.startup (Linux) command.
  5. Enable outgoing synchronization.
    1. Open a web browser and enter the URL for your Jazz® Team Server. For example: https://host-name:9443/ccm/. Log on as a Jazz administrator.
    2. In the Configuration section of the Application page, click Advanced Properties.
    3. Scroll to the Item Interoperation component. For, click Edit. For Outgoing Synchronization Enabled, select true in the drop-down list.
    4. Click Save at the top of the page to save the change.
  6. Force outgoing synchronization of work items:
    1. In the Synchronization Rules view, double-click the synchronization rule to open it.
    2. Temporarily clear the Synchronize All Item States check box. Click Save to save the rule.
    3. Right-click the synchronization rule and select Synchronize Out.
    4. Select All items selected by the synchronization rule. Click OK.
    Note: This operation can take a long time to complete, depending on the number of work items being synchronized. It might be appear that the operation has completed, but that is because the operation spawns a background task. To monitor the status of the operation, navigate to the application administration page in a browser. For example: http://fully-qualified-host-name:9443/ccm/admin. In the Status section, click Active Services and look for the task. When that task entry is gone, the task has completed. At that point, you can check the ClearQuest Gateway log file for outbound changes.
  7. After you confirm that the outgoing synchronization task has completed, open the synchronization rule or rules that you changed in the previous step and select the Synchronize All Item States check box. Click Save to save the rule.


All work items that were changed by the server rename operation are synchronized with the ClearQuest user database. The new server URL is propagated to the corresponding fields (except for comments in the Discussion field) in the ClearQuest records. The URL links in ClearQuest record comments are not updated to reflect the updated work item URL links because ClearQuest does not support modifying existing comments. In those ClearQuest records, a comment is added stating that a server rename operation has occurred and that the previous comments might contain stale URL links.