Introduction to the RequisitePro to Rational Team Concert Connector
Steve Arnold, IBM Rational
Last updated: July 9, 2010
Build basis: Rational Team Concert 2.0.x, RequisitePro 18.104.22.168
This article discusses the purpose and use of version 2 of the Requisite Pro to Rational Team Concert connector, and then walks through how to install and set it up. This connector is an unsupported incubator.
What does the Connector do?
There are three things you can and should do with your requirements. You should use them to drive design and development, drive testing, and drive your planning.
This article describes a Jazz connector that copies requirements from Rational RequisitePro to plan items in 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. First, 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 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 synchronised. You can choose to either synchronise all top-level requirements of a particular kind, or you can choose a view to synchronise. It is also possible to setup multiple synchronizations, so if you wished to synchronise multiple kinds of requirements, then you would simply setup and run several synchronizations.
Download the connector
Download the RequisitePro Connector (ReqProRTCConnector_V2.zip) file from the Rational Team Concert 22.214.171.124 iFix 3 download page, found under the Incubators section.
The zip file includes client and server components referenced later in this article.
What's new in version 2?
The main change was to rewrite the connector to make use of the RequisitePro REST api's. This requires RequisiteWeb to be installed, but provides several big benefits. It allows the connector to be deployed to non-windows jazz servers, and also greatly simplifies the installation process.
Removing previous versions
It is advisable to uninstall previous versions of the connector. Follow these steps to un-install an old version of the connector:
- In the file system remove the RequisitePro connector update site folder from the server directory, and remove the reqproconnector.ini from Jazz Server InstallDir/jazz/server/conf/Jazz/provision_profiles.
- Start the RTC server, then navigate to here https://localhost:9443/jazz/admin/cmd/requestReset and reset the server
- Stop the server, restart it to refresh the plugins, and then stop it again ready to install the new connector.
The old connector is now uninstalled.
Installing the server
Installing the server is a simple process. Unzip the server.zip file found in the ReqProRTCConnector_V2.zip downloaded earlier. You should find a 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 folder com.ibm.uk.reqproconnector.repositorymanager.updatesite to your Jazz server folder InstallDir/Jazz/server
- Copy reqproconnector.ini to InstallDir/jazz/server/conf/Jazz/provision_profiles
Your file system should now look like this:
- Now restart the Jazz server in order to load up the changes.
Setting up and Configuring 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 synchronise to. Secondly you need to setup a syncrhonisation rule.
Configuring the work item type so its ready for synchronizationIn order for the synchronization to work, it's necessary to store the requirement key on the the work item. So you need to create a new field on the work item in order to store the value.
- Right on the project area, and choose Open
- Click on the Process Configuration tab, and then navigate to Project Configuration->ConfigurationData->Work Items->Types and Attributes
- Choose the type you wish to synchronise requirements to in the drop down, then add a custom Attribute, with a name of key, id of key and type of Small String.
- Save the change.
Here is an example of a Story customised to include the Key field.
Setting 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
- Select the connection in the Team Artifacts view. Right click and choose Administer->Synchronization Rules.
- Now create a new External Connection to represent the RequisitePro project:
- Right click on the External Repository Connections in the Synchronization Rules view, and choose New->External Repository Connection
- Specify the name of the connection, the RequisitePro rest connection (e.g. http://reqwebhostname/ReqWeb/Servlet/project/projectname, and login credentials, as well as the target project area. Note that there is a current limitation that the name of the project in the RequisiteWeb catalog must contain no spaces.
The screen should look like this:
- Now you need to set up the mapping between RequisitePro and TeamConcert. In the Synchronization Rule view, right click on the project area and choose New->Synchronization Rule. The steps to setup the rule are as follows:
- Specify a name for the rule
- At the top left of the screen, specify the work item type, the external repository you created earlier, the external manager (RequisiteWeb 7.1) and the requirement type you want to synchronise to.
- Then specify the mapping. At a minimum you must specify FiledAgainst=Team,key=key(make sure you mark the key as the external identifier),Type=RtcType,Summary=Name. Note that the FiledAgainst property, needs to use the CategoryTransformer - so untick the No Transformation (Just Copy) and choose the CategoryTransformer in the dropdown.
- If you have enumerated fields, then map the two fields together, untick the No Transformation (Just Copy) tick box, and add the enumeration mapping into the Value Mapping box
When finished, the synchronization rule should look something like this:
- You now need to configure the permissions for the synchronization client. The client requires Synchronise 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 on the Process Configuration tab, and navigate to Team Configuration->Permissions. Then in the main panel, select Item Connector->Synchronise with external objects and make sure that everyone has permission for this.
Installing the client
To install the client, unzip the client.zip found in the ReqProRTCConnector_V2.zip that you downloaded earlier. Edit the start_reqpro_connector.bat, and update the environment variable to the Jazz client jre bin directory, and ext directory. This must be the jre supplied with the Jazz client.
You then need to download the client jars from Jazz.net (Click Here), and save these in a folder called jpjc in the same directory as the client. Now update the batch file again and set the JAVA_CLIENT_JARS variable to point at the directory holding all the jar files.
Running 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, 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.
I recommend that you create a separate user for use with the connector. The user must have JazzAdmin privileges, and have a developer, build, clearcase connector or clearquest connector client license.
- Then from a command line, run the start_reqpro_conector.bat. This will connect to RequisitePro, and synchronise the requirements with the Jazz Team Server.
- Once you have verified that the connector has worked and copied requirements into the Jazz team Server, then this file should be set to run at frequent intervals. This can be done by going to Control Panel->Scheduled Tasks->Add Scheduled Task, and scheduling the file to run every 15 minutes.
- The reverse synchonisation 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 Synchronise Out....
If requirements changes do not correctly flow between the systems, then 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 unsynchronised, and you can decide which change to accept. To see the unsyncrhonised requirements, click on the rule in the Synchronization View and choose Show Unsynchronised.
You should now have a working bi-directional synchronization of requirements from RequisitePro, to work items in Team Concert.
The connector has the following limitations
- RequisitePro multi-select 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
The RequisitePro to TeamConcert Connector can be used to synchronise requirements with high-level plan items. This means that the project plans have strong traceability to the agreed requirements, and should lead to improved project delivery, and improved customer satisfaction by ensuring that the stated requirements are planned, measured against and delivered. This version of the connector has been re-architected to use the RequisitePro REST api's, thus allowing this to be used on non windows servers, and provide a more robust solution.
About the author
Steve Arnold is a senior technical consultant working for IBM Rational 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. He can be contacted at firstname.lastname@example.org.
© Copyright IBM Corporation 2009. All Rights Reserved.