1. ClearQuest Synchronizer Tools, CQ Importer, and General Tips Matthew Alexander June 2014

2. Types of CQ/RTC Integrations CQ Synchronizer CQ Bridge Two way data synchronization One way data migration Work Items Rational Team Concert CQ Importer Work Items Rational Team Concert CQ records ClearQuest Work Items Rational Team Concert CQ records ClearQuest Traceability / links ClearQuest CQ records https://jazz.net/library/article/1310

3. CQ Synchronizer Setup Wizard ● Web-based wizard that automates the steps for configuring the CQ and RTC environment for synchronization ● Populates the cqconnector.properties file ● Registers and applies the JazzInterop package to a CQ user database ● Creates an external repository connection on Jazz server ● May create sample synchronization rules (not recommended) ● URL is in the format servername:portNumber/cqconnector/cqsetup ● Users may still need to take additional manual steps ● Enable outgoing synchronization on the Jazz server ● Jazz user must have permission to create external repository connection and create/edit synchronization rules ● Create/modify synchronization rules ● Hosted in the CQ Gateway (must run on Windows)

4. CQ Synchronizer Continued – Resolving Conflicts ● Conflicts can occur for various reasons, including when two users make nearly simultaneous changes to a ClearQuest record and its corresponding work item. ● Sometimes, you may manually resolve the conflict by selecting the appropriate value.

5. Which Records are Selected for Synchronization? ● CQ record selection defined by queries (one per record type) ● Work item selection defined by enabling team areas in sync rules ● Selection determines what gets connected – once connected, synchronization continues even if selection changes ● Connection only happens when a new CQ record/work item is created

6. SyncTool ● Synchronization is only triggered by new record/work item creation ● We need a way for existing CQ Records to start synchronizing ● SyncTool fills this need ● Command line tool ● Needs CQ Synchronizer to be setup ● Example command: synctool.bat recordType=Defect jazzServer=https://cqConnector:cqConnector@myJazz Server:9443/ccm projectArea="CQ Connector"

7. Creating Users ● Done using ClearQuest User Administration ● User databases must be upgraded to have user changes applied ● Demo SyncToBridgeTool ● Used by existing CQ Synchronizer user who want to start using CQ Bridge ● Creates a CQ Bridge link between a CQ record and RTC work item which have been synchronized ● Works by querying on all work items in a project area that have an external connection ● Example command: syncToBridgeTool.bat jazzUrl=https://jbslnxvh08.ottawa.ibm.com:9443/ccm jazzUser=mattalex jazzPwd=mattalex jazzPA=cqconnector jazzWIType=Defect cqRootServicesUri=http://spidermatt.rtp.raleigh.ibm.com/cqweb/oslc/repo/jbslnxvh 08/discovery cqUserDb=SAMPL cqUser=mattalex cqPwd=mattalex

8. Creating Users ● Done using ClearQuest User Administration ● User databases must be upgraded to have user changes applied ● Demo Sync with Bridge ● New in RTC 5.0 ● Creates CQ Bridge links as part of synchronization ● Add four parameters to the cqconnector.properties file ● cq.createOslcLinkJazz=true ● cq.createOslcLinkClearQuest=true ● cq.rootServices=http://spidermatt.rtp.raleigh.ibm.com/cqweb/oslc/repo/jbslnxvh08/discovery ● cq.recordTypeDbId.Defect=12345678

9. ClearQuest Importer ● Part of the RTC Eclipse client ● One-way migration of CQ records to RTC ● No relation to CQ Synchronizer and should not be used together ● Uses an xml mapping file to specify how fields are mapped ● Also supports importing the following types Users, Notes, Attachments, Work Item Relationships (duplicates, parent / child, blocks / depends on, and related) ● Requires CQ to be installed on the same machine as the RTC 32-bit client ● As of RTC 5.0, is only supported on Windows

10. ClearQuest Importer ● Example mapping file is provided (snippet displayed to the right) ● To find RTC target IDs: ● Open the project area ● Click Process Configuration tab ● Expand Project Configuration ● Expand Configuration Data ● Expand Work Items ● Double-click Types and Attributes ● Can find IDs by double-clicking on attribute in Attributes section ● Built on Bugzilla code, which is managed by the Work Items team ● Does not support stateless CQ record types

11. ClearQuest Importer Tips ● A more detailed sample mapping file can be found in the Work Items from CSV Importer (File > Import > Team > Work Items from CSV) ● CQ records can be saved as CSV from the CQ Importer and imported using Work Items from CSV Importer ● Only works on the 32-bit RTC Eclipse client ● For the “Update work items which have previously been imported” option to work, the custom “Imported from” field must contain the CQ record ID

