Development teams who use IBM® Rational® Change can take advantage of the project management features in IBM® Rational® Team Concert to manage new development and change across organizations, across heterogeneous systems, and across code repositories, from a single view. The configuration required to integrate these tools, however, can be challenging. This article describes how to integrate the tools and how to configure the synchronizer and Open Services for Lifecycle Collaboration (OSLC) bridge to support the integration.
Why integrate Rational Change and Rational Team Concert?
If the tools are integrated, Rational Change developers can make use of project management and release planning features (Gantt charts and work breakdown charts, for example) of Rational Team Concert, Typically, the output of the project planning process is a set of change requests (called work items) that detail the work to be done. When the work items are assigned to individuals and submitted for review and approval, the project plan is automatically updated. By integrating Rational Team Concert and Rational Change, project management can be performed in Rational Team Concert with automatic updates to and from Rational Change to keep the plans in sync.
In many organizations, new apps and interfaces for web and mobile are being built on top of core business logic that has been managed in IBM® Rational® Synergy and Rational Change for decades. In many cases, these new interfaces are developed with one of the current process models such as scrum and therefore benefit from being managed in a tool such Rational Team Concert, which is designed for agile development. Ideally, the stable, business-logic code base can remain in Rational Synergy and Rational Change and new development can be performed in Rational Team Concert. By integrating Rational Change with Rational Team Concert, Rational Team Concert can manage new development and required changes to legacy code from a single source, without the cost or effort required to move the code base into a new software configuration management tool.
In some organizations, different groups use different tools. For example, some groups might use Rational Synergy and Rational Change, and other groups might use other software development tools. Rather than move all of the code into a single repository to facilitate collaboration, the development teams can use Rational Team Concert to view and manage change across the groups from a single source.
Two types of integrations
The most basic integration of Rational Team Concert and Rational Change is a simple relationship or link between a work item in Rational Team Concert and a change request in Rational Change. This OSLC link makes it easy to navigate from one tool to the other, and it provides some limited, rich hover information.
A more sophisticated integration is to synchronize work items and change requests between the two tools. This article focuses on how to integrate Rational Team Concert and Rational Change by using the Rational Change synchronizer for Rational Team Concert.
Install the Rational Team Concert synchronizer
The Rational Team Concert synchronizer is a synchronizer for the IBM® Rational® Synchronization Server. The Rational Synchronization Server provides synchronization services for Rational Change to several other tools, including IBM® Rational® Focal Point and IBM® Rational® ClearQuest®, in addition to Rational Team Concert.
Install prerequisites for Rational Team Concert Synchronization Server
The Rational Synchronization Server is a web application that runs inside of the Apache™ Tomcat™ Catalina web app server. It has the following dependencies:
- Apache Tomcat: Obtain a fresh copy of Apache Tomcat from the Apache Foundation download site or mirror site. At the time this article is written, the correct version is Tomcat 5.5.x or 6.x. Check the readme for the version of the synchronizer you are using.
- Java® Runtime: Obtain a fresh copy of Java® runtime from java.com. At the time this article is written, the correct version is JRE 6.0. Check the readme for the version of the synchronizer you are using. The Rational Synchronization Server is a 32-bit program, so a 32-bit copy of Java should be used, even on 64-bit platforms.
See the readme for Rational Synchronization Server 184.108.40.206, the version current at the time this article is written. The readme for other versions can be found in the integrations section of the Rational Change information center.
Download the Rational Team Concert Synchronization Server
The latest updated version of the Rational Synchronization Server software can be obtained from IBM Fix Central. At the time of this writing, the current version is here.
Configure Rational Team Concert work item to capture link to Rational Change
The Rational Synchronization Server needs two pieces of information to maintain synchronization of objects: the ID of the proxy object in Rational Change, and a URL link to that object. This information is stored in Rational Team Concert as attributes. The attributes must be created on the list of attributes or added to the list of attributes for the types of Rational Team Concert artifacts that are to be synchronized with Rational Change. Search jazz.net for articles describing how to edit work item attributes. The example in this article describes how to synchronize Rational Team Concert defects with system change requests in Rational Change.
Define the Rational Team Concert attributes
To synchronize defects, you need to create two attributes for the Defect type. To synchronize multiple types of Rational Team Concert artifacts, create unique ID mapping attributes for each work-item type. Do not reuse the ID mapping attribute across the work-item types. If an ID mapping attribute is used in one synchronizer, do not use it in other synchronizers. The query to pull the modified work items and change requests is based on the ID mapping attribute. If more than one synchronizer has the same ID mapping attribute, the object to be synchronized gets picked by more than one synchronizer. Prevent this situation by using unique ID mapping attributes. This rule applies only to ID mapping attributes, not to URL mapping attributes, because URL mapping attributes are not used to form queries. The URL mapping attributes contain only the HTTP URLS of the OSLC links for the respective objects.
In the Types and Attributes section of the project area configuration in Rational Team Concert, as shown in Figure 1, select the Defect type of artifact and add two attributes of type Medium String. This example uses
cr_url as the names for the two attributes. The name can be anything. The name you choose is provided to the synchronizer in the following steps.
Figure 1. Add attributes to Rational Team Concert
Add linked Rational Change request attributes to Rational Team Concert web forms
The only requirement is to define the attributes to capture the information from the synchronization process. However, if you want to display the attributes on the work item form in Rational Team Concert, add the attributes to the presentation editor for the Defect type. For this example, because this data is about a related artifact, put it on the Links tab. Add a Rational Change Requests section to the Links tab of the default Editor Presentation and add two attributes to it as shown in Figure 2.
Figure 2. Add attributes to the presentation editor for Defect type
These changes are made to the shared sections of the Editor Presentation, so to keep them from showing when they contain no data, the individual presentations are set to not display when empty, as shown in Figure 3.
Figure 3. Specify no display of empty sections
Figure 4 shows the result of these settings on an actual work item viewed through a web browser.
Figure 4. Example of work item viewed through a browser
Configure Rational Change to capture link to Rational Team Concert work item
As with Rational Team Concert, Rational Change needs to keep a record of which Rational Team Concert work item is synchronized with a change request in Rational Change. As with Rational Team Concert, you need to add two attributes to the change request lifecycle to capture this data.
Define the attributes in Rational Change
In this example, the type of Rational Change request to be synchronized is a System Change Request (SCR). To add attributes to Rational Change, you need to edit a lifecycle. Select the Lifecycle Editor link in the Rational Change administration interface. Select the appropriate workflow file from the list that appears and click Edit. In the Lifecycle Editor, click the Edit button near the CR Process in the button bar as shown in Figure 5.
Figure 5. Edit a lifecycle in Rational Change
Select the Attributes tab of the CR Process Properties, and click the Create button to create a new attribute called
rtc_wi_id. This attribute needs to be of Web Type
CCM_STRING and DBType
string, as shown in Figure 6. Repeat this process for a similar attribute named
rtc_wi_url. This creates the attribute for all lifecycles in the package. As with Rational Team Concert, do not reuse attributes across multiple synchronizers. To make the attributes available to a particular lifecycle, add the attributes to that lifecycle.
Figure 6. Create new attributes of Web Type CCM_String
Add attributes to a specific lifecycle in Rational Change
To add the attributes to the specific lifecycle, select the lifecycle in the Select a Lifecycle pulldown on the left side of the browser window and click Edit, as shown in Figure 7. In this example, the attribute is added only in the System Change Request lifecycle, but you can use the same process to add these attributes to other lifecycles as well.
Figure 7. Add attributes to a specific lifecycle
In the list of attributes, select the two attributes to add to this lifecycle, click the right arrow to add them to the lifecycle, and click the Update button as shown in Figure 7.
To help with debugging and clarity, add the attributes to the dialog. In the same window, select the Define Dialog tab, select the two attributes and add them to the dialog as shown in Figure 8. You are not required to display attributes in Rational Change. It is sufficient to have them in the lifecycle. If you do not want to see these two attributes, you do not have to add them to the dialog.
Figure 8. Select attributes from the Define Dialog tab
In this example, attributes are added to the end of the form with the other links. Next, you save the CR process file, create a package, and install the package into your Rational Change installation to see these links. The result of these changes is shown in Figure 9.
Figure 9. Resulting work item URL
Consider state transitions and owners for work items
Before you set up the synchronizer, make sure you address two other areas of configuration for Rational Change and Rational Team Concert:
- Ensure that you have the same number of states and work flows across both tools.
- Use the same list of potential work item owners and assignees across both tools.
Use the same number of states and same work flow across tools
The synchronizer maps lifecycle states between Rational Team Concert and Rational Change. Therefore, it is best to have the same number of states and the same basic work flow between the two tools. If not, a situation can arise where inaccurate data is recorded because a work item that is moved to the tool with the longer work flow can be promoted, but is then returned (erroneously) to the previous state when it is synchronized back into the tool with the shorter work flow. In Figure 10, the work flow in red represents Rational Change, and the work flow in green represents Rational Team Concert. The state mappings are in blue.
Figure 10. Work flows for Rational Change and Rational Team Concert and state transitions
It is possible for a state transition from Req Chg state to the Implement state to be lost when it is synchronized back to Rational Team Concert. In this case, a change request that is in the In Progress state in Rational Team Concert is synchronized into Rational Change in the Req Chg state. If the change request in Rational Change is transitioned to the Implement state, when it is synchronized back into Rational Team Concert it is again defined to be in the In Progress state. On a subsequent sync, it will again be in Rational Change in the Req Chg state, losing the transition that was done previously.
Use the same list of potential work item owners across both tools
During typical operation, the Rational Change synchronizer for Rational Team Concert assigns an owner to a work item in one tool based on an owner or assignee attribute in the other tool. This assignment can happen on the initial synchronization when a work item is first created in the other tool, or it can happen on a subsequent synchronization.
If the user name is not defined in the other tool, synchronization errors occur. Therefore, it is important that the list of users who are possible owners or assignees be the same between both tools. Consider this requirement during the initial implementation of Rational Team Concert. Although it is possible to maintain two lists of users manually, it is much easier to use a common LDAP server such as Microsoft® Active Directory® to provide the same list of users to both tools. To maintain an identical set of users in both tools is a tedious, time-consuming operation, at best. (To simplify the example in this article, this suggestion is not implemented.)
Administer the synchronizer
After you install the synchronizer, add the necessary attributes to the appropriate artifact types in both Rational Team Concert and Rational Change, and resolve the differences in the lifecycles and user lists, you can set up the synchronizer.
Use the web admin tool to set up the synchronizer
If you use an earlier release of the Rational Synchronization Server (220.127.116.11 or prior), use the Microsoft® Internet Explorer® web browser. For current versions, you can also use Mozilla® Firefox®.
Note: After you log in, if the web page has garbled characters, check the URL for lowercase. In some cases, the login switches the last parameter of the URL from mixed case SyncFramework.html to all lowercase syncframework.html. The correct URL is mixed case. For example,
http://clmdemo:8082/TlogicIntegration/admin/syncframework is incorrect. Rather, the correct URL uses a mixed case spelling of SyncFramework:
Configure the synchronizer
The steps for how to configure the synchronizer are described in the help that is built into the synchronizer. This article gives a few key tips. As shown in Figure 11, the link to synchronizer-specific help is on the navigation bar for the Installed Synchronizers.
Figure 11. Link to specific help for Rational Synchronization Server
On the Rational Change Server page of the Rational Change-Rational Team Concert synchronizer configuration, the user that is shown is the user that logs into Rational Change and carries out all the actions in Rational Change. To make this simpler, you can have a unique Rational Change user that has administrative rights in the Rational Change database and can clearly be identified in audit logs as the synchronizer and not a person.
In the example in Figure 12, a regular user
bernie is used. However, it is better not to define a regular user but to use a system user specific to synchronization, instead. Because the intent of this example is only to sync System Change Request type change requests with defect type requests, the set of artifacts in the Rational Change database can be limited with the Migrate query. In the example, you select only objects of type System Change Request by looking for artifacts that have a workflow state that starts with
Figure 12. Sync System Change Request type change requests with defects
A significant part of the synchronization process is to map the states, as the section on state transitions describes. For both Rational Team Concert and Rational Change, a state must be mapped in the other tool, as shown in Figure 13.
In Figure 13, each Rational Change state is mapped to a Rational Team Concert state, and similarly, each Rational Team Concert state is mapped to a Rational Change state. In this example, a change request in Rational Change in the Requirements Change state can be synchronized with a work item in the In Progress state, but there is no mapping that places a change request into the Requirements Change state when the change request is created from synchronization with Rational Team Concert.
Figure 13. State mapping for Rational Change and to Rational Team Concert and the reverse
Figure 13. Sync System Change Request type change requests with defects
Any attribute that is mandatory in one tool but not in the other needs to have a default value defined to prevent errors when new artifacts are created.
Run the synchronizer
To run the synchronizer, open the Start/Stop Synchronizer panel under the Administration section of the navigation bar. Control which synchronizer runs from the list of defined synchronizers.
Although the log files contain valuable information, they can become large. Clear the log between every run until you get runs with no errors. Current releases of the synchronizer support log file rotation to help manage large logs. If you do experience errors, click the Log Debug Messages checkbox as shown in Figure 14, to write much more information into the log.
Figure 14. Log Debug Messages checkbox in the synchronizer
After the synchronizer starts running, click the Refresh button to see any changes. On the initial synchronization, this process can take hours for even small databases. However, after the two databases are in sync and all of the old change requests are processed, the synchronization is very efficient.
When the synchronization is complete (or even while it is still running) you can open the log to observe progress. The open log file does not automatically update. Therefore, you need to close it and open the log file again to get the latest changes.
Review the logs and fix errors
It can take several tries to get a synchronizer set up correctly. Until it is correct, you continue to receive a
synchronization failed message, and you get the opportunity to download a log file. The best debugging clues are in the log, but the debug process is not easy. When you choose to turn on the debug feature, you get a lot of information in the log file and some of it is confusing. Typically, the synchronization typically fails in one or more of these areas:
- One of the queries fails because of a syntax error. This situation is more common with Rational Change queries because the Rational Team Concert interface uses Rational Team Concert named queries
- One of the following attributes has a problem:
- A user name comes from the other tool and that user name is not defined in this tool.
- An enumeration does not have a match.
- A required field does not have a value or a synchronizer default.
- The ID and URL attributes are specified incorrectly or defined incorrectly in the lifecycle.
In Figure 15, the synchronizer tries to create an object in Rational Team Concert for Rational Change Request 184 from Rational Change. You can see that the attributes for
description have synchronized correctly, so look in Rational Change at the other attributes that are synchronized for cause of the problem. In this case, there is a problem with the priority attribute that is set to
Any in Change Request 184 in Rational Change.
Figure 15. Errors in log file when the synchronizer tries to create an object
Because this synchronization failure is not caused by the definition of the synchronizer but is caused by the data, errors such as this can occur even after the synchronizer runs successfully. Be prepared to look into each one and address each situation as it comes up. You can make changes to the input validation in either Rational Team Concert or Rational Change so that the data is without errors.
Synchronize Rational Change data with Rational Team Concert to bring significant value to any organization that uses Rational Synergy and Rational Change and wants to begin to adopt all or part of Rational Team Concert. Use the synchronizer to keep change request data in sync between the two tools before, during, and after an initial Rational Team Concert deployment. The synchronizer is flexible, but it does require some forethought about how data is to be mapped between the two tools. After the synchronizer is running successfully, remain vigilant to ensure that the synchronization continues to run correctly. Be proactive and address issues that you detect.
- Start at developerWorks to learn about features and benefits, get product details and information on related Rational products, and to find more technical articles and where to get support. For information on Rational Change, see the product page on developerWorks.
- Discover more about Rational Team Concert:
- Find Rational Team Concert articles and links to many other resources on IBM developerWorks, and check the product overview page, features and benefits, system requirements, and the user information center.
- Check the Rational Team Concert page on Jazz.net.
- Watch the Using Rational Team Concert in a globally distributed team webcast or a demonstration of the Dashboards and reports, or listen to the podcast about IBM Rational Team Concert and Jazz.
- Explore the Rational software area on developerWorks for technical resources, best practices, and information about Rational collaborative and integrated solutions for software and systems delivery.
- Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
- Improve your skills. Check the Rational training and certification catalog, which includes many types of courses on a wide range of topics. You can take some of themanywhere, anytime, and many of the Getting Started ones are free.
Get products and technologies
- Download Rational Team Concert from Jazz.net and try it free on up to 10 developers for as long as you want (requires registration). If you'd prefer, you can try it in the sandbox instead, without installing it on your own system.
- Check the Rational trials and demos page for Rational software. Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, or use it in a cloud environment.
- Join the Enterprise Change Management with Rational Change forum to ask questions and participate in discussions.
- Get connected with your peers and keep up on the latest information in the Rational community.
- Rate or review Rational software. It's quick and easy.
- Share your knowledge and help others who use Rational software by writing a developerWorks article. Find out what makes a good developerWorks article and how to proceed.
- Follow Rational software on Facebook, Twitter (@ibmrational), and YouTube, and add your comments and requests.
- Ask and answer questions and increase your expertise when you get involved in the Rational forums, cafés, and wikis.