Migrating from a ClearCase-ClearQuest integration to a ClearCase-Rational Team Concert integration

Masa Koinuma
Last Updated: January 5, 2012
Build basis: Rational Team Concert 3.0.1

Comparing ClearQuest-enabled UCM and ClearCase Bridge

Both CQ-enabled UCM and ClearCase Bridge provides a powerful integration of change management(CM) system with source control management(SCM) system, and provides a linkage from a CM record to a SCM change-set. For example, CQ-enabled UCM provides a link from a CQ record to an UCM Activity and allows looking up linked object’s information from one system to another. Similarly, ClearCase Bridge provides a link from a Rational Team Concert work item to an UCM Activity and allows customer to trace artifacts from one system to another.

The CQ-enabled UCM provides a tighter integration between a ClearQuest record and an UCM activity than the Bridge. The relation is always one to one, and corresponding object in the other system is created automatically when necessary. It is as if the relation of UCM activity and ClearQuest record is kept transparent as much as possible, so developers see them as a single artifact. For example, GUI provides queries of ClearQuest records instead of UCM activities when a developer starts working on a ClearCase view, and ClearQuest record transitions to a ‘complete’-type state when you deliver an UCM activity, and you can not work on an UCM activity any more when ClearQuest record’s state is in a ‘complete’-type state. One major reason for customers to deploy CQ-enabled UCM is to have governance control. Since ClearQuest record and UCM activity are tightly integrated, the change set information can be tracked from the ClearQuest records.

ClearCase Bridge provides a more flexible integration between a Rational Team Concert work item and an UCM activity. A lot of actions are up to developers and they can link or unlink objects any time. In other words, developers need to be aware that SCM system’s change-set artifact is different from CM systems artifacts. Work items and UCM Activities can have multiple to multiple relationships that help various use-cases beyond what the one-to-one ClearQuest-enabled UCM can provide. For example, you can have separate UCM activities – one for product-fix and one for test-code-fix, and bind them to single work item. In terms of process governance, you can also create a query with any filters to look up SCM artifacts through work items. But it relies on developer’s effort to associate UCM activities with Rational Team Concert work items.
One other difference from ClearQuest-enabled UCM is that the ClearCase Bridge is an integration technology based on Eclipse client. Developers can simply set up plug-ins – one from ClearCase, and the other from Rational Team Concert – into an Eclipse shell, and there is no additional configuration required for an administrator. You can read Tip: Installing the ClearTeam Explorer to Rational Team Concert to understand how to set up the ClearCase Bridge environment.

Screenshot of work item Links tab. Associated ClearCase UCM activity is listed and you can navigate to the change-set by Open button.

In order to make it easy to distinguish, the ClearCase Bridge is called Rational Team Concert-enabled ClearCase UCM (or simply RTC-enabled UCM) later in this document.

Tips for migration to RTC-enabled UCM

There are a couple of techniques to apply to your RTC-enabled UCM environment in order to fill in the difference from CQ-enabled UCM project. Some of them are actually valuable to not just customers who would like to migrate from CQ-enabled UCM project, but also those who would like to apply more seamless integration of ClearCase deployment as SCM system, with Rational Team Concert.

Suspending ClearQuest-enabled UCM

When you migrate from CQ-enabled UCM to RTC-enabled UCM, you have to switch CM system from ClearQuest to Rational Team Concert. The RTC-enabled UCM does not allow you to associate UCM activities with RTC work item if the UCM project is CQ-enabled. We recommend you to start with a new ClearCase UCM project. The process looks like the following:

1. create a new UCM project in ClearCase system, without enabling ClearQuest
2. set up Rational Team Concert
3. manage all the change requests, defects, tasks in Rational Team Concert work item
4. associate UCM activities with Rational Team Concert work item via the Bridge link

However, there might be situations that you cannot start with a new UCM project but have to keep using existing UCM project which is already CQ-enabled. One way to keep using the UCM project that is currently CQ-enabled but migrate to RTC-enabled is to suspend CQ integration by this command

  cleartool chproject -crmenable user-dbname -suspend project-selector   

This command will temporarily marks the ClearQuest-enabled UCM as “integration suspended” which allows developers to continue to work in ClearCase without ClearQuest.

Auto association of UCM activity

As described above, developers need to associate ClearCase UCM activity with Rational Team Concert work item. And you can associate the artifacts automatically by setting current work item in your Eclipse client. Here is a typical work-flow when your team uses auto-association.

Setup: All developer’s Eclipse client has CCRC or ClearTeam Explorer and Rational Team Concert in a single instance. Please refer Tip: Installing the ClearTeam Explorer to Rational Team Concert to set up the environment.

1. A Rational Team Concert work item is filed by a developer, a tester, or a project manager
2. Project manager will review the work items and assign them to developers
3. In the developer’s environment, he or she will open My Work view in the Eclipse client. The view is available in Rational Team Concert’s Work Items perspective by default.
4. The developer can find work items that are assigned to himself or herself in the My Work view. He or she can pick one and right-click.
5. Select Set as Current Work Item in the pop-up menu, and you can verify it is set in the right bottom status area of the Eclipse workbench. Note that you can alternatively create a work item query and find items assigned to you, then set it as a current work item.
6. Switch to ClearCase perspective, and navigate to a ClearCase view in the CCRC interface.
7. Check out a file or Add to source control
8. In the Check out dialog (or Add to source control dialog ), and press New… button in the Select activity section.
9. Give activity’s headline and ID appropriately and press OK
10. Now the UCM activity is created and it is automatically associated to the work item that was chosen as a current one. When you open the Work Item editor, the UCM activity is displayed in the Links tab.

    
    Screenshot of current work items indicator at the right bottom of workspace. The newly created UCM activity is automatically associated to curent work item.

Note that the auto-association is available with CCRC 7.1.2 or later ( including ClearTeam Explorer 8.0 ) , and Rational Team Concert 3.0 or later.

Query on dashboard – Find Work Items that have UCM activity links

One of the popular features of Rational Team Concert is the dashboard which visualizes various aspects of your project’s live data in a single web page. You can take advantage of it to monitor developer’s work in your project. In order to ensure UCM activity’s linkage to Rational Team Concert work item, you, as an administrator, would like to set up a dashboard widget that displays work items that does not have UCM activity reference. Here are steps to set it up:

1. Set up a work item query by:
   1. In Team Artifacts view, navigate to <your project area> > Work Items
   2. Right click there and select New > Query…
   3. Choose one of the link in the Query Editor to start editing
   4. Press Add Conditions… button
   5. In the Add Conditions… dialog, check Show links, and select ClearCase Activities
   6. Select a drop-down next to ClearCase Activities and choose either exist or, does not exist
   7. Specify name of the query, add other conditions, and save the query

   

2. Add a widget to your dashboard page by:
   1. In a web browser, navigate to your dashboard page
   2. Click Add widget link at the right top
   3. Navigate to Work Items < Work Items and Add the widget
   4. Select a query you just created, and save

Please refer to Rational solution for Collaborative Lifecycle Management 3.0.1 Information Center for general information about dashboard and widget.

Process Enforcement by ClearCase triggers that calls the OSLC APIs

The CQ-enabled UCM provides rich process enforcement and auto-state transition capability. For example, setactivity command ( from either GUI or CLI ) does not allow you to set a UCM Activity if its ClearQuest record is in completed state. You may want to achieve this type of integration with RTC-enabled UCM.

OSLC is an industry-standard HTTP-REST API for lifecycle tools such as Rational Team Concert, and you can access, edit Rational Team Concert work item via HTTP-REST service. One of the possible solutions here is to develop a script that manipulates Rational Team Concert work item via the RTC OSLC interface and run the script as a ClearCase trigger. For example, in the above setactivity’s case, you can develop a script that looks up linked work item for the UCM activity, check the work item state, and reject setting activity if the linked work item is resolved.

You can read Using ClearCase triggers to implement ClearCase Bridge capabilities in Rational Team Concert to learn some of the basics to make use of OSLC in a ClearCase trigger script.

Sample trigger script that calls OSLC

Here is a sample Perl script that is intended for ClearCase deliver operation to check if all UCM activities have associated Rational Team Concert Work Items. Like the referred document above, the script also uses the cURL command-line tool to easily generate the HTTP requests.

  #  # Licensed Materials - Property of IBM  # (c) Copyright IBM Corporation 2012. All Rights Reserved.   #  # Note to U.S. Government Users Restricted Rights:  Use, duplication or  # disclosure restricted by GSA ADP Schedule Contract with IBM Corp.  #  use strict;  use URI::Escape;    # link type for activity-work item relation  my $ACT2WI = "rtc_cm:com.ibm.team.connector.ccbridge.common.act2wi.s";    my $CURL = "c:/curl/curl.exe";  my $CURLOPTS = "-k -L -b c:/cookies.txt -c c:/cookies.txt --header "OSLC-Core-Version: 2.0" --header "accept: application/xml"";    my $HOST = "https://localhost:9443/jazz";  my $USER = "user1";  my $PASSWORD = "user1pw";  my $PROJECTAREA = "Project Area Name";    # Log in to the Jazz server  system("$CURL $CURLOPTS $HOST/authenticated/identity");  system("$CURL $CURLOPTS -d j_username=$USER -d j_password=$PASSWORD $HOST/j_security_check");    # retrieve activities to deliver  my @activities = split(/ /, $ENV{CLEARCASE_DLVR_ACTS});    # find work item URL for a project area  my $workItemURL = findProjectAreaContext($PROJECTAREA);  die "Cannot find Project Area : ${PROJECTAREA}." if (not defined $workItemURL);    # verify every activity has work item link  foreach my $activity ( @activities ) {      next if ($activity =~ /^deliver./ or $activity =~ /^rebase./ );      my $workItem = findLink($ACT2WI, 'activity:' . $activity);      die "Cannot find workItem for ${activity}." if (not defined $workItem);  }    #  # Call OSLC interface to look up the work item link  #  sub findLink {      my ($linkType, $objSel) = @_;        # Get the ClearCase universal selector for the object      my $uri = getUniversalSelector($objSel);        # Only add the link if it isn't already there      my $properties = uri_escape("${linkType}="${uri}"");        my @lines = qx($CURL $CURLOPTS ${workItemURL}?oslc.where=${properties} 2>&1);      foreach my $line (@lines) {          if ($line =~ /<rdfs:member rdf:resource="(.*)"/>/) {              return $1;          }      }      return ;  }    #  # Call OSLC interface to look up Project Area context  #  sub findProjectAreaContext {      my ($projectAreaName) = @_;        my $illegalString = "IllegalArgument to findProjectAreaContext";            my $contextURL = '';      my @lines = qx($CURL $CURLOPTS $HOST/oslc/workitems/catalog 2>&1);      foreach my $line (@lines) {          if ($line =~ /<oslc:ServiceProvider rdf:about="(.*)/services.xml">/) {              $contextURL = $1;          } elsif ($line =~ /<dcterms:title rdf:parseType="Literal">$projectAreaName</dcterms:title>/) {              return $contextURL;          }      }      print "$illegalString: Cannot find a project area from argument.n";      return;  }    #  # 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;  }  

The script can be added as pre-op trigger for deliver_start operation by this command.

  > cleartool mktrtype -ucmobj -all -preop deliver_start -execwin "ccperl work_item_link_checker.pl"    -nc trtype:work_item_link_checker@<your UCM project VOB tag>