12. Creating Users ● Done using ClearQuest User Administration ● User databases must be upgraded to have user changes applied ● Demo CQ Setup Wizard Tips ● Only works when CQ Gateway installed on Windows ● Built off of Foundation code – changes with their bundles break the wizard ● See https://jazz.net/wiki/bin/view/Main/CQConnectorDebuggingCQSetupWizardhttps://jazz.net/wiki/bin/view/Main/CQConnectorDebuggingCQSetupWizard ● See 308290: CQ synchronizer Setup Wizard does not work on Windows308290: CQ synchronizer Setup Wizard does not work on Windows ● See 278696: cqsync wizard setup link does not work278696: cqsync wizard setup link does not work ● See 254891: CQ sync setup wizard fails on startup.254891: CQ sync setup wizard fails on startup. ● See 233402: CQ Synchronizer Setup Wizard is broken - missing dependencies233402: CQ Synchronizer Setup Wizard is broken - missing dependencies ● To debug javascript issues, use FireBug in FireFox (see https://jazz.net/wiki/bin/view/Main/CQConnectorDebuggingCQSetupWizard) https://jazz.net/wiki/bin/view/Main/CQConnectorDebuggingCQSetupWizard ● Once the JazzInterop package is registered on a machine, it remains registered. To test the registration, you must manually unregister the package from the command line: ● packageutil registerpackage JazzInterop 1.11 -unregister

13. Creating Users ● Done using ClearQuest User Administration ● User databases must be upgraded to have user changes applied ● Demo CQ Synchronizer Tips ● Problems with initial setup ● Check the CQ Gateway Status page and verify the message at the top says “Accepting all requests” ● Open your External Repository Connection in RTC client, copy the “Info” field, and paste in a web browser ● URL should look something like http://servername.ibm.com:8081/cqconnector/gatewayhttp://servername.ibm.com:8081/cqconnector/gateway ● Verify the Jazz server can reach the CQ Gateway ● Open a synchronization rule in the RTC client ● If you see this error at the top of your rule, the Jazz server can't reach the gateway:

14. Jazz Server Pieces ● Interop code (Jazz Item Connector Framework) is included with Jazz server ● CQ External Repository Manager (named CQExternalManager) is included with Jazz server ● Synchronization Rules will be stored on the Jazz server (none are provided with the server itself) ● Value Transformers are stored on the Jazz server (some provided by default) Creating Users ● Done using ClearQuest User Administration ● User databases must be upgraded to have user changes applied ● Demo CQ Synchronizer Tips ● Problems with initial setup (continued) ● Start with simple sync rules ● Begin with the required fields of CQ records/RTC work items ● Slowly add more fields and test as you go ● Do the sync rules worksheet (Knowledge Center) ● Setup the sample environment using the provided sample sync rules ● Verify the user IDs used by the CQ Gateway have the correct permissions (Jazz user may need to be member of the project area) ● Verify outgoing synchronization is enabled on the Jazz server and on the external repository connection ● The CQ Synchronizer does not create CQ users ● If an RTC user who doesn't exist in CQ creates/edits/is assigned to an RTC work item which is synchronized, a synchronization error will occur ● Create the user in CQ (make sure the name, user id, and email address match) and retry synchronization

15. Jazz Server Pieces ● Interop code (Jazz Item Connector Framework) is included with Jazz server ● CQ External Repository Manager (named CQExternalManager) is included with Jazz server ● Synchronization Rules will be stored on the Jazz server (none are provided with the server itself) ● Value Transformers are stored on the Jazz server (some provided by default) Creating Users ● Done using ClearQuest User Administration ● User databases must be upgraded to have user changes applied ● Demo CQ Synchronizer Tips ● Incoming/Outgoing and Internal/External terms written from the Jazz server perspective ● Incoming = being sent from CQ to Jazz ● Outgoing = being sent from Jazz to CQ ● Look at the ccm.log file for errors on the Jazz server ● Turn debugging on in the..ClearQuestSynchronizer\gateway\log4j.properties file

