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
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.
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:
- 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.
- Start the RTC server, then navigate to https://localhost:9443/jazz/admin/cmd/requestReset, and reset the server.-
- 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 ReqProCon_server.zip file included with this article (see the Downloads section), look for the folder called com.ibm.uk.reqproconnector.repositorymanager.updatesite and a file called reqproconnector.ini. Follow these steps to install the server side of the connector:
- Copy the com.ibm.uk.reqproconnector.repositorymanager.updatesite folder to your JazzInstallDir/Jazz/server.
- 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
- 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.
- Right-click on the project area, and choose Open.
- Click the Process Configuration tab, and then navigate to Project Configuration > ConfigurationData > Work Items > Types and Attributes.
- 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
- Save the changes.
Figure 3. Example of a customized Story, including the 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.
- First, select the connection in the Team Artifacts view. Right-click and choose Administer > Synchronization Rules.
Figure 4. Menu option to administer synchronization rules
Now create a new external connection to represent the RequisitePro project:
- In the Synchronization Rules view, right-click External Repository ConnectionsSynchronization, and choose New > External Repository Connection.
- 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
Now you need to set up the mapping between RequisitePro and Rational Team Concert.
- In the Synchronization Rule view, right-click the project area and choose New > Synchronization Rule. Follow these steps to set up the rule:
- Specify a name for the rule.
- 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.
- 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
- 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.
- 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
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.
- To do this, open the project area, click the Process Configuration tab, and navigate to Team Configuration > Permissions.
- 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
Install the client
- To install the client, download and then unzip the ReqProCon_client.zip file from the Downloads section of this article.
- 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.
- You then need to download the client Java Archive (JAR) files from Jazz.net, and save these in a folder called
jpjcin the same directory as the client.
- 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 reqproconnector.properties 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.
- 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.
- 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.
- 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.
- 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
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.
- Rational RequisitePro:
- Learn more about the features and benefits of Rational RequisitePro
- Browse the RequisitePro page on developerWorks for links to technical articles and many related resources. The developerWorks Rational software landing page is also a good starting place.
- Watch one of the Rational RequisitePro demos (scroll down).
- Explore the RequisitePro Information Center.
- Rational Team Concert
- Learn more about the features Rational Team Concert
- Rational Team Concert Information Center
- IBM developerWorks page for Rational Team Concert, with links to many other resources
- Webcast: Using Rational Team Concert in a globally distributed team
- Demo: Dashboards and reports
- Podcast: IBM Rational Team Concert and Jazz
- 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
- Rational Team Concert trial downloads (free):
- Download Rational RequisitePro for a free trial.
- Download these IBM product evaluation versions and get your hands on application development tools and middleware products from Rational®, DB2®, Lotus®, Tivoli®, and WebSphere®.
- Participate in the Using Rational Team Concert discussion forum on Jazz.net.
- Join the RequisitePro forum to ask questions and participate in discussions.
- Join the discussions in other Jazz.net forums.
- Check out developerWorks blogs and get involved in the developerWorks community.