Integration overview

You can use a different software configuration management (SCM) system with IBM® Rational Team Concert™ rather than using its version control system. There are three ways of integrating another SCM. (For complete information, see Integrating other SCM Systems with Rational Team Concert 2.0.) One way is to link the Rational Team Concert work items to changes in the external SCM. There are linking tools for Subversion and IBM® Rational® ClearCase® software. (For details, see Linking work items to Subversion repositories and Using the ClearCase Bridge to Rational Team Concert.) This article explains how to link the changelists in Perforce to the work items in Rational Team Concert.

About Perforce triggers

Perforce is a software configuration management (SCM) system. The basic operations, such as editing files, are performed in changelists. Perforce triggers are user-written scripts that are called when certain operations are performed, such as the submission of a change.

Some data, such as the user name of the triggering user and the ID of the changelist, will be passed to the scripts in variables, while other data that is not provided in variables can be acquired by using p4 commands and then passed to the scripts. For example, when a changelist is submitted, a Perl program can be executed with arguments that are the user name of the triggering user, the ID of the changelist, and the comments from the changelist. (For more information, see Scripting Perforce: Triggers and Daemons.)

The Rational Team Concert REST API

External systems can create, read, update, and delete the work items in Rational Team Concert through the REST API. For example, those systems can check whether or not work items exist and can update the work items with new data in response to status-changing events in the external systems.

Back to top

Prerequisite software

In the examples in this article, these programs are used on the Microsoft® Windows® operating system. The cURL and Perl are not necessarily restricted to the Cygwin runtime system.

• Perforce:
  • Visual client (P4V)
    • A user named p4tester uses P4V.
  • Web client (P4Web)
    • P4Web runs on port 8080.
  • Server (P4D)
    • P4D runs on port 1666.
• Rational Team Concert 2.0:
  • Client for the Eclipse IDE
    • A user named testuser uses this client. The default password for this example is testuser.
    • A project area named TestProject is created by the user.
  • Server
    • The server runs on port 9443.
• Other
  
  • Cygwin cURL
  • Cygwin Perl

Back to top

A typical use case

This article describes a typical use case that involves two people, a technical lead and a developer, who follow these steps:

1. Create a work item in Rational Team Concert.
   • The technical lead creates a work item and assigns it to the developer (see Figure 1).
   • The developer receives an email notification from Rational Team Concert, which specifies the ID of the work item.

2. Check out and edit files in Perforce.
   • The developer checks out the files and edits them in a changelist.
3. Write the ID of the work item in the Comment field in Perforce.
   • The developer opens the Submit menu by right-clicking on the changelist.
   • In the Submit dialog window, the developer writes the ID of the work item in the Comment field.
4. Submit in Perforce.
   • The developer clicks the Submit button. After the trigger for integrating Perforce and Rational Team Concert data is invoked, the work item and the changelist are updated (see Figure 2, Figure 3, and Listing 1). When the link in the work item is clicked (see "link for changelist:7" in Figure 2), the user's browser shows the updated comment in the changelist.

	
$ p4 change -o 7
...
Change: 7
...
Description:
        This is a test submit.

        <witem>:10

        <a link to a work item>
        https://jazz.yourhost.com:9443/jazz/oslc/workitems/10.xml

Back to top

Implementing the trigger

For a full explanation of how to link changes in other SCMs to the work items in Rational Team Concert, see Integrating other SCM Systems with Rational Team Concert 2.0. In this article, linking a changelist in Perforce to a work item in Rational Team Concert is implemented in two phases: check and update.

The check phase

Here are three steps for the check phase:

1. Extract the ID of the work item.
   • Define the format of the comment required for the trigger to extract the ID of the work item from the comment in the changelist. For example, a pair of a specified tag and the ID of the work item, such as <witem>:10. Using this format, the trigger searches for the ID of the work item in a comment that can be acquired by this command:
     
     p4 triggers -s (the ID of the changelist)
     
     The %changelist% variable that contains the ID of the changelist is passed to the trigger. The trigger should fail if the comment does not conform to the format. For Perl, exit(1); stops the trigger with a failure status.
2. Log in to Rational Team Concert.
   • cURL can be used to be authenticated by Rational Team Concert. When the trigger logs into the Rational Team Concert server, the information for authentication is saved in a cookie file. That cookie file is used in all of the steps that follow.
