Using ClearCase triggers to implement ClearCase Bridge capabilities in Rational Team Concert
This article provides information on how to write a ClearCase trigger that will create associations (links) between Rational Team Concert work items and ClearCase data. The ability to create these links from triggers is useful to users not using the ClearCase Remote Client (CCRC) which has built-in bridge support. Sample triggers are provided at the end of the article.
Introduction
Rational Team Concert includes a ClearCase Bridge that creates links between Jazz work items and ClearCase data, enabling users to trace between the code (or other ClearCase artifact) and the work item(s) it implements. Work items can also be linked to other Rational Team Concert artifacts, such as build results, enabling traceability across the development lifecycle.
As of Rational Team Concert 3.0, UI support for the bridge is limited to the Eclipse-based ClearCase Remote Client (CCRC) and the ClearCase SCM adapter UIs. However, it is possible to write a ClearCase checkin trigger that will run regardless of the UI or command line in use to create the same associations as the bridges accessed via the UIs would.
Such a trigger-based method of creating work item links is helpful to those who use the ClearCase command-line or a UI other than the ClearCase Remote Client, such as the native ClearCase client or the Visual Studio IDE, or for those who have a combination of UIs in use.
The trigger approach takes advantage of the Open Services for Lifecycle Collaboration (OSLC) for Change Management (CM), a standard HTTP-based REST API for accessing data in change management systems. The RTC-specific implementation of this standard is called “rtc_cm.” The full specification can be found in Resource Oriented Work Item API 2.0.
ClearCase-specific work item links
Rational Team Concert work items support two types of ClearCase-specific links; ClearCase Activities, for UCM users, and ClearCase Versions, for base ClearCase users. Either type of link may be accessed from a trigger (or other script or program), though access to ClearCase Versions links is available only in Rational Team Concert 2.0.0.2 ifix3 or later.
ClearCase-specific links show up in the Links tab of RTC work items; a work item with ClearCase Versions links is shown below:
Writing a trigger script that uses OSLC
Although the rtc_cm API can be invoked from a number of languages, for scripts it is convenient to use the “cURL” command-line tool to easily generate the HTTP requests. More information on cURL can be found at the cURL home page.
Before any link manipulations can be performed, the script must connect to a Jazz server with a valid user name and password. Examples of how to do this along with more details on what each option means can be found in RTC REST API, which also contains some examples of accessing work item data in general.
The Perl script below is provided for example purposes only; you may need to customize it for your environment; for example, modifying the paths to reflect the location of executables and changing the names of servers and users.
Example trigger for associating work items with UCM activities or base ClearCase versions
For UCM checkins, this trigger finds the UCM activity associated with the file being checked in, and links it to the work item. For base ClearCase checkins, the trigger creates a link between the checked-in version and the work item.
The ClearCase command to create a trigger would look something like:
cleartool mktrtype -c "Trigger to create link from UCM activity to work item" -element -all -postop checkin -execwin "ccperl path-to-trigger/createlink.pl"
ccperl (also known as ratlperl) is a version of Perl distributed with ClearCase.
# # Licensed Materials - Property of IBM # (c) Copyright IBM Corporation 2011. All Rights Reserved. # # Note to U.S. Government Users Restricted Rights: Use, duplication or # disclosure restricted by GSA ADP Schedule Contract with IBM Corp. # # Checkin trigger script to associate a ClearCase UCM activity or base ClearCase # version with a Jazz work item in Rational Team Concert on checkin, using the # work item OSLC interfaces. # # Note that this script is provided as an example and may need further # customization to work in your environment. use URI::Escape; my $ACT2WI = "rtc_cm:com.ibm.team.connector.ccbridge.common.act2wi.s"; my $VER2WI = "rtc_cm:com.ibm.team.connector.ccbridge.common.ver2wi.s"; my $CURL = "c:/curl/curl.exe"; my $CURLOPTS = "-k -L -b c:/cookies.txt -c c:/cookies.txt"; my $HOST = "https://localhost:9443/jazz"; # Prompt for a work item print "nEnter a work item to associate with this checkin: "; my $workitemNum = <STDIN>; chop($workitemNum); my $workitem = "$HOST/oslc/workitems/$workitemNum"; # Log in to the Jazz server system("$CURL $CURLOPTS $HOST/authenticated/identity"); system("$CURL $CURLOPTS -d j_username=user1 -d j_password=user1pw $HOST/j_security_check"); # Checkin sets the CLEARCASE_ACTIVITY environment variable for UCM checkins my $activity = $ENV{'CLEARCASE_ACTIVITY'}; if ("$activity" eq "") { associateVersion($workitem); } else { associateActivity($workitem, $activity); } # # Associate a ClearCase UCM activity with a work item # sub associateActivity { my ($workitem, $activity) = @_; my $illegalString = "IllegalArgument to associateActivity"; if ("$workitem" eq "") { print "$illegalString: No work item for checkinn"; return; } if ("$activity" eq "") { print "illegalString: No activity for checkinn"; return; } return createLink($workitem, $ACT2WI, "activity:$activity"); } # # Associate a base ClearCase version with a work item # sub associateVersion { my ($workitem) = @_; my $illegalString = "IllegalArgument to associateVersion"; if ("$workitem" eq "") { print "$illegalString: No work item for checkinn"; return; } # Checkin sets the CLEARCASE_XPN environment variable my $extendedPathname = $ENV{'CLEARCASE_XPN'}; if ("$extendedPathname" eq "") { print "Environment variable CLEARCASE_XPN not foundn"; return; } return createLink($workitem, $VER2WI, $extendedPathname); } # # Call OSLC interface to create the work item link # sub createLink { my ($workItem, $linkType, $objSel) = @_; # Get the ClearCase universal selector for the object my $uri = getUniversalSelector($objSel); # Only add the link if it isn't already there $properties = uri_escape("$linkType{*}"); my @lines = qx($CURL $CURLOPTS $workitem.xml?oslc_cm.properties=$properties 2>&1); foreach (@lines) { my $line = $_; if ($line =~ /<$linkType rdf:resource="(.*)" oslc_cm:label="(.*)"/>/) { if ("$uri" eq "$1") { return; } } } $objSel =~ s//\/g; my $data = qq("rdf:resource":"$uri", "oslc_cm:label":"$objSel"); my $moreopts = qq(-H "Accept: application/json" -H "Content-Type: application/json"); my $status = system("$CURL $CURLOPTS $moreopts -d "{$data}" $workitem/$linkType"); print "n"; return $status; } # # Get the ClearCase universal selector for a ClearCase object # sub getUniversalSelector { my ($object) = @_; my $illegalString = "IllegalArgument to getUniversalSelector"; my $uri = qx(cleartool describe -fmt %[universal_selector]p $object 2>&1); if ($uri =~ /oid:(.*)@vobuuid:(.*)$/) { my $objUuid = $1; my $vobUuid = $2; $objUuid =~ s/[:.]//g; $vobUuid =~ s/[:.]//g; $uri = 'oid:' . $objUuid . '@vobuuid:' . $vobUuid; } else { print "$illegalString: Cannot compute URI from argument.n"; return; } return $uri; } For more information
- Accessing the rtc_cm OSLC interface
- cURL home page
- cURL examples calling OSLC
- OSLC Change Management specification
Copyright © 2012 IBM Corporation