Running the ClearQuest Connector setup wizard is just the beginning of integrating IBM® Rational® Quality Manager and IBM® Rational ClearQuest®. After running the setup wizard, you need to align the Rational Quality Manager workflow with the Rational ClearQuest state transition model so that states in Rational Quality Manager match those in Rational ClearQuest. You also need to map mandatory fields in Rational ClearQuest records to corresponding fields in Rational Quality Manager. Rational Quality Manager has a built-in defect-tracking system, but some users might continue using ClearQuest for defect tracking. When the test team enters defects in Rational Quality Manager, the ClearQuest Connector either creates or synchronizes a copy of the defect in Rational ClearQuest. Similarly when a user submits or edits a defect in Rational ClearQuest, a copy of the defect in Rational Quality Manager is kept synchronized with the one in Rational ClearQuest.
Before continuing with the procedures that follow, make sure that you have Rational ClearQuest installed and that the schema and user database are set up. Verify that ClearQuest Connector has been installed on the computer where Rational ClearQuest is installed. (You can download the ClearQuest Connector from jazz.net at jazz.net/downloads/rational-team-concert/.) Complete the setup steps in the "Running the Setup Wizard" section in this wiki: jazz.net/wiki/bin/view/Main/CQConnectorSetupWizardDemo.
The IBM Rational Team Concert™ rich client must be installed on a computer that can access the Rational Quality Manager server over the network. (You can download the Rational Team Concert rich client from the jazz.net web site at jazz.net/downloads/rational-team-concert/).
After you watch the setup wizard connector demo from the wiki mentioned earlier, start the Rational Quality Manager server and the ClearQuest Gateway. To complete the integration, follow the procedures here to make further configurations in the Rational Quality Manager workflow.
Disable outgoing synchronization
Before proceeding, temporarily disable outgoing synchronization:
- Start the Rational Team Concert client, and use the client to connect to the Rational Quality Manager project area.
- If the Welcome page in Rational Team Concert opens, close the page.
- On the left side of the Rational Team Concert client, right-click the user ID in Team Artifacts, and then click Administer > Synchronization Rules, as shown in Figure 1. This action opens a view near the bottom of the Rational Team Concert client.
Figure 1. Open the synchronization rules view
- Expand External Repository Connections.
- Right-click the displayed connection, and select Open as shown in Figure 2. The external connection was created as part of the ClearQuest Connector Setup wizard.
Figure 2. Open the External Repository Connection Window
- In the dialog box that opens, select Disable automatic outgoing synchronization, as shown in Figure 3, and then click OK.
Figure 3. Disable outgoing synchronization
Configure the synchronization rules for external users
The ClearQuest Gateway uses one connector user to communicate between Rational ClearQuest and Rational Quality Manager. If configuration for external users is not set up, all defects that users submit or modify are associated with that one connector user. However, you can configure the ClearQuest Connector so that defect submissions and modifications are associated with the actual user who makes the change:
- In the Synchronization Rules section of Rational Team Concert, right-click the rule that corresponds to Defect, and select Open. (See Figure 4.)
Figure 4. Open the Defect synchronization rule
- In the Property Mappings section, click Add. the Property Mappings dialog box that opens.
- In Choose an external property to map from, click Existing or user defined, select modifiedBy, and then select External modifier, as shown in Figure 5.
- Click OK, and then click Save.
Figure 5. Configure the modifiedBy setting
Map the Comments and Notes fields
Customers typically add comments to defects to request further information from the submitter or to clarify the defect. You need to map the Comment field in Rational Quality Manager to the Notes field in Rational ClearQuest:
- In the Property Mappings section Rational Quality Manager, click Add.
- In the first list, select Comments.
- In the second list, select In/Out.
- In the third list, select Notes_Log, and then click OK. (See Figure 6.)
Figure 6. Configure the Comments and Notes fields
- In the Property Mappings section, clear the No Transformation (just copy) check box.
- Scroll to and select the synchronization rule for the user in the Reference synchronization rule list: com.ibm.rational.clearquest.users.Quality Manager. (See Figure 7.)
- From the Value Transformer list, select Work Item Comments Transformer, as shown in Figure 7, and then click Save.
Figure 7. Configure synchronization rules
Align Rational Quality Manager workflow with the Rational ClearQuest transition model
The "workflow" in Rational Quality Manager is analogous to the state transition model in Rational ClearQuest. The states and values in the two products need to be aligned so that synchronization works correctly:
- On the left side of the Rational Team Concert rich client, right-click the project area, as shown in Figure 8, and then select Open.
Figure 8. Open a project area
- Click the Process Configuration tab. (See Figure 9.)
- Expand Process Configuration, expand Configuration Data, and then expand Work Items (advanced).
- Select Workflows. (See Figure 9.)
Figure 9. Open a Rational Quality Manager workflow
- In the Transitions section of the workflow, map Rational Quality Manager states and actions to the states in Rational ClearQuest records.
- Select actions that are required to make the transition from one state to the next. For example, see Figure 10. For the user to change the "In Progress" state to the "Closed" state, the user must select Close.
Figure 10. Set up states in the workflow
- If a transition is permitted but the list does not include the appropriate action, you can add an action by selecting New Action.
In Figure 11, the user permits a transition from "In Progress" to "Duplicate." However, Rational Quality Manager does not yet have an action that permits that transition. You can add an action by clicking the list, and selecting New Action. For the new action, you create an action called Duplicate that permits the transition from the "In Progress" state to the "Duplicate" state.
Figure 11. Add a permitted action
- If a transition is not permitted, select None as the action for that transition. In Figure 12, users cannot change from the "In Progress" state to the "Duplicate" state, so the action there is set to None.
Figure 12. An action that is not permitted
- For the other transitions from the "In Progress" state, verify whether the transition is appropriate for you. If the transition is not permitted in Rational ClearQuest, then select None.
- Continue across the entire row and make sure that the correct action is set for each cell. Use the Tab key to move from one cell to the next in the row.
- To add, remove, or edit states scroll to the States section, after the Transitions section. See Figure 13.
Figure 13. Examine valid states
- To add, remove, or edit resolutions, scroll to the Resolutions section. See Figure 14.
Figure 14. Examine valid resolutions
- Scroll to the Actions section and verify that all the actions meet your needs; then make changes as necessary. See Figure 15.
Figure 15. Review valid actions
Map mandatory fields
The two products have different requirements for when mandatory fields must be entered. By default, in Rational Quality Manager when you move a defect from the "New" (Submitted) state to the "In Progress" (Assigned) state, there is no need to specify an owner for that defect. However, in Rational ClearQuest when you move a defect from the "Submitted" state to the "Assigned" state, you must specify an owner and set a priority. The error message that Figure 16 shows states that the Owner and Priority fields need to be set in order to change the defect to the "In Progress" state.
Figure 16. Analyze synchronization status errors
To resolve this issue, change the model in Rational Quality Manager to make this field mandatory in this case:
- From the Process Configuration page that you used in an earlier procedure, expand Team Configuration, and then select Operation Behavior as shown in Figure 17.
Figure 17. Open the Operation Behavior view
- In the middle of the editor, find the Operation Behavior section. Scroll down to the Work Items section, and select the icon in the Everyone column. (See Figure 18.)
Figure 18. Navigate the Operation Behavior window
- Scroll down further in the Work Items section, and select Required Properties. (See Figure 19.)
Figure 19. Go to the Required Properties section
- Scroll down to the Category or Type section as shown in Figure 20, and select com.ibm.team.workItem.workItemType.
- Expand the com.ibm.team.workItem.workItemType item by clicking the plus sign (+) to the left of the entry.
Figure 20. Select the work item category or type
- In the Category or Type section, scroll down and expand the Defect item, and then select In Progress.
- Click Edit as shown in Figure 21.
Figure 21. Edit defect properties
- In the Edit Defect dialog box that opens, select both Owned By and Priority. These two fields are both required in Rational ClearQuest when a user puts a defect in the "Assigned" (In Progress) state.
- Click OK, and then click Save.
- Select other rows that are displayed in this section such as Closed or Resolved, and specify the mandatory fields that Rational ClearQuest requires when a defect is put into that state.
- After you complete the earlier procedures, click the External Repository Connections entry at the bottom of the page. (See Figure 22).
Figure 22. Open the External Repository Connectiosn page
- Enable the outgoing synchronization by clearing the Disable automatic outgoing synchronization check box as shown Figure 23.
Figure 23. Enable outgoing synchronization
Synchronization is enabled again and you have changed the transition model to meet your needs. You might still need to adjust settings further. When you need to adjust either the synchronization rules or the state transition model (workflow), return to the dialog box in Figure 23, and select Disable automatic outgoing synchronization to temporarily stop synchronization.
Set synchronization times
You set synchronization delays independently for each product.
In Rational Quality Manager, you set synchronization times in the Advanced Properties section on the Jazz Server Administration page:
- Open Rational Quality Manager in a browser (Internet Explorer 7 or Firefox 3.0 or later), and log in as a user with administrative permissions.
- At the top right side of the Rational Quality Manager main page, click Admin > Jazz Server Administration.
- On the left side of the page, click the Advanced Properties link.
- When the page opens, search for
interopto move quickly to the Item Interoperation section.
- In that section, make sure that the Outgoing Synchronization Enabled field is set to
- Set the Outgoing Synchronization Task Fixed Delay field to a low number, say 10, which indicates seconds. By default this value is set to
- Scroll to the top of the page, and click Save.
For Rational ClearQuest, you set synchronization times in the Connector Gateway.
- Go the Rational Team Concert Connector Gateway installation location.
- Go to the
cqconnector.propertiesfile in the RTC-CQConnector-Install dir\jazz\connectors\gateway folder.
- Open the
cqconnector.propertiesfile, and set the value to 10 seconds as shown in the following line, and then save the file.
- If the Connector Gateway was already running, then shut it down and restart it for the change to take affect.
Troubleshooting synchronization problems
Sometimes the synchronization function might not work for various reasons. You can use the Rational Team Concert rich client to determine reasons for problems.
When a defect does not synchronize with a counterpart (assuming that the fixed delay time has passed), complete this procedure:
- Right-click the Defect synchronization rule in Rational Team Concert, and select Show Unsynchronized. (See Figure 24.)
Figure 24. Show unsynchronized defects
The Synchronization Status page opens as shown in Figure 25 and Figure 26.
- Double-click an item that failed to synchronize, and read the error message for clues about how to resolve the problem. You might need to temporarily stop automatic synchronization, as explained earlier. Be sure to re-enable synchronization after you complete the changes.
Figure 25. Examine synchronization status
Figure 26. Synchronization status details
- Continue adjusting the synchronization rules and the transition model and checking for unsynchronized items until defects can be entered and changed without errors.
- Go though all possible states in a defect to ensure that the two products can synchronize all states without errors. You can also search the help topics in Rational Team Concert help for further details.
Intregrated, synchronized, and ready to go
Running the ClearQuest Connector setup wizard opens the door for integration. The setup wizard does not detect your workflow and requirements for logging defects. Therefore, after the ClearQuest Connector is initially set up, you need to describe your environment and adjust the described settings so that Rational Quality Manager and Rational ClearQuest can work together. Follow the earlier steps and two applications will work together to keep you connected, synchronized, and efficient.
- See the "Getting Started with ClearQuest Connector" section of the Rational Team Concert Information Center.
- Check the Rational Quality Manager page on IBM® developerWorks® for links to product documentation, articles, tutorials, courses, downloads, and other useful areas.
- Explore the Rational Quality Manager Information Center for technical details.
- For tips, read these developerWorks articles by Michael Kelly:
- Getting started with IBM Rational Quality Manager (December 2008)
- For Managing your first project with IBM Rational Quality Manager (October 2008)
- Browse the IBM Quality Management page to learn more about what is available.
- Learn about other applications in the IBM Rational Software Delivery Platform, including collaboration tools for parallel development and geographically dispersed teams, plus specialized software for architecture management, asset management, change and release management, integrated requirements management, process and portfolio management, and quality management.
- Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
- Explore Rational computer-based, Web-based, and instructor-led online courses. Hone your skills and learn more about Rational tools with these courses, which range from introductory to advanced. The courses on this catalog are available for purchase through computer-based training or Web-based training. Additionally, some "Getting Started" courses are available free of charge.
- Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
Get products and technologies
- Download the free trial version of Rational Quality Manager.
- Download these IBM product evaluation versions and get your hands on application development tools and middleware products from Rational®, DB2®, Lotus®, Tivoli®, and WebSphere®.
- Download trial versions of IBM Rational software.
- Join the Rational Quality Manager forum, which also includes discussions about Rational Test Lab Manager.
- Check the Rational TestManager forum on developerWorks.
- Check out developerWorks blogs and get involved in the developerWorks community.