16. Jazz Server Pieces ● Interop code (Jazz Item Connector Framework) is included with Jazz server ● CQ External Repository Manager (named CQExternalManager) is included with Jazz server ● Synchronization Rules will be stored on the Jazz server (none are provided with the server itself) ● Value Transformers are stored on the Jazz server (some provided by default) Creating Users ● Done using ClearQuest User Administration ● User databases must be upgraded to have user changes applied ● Demo CQ Synchronizer Tips ● Touchy areas ● Attachments ● Great deal of custom code surrounding attachments ● Attachments are synchronized as their own Jazz items ● Preferred if CQ customers use an FTP server for attachments if possible ● CQ notes_log – RTC work item comments ● CQ notes_log treated as one long text file ● Our code transforms it to multiple RTC work item comments ● Formatting is not always consistent in CQ ● Date formats ● Submit, due dates, etc ● Dates in notes_log ● CQ Importer

17. Jazz Server Pieces ● Interop code (Jazz Item Connector Framework) is included with Jazz server ● CQ External Repository Manager (named CQExternalManager) is included with Jazz server ● Synchronization Rules will be stored on the Jazz server (none are provided with the server itself) ● Value Transformers are stored on the Jazz server (some provided by default) Creating Users ● Done using ClearQuest User Administration ● User databases must be upgraded to have user changes applied ● Demo CQ Synchronizer Tips ● How to decommission the CQ Synchronizer or “start over” ● CQ side ● Create queries to select all records of the following record type and then delete the records: ● JazzConnectorChangeEvents ● JazzConnectorProperties ● JazzConnectorQueryInfo ● JazzConnectorSyncHistory ● Jazz side ● Delete all synchronization rules (this breaks the linkage between work items and CQ records) ● Disable outgoing synchronization on the server and external repository connection (optional) ● Delete the external repository connection (optional)

18. Jazz Server Pieces ● Interop code (Jazz Item Connector Framework) is included with Jazz server ● CQ External Repository Manager (named CQExternalManager) is included with Jazz server ● Synchronization Rules will be stored on the Jazz server (none are provided with the server itself) ● Value Transformers are stored on the Jazz server (some provided by default) Creating Users ● Done using ClearQuest User Administration ● User databases must be upgraded to have user changes applied ● Demo CQ Synchronizer Tips ● A CQ user database and a CQ Synchronizer gateway always have a 1:1 relationship (the CQ Gateway can only connect to one CQ database) ● The CQ Gateway may connect to multiple Jazz servers ● A Jazz server can connect to multiple CQ Gateways ● The CQ Gateway can connect to multiple Jazz servers and multiple project areas in each server ● A project area has its own sync rules ●

19. Jazz Server Pieces ● Interop code (Jazz Item Connector Framework) is included with Jazz server ● CQ External Repository Manager (named CQExternalManager) is included with Jazz server ● Synchronization Rules will be stored on the Jazz server (none are provided with the server itself) ● Value Transformers are stored on the Jazz server (some provided by default) Creating Users ● Done using ClearQuest User Administration ● User databases must be upgraded to have user changes applied ● Demo Resources ● Team wiki: https://jazz.net/wiki/bin/view/Main/ConnectorItemMainhttps://jazz.net/wiki/bin/view/Main/ConnectorItemMain ● Knowledge Center: https://pic.dhe.ibm.com/infocenter/clmhelp/v4r0m6/topic/com.ibm.team.connector.cq.doc/topics/c_rtc_ and_cq.html https://pic.dhe.ibm.com/infocenter/clmhelp/v4r0m6/topic/com.ibm.team.connector.cq.doc/topics/c_rtc_ and_cq.html ● Comparing concepts between ClearQuest and RTC: https://jazz.net/library/article/499https://jazz.net/library/article/499 ● RTC/CQ Integration Cookbook: https://jazz.net/library/article/1310https://jazz.net/library/article/1310 ● Popular ClearQuest & Team Concert YouTube videos: http://www.youtube.com/watch?v=UCD5s8b87T8&list=PLU84HfK_YRUIcVfG88qDSINpADDapIOdT http://www.youtube.com/watch?v=UCD5s8b87T8&list=PLU84HfK_YRUIcVfG88qDSINpADDapIOdT ● Guidance on importing ClearQuest records to RTC: https://jazz.net/library/content/articles/rtc/4.0/cq- importer-additional-guidance/https://jazz.net/library/content/articles/rtc/4.0/cq- importer-additional-guidance/ ● Tips on writing sync rules: https://jazz.net/wiki/bin/view/Main/WritingSyncRuleshttps://jazz.net/wiki/bin/view/Main/WritingSyncRules ● FAQ: https://jazz.net/library/article/88/https://jazz.net/library/article/88/ ● Jazz.net forums ● Work items