3. Check whether or not the work item exists.
   • The URL of a work item has this format:
     
     https://(hostname of the Rational Team Concert server):(port number)/jazz/oslc/workitems/(the ID of the work item).xml
     
     
   • From the ID of the work item, the trigger reads the work item by using the Rational Team Concert REST API. The work item exists if the cURL returns data without any error messages, such as this one:
     
     <oslc_cm:status>404</oslc_cm:status>
     
     If the work item does not exist, the trigger should fail and terminate.

The update phase

Here are the three steps for the update phase:

1. Write the link in the work item.
   • A changelist has URLs as described in P4Web User Guide - P4Web URL Reference. This is an example of a URL format:
     
     http://(p4web client):8080/(ID of a changelist)?ac=10
     
     This can be accessed by using P4Web.
     
   • Using the URL format, the trigger stores the link of the changelist in the rdf:resource attribute in a JSON form (JavaScript Object Notification). The label of the link is also set to the oslc_cm:label attribute. In Windows, each inner double quotation mark must be cancelled with a backslash that is within the brace surrounded by double quotation marks in the JSON form.
2. Write the user name or the triggering user and the ID of the changelist in the work item.
   • The user name of the triggering user is stored in the %user% variable.
   • After the %changelist% and %user% variables are passed, the trigger sets the user name of the triggering user and the ID of the changelist to the dc:description attribute in the JSON form. Finally, cURL updates the work item with all of the data in a JSON form.
3. Write the link in the changelist.
   • The data for the changelist is acquired with this command:
     
     p4 change -o (ID of a changelist)
     
     At the end of the Description area, the trigger adds a link to the work item using this format:
     
     <a link to the work item>
https://(hostname of the Rational Team Concert server):(port number)/jazz/oslc/workitems/(ID of the work item).xml
     
     After the modified data is copied into the file, you can modify the data in the changelist with this command:
     
     p4 -u (user name of the triggering user) change -i -u < (file that the modified data is copied into)

How to set a trigger

Use this command to set a trigger:

p4 triggers

The setting must start with a tab space, as in this example:

sample change-submit //depot/... "C:\cygwin\bin\perl.exe C:\cygwin\tmp\p4-rtc.pl %changelist% %user%"

Troubleshooting

• If a license error appears when running p4 commands in a trigger, you might need an additional license for perforce.com.
• If a changelist URL cannot be accessed through p4web, using the -sBD option when starting p4web might work:
  
  p4web.exe -sBD
  
  Caution:
  This is an experimental and unsupported option. For normal environments, the options are described in Starting P4Web.

Back to top

Summary

This article explained the steps for integrating Perforce SCM software with Rational Team Concert. One approach for integration is to link a changelist in Perforce to a work item in Rational Team Concert by using Perforce triggers. When a user submits a changelist in Perforce, that activates the trigger to write a link to the changelist into a field for the related artifact in the work item and also writes a link to the work item in the comment field of the changelist. In the field for discussion in the work item, the trigger can write the data about the changelist, such as the user name of the triggering user and the ID of the changelist, that is stored in variables or that is acquired by using appropriate p4 commands.

Back to top

Acknowledgements

The author thanks Takehiko Amano and Masaki Wakao for technical advice.

Back to top

Download

Information about download methods

Resources

Learn

• Integrating other SCM systems with Rational Team Concert 2.0
  
  
• Linking work items to Subversion repositories
  
  
• Using the Rational ClearCase Bridge to Rational Team Concert
  
  
• Perforce
  
  
• Scripting Perforce: Triggers and Daemons
  
  
• P4Web User Guide - P4Web URL Reference
  
  
• Starting P4Web
  
  
• Rational Team Concert on developerWorks
  
  

Get products and technologies

• Perforce Downloads
  
  
• Rational Team Concert
  
  
• Cygwin
  
  
• Free Rational Team Concert trial downloads
  
  

Discuss

• My developerWorks community
  
  
• Jazz.net forum
  
  

About the author

Ken Kumagai is an IBM software developer for the IBM Rational ClearCase MultiSite team. He works in the Software Development Laboratory in Yamato (YSL), Japan. One of his current interests is how existing systems can work seamlessly with IBM Rational Team Concert and collaboration tools, which are based on IBM Rational Jazz technology by using the Open Services for Lifecycle Collaboration (OSLC). In his spare time, Ken enjoys reading books at the nearest coffee shop.

Rate this article

Comments

Back to top

Table of contents

• Integration overview
• Prerequisite software
• A typical use case
• Implementing the trigger
• Summary
• Acknowledgements
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Rational Team Concert
• Demo: Rational and Jazz
• Webcast: Agile development with IBM Rational Synergy and IBM Rational Team Concert
• Buy: Rational Team Concert

Dig deeper into Rational on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers