Integrate IBM Rational Team Concert and IBM Rational Change

Manage new development and change across development platforms from a single view

Organizations that use IBM Rational Change are hesitant to transition to a new change-tracking tool. However, they need access to integrated project planning features and they need better collaboration and integration with other tools in the application development lifecycle. One option is to integrate Rational Change with IBM Rational Team Concert to get access to these capabilities, without disrupting existing projects that use Rational Change and IBM Rational Synergy.

Stephen S. Grossman (sgrossma@us.ibm.com), Systems Engineer, IBM

Author1 photoSteve has more than 20 years of experience with IBM Rational Synergy and has worked with Rational Change from its first introduction. Steve has helped many customers with their change and configuration management needs using Rational Synergy and Rational Change. Steve continues to assist companies to transition to more modern software configuration management technologies. He speaks on change management topics at the IBM Innovate conference. One of his focus areas is integration between various tools across the system development lifecycle.



11 February 2014

Also available in Chinese

Introduction

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 1.4.0.4, 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_id and 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
Customize attributes for a type

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
Make changes in the Editor Presentation view

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
Select checkboxes Hide if Empty, Hide on Creation

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
Work item instance after customization

Click to see larger image

Figure 4. Example of work item viewed through a browser

Work item instance after customization

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
View of button to Edit Rational Change workflow

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 TypeCCM_STRING and DBTypestring, 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
View of numbered steps for attribute customization

Click to see larger image

Figure 6. Create new attributes of Web Type CCM_String

View of numbered steps for attribute customization

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
Steps to add Rational Change attributes

Click to see larger image

Figure 7. Add attributes to a specific lifecycle

Steps to add Rational Change attributes

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
Steps to put attributes on dialog

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
Rational Change Request shows RTC Workitem URL

Click to see larger image

Figure 9. Resulting work item URL

Rational Change Request shows RTC Workitem 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
Diagram of two workflows showing state mapping

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 (1.4.0.3 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: http://clmdemo:8082/TlogicIntegration/admin/SyncFramework.html

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
View of launching synchronizer configuration

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 scr_*.

Figure 12. Sync System Change Request type change requests with defects
Display of query to restrict synchronized types

Click to see larger image

Figure 12. Sync System Change Request type change requests with defects

Display of query to restrict synchronized types

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
Display of admin interface to map states

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
Display of interface to start synchronization

Click to see larger image

Figure 14. Log Debug Messages checkbox in the synchronizer

Display of interface to start synchronization

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 severity, summary, and 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
Snippet of annotated log file showing error

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.

Summary

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.

Resources

Learn

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.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=961975
ArticleTitle=Integrate IBM Rational Team Concert and IBM Rational Change
publish-date=02112014