Synchronize requirements between Rational Team Concert and Rational RequisitePro

Use the Jazz Connector to initialize your project plan from your requirements

This article describes a Jazz connector that synchronizes requirements to work items in IBM® Rational Team Concert® so that you can initialize your plan based on your requirements. You will learn how to install the connector and get it up and running in your environment.


Steve Arnold (, Senior Technical Consultant, IBM China

Photo of Steve ArnoldSteve is a Senior Technical Consultant working for IBM Rational software in the UK, where he has worked since 2000. His main areas of expertise are UML design and MDA, plus he has a strong interest in Eclipse and product extensibility.

developerWorks Master author

10 August 2010

Also available in Chinese Portuguese Spanish

What the connector does

There are three things that you can and should do with your requirements: use them to drive design and development, to drive testing, and to drive your planning. The diagram below shows how the roles of project manager, architect and test lead use requirements to accelerate their tasks.

Figure 1. Requirement uses
Reqs form basis for PMs, architects, test leads.

This article describes an IBM® Rational® Jazz™ connector which copies requirements from IBM® Rational® RequisitePro® to plan items in IBM® Rational Team Concert®. The requirements can then be assigned to iterations and decomposed into tasks for the development team to implement. This approach ensures that planning is managed at the requirement level and that the progress of implementing the requirements (normally stories or use case scenarios) can be measured and managed.

The code here makes use of the Jazz connector architecture, which gives several benefits. Firstly it provides a comprehensive mapping framework, so fields in Rational RequisitePro can be easily mapped to fields in Rational Team Concert. Also, the framework provides strong synchronization mechanisms for ensuring that changes are passed successfully between the two systems and for resolving conflicts if they occur.

What's new in Version 2

The main change was to rewrite the connector to make use of the RequisitePro REST APIs. This requires RequisiteWeb to be installed but provides several big benefits. It allows the connector to be deployed to non-Microsoft® Windows® Jazz servers and also greatly simplifies the installation process.

The connector also provides two mechanisms for selecting which requirements should be synchronized. You can choose to either synchronize all top-level requirements of a particular kind, or you can choose a view to synchronize. It is also possible to setup multiple synchronizations, so if you wished to synchronize multiple kinds of requirements, then you would simply setup and run several synchronizations.

Remove previous versions

It is advisable to uninstall previous versions of the connector. Follow these steps to uninstall an earlier version of the connector:

  1. In the file system, remove the RequisitePro connector update site folder from the server directory, and remove the reqproconnector.ini file from the Jazz Server InstallDir/jazz/server/conf/Jazz/provision_profiles.
  2. Start the RTC server, then navigate to https://localhost:9443/jazz/admin/cmd/requestReset, and reset the server.-
  3. Stop the server, restart it to refresh the plug-ins, and then stop it again to be ready to install the new connector.

The previous connector is now uninstalled.

Install the server

Installing the server is a simple process. When you unzip the file included with this article (see the Downloads section), look for the folder called and a file called reqproconnector.ini. Follow these steps to install the server side of the connector:

  1. Copy the folder to your JazzInstallDir/Jazz/server.
  2. Copy the reqproconnector.ini file to JazzInstallDir/server/conf/jazz/provision_profiles.

Your file system should now look like this Figure 2.

Figure 2. Server file system
Jazz server file system showing installed plugin
  1. Now restart the Jazz server to load the changes.

Set up and configure the server and synchronization rules

Now that the server side components are installed, you need to do two things. Firstly you need to configure the work item types you are going to synchronize to. Secondly you need to setup a synchronization rule.

Configure the work item type to be ready for synchronization

In order for the synchronization to work, it's necessary to store the requirement key on the work item. So you need to create a new field on the work item in order to store the value.

  1. Right-click on the project area, and choose Open.
  2. Click the Process Configuration tab, and then navigate to Project Configuration > ConfigurationData > Work Items > Types and Attributes.
  3. In the drop-down menu, choose the type with which you wish to synchronize requirements, and then add a custom attribute with a name of key, ID of key, and type of Small String.
  4. Save the changes.
Figure 3. Example of a customized Story, including the key field
Story work item customized with a key field

Set up a synchronization rule

Now you need to setup the synchronization rule, which is a mapping of the RequisitePro fields to the work item fields.

  1. First, select the connection in the Team Artifacts view. Right-click and choose Administer > Synchronization Rules.
Figure 4. Menu option to administer synchronization rules
Two drop-down menus with selections highlighted

Now create a new external connection to represent the RequisitePro project:

  1. In the Synchronization Rules view, right-click External Repository ConnectionsSynchronization, and choose New > External Repository Connection.
  2. Specify the name of the connection, the RequisitePro REST connection (for example: http://reqwebhostname/ReqWeb/Servlet/project/projectname), the login credentials, and the target project area.

    Note: There is a limitation that the name of the project in the RequisiteWeb catalog must contain no spaces.

The screen should look like Figure 5.

Figure 5. External Repository Connection window
Properties dialog box

Now you need to set up the mapping between RequisitePro and Rational Team Concert.

  1. In the Synchronization Rule view, right-click the project area and choose New > Synchronization Rule. Follow these steps to set up the rule:
  2. Specify a name for the rule.
  3. At the top left of the screen, specify the work item type, the external repository that you created earlier, the external manager (RequisiteWeb 7.1) and the requirement type that you want to synchronize to.
  4. Then specify the mapping. At a minimum you must specify:
    • FiledAgainst: Team
    • Key: key (make sure that you mark the key as the external identifier)
    • Type: RtcType
    • Summary: Name
  5. Notice that the FiledAgainst property needs to use the CategoryTransformer, so uncheck No Transformation (Just Copy) and choose the CategoryTransformer in the drop-down menu.
  6. If you have enumerated fields, then map the two fields together, uncheck the No Transformation (Just Copy) check box, and add the enumeration mapping into the Value Mapping box.

When you are finished, the synchronization rule should look something like Figure 6.

Figure 6. A simple synchronization rule
Shows Type, Property, and Value mapping selections

You now need to configure the permissions for the synchronization client (also see Figure 7). The client requires Synchronize with external objects permission. You can either add the user who will be executing the synchronization to the project or modify the project settings so that all users have this permission.

  1. To do this, open the project area, click the Process Configuration tab, and navigate to Team Configuration > Permissions.
  2. Then, in the main panel, select Item Connector > Synchronize with external objects, and make sure that the selected user or everyone has permission for this.
Figure 7. Project permissions to synchronize with external objects
Selection circled under Item Connections

Install the client

  1. To install the client, download and then unzip the file from the Downloads section of this article.
  2. Edit the start_reqpro_connector.bat file, and update the environment variable to the Jazz client jre bin directory and ext directory.

    This must be the JRE (Java™ Runtime Environment) supplied with the Jazz client.

  3. You then need to download the client Java Archive (JAR) files from, and save these in a folder called jpjc in the same directory as the client.
  4. Now update the batch file again, and set the JAVA_CLIENT_JARS variable to point to the directory that holds all of the Java™ Archive (JAR) files.

Run the synchronization

To run the synchronization, you first need to modify the file with your settings. You can configure how requirements are selected, either by either requirement type or by view. In the supplied file, it is configured for selecting views, with the options for selecting by requirement type commented out.

  1. It helps to create a separate user for use with the connector. The user must have Jazz Admin privileges and have a developer, build, and an IBM® Rational® ClearCase® connector or IBM® Rational® ClearQuest® connector client license.
  2. Then, from a command line, run the start_reqpro_conector.bat file. This will connect to RequisitePro and synchronize the requirements with the Jazz Team Server.
  3. After you have verified that the connector has worked and copied requirements into the Jazz Team Server, set this file to run at frequent intervals by selecting Control Panel > Scheduled Tasks > Add Scheduled Task, and scheduling the file to run every 15 minutes.
  4. The reverse synchronization is handled automatically by the Jazz Team Server. However, to force the synchronization, select the rule in the Synchronization Rule view, right-click, and choose Synchronize Out.

If requirements changes do not correctly flow between the systems, this is probably because the requirement has been modified in both systems in the same synchronization period. In this case, the failing requirements will show up as unsynchronized, and you can decide which change to accept. To see the unsynchronized requirements, click the rule in the SynchronizationView and choose Show Unsynchronized.

Figure 8. The Show Unsynchronized menu option
Option selected on drop-down menu

You should now have working bidirectional synchronization between requirements from Rational RequisitePro and work items in Rational Team Concert.


The connector has the following limitations:

  • Rational RequisitePro multiselect enumeration fields are not supported in the mapping.
  • The name of the project as registered with RequisiteWeb should not contain spaces. This can be worked around by adding a second entry to the RequisiteWeb catalog for use by the connector


You can use the Rational RequisitePro to Rational Team Concert Connector to synchronize requirements with high-level plan items. This means that the project plans have strong traceability to the agreed requirements, which should lead to improved project delivery and improved customer satisfaction by ensuring that the stated requirements are planned, evaluated, and delivered. This version of the connector has been redesigned to use the RequisitePro REST APIs, which means that you can use it on servers other than Microsoft Windows servers.


Client filesReqProCon_client.zip228KB
Server filesReqProCon_server.zip68KB
Connector filesreqproconnector_v2_16Jun_src.zip722KB



Get products and technologies



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

Zone=Rational, DevOps
ArticleTitle=Synchronize requirements between Rational Team Concert and Rational RequisitePro