ClearQuest Synchronizer and ClearQuest Bridge Tech Enablement for CLM 4.0

1. Lorelei Ngooi & Yuhong Yin June 2012 ClearQuest Synchronizer and ClearQuest BridgeTech Enablement for CLM 4.0

2. Agenda • (Lorelei) CQ Synchronizer Server Rename Support • (Yuhong) CQ Bridge Server Rename Support • (Yuhong) A Tool to Transition from a Synchronizing Integration to a Bridging Integration

3. ClearQuest Synchronizer and Server Rename Overview • Server rename impacts not just the CLM applications but also any applications that integrate with the Jazz™ Team Server or CLM applications. References to CLM servers, links to CLM artifacts, connections to Rational Team Concert repositories, and links in work item data sync’ed in another repo like CQ must all be updated. • Renaming a server is a complex and potentially disruptive operation because it might be difficult or impossible to correct the stored links into the server from other applications and systems. It is supported only for a limited set of scenarios, requires careful advance planning, and should generally be used only as a last resort when other approaches are unworkable. • As of CLM 2012, CLM server rename is supported by the ClearQuest Synchronizer. This applies to its integration with RTC and RQM. • A set of steps need to be followed both before and after server rename. • Plan for an outage.

4. How server rename affects the ClearQuest Synchronizer • The CQ Synchronizer synchronizes work item changes to CQ and vice versa. • When server rename occurs, URL links in work item fields will be updated for the new server URL. • Sync behavior • The new URLs are not automatically synchronized with Rational ClearQuest records. You must manually force outgoing synchronization of work items to propagate the changes to ClearQuest. • Comment behavior • 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.

5. Server rename scenarios • Setting up a staging environment with a copy of production data • Support to stage CLM deployment only, not integrations. • If the ClearQuest Synchronizer is included in the production environment, then you must block access to the ClearQuest Gateway. Otherwise, a test Jazz Team Server might be connected to a production ClearQuest Gateway, which could cause test data to be synchronized out to the production environment. To block access to the ClearQuest Gateway, you edit the mapping file. • Moving a pilot deployment to full production. • In this scenario, you probably want to continue to use the ClearQuest Gateway. Therefore, you do not need to edit the mapping file.

6. Steps to follow before a server rename • Disable outgoing synchronization. • Disable incoming synchronization by stopping the CQ Synchronizer Gateway. • For extra precaution, back up the ClearQuest production databases (schema repository and user database). • For the test staging environment using production data scenario only, • Block access to the ClearQuest Gateway by editing the generated mapping file.

7. Block access to production CQ Gateway in URL mapping file: production to staging environment scenario Initial, generated mapping file: Modified mapping file to block access:

8. Steps to follow after a server rename in the production to staging environment scenario • Since the CQ Synchronizer is not being staged, just verify that the staging CLM env. is not sync’ing out to the production CQ Sync env. • Verify that outgoing sync is disabled. • Verify that the external repository connection is set to the bogus URL specified in the mapping file.

9. Steps to follow after a server rename in the pilot to production scenario • Update the cqconnector.properties file to the renamed Jazz server. • Start the CQ Gateway. • Enable outgoing synchronization. • Manually force outgoing synchronization of work items.

10. Agenda • (Lorelei) CQ Synchronizer Server Rename Support • (Yuhong) CQ Bridge Server Rename Support • (Yuhong) A Tool to Transition from a Synchronizing Integration to a Bridging Integration

11. How Server Rename Affects CQ-CLM Bridge? • As of CLM 2012 and ClearQuest 2Q 2012 patch release, CLM server rename is supported by the bridge. This applies to its integration with RTC/RQM/RRC. • CQ-CLM bridge integration stores links to the CLM servers, work items, testing assets and requirements the ClearQuest Web server configuration files and in OSLCLinks records in the ClearQuest user database. • These links becomes stale after a CLM server rename event. • A perl script (clm_server_rename.pl) is shipped with ClearQuest to remap URIs stored in CQWeb configuration files and stored in ClearQuest user database. • The script needs to run on the CQWeb server after a CLM server renaming event. • It is installed to $CQ_WEB_SERVER_PROFILE_TOP\installedApps\<cell>\TeamEAR.ear\cqweb.war\WEB-INF\classes • Caveat: Only structural links/URIs stored at ClearQuest side will be remapped. Embedded links (for instance, link to a RTC WI inserted as part of a ClearQuest record’s notes field) will not be remapped.

12. Steps to follow to deal with CLM server rename • CQ admin notifies the CQ user community that existing links might be broken • Log on to ClearQuest Web server as a user with both local administrator and ClearQuest Super User privileges. • Reconfigure cross-server communication only on the ClearQuest Web server. Do this by running the URI remapping tool with the -remapconfigfiles option, for each cross-server friend for which you have reestablished cross-server communication. • For each cross-server friend for which you have reestablished cross-server communication, run the tool again with the -update option. • If your deployment includes Rational ClearQuest MultiSite, you must repeat the previous step at each replica where the affected ClearQuest OSLCLinks records are mastered. The tool reports the OSLCLinks records that are mastered remotely. • Send a final notification to the user community that the URI remapping is complete. Be sure to specify the limitations. • See Remapping URIs after renaming a CLM server for details.

13. Server Rename References (for CQ Synchronizer and CQ Bridge) • Impact of Server Rename and Integrated Products • Preparing the ClearQuest Synchronizer for renaming the Jazz Team server • Renaming your Rational solution for Collaborative Lifecycle Management Server • Server Rename in the InfoCenter

14. Agenda • (Lorelei) CQ Synchronizer Server Rename Support • (Yuhong) CQ Bridge Server Rename Support • (Yuhong) A Tool to Transition from a Synchronizing Integration to a Bridging Integration

15. The new syncToBridge tool • The SyncToBridge tool is a standalone Java application that bundles as part of the CQ-RTC Synchronizer component in RTC 4. • It starts from RTC side and finds all the work items in a project area (of specific type) that have been synchronizer enabled. It walks through the list, locates the CQ record, and establishes the OSLC-based bridge link between a synchronizer enabled work item and its corresponding CQ record. This process can be repeated. • User can then decommission the synchronizer.

16. The new syncToBridge tool (cont’d) • The syncToBridge tool is installed to the [CQ Synchronizer Installation]\gateway directory. • Usage: syncToBridgeTool jazzUrl=<value> jazzUser=<value> jazzPwd=<value> jazzPA=<value> jazzWIType=[all] cqRootServicesUri=<value> cqUserDb=<value> cqUser=<value> cqPwd=<value> • Note: before you start, make sure you have the CQ bridge setup and configured between the jazz server and the CQ web server. • See “Migrating from CQ Synchronizer to CQ Bridge” for more information.