uc.png Real world OSLC using Rational Team Concert

Authors: Glenn Bardwell, IBM Jazz L3,Richard Rakich, IBM Architect/Project Lead
Build basis:Rational Team Concert 4.0

OSLC Open Services for Lifecycle Collaboration (OSLC) is a technology that allows software lifecyle tools to share data. RTC applications communicate via OSLC (Open Services for Lifecycle Collaboration). Why is this relevant to you?

Below is a real world example of Rational's own use of OSLC to integrate customer support data into Rational Team Concert. The project is called Rational OSLC Client Request (ROCR). It is typical of the kind of product integrations that are possible with OSLC.

earchitecture.png

Background

Rational ClearQuest, is a highly configurable bug tracking system. It is used in internally in Rational, to manage Customer Support data APARs and other customer facing assets. Retain is a legacy CRM system used to manage customer data.

ClearQuest integrates with Retain via the Retain bridge. Rational Customer support enters customer names into Retain. Customer names are pulled into ClearQuest via the Retain Bridge, a software interface between Retain and ClearQuest.

Rational CLM (RTC, RQM, RRC, etc) is used internally in Rational to manage source code, defects, enhancements, and other development artifacts.

ROCR requirements

The earlier version of the Rational RTC Escalation record included a customer name, but this name was typed into the Escalation by the author. There was no way to guarantee that the name was the same across all Escalations. This made it difficult to report on, and track issues common to a customer.

In ROCR the requirements were more stringent. The Escalation author was required to select the customer name from a list. The names also couldn't be hard-wired into the ROCR escalation record. That would require too much administrative overhead. There had to be a way to dynamically update RTC with new customer data as it became available.

Solution

Getting Retain data into XML

architecture.png


ROCR uses the the ClearQuest OSLC interface to run queries against ClearQuest. The ROCR team created batch files that run periodically, extract data from ClearQuest and then write the data to XML files.

Getting the XML into RTC

The ROCR team created a new WorkItem type: Escalation. In the Escalation record, the ROCR team added new attributes whose values are read from the web. The ROCR team pointed RTC to a web server that served up the XML.

Getting Retain data into XML

The ROCR team setup a two batch/Perl programs that run periodically and query ClearQuest. Here's how they work.

The first batch file gets the list of products that are available to customers. ClearQuest stores this data in a record type: Product.

Below are a list of the parameters that can be passed to the batch file. The credentials can be passed explicitly or through a named file.

-cquser
The ClearQuest user Id

-cqpassword
The ClearQuest password

-cqprojectarea
The project area is the CQ Schema name.  Default value: CQPAR

-recordtype
The record type to query on.  Default value: Product
Note that it depends on the Lyo OSLC perl library. See Lyo Perl library,

The first step in the script is to log into ClearQuest. The Perl code handles login, ROCR administrators supply the credentials.

my $CQ = Lyo::OSLC::CQ::CM->new;
$opt{cqurl} = 'https://l2l3-cmn-cq.ratl.swg.usma.ibm.com/cqweb/oslc'
$CQ->credentials($opt{'cquserid'}, $opt{'cqpassword'});
$CQ->setBaseURI($opt{'cqurl'});
Once the ClearQuest (CQ) object is created from a URL and credentials, the Perl code runs a query against CQ. Below is the query that extracts the list of product names of from ClearQuest. The code removes duplicates and sorts the results.

my @query = (qq(dcterms:type="Product"));
my $rdf = $cqclient->oslcWhere($opt{'cqprojectarea'}, $opt{recordtype}, $query, \@props);
my $records = $rdf->QueryResults();
foreach my $record (@${records}) {
        if (! (scalar grep $record->{'cq:Product'} eq $_ ,  @prodnames) ) {
            push(@prodnames, $record->{'cq:Product'});
            push(@result, {
                            'Product' => "$record->{'cq:Product'}",
                           });
        }
    }
my @sorted = sort { lc($a->{'Product'}) cmp lc($b->{'Product'}) } @result; # alphabetical sort

Finally the data is written out to an XML file.

    open( my $fh, ">/ROCRProdList.xml" ) or die "cannot open /ROCRProdList.xml: $!";
    my $xml = XMLout(
                     \@sorted,
                     'NoAttr' => 1,
                     'RootName' => 'xml',
                    );
    $xml =~ s/anon/node/g;
    print $fh $xml;
    close($fh);
A second batch file builds a list of customers names. In Rational, customer names are kept in a ClearQuest record called a RETAIN_PMR. The code is similar to the code that read the product list. The record type and the query fields differ.
    my @query = (qq(dcterms:type="RETAIN_PMR"));
    my @props = (
                'cq:customerName',
                'cq:customerNumber',
               );
    my $rdf = $cqclient->oslcWhere($opt{'cqprojectarea'},$opt{recordtype}, $query, \@props);
    my $records = $rdf->QueryResults();
    foreach my $record (@${records}) {
        if (! (scalar grep $record->{'cq:customerNumber'} eq $_ ,  @custnums) ) {
            push(@custnums, $record->{'cq:customerNumber'});
            push(@result, {
                            'customerName' => "$record->{'cq:customerName'} \($record->{'cq:customerNumber'}\)",
                            'customerNumber' => "$record->{'cq:customerNumber'}",
                           });
        }
    }
The batch files create two files, one containing the list of customer products and a second containing the list of customer names and numbers. They look like:

<xml>
  <node>
    <Product>ClearCase</Product>
  </node>
  <node>
    <Product>Rational Team Concert</Product>
 </node>


<xml>
  <node>
    <customerName>RTC Customer</customerName>
    <customerNumber>12345</customerNumber>
  </node>
  <node>
    <customerName>Acme Corp</customerName>
    <customerNumber>67890</customerNumber>
  </node>
</xml>

Serving up the XML

The ROCR team set up Apache Web Server to serve the XML files. To see this yourself, download Apache Web Server. Store the XML data in ROCRProdList.xml in htdocs directory. Point your browser to http://localhost/ROCRProdList.xml into the browser, and you should see the file in the browser. Updating the XML File

The ROCR team set up cron to periodically run the batch files. You can see this also. On windows the at command runs jobs periodically (see at -help from the MS-dos command line), On Linux, the cron command runs jobs periodically.

RTC integration

The ROCR team used RTC Http Value Set Providers to dynamically build content for dropdowns and pickers in the ROCR Escalation record.

See Customization of Work Items in Rational Team Concert, for for more details on RTC customization. The ROCR team created a customized Workitem Type: Escalation. In an Escalation, the ROCR team created two custom attributes: Product Name, and Customer Name. Under Attribute Customization, they created two new HTTP Filtered Value Sets.

rocrproduct.png

com.ibm.rational.escalation.attr.cust.customerName and
com.ibm.rational.escalation.attr.cust.productList.
rocrcustomized.png

The Filtered Value set user interface, provides a mechanism for parsing the XML to extract the relevant fields. Recall the data. Customization
<xml>
  <node>
    <Product>ClearCase</Product>
  </node>
  <node>
    <Product>Rational Team Concert</Product>
 </node>
</xml>

<xml>
  <node>
    <customerName>RTC Customer</customerName>
    <customerNumber>12345</customerNumber>
  </node>
  <node>
    <customerName>Acme Corp</customerName>
    <customerNumber>67890</customerNumber>
  </node>
</xml>
The ROCR team needed the data inside of , and . XPath, provides a way to get that data.

Some background on XPath

Imagine you're a ROCR developer looking trying to determine what values to put in the Attribute Customization. You have a customer XML file. If you think of the XML as a table, where each row is a node, then to describe an arbitrary row in this table, you'd select ./xml/node. An example of a row is:

    Acme Corp
    67890
Now, to extract a the customerName column from the row, you'd select a Column XPath expression of ./customerName, and finally to present that you'd select an Entry label format of ${0}.

The ROCR team used a Value Set Picker to present customer names. There are too many names to list in a dropdown. The product list is smaller, so the ROCR team used a ValueSet Combo.

presentation.png

presentationdetail.png

Putting it altogether, the following shows a ROCR Escalation displaying a product list.

er.png

Related topics: Deployment web home, Deployment web home

External links:

Additional contributors: TWikiUser, TWikiUser

This topic: Deployment > WebHome > DeploymentIntegrating > RealWorldOSLCUsingRationalTeamConcert
History: r3 - 2014-01-13 - 14:40:03 - Main.ralphe
 
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use. Please read the following disclaimer.
Ideas, requests, problems regarding the Deployment wiki? Create a new task in the RTC Deployment wiki project