Chapter 6. Integrations

The chapter is divided into two main parts: the ClearQuest integrations and the Jazz-based product integrations. The chapter starts with a brief introduction to product integrations and the advantages they provide to an organization. The ClearQuest integration section starts with a description of the ClearQuest packaged (built-in) integrations with Rational products such as ClearCase and RequisitePro, and with third-party products like Microsoft Visual Source Safe and Microsoft Project. The ClearQuest section continues with a description of building new integrations. We explain the various methods of integrating applications with ClearQuest and give some examples.

The second part of the chapter focuses on integrations of the Jazz-based products, Rational Quality Manager and Rational Team Concert. We discuss integrations between one Jazz product and another Jazz product and continue with integrations with Rational legacy products such as ClearQuest, ClearCase, and RequisitePro. An explanation is provided on the REST API that allows business partners and customers to build integrations to third-party applications.

6.1. Introduction

Most companies use various tools for creating software and to manage the process of change. Using ClearQuest, ClearCase, and RequisitePro is a common example. The fact that several tools are used in the process, and that each tool has its own repository in which to store data, may have a negative effect on process management. When a team is working on a specific change, they would like to know the source of the change, the reason for the request, who has requested it, and who will be affected by it. All of this information exists without integrations between the tools, so why bother integrating them?

Each time you work in one tool and you look for information in another tool, you are required to have access to that tool, which means having a license, sometimes a local installation, and some level of knowledge of the tool itself. This means investing in enablement and in licensing. When the tools are integrated, some of that pain is removed and you have direct access to data in your working environment. The level of integration also defines the value that you gain from establishing the integration.

For quality assurance purposes and the ability to generate quality reports that require data from several tool repositories, the integration between the tools will improve significantly the organization’s ability to get value from the tools.

Tool integrations can help close the gap between separated teams such as development and testing, business analysts and development, development and operations. Integration allows one team to have direct access to the data of another team. This seamless integration helps smooth the process and increases cooperation of the practitioners.

Integrating a change management application with other lifecycle management applications can help an organization on several levels:

• The practitioner’s level

Integration increases the efficiency of the practitioner’s work and allows easy access to data, quick transition from one tool to another, and a user-friendly experience.

• The management level

Integration provides a clear view of information and process status, although data spans over several repositories. It also enables better governance of the business process.

• The quality assurance level

Integration provides the ability to generate quality metrics from several repositories and on several organizational levels.

From an architectural point of view integration can be performed on one or more of the following levels: data, tools, and process. Figure 6.1 illustrates an architectural view of the three levels of integration between development (IBM Rational tools) and operations (IBM Tivoli tools).

• Data level

Data-level integration allows applications to share data, exchange data, or view data. The Rational Quality Manager to ClearQuest Connector integration is a good example of two applications exchanging data in a synchronized manner.

• Process level

Process-level integration allows an organization to create a single process that spans several tools and environments. The integration between Tivoli Service Request Manger (TSRM) and ClearQuest is an example of how the process in the development organization is unified with the process in the operations organization.

• Tools level

Tools-level integration allows users direct access from one tool to another, or allows one application to perform actions in another application. One example is the Rational Test Lab Manager launching Rational Functional Tester to execute automated test scripts.

Figure 6.1. Integration architecture levels

But integrations also have disadvantages that we need to consider. The integration between two tools usually depends on the version of the tools, so we are limited to a specific version of each. When we need to upgrade a tool, we usually also have to upgrade the tools integrated with that tool and sometimes even set up the integration again. If you plan to move your repository to a newer server, the process is more complex and requires careful planning.

When you plan the backup procedure, make sure the integrated repositories are backed up at the same time; otherwise when restoring the database, the integration can be out of sync.

Some integrations require additional administrative and maintenance effort. For example, a process that synchronizes data between two repositories should be treated like an additional application that needs to be maintained.

6.2. ClearQuest Integrations

ClearQuest integrations are divided into two main categories. The first category is integrations provided by Rational that you can implement by installing a package or packages and following some configuration instructions. The second category includes integrations that you create using tools and techniques or that you develop with one of the programming tools made available by Rational, such as the ClearQuest Application Program Interface (API) and the Representational State Transfer (REST) API.

6.2.1. ClearQuest Packaged (Built-in) Integrations

You can integrate Rational ClearQuest with other software applications by adding the required Rational ClearQuest packages to an existing schema. The package will add to the schema the required entities that build the integration, such as fields and hooks and in some cases new record types.

Some Rational ClearQuest integrations are independent integrations that require adding only the appropriate package to the ClearQuest schema. Other integrations are dependent integrations that require adding one or more packages in a specific order and may also require additional configurations of Rational ClearQuest and the integrated application.

It is important to note that not all ClearQuest integrations can be applied to the Web client; therefore, fields, forms, reports, scripts, and other functionality added to the Rational ClearQuest client for Windows, UNIX, and Linux by an integration package may not be available through the Web client. Examples of integrations that do work with the Web client include UCM and RequisitePro. Integrations that do not work over the Web include Microsoft Visual Source Safe.

6.2.1.1. ClearQuest Independent Integrations

The following integrations are independent integrations. Note that you can use the same installation process for all independent integrations. For more information on how to add independent integration packages to your ClearQuest schema, see ClearQuest help > Managing change and releases > Integrating Rational ClearQuest with other products > Rational ClearQuest integration packages > Adding independent integrations.

The following are the independent integrations:

• IBM Rational ClearCase and Rational ClearQuest

This integration allows the developer to associate one or more Rational ClearQuest change requests with one or more Rational ClearCase artifact versions (during check-in). We would like to emphasize that this is a base ClearCase (non-UCM) integration. The change set information that is created during the association of the checked-in versions and the ClearQuest records is copied into the ClearQuest field. A hyperlink is also created in the ClearCase version that points to the ClearQuest record ID. So, from either tool’s point of view, you can see the associated data without having to access the other tool’s data store. This means there is also no authentication required into ClearCase to access the change set data.

The required package is ClearCase.

• IBM PureCoverage and Rational ClearQuest

This integration allows you to submit code coverage data to a Rational ClearQuest database and track it. Developers can submit a defect directly from the PureCoverage result log.

The required package is PQC (an acronym for Purify, Quantify, and Coverage).

The PurifyPlus Installation and Getting Started Guide includes instructions for setting up the ClearQuest integration for each ClearQuest client type.

• IBM Purify and Rational ClearQuest

This integration allows you to submit data to a Rational ClearQuest database and track it. Developers can submit a defect directly from the Purify result log.

The required package is PQC.

The PurifyPlus Installation and Getting Started Guide includes instructions for setting up the ClearQuest integration for each ClearQuest client type.

In Figure 6.2 you can see how a ClearQuest defect is submitted from an error in Rational Purify.

Figure 6.2. Submitting a ClearQuest defect from Rational Purify

• IBM Quantify and Rational ClearQuest

This integration allows you to submit performance data to a Rational ClearQuest database and track it. Developers can submit a defect directly from the Quantify result log.

The required package is PQC.

The PurifyPlus Installation and Getting Started Guide includes instructions for setting up the ClearQuest integration for each ClearQuest client type.

• Your e-mail system and Rational ClearQuest

This integration enables Rational ClearQuest to communicate with users through their e-mail systems.

The required package is E-mail.

6.2.1.2. ClearQuest Dependent Integrations

The following integrations are dependent integrations. A dependent integration requires the installation of one or more additional packages and possibly additional configuration steps. The order in which the packages are installed is important.

For more information and instructions for installation and setup of the dependent integrations, see ClearQuest help > Managing change and releases > Integrating Rational ClearQuest with other products > Rational ClearQuest integration packages > Adding dependent integrations. This help page contains links to each integration help page.

The following are the dependent integrations:

• IBM Administrator and Rational ClearQuest

This integration associates IBM projects with Rational ClearQuest databases. A common IBM project is required to integrate ClearQuest with RequisitePro and ClearQuest with TeamTest. The package adds the field Project which is common in the integrated tools and is required to establish the integration.

The package required is the Repository package.

For more information go to the “Adding dependent integrations” help page and click on the link “Adding an IBM Administration integration.”

• IBM Rational ClearQuest Project Tracker and Rational ClearQuest

This integration allows you to exchange project data between the two systems. It allows the creation of a ClearQuest record from tracker actions and synchronized data between tasks in Microsoft Project and records in ClearQuest.

For installation and detailed setup information see ClearQuest help > Managing change and releases > Integrating Rational ClearQuest with other products > Rational ClearQuest integration packages > Adding Rational ClearQuest Project Tracker integrations.

For information on the integration usage and use cases see ClearQuest help > Managing change and releases > Integrating Rational ClearQuest with other products > Using Rational ClearQuest with Project Tracker (PDF).

• IBM RequisitePro and Rational ClearQuest

This integration associates RequisitePro requirements with Rational ClearQuest records. It can be used in more than one way. To set up the integration you need to install the Repository and RequisitePro packages and enable the record types you need to integrate. The next step is performed using the RequisitePro administration. You need to add properties of type ClearQuest Integrations to each requirement type that you want to integrate with ClearQuest. The last step is performed from the Rational Administrator. Select the common RA project and define the integration properties.

One use case is when an enhancement request record is captured in ClearQuest. The workflow continues until the request is approved; once the request is approved in ClearQuest, the relevant requirement in RequisitePro is updated and linked to the ClearQuest record. In this way you establish traceability between the requirements and the requests.

The second use case is when an approved requirement record in RequisitePro is linked to a ClearQuest change request record that will govern the implementation process of that requirement.

Combining the two use cases, you have full traceability from the stakeholder request to the requirement to the change work item.

For information on how to add the Rational RequisitePro and Rational ClearQuest integration, go to the “Adding dependent integrations” help page and click on the link “Rational RequisitePro and Rational ClearQuest integration.”

Also see the help in Let’s Go Rational RequisitePro and in Rational Administrator.

Required packages are Repository and RequisitePro.

• IBM TeamTest and Rational ClearQuest

This integration allows you to submit defects found through TeamTest to Rational ClearQuest databases and to track them.

For more information see ClearQuest help > Managing change and releases > Integrating Rational ClearQuest with other products > Rational ClearQuest integration packages > Adding an IBM TeamTest integration.

• IBM Unified Change Management (UCM) and Rational ClearQuest

This integration links Rational ClearCase UCM projects and activities to records in Rational ClearQuest. It is probably the most used integration among ClearQuest implementations. When applying this integration, the UCM activity (which physically lives in the ClearCase data store) is represented as a ClearQuest record (that is UCM-enabled), and it allows linking the ClearCase versioned artifacts to the ClearQuest activity containing the change instructions. Figure 6.3 shows a ClearQuest record that stores the ClearCase Change Set information. This allows you to know for each change request what artifact versions were changed to resolve the change.

Figure 6.3. The ClearCase Change Set displayed in the ClearQuest record

For more information see ClearQuest help > Managing change and releases > Integrating Rational ClearQuest with other products > Rational ClearQuest integration packages > Adding a ClearCase UCM integration.

Required packages are AMStateTypes, UCMPolicyScripts, and UnifiedChangeManagement. The package BaseCMActivity, which adds an Activity record type, is optional.

The UCM integration from ClearQuest to ClearCase does not copy change set data as the base ClearCase integration. Instead, an ActiveX client plug-in allows ClearCase commands to be executed from the ClearQuest client on Windows. So developers have direct access to ClearCase from ClearQuest, which is a huge benefit. For platforms that don’t support ActiveX, the change set is displayed at runtime. This means that the user does have to authenticate once to the ClearCase system to present the change set, or perform other exposed ClearCase actions.

• Microsoft Visual Source Safe and Rational ClearQuest

The required package is Visual Source Safe.

This integration associates Visual Source Safe versioned artifacts with Rational ClearQuest records. It is similar to the base ClearCase and ClearQuest integration. Figure 6.4 shows the Source Safe tab in a ClearQuest record with the versioned artifacts that were changed to resolve this change request.

Figure 6.4. Visual Source Safe integration in the ClearQuest Windows client: the VSS change set is displayed in the ClearQuest record.

For more information and setup instructions see ClearQuest Help > Managing change and releases > Integrating Rational ClearQuest with other products > Adding a Microsoft Visual Source Safe integration.

• Rational Build Forge and Rational ClearQuest

In order to integrate Rational Build Forge with ClearQuest you need two packages. The DeploymentTracking package supports the deployment approval process, and the BuildTracking package enables traceability between the build and deployment phases.

While these two packages are not specific to the Build Forge integration, they are used by the integration to create and update the build records in ClearQuest. This integration requires you to add Build Forge environment variables that tell Build Forge how to log in to ClearQuest in order for the integration to update the ClearQuest build records.

For more information on this integration, how to set it up, and use cases, we suggest the following white paper:

Duer, Kristofer, “Integrating Build Forge with ClearQuest,” IBM White Paper, www-01.ibm.com/support/docview.wss?uid=swg27015041, 2009 (accessed February 24, 2011).

• Rational Quality Manager and Rational ClearQuest

This integration is described in section 6.3, “Jazz Products Integrations.”

• Rational Team Concert and Rational ClearQuest

This integration is described in section 6.3, “Jazz Products Integrations.”

• IBM Tivoli Provisioning Manager (TPM) and Rational ClearQuest

If your organization is using ClearQuest and IBM Tivoli Provisioning Manager (TPM), you can integrate the two products. The integration bridges development and operations, associating your release with the location of an IBM Tivoli Provisioning Manager server, which helps better govern the release and deploy process. You can use the TPM package functionality to add a URL link to the Tivoli Provisioning Manager Web user interface to your deployment record, providing simple user interface integration between Rational ClearQuest and Tivoli Provisioning Manager.

To create the integration apply the TPM package to your schema. The package creates three state-based record types: BTBuild, DTApproval, and DTDeployment. The package creates the following stateless record types: DTEnvironmnet, DTRelease, DTRoles, TPMServer, and TPMServer. In addition the package makes use of the eSignature, NotesLog, and UCM packages.

6.2.2. Creating New Integrations with ClearQuest

When you plan to integrate ClearQuest with another application, you should carefully examine and define the needs. Based on the requirements you will select the integration method. You have several methods of integration:

• Data exchange through importing and exporting records

• E-mail to exchange data using the E-mail Reader service

• API (ClearQuest includes several API libraries that can be used to integrate it with other applications)

• Web services

In the next sections we shall describe these integrations and provide some examples.

6.2.2.1. Import and Export

This integration is appropriate only when we need to exchange data with another application or data source, and if the required data update rate is not high. For example, if you need to import part numbers once a month or even once a day, this can be a good solution. To export and import data from the ClearQuest database you can use the ClearQuest Import Tool and ClearQuest Export Tool utilities. Because these utilities do not have a command-line interface and can be operated only via the GUI interface, we think they are useful for one-time operation, such as the initial import from an old system or adding data after schema changes. For integration we need a utility that can be operated automatically with tools such as Windows AT scheduler or UNIX Cron.

Note that before version 7.0 the ClearQuest Import Tool and ClearQuest Export Tool utilities were stand-alone utilities. Since version 7.0 these utilities are incorporated in the ClearQuest Eclipse client, and the import and export utilities can be used only from the Eclipse client. They are activated from the file menu as shown in Figure 6.5.

Figure 6.5. Exporting and importing records from the ClearQuest Eclipse client

The mode of import is defined in the ClearQuest Eclipse client in the following way: Select Windows > Preferences and open ImportTool. Figure 6.6 shows an example of the default preferences. Also note that the default directory, c: emp, can be changed on the ClearQuest > Advanced preferences page.

Figure 6.6. Setting the import records preferences in the ClearQuest Eclipse client

For more information on importing data, configuration of the ClearQuest Import Tool, and the format of the import file, see ClearQuest help > Developing schemas with the Rational ClearQuest Designer > Importing and exporting data > Importing data into Rational ClearQuest. Also see section 7.3.5, “Importing Initial Data” in Chapter 7, “Disciplines, Part 2.”

6.2.2.2. E-mail Reader

The E-mail Reader is a service that reads formatted e-mails from a specific e-mail box, parses the e-mails, and performs an action in the ClearQuest database. E-mails should be well formatted; otherwise the parser will reject them. You can extend an application so that it will send an e-mail to the E-mail Reader and perform the following operations:

• Submit a new record

• Modify an existing record

• Change the state of a record

The mail can include field names and their values to be updated.

Using the E-mail Reader as an integration tool has advantages and disadvantages.

The advantages are that it is easy to use and to configure, and it can be applied to many applications.

The disadvantages are that the integration is unidirectional—from an external application to ClearQuest. The sender does not get a confirmation that the e-mail was processed. The integration is not very stable; for example, if there is an error, the recovery process is manual; the administrator has to examine the log file and take corrective action or notify the submitter by e-mail.

Here is an example of using the E-mail Reader for integration: A company has teams developing in Windows using ClearCase/UCM and a ClearQuest integration, and teams developing in UNIX using CVS and ClearQuest Web. They have integrated CVS with ClearQuest so that artifact versions are included in the ClearQuest record. For that they wrote a CVS check-in trigger that sends an e-mail to the E-mail-Reader mailbox with the values to modify.

This trigger in CVS sends an e-mail upon check-in to the E-mail Reader e-mail address. They used the action Modify to add the file name and the file version to a specific field in the ClearQuest defect record.

The E-mail Reader is configured by executing the following application:

<Installation Directory>RationalSDLCCommonmailreader.exe

Figure 6.7 shows the E-mail Reader application with one E-mail Reader mailbox configured: Book:scrum (Book is the ClearQuest repository name and scrum is the ClearQuest user database name).

Click on Add... to add another mailbox or click on Properties to view and modify the selected mailbox properties. After clicking on Add... a wizard will guide you to provide the SMTP and POP server addresses (in many cases they are the same) as well as the e-mail address and login for the user to log in to the POP3 server. We strongly suggest creating a new dedicated user for the E-mail Reader.

Figure 6.7. Configuring the E-mail Reader

The next step is to define the e-mail handler (the options are ClearQuest and RequisitePro). Select ClearQuest and click Configure... The wizard page is shown in Figure 6.8.

Figure 6.8. Configuring the E-mail Reader: selecting the ClearQuest handler

The wizard requires you to provide the following information: ClearQuest repository, ClearQuest user database, user and password to log on to the ClearQuest database; one or more record types that actions will be performed on; and a default action and default field for each record type. We suggest when you create the e-mail that you do not use the default action and field and always explicitly define the action and field in the e-mail. This will be discussed later in the e-mail format section.

In the second tab, Service Information and Options, fill in the log file path. It is not mandatory but highly recommended as it can help in solving problems in case they occur. Also the error notification e-mail is recommended; in this way the ClearQuest admin can address problems immediately as they occur. Figure 6.9 is an example of a trace log file and the admin error notification e-mail.

Figure 6.9. Configuring the E-mail Reader: setting service information and administrator options

After the E-mail Reader is configured, you need to start the E-mail Reader service. In the control panel > Services open the Rational ClearQuest Mail Service. Configure the logon account, set the type to Automatic, and click the Start button.

The e-mail sent to the mailbox must be well formatted as in Listing 6.1.

Listing 6.1. E-mail Format for the E-mail Reader

---

Subject: <record type> <action> <record ID>
Body:
    [<fieldname>:]< field value>
    [<fieldname>:]< field value>
    {[<multiline_fieldname>:] This is an example of a field value
      for a field whose data type is a multiline text field.
      It requires braces.
    }

---

E-mail messages must be in ASCII text only; HTML, MIME encoding, and attachments are not supported by the Rational E-mail Reader.

Figure 6.10. is an example of an e-mail sent to the E-mail Reader POP3 e-mail address [email protected]. The record type is Defect and the record is BHALM00001982. The action to perform on that record is Assign; the e-mail body includes the values for the fields Owner and Priority.

Figure 6.10. Configuring the E-mail Reader: example of e-mail format

Detailed instructions for how to configure the E-mail Reader can be found in ClearQuest help > Administering > Administering ClearQuest > Administering the E-Mail Reader.

6.2.2.3. Creating Integration with Perl and BASIC API

The well-known BASIC and Perl API can be used either from within hooks in the schema or from an external program. Such a program can access an external application database, check for status, read the values of some table columns, and update ClearQuest records with those values. In a similar way the program can take data from the ClearQuest database and update records of an external application database, or perform actions on ClearQuest records based on field values in the external database.

When using the API in an action hook, we assume that the user has performed an action and we want to synchronize with or update another application with the changed data. In most cases this is the real use case—we are updating the integrated application whenever a change occurs. But in some situations we want to verify whether an operation was performed, for example, when the due date is approaching. In these situations we shall have to use an external program utility that is not dependent on user actions.

Another disadvantage of creating integrations from hooks is that it slows down the user. It takes some time to perform the integration, and if it is more than a second, the user will experience it as slow application performance.

The code in Listing 6.2 is an example of how to log in to ClearQuest from an external BASIC program.

Listing 6.2. Importing a Record from an Excel File

---

' Remember to add ClearQuestOLEServer as a reference to your VB project
' to access the ClearQuest OAd* object types below
' Remember to add the clearquest.bas module to your VB project
' to access the AD_* constants

Dim oSession As Session
Set oSession = CreateObject("CLEARQUEST.SESSION")
oSession.UserLogon "user", "password", "DB_Name", _
AD_PRIVATE_SESSION, "DB_set"

---

The code in Listing 6.3 is an example of how to log in to ClearQuest from an external Perl program. Note that the number of parameters passed to the session method UserLogon() is not the same in BASIC and Perl, and the session_type parameter is not required in Perl.

Listing 6.3. ClearQuest Logon—Perl

---

use CQPerlExt;
use Env;

#  Get  a CQ session
my $CQsession = CQPerlExt::CQSession_Build();
$CQsession->UserLogon("user","password","DB_Name","DB_set");

---

The following is an example of an integration that we have built for a customer:

The customer needed their ClearQuest defect-tracking system to recognize all devices stored in their ERP system so that the tester would be able to select the tested device from a closed choice list, to prevent typing errors. Because their product included many devices, each one having many configurations, and devices could be purchased from several vendors, a daily update was required. The solution was to have the ERP system export the list of devices with the properties of each device to an electronic data sheet (Microsoft Excel). The export from the ERP system is done nightly and the file is saved to a shared directory in the server. A ClearQuest Perl utility that runs nightly reads the data sheet and updates the Device stateless records.

The Windows AT scheduler executes this Perl utility nightly one hour after the ERP export utility is started.

A few explanation notes:

• The utility queries the ClearQuest database. If a record exists, it is updated; if the record does not exist, a new record is created.

• Note that the stateless record type has two fields as unique key; see how the key is constructed to get the entity.

Listing 6.4. ClearQuest Import Script—Perl

---

# Purpose:  Update the Device records with data from file
#           If record does not exist create new record.
# Input  :  Excel file - location and name are hard-coded in the script
#           All cells must have values. The program exists on empty row.
#           CQ database name and user login are hard-coded
# Output :  Operation log to stdout.
# Execution: cqperl Import_device.pl

use CQPerlExt;
use Env;
use strict;
use Win32::OLE qw(in with);
use Win32::OLE::Const 'Microsoft Excel';
my $EntityObj;
my $DevicePN, $MemoryPN, $MemConfig, $MemVersion;

$Win32::OLE::Warn = 3;                    # die on errors...

my $session= CQPerlExt::CQSession_Build();
#  Replace user/db values on next line.
$session->UserLogon("user","password","connection","database");
my $Excel = Win32::OLE->GetActiveObject('Excel.Application')
    || Win32::OLE->new('Excel.Application', 'Quit'),
my $Book = $Excel->Workbooks->Open("P:\Bench\Data\Devices.xls");

# We use the first worksheet, columns 1 through 4.
my $Sheet = $Book->Worksheets(1);
# First row includes headers
my $row=2;
while (1 == 1){
# - - - -  Get the Device for edit ( CQ record ) - -
  $DevicePN = $Sheet->Cells($row,1)->{'Value'};
  $MemoryPN = $Sheet->Cells($row,2)->{'Value'};
  $MemConfig = $Sheet->Cells($row,3)->{'Value'};
  $MemVersion = $Sheet->Cells($row,4)->{'Value'};

#  we stop reading when we encounter an empty row
 last  if ($MemoryPN eq "" || $DevicePN eq "");
 if ( dev_exist ( $session, $MemoryPN ,  $DevicePN ) == 1 ) {

# - - - - Construct the CQ Unique key from the two fields
  my $ukey =  $MemoryPN . " " . $DevicePN ;
  print "++++++ Device exists ++++++ update Entity $ukey  ";
  $EntityObj = $session->GetEntity("Device", $ukey );
  $session->EditEntity( $EntityObj, "Modify" );
#           - - - -  Enter the field to CQ - - - - -
  $EntityObj->SetFieldValue("MemConfig" , $MemConfig );
  $EntityObj->SetFieldValue("MemVersion" , $MemVersion );
 }
 else {
  print "++++++ NO device in CQ  ++++++ Build new Entity ";
  $EntityObj = $session->BuildEntity("Device");
  $EntityObj->SetFieldValue("DevicePN", $DevicePN  );
  $EntityObj->SetFieldValue("MemoryPN", $MemoryPN  );
  $EntityObj->SetFieldValue("MemConfig", $MemConfig );
  $EntityObj->SetFieldValue("MemVersion", $MemVersion );
 }
   my $result = $EntityObj->Validate();
   if ($result) {
      $EntityObj->Revert();
    print "Error: $result ,  in row: $row  ";
   }
   else {
      $EntityObj->Commit();
    print "Record  successfully Modified from line $row  ";
   }
 print " ";
 $row++;
}
CQPerlExt::CQSession::Unbuild ($session);
$Book->Close;


sub dev_exist {
 my ( $session, $MemoryPN ,  $DevicePN ) = @_;
 my $sql_query = "select Controller from Device where
            Memory_PN = '$MemoryPN'  AND  Device_PN = '$DevicePN' ";
 my $sql_result = $session->BuildSQLQuery($sql_query);
 $sql_result->Execute();
 if ( $sql_result->MoveNext() == $CQPerlExt::CQ_SUCCESS) {
     return 1;
 }
 else {
     return 0;
 }
}

---

The previous examples showed how to connect to ClearQuest from an external application. You can connect from a ClearQuest hook to an external database to perform various operations such as running a query to verify data consistency, updating a table column with data from ClearQuest, or retrieving data to update ClearQuest records. This will allow you create bidirectional integration.

The following code is an excerpt of a hook to perform a lookup on external databases not under IBM Rational ClearQuest control:

set objConn = CreateObject("ADODB.Connection")
set objRs = CreateObject("ADODB.Recordset")

REM --- Supply connection string and open connection
objConn.ConnectionString = "DSN=prio;uid=xxxx;pwd=yyyy;database=
prio;"
objConn.Open

The full hook example can be downloaded from the following source:

Drexler, Michael, “Hook to Perform Lookup on External Databases Not under IBM Rational ClearQuest Control,” IBM developerWorks, www.ibm.com/developerworks/rational/library/4388.html, 2004 (accessed February 24, 2011).

Another way of using the BASIC API is via the ActiveX control. Use of ActiveX controls applies only to the Rational ClearQuest for Windows client.

The ActiveX control provides a way to incorporate any registered ActiveX control into a form. For example, you might use an ActiveX control to access and update an external database. You write the initialization record script that runs when the form that contains the control is opened and the action record script that runs when a user initiates an action (such as Submit), or the action is completed or reverted.

The ClearQuest and Base ClearCase integration uses an ActiveX control to establish the integration.

The ClearQuest API reference manual contains detailed information on the architecture and the methods that can be used for integration: ClearQuest help > Reference > API Reference.

6.2.2.4. Rational CM API

The CM API provides one unified Java API for access to both Rational ClearQuest and Rational ClearCase. This capability to use the same library to access two products provides a significant advantage for customers that use both products. In addition, this library extends the WVCM (Workspace Versioning and Configuration Management) API, which is a standard Java API for configuration management.

Having an API allows you to develop a Java program that will access ClearCase, ClearQuest, and external applications to exchange data and perform other actions. For example, the integration between IBM Tivoli Service Request Manager (SRM) and ClearQuest is implemented using the CQ CM API JNI (Desktop) provider.

Figure 6.11 demonstrates how the products are evolving to use the CM Library to connect to the repository. ClearCase Remote Client (CCRC) uses the CM library to connect to the Web server over HTTP. ClearQuest Web uses the CQ CM API WAN (Network) provider to connect to the ClearQuest core that connects via ODBC to the repository. You can also write your integration with ClearCase or ClearQuest core using the CC/CQ CM API interfaces.

Figure 6.11. Usage of the CM Library: client’s interaction with the CM Server and the repositories Courtesy Yuhong Yin

It is important to note that in release 7.1.x for ClearQuest CM API, only the JNI desktop provider is officially supported. Our focus here is on the Customer Integration client component, so for creating a new integration using the CM Library at this release HTTP is not supported (as in CCRC) and JNI should be used.

The CM API programming model comes from the WVCM standard. A client application is started by generating a provider. A provider object connects a single user on the client to one or more servers. A server consists of a collection of resources of different types. Resources

• Live in repositories

• Have locations so that clients can uniquely address the repository

• Have a set of type-specific properties, such as version number or field content

• Optionally have content, such as an attachment

• Support a type-specific set of operations that involve interaction with the server and are identified in the interface by beginning with the word do

Clients access resources on the server by using strongly typed proxies to

• Read/write resource properties

• Read/write resource content

• Apply an operation to a resource

Figure 6.12 shows the relationship of the provider and the proxies on the client and the resources on the server.

Figure 6.12. Client’s interaction with resources on the server

The code in Listing 6.5 is an example of a method that uses the CM API to shows a list of all records. Note how a provider is created, then a record proxy is built, then wanted properties are defined, and finally the operation doReadProperties is used to read records.

Listing 6.5. CM API example

---

static void showRecord(String location) throws Exception {

    CqProvider provider = (CqProvider) ProviderFactory
            .createProvider(CQ_ONLY_PROVIDER_CLASS, g_callback);

    CqRecord record = provider.buildProxy(CqRecord.class, location);

    PropertyRequest wantedProperties = new PropertyRequest
            (CqRecord.LEGAL_ACTIONS.nest(CqAction.DISPLAY_NAME),
             CqRecord.ALL_FIELD_VALUES
            .nest(CqFieldValue.VALUE
                 .nest(CqFieldValue.VALUE,
                       CqFieldValue.FIELD_DEFINITION
                           .nest(CqFieldDefinition.IS_SYSTEM_OWNED))));

    record = (CqRecord)record.doReadProperties(wantedProperties);

    StringBuffer buf = new StringBuffer("Fields... ");

    for (CqFieldValue field: record.getAllFieldValues())
        if (!field.getFieldDefinition().getIsSystemOwned())
            buf.append("  " + field.getName() + " = "
                            + field.getValue() + " ");

    buf.append(" Legal Actions...   ");

    for (CqAction action: record.getLegalActions())
        buf.append(action.getDisplayName() + ", ");

    showMessageDialog(null, buf.toString(), location,
                                    INFORMATION_MESSAGE);

    provider.terminate();
    System.exit(0);
}

---

For more information see ClearQuest help > Extending product function > Programming with CM API and ClearQuest help > Tutorial > CM API tutorial.

6.2.2.5. RESTful Change Management API

The HTTP-based REST API that is compliant with Open Service for Lifecycle Collaboration (OSLC) allows creating, modifying, and querying work items from non-Java clients. In addition to direct modification and query functionality, the API also exposes complete HTML components that allow searching and creating work items.

Adhering to the OSLC specification lets you write clients that will work with any OSLC-compliant implementation of the Change Management API, including Rational ClearQuest.

To learn more about the ClearQuest OSLC REST API visit

Padgett, Samuel, “ClearQuest OSLC CM REST API,” https://jazz.net/wiki/bin/view/Main/RcmRestCmApi, December 7, 2010 (accessed February 23, 2011).

More information about OSLC can be found at OSLC Change Management: http://open-services.net/bin/view/Main/CmHome.

From the ClearQuest Web client you can create a REST URI template. A wizard will assist you in creating URI templates that can be used to integrate ClearQuest Web with other Web applications.

To run the wizard:

1. Click the New button, and select New REST URI.

2. Fill in the required fields and click the Create button. The REST URI template is created.

You can edit the template by adding field values, username, and password.

The following URI line is an example of a template created with the wizard. Note that the double curly brackets {{Enter}} are placeholders for data that you should provide.

http://sak09.mega.ibm.com/cqweb/restapi/SAKDev/DMLM/RECORD/{{recor
dId}}?format=HTML&recordType=ALMActivity&action=Activate&fieldsXml
=<Field><Name>FailedInBuilds</Name><Value><![CDATA[{{Enter}}]]></V
alue></Field><Field><Name>FixedInBaselines</Name><Value><![CDATA[{
{Enter}}]]></Value></Field>&autoSave=true&loginId={{loginid}}&pass
word={{password}}&noframes=true

For more information see ClearQuest Help > Managing change and releases > Using your Rational ClearQuest Web client > Creating REST URIs to log on and perform common tasks.

6.2.2.6. Other Integration Types to ClearQuest

The following are examples of integrations to ClearQuest created by customers that take advantage of open technology to create a solution to integrate with ClearQuest:

• Web services

This solution uses Web services to create a nonhuman integration with ClearQuest. The following link is a paper that shows the use of SOAP and Web services for integrating a testing tool within a ClearQuest hook:

Jalammar, “Invoking a SOAP Web Service through Hooks,” www.ibm.com/developerworks/forums/thread.jspa?threadID=189932, January 9, 2008 (accessed March 3, 2011).

• XML

This is a TCP socket-based service layer on ClearQuest that enables platform-independent clients to execute ClearQuest commands via XML. The solution documentation and download are available from “cqxmlintf—ClearQuest XML Interface,” http://code.google.com/p/cqxmlintf/, October 2008 (accessed February 24, 2011).

6.2.3. Third-Party Integrations to ClearQuest

Some third-party vendors and system integrators have developed integrations with ClearQuest to improve their offerings:

• HP Mercury Test Director and Quality Center integration to ClearQuest

This integration allows users using HP’s test management tools to report defects in ClearQuest.

• ClearVision Subversion integration to ClearQuest

This integration is bidirectional, meaning users can also record ClearQuest information against the Subversion version history.

• VersionOne and ClearQuest

This integration creates defects in VersionOne based on defects in ClearQuest. Using this integration your organization can manage and triage defects reported by customers and promote them to VersionOne once you determine a fix is necessary.

• An IBM internal project has developed an integration between SAP Solution Manager and ClearQuest to improve the change management process in SAP deliveries.

The previous examples are only a few of the many third-party integrations that exist in the market.

If you need an integration to an application and it is not available, you can either develop it using one of the techniques that we have described, or you can contact Rational Services or one of the Rational partners that provide such a service.

6.3. Jazz Products Integrations

Jazz includes built-in integrations to several applications that are provided by Rational, and you can install and use them. In addition, you can develop your own integrations to external applications.

In the next sections we shall describe the Rational Quality Manager integrations and the Rational Team Concert integrations to be followed by a section on the Jazz integration architecture and how to build a new integration.

6.3.1. Rational Quality Manager Integrations

Rational Quality Manager (RQM) and Rational Test Lab Manager (RTLM) include the following built-in integrations: ClearQuest, RequisitePro, DOORS, test automation tools, software inventory and automation tools, Rational Team Concert, and Rational Requirements Composer.

The following sections describe these integrations.

6.3.1.1. ClearQuest Connector

The Rational Quality Manager to ClearQuest Connector allows synchronizing between records in ClearQuest and work items in Rational Quality Manager. The synchronization rules define the mapping of the objects to be synchronized, such as fields, the values of pick lists, and the states. Whenever a record changes in one system, the Connector service reads the changes and updates the equivalent record in the second system. For example, if a ClearQuest user changes the defect state to Resolved and adds data to the Resolution field, the Connector will pick up the changes and according to the synchronization rules change the state of the defect work item in Rational Quality Manager to Resolve and will add the data from the ClearQuest Resolution fields to the Jazz Discussion field. Note that the state names and the field names are not the same, but the sync rule mapping is what enables the Connector service to copy the correct value to the correct field. The diagram in Figure 6.13 shows the interaction between the Connector service, the ClearQuest and Rational Quality Manager applications, and the synchronization rules data.

Figure 6.13. Jazz to ClearQuest Connector service: Connector service interaction with the integrated applications

The following steps describe the general creation stages of the integration:

1. Download the ClearQuest Connector from Jazz.net; note that the Connector is under Rational Team Concert downloads (and not Rational Quality Manager). Also note that the Connector is not available for Jazz Express version servers.

2. Install the Connector on the selected server.

3. Add the package JazzInterop to the ClearQuest schema. The package comes with the Rational Quality Manager installation.

4. Enable the ClearQuest record type that will be synchronized to this package.

5. Create a special ClearQuest user and give it the SQL Editor privilege.

6. Edit the properties to match your environment in the file:

<ClearQuest Connector installation directory>gatewaycqconnector.properties

7. Use the Rational Team Concert client to create a new repository connection. The dialog form is shown in Figure 6.14.

8. Enter the Rational Quality Manager server information and then click Finish.

9. Ensure that the user in the Authentication section in the dialog has the same name as the user that was created in ClearQuest.

10. Open the Jazz Project area, and in the Process Configuration include Item Connectors in Permitted actions for the role.

11. Create a new External Repository Connection in Jazz repository connection > Administrator > Synchronization Rules, and provide the InterOpGateway connection information.

12. Import the synchronization rules.

Figure 6.14. Creating a ClearQuest connection to a Jazz repository: defining the Jazz URI and the authenticated user

13. Modify the synchronization rules and create additional rules as required.

14. In the Advanced Properties of the Rational Quality Manager Jazz Server Administration set the correct values in Item Interoperation. Figure 6.15 shows an example of that section.

Figure 6.15. Configuring the Jazz to ClearQuest Connector: setting the Interoperation properties in the Jazz server administration

15. Start the integration process by running

<Connector Install Dir>jazzconnectorsgatewayserver.startup.bat

See the detailed instructions for building the integration and synchronization rules in the Rational Team Concert online help: Integrating > Rational Team Concert and Rational ClearQuest > Configuring and using the Rational ClearQuest Connector.

Most of the operations required to set up the ClearQuest Connector can now be accomplished with a Web-based setup wizard. Once you install and start the ClearQuest Connector Gateway, the wizard can be accessed with a Web browser at the URL http://hostname:8081/cqconnector/setup.

Here is some additional reading and information on the Connector:

IBM Rational, “Rational Team Concert 2.0,” https://jazz.net/downloads/rational-team-concert/releases/2.0?p=news#cq-connector, June 25, 2009 (accessed February 23, 2011).

Mehra, Maneesh, “Setup ClearCase & ClearQuest Connectors in a ClearQuest-Enabled UCM Environment,” http://jazz.net/library/article/30, July 2009 (accessed February 23, 2011).

6.3.1.2. ClearQuest Bridge

The ClearQuest Bridge integration to the Jazz work item enables you to work with a Rational Team Concert or Rational Quality Manager Web client while the work items are stored in the ClearQuest database. Unlike the ClearQuest Connector integration, there is no synchronization involved, so there is no duplication of data. The disadvantage is in creating reports, as the reporting tool needs to retrieve the data from two repositories. This solution is good for customers having a ClearQuest implementation for work item (or just defect) management that would like to move to Agile development with Rational Team Concert or manage their test effort with Rational Quality Manager, yet do not want to divide their defect data into several repositories.

The following steps describe the creation stage of the integration:

1. In the Jazz Web, select Admin > Server Administration > Advanced Properties.

2. Scroll down to the ClearQuest Bridge section and click Edit.

3. Set the ClearQuest parameters as required. Make sure that the Enable ClearQuest Bridge WebUI is set to “true.” See an example in Figure 6.16.

4. Save the change.

Set ClearQuest as “friend,” as described in the following steps:

1. In the Jazz Web, select Admin > Server Administration > Cross-Server Communication.

2. Fill in the fields in the form as required. You can give any value to the Title and the OAuth Secret fields.

3. Mark the Trusted check box.

4. Click Request Access.

Figure 6.16. ClearQuest Bridge integration definition

The result is added to the Server Friends List. Figure 6.17 is an example of a ClearQuest server defined as a friend.

Figure 6.17. Add a ClearQuest server to Friends List

The last phase is to set up a link between the Rational Quality Manager project area and the ClearQuest database, as described in the following steps:

1. In the Jazz Web, select Admin > Project Area Management.

2. Click on the project area that you want to link.

3. In the Links section click Add.

4. Select the ClearQuest server.

5. Click Finish.

6. Click Save.

The ClearQuest user database will appear under the Service Provider column as demonstrated in Figure 6.18.

Figure 6.18. ClearQuest as service provider to a RQM project area

Now when you enter Rational Quality Manager as a user and hover over the Defect icon, you will see new options as shown in Figure 6.19.

Figure 6.19. Defect section in RQM after Bridge integration with ClearQuest was established

Clicking on Create Defect in “CQ user DB” will open the ClearQuest Submit form of the default record type.

When you click on Go to Defects on “CQ user DB” it will open the ClearQuest Web client.

If you want to create work items in Jazz, click on Go to Work Items....

When the tester reports a defect during test execution, a ClearQuest form will be opened and the ClearQuest defect will be associated with the result log. When a user hovers over the Defect link in the result log, the record data will pop up, as shown in Figure 6.20.

Figure 6.20. Opening a ClearQuest defect from the RQM test results log

Clicking on the link will open the ClearQuest form of that record.

The ClearQuest Bridge provides viewlets for

• Listing queries/records registered as ClearQuest Favorites

• Displaying the results for a specified ClearQuest query

• Showing Rational Team Concert work items and their links to ClearQuest records

For more information see Rational Team Concert Help > Integrating > Rational Team Concert and Rational ClearQuest > Configuring and using the Rational ClearQuest Bridge.

6.3.1.3. RequisitePro

The Rational Quality Manager and RequisitePro integration allows you to import requirements from a RequisitePro project. For each imported requirement a work item of type Requirement will be created in Rational Quality Manager. The Rational Quality Manager and RequisitePro requirements are synchronized, automatically or manually. Figure 6.21 shows the definition of the RequisitePro Web server in Rational Quality Manager system properties. The RequisitePro Web components must be installed and the Web server must be configured and running.

Figure 6.21. RequisitePro server definition in RQM Jazz server

To import requirements, hover over the Requirements icon and select Import Requirements. Figure 6.22 shows the Rational Quality Manager screen.

Figure 6.22. Import requirements from RequisitePro to RQM

For more information see Rational Quality Manager Help > Integrating > Rational Quality Manager and Rational RequisitePro.

The requirements can be associated with the test plan and with test cases. When testers create test cases, they associate the requirement(s) (in the Requirement section of the test case). These requirements are the reason for creating the test case and one of the basic sources of information when writing the test design and test procedure. When the Requirement link in the test case is selected, the RequisitePro Web displays the requirement. The integration to the test plan is identical. In this way the test manager can generate a report of all requirements that are not covered with test cases for a specific release. It also allows traceability from requirements to test cases to defects to get you closer to a full ALM implementation.

6.3.1.4. IBM Rational DOORS

When you integrate IBM Rational Quality Manager with IBM Rational DOORS, you can export requirements from Rational DOORS directly into the Requirements view in a test plan or test case. This integration is similar to the Rational RequisitePro integration described in the previous section.

For more information see Rational Quality Manager Help > Integrating > Rational Quality Manager and Rational DOORS.

6.3.1.5. Rational Test Automation Tools Integrations

Rational Quality Manager and Rational Test Lab Manager are integrated to the following Rational test automation tools:

• Rational Functional Tester (RFT)

• Rational Performance Tester (RPT)

• Rational AppScan

The integrations allow testers to execute automated scripts from a Rational Quality Manager test suite or test case.

You need to install and configure the integration by running the adapter that sets up the integration between Rational Quality Manager and the test automation tool. For each Rational test automation tool there is a different adapter; we shall describe in brief the Rational Functional Tester adapter.

The first step is to configure the adapter. Run the adapter program from Start > Program Files > IBM Software Delivery Platform > IBM Rational Functional Tester > Adapter to Rational Quality Manager > Configure Adapter.

The Rational Functional Tester Adapter dialog box opens. Fill in the Jazz server URL and the login and password of a user with access to Rational Quality Manager; the list of available project areas will appear. Select one and provide a name to the adapter. See an example in Figure 6.23.

To activate the adapter hit the Start Adapter button. In the tab Adapter Console you can see the connection status and additional messages.

Figure 6.23. Functional Tester adapter to Quality Manager

The next step is connecting the Rational Functional Tester script to a Rational Quality Manager script. This is done in Rational Quality Manager in the following way:

1. Go to Construction > Create Test Script.

2. In the Create Test Script dialog, enter the name of the script (this is the Rational Quality Manager script, but we recommend giving it the same or a similar name as the Rational Functional Tester name).

3. Select Functional Tester as Type.

4. Select “Use test resource from a shared location.” Figure 6.24 is an example of creating a functional test script in Rational Quality Manager.

Figure 6.24. RFT integration to Rational Quality Manager: importing an automated script

5. To select the script from the test resource, click on Browse.

6. In the dialog that opens, browse and locate the test script file in the shared directory. Note the extension of the file. Select the file and click OK.

7. The last step is to add the script to a test case. Now when you execute the test case the adapter will copy the script to the Rational Functional Tester machine and execute it.

For additional information see Rational Functional Tester Help > Integrating > IBM Rational Functional Tester and Rational Quality Manager.

6.3.1.6. Build Forge

You can integrate IBM Rational Build Forge with IBM Rational Quality Manager to define and run projects that build and package software from Rational Quality Manager. This allows easy setup of the machines in the test lab for easy execution of integration and system tests.

You must have the Rational Test Lab Manager (RTLM) installed with available licenses and permission set.

For more information see Rational Quality Manager Help > Integrating > Rational Quality Manager and software inventory and automation tools > Rational Quality Manager and Rational Build Forge.

6.3.1.7. Rational Quality Manager and STAF STAX

Software Testing Automation Framework (STAF) is a framework that improves component reuse and automation in test environments. It is an open-source multiplatform framework for reusable components such as services for resource management, logging, and monitoring. Software Testing Automation Framework Execution Engine (STAX) is an XML-based execution engine implemented as an external STAF client. STAX automates the workflow of test cases and test environments.

These integrations allow the Rational Test Lab Manager to manage the test lab processes and execute automated test scripts on remote lab machines, collect results, and display logs on the Rational Quality Manager client. You need to install STAF and STAX on the Rational Quality Manager server and to install STAF on each test agent machine.

For more information and for installation and configuration instructions see Rational Quality Manager Help > Integrating > Rational Quality Manager and software inventory and automation tools > Rational Quality Manager and STAF STAX.

6.3.2. Rational Team Concert Integrations

Rational Team Concert can be integrated with other applications. We can classify those integrations as

• Integration with Jazz-based applications such as Rational Quality Manager or Rational Requirements Composer

• Integration with Rational legacy products such as ClearCase and ClearQuest

• Integration with third-party applications such as Subversion (SVN)

• New integrations creation with the API

The technology used for the integration differs, but the roadmap is to use the REST API. In the next sections we shall describe some of those integrations.

6.3.2.1. Rational Team Concert and Rational ClearCase

Rational Team Concert includes a ClearCase Connector that supports flexible interoperation between Rational Team Concert source control using the ClearCase Synchronizer and the ClearCase Importer. The ClearCase Connector also supports associations between Jazz work items and Rational ClearCase UCM activities using the ClearCase Bridge.

• Using the ClearCase Connector for Rational Team Concert source control

The Connector supports two integration methods. The synchronizer is a bidirectional synchronization between ClearCase and Rational Team Concert. This allows organizations that use both ClearCase and Rational Team Concert to synchronize versioned artifacts.

The ClearCase Importer is a unidirectional importing tool to import ClearCase/UCM and base ClearCase files and folders to Rational Team Concert source control. This allows teams to gradually move from ClearCase to Rational Team Concert using legacy assets by importing small portions of the assets each time.

• Using the ClearCase Bridge to Rational Team Concert

Rational Team Concert includes a ClearCase Bridge that supports associations between Jazz work items and Rational ClearCase UCM activities. The integration allows you to integrate ClearCase source control with Rational Team Concert so that you can use work items and other change management functionality and continue using source control in ClearCase.

6.3.2.2. Rational Team Concert and Rational ClearQuest

The Rational Team Concert and ClearQuest integrations are identical to the Rational Quality Manager and ClearQuest integration that was described in section 6.3.1, “Rational Quality Manager Integrations,” as they are both based on the Jazz server.

This is as good a place as any to compare the two integration types: Connector and Bridge.

The Connector integration duplicates data. The same defect exists in ClearQuest and in the Jazz server (Rational Team Concert or Rational Quality Manager) but the defects have different IDs and possibly other fields that are not synchronized. Duplication of data is considered risky as it is possible that at a specific time the two records will not have the same data. Another known issue is the stability of the synchronization; unsynchronized records may be in the queue and the administrator is required to manually force the synchronization from the Rational Team Concert client.

Figure 6.25 is an example of the list of unsynchronized records as displayed in the Rational Team Concert client.

Figure 6.25. Rational Team Concert to ClearQuest Connector: synchronization status

The big advantage is the reporting. You can create queries and reports by extracting data from a single repository. Various defect reports can be created from both Rational Quality Manager and ClearQuest using the internal reporting utilities, without the need to use a tool (such as IBM Rational Insight) that can access two repositories. See Chapter 9, “Metrics and Governance,” for an additional discussion of reporting.

The Bridge integration uses the OSLC technology to create a link from one tool to another. The advantage is that there is only one record where the data exists and no synchronization is required. There is only one ID for each defect, which eliminates confusion and mistakes.

The disadvantage is that the end user response time is higher (slower), and some users are very sensitive to performance issues. Another disadvantage is the reporting. It is harder to generate reports when the data is in two repositories; tools like Rational Insight are required to derive reports that include data from both Rational Team Concert and Rational ClearQuest.

6.3.2.3. Subversion (SVN)

Rational Team Concert enables Subversion users to take advantage of Rational Team Concert source control and work items to collaborate more effectively when working with a Rational Team Concert community.

Two styles of collaboration are supported:

• You can import the contents of a Subversion repository to one or more Rational Team Concert source control components.

• If you install a Subversion client for Eclipse into the Eclipse instance that supports Rational Team Concert, you can link Subversion revisions to work items.

Teams that use Rational Team Concert source control and Subversion can use either or both of these capabilities.

6.3.2.4. Build Engines

The Jazz technology platform provides support for the automation, monitoring, and awareness of a team’s builds. The following generic build-related items are stored in the Jazz repository and support the build process:

• Build definition: defines a build, such as a weekly project-wide integration build

• Build engine: represents a build system running on a build server

• Build request: represents a request to run a build

• Build result: represents the output from a build

While Jazz users can make use of the build items incorporated in Jazz Build Engine, they can also use other build engines such as IBM Rational Build Forge or CruiseControl. When you set up a build that does not use the Jazz Build Engine, you need to create build definition and build engine objects in Rational Team Concert.

For more information see RTC Help > Managing change and releases > Building with Jazz Team Build > Jazz Team Build setup variation.

Also see “Team Build Examples” on Jazz.net; select TWiki > Main Web > BuildMain > BuildExamples.

6.3.2.5. Other Integrations

The following is a list of the available integrations to Rational Team Concert organized by category:

• Build and process automation

IBM Rational Build Forge

Hudson

CruiseControl

Maven

• Collaboration

IBM Lotus SameTime

IBM Lotus Quickr

IBM Lotus Connections

GoogleTalk

Microsoft SharePoint

Skype

• Defect tracking

IBM Rational ClearQuest

BSD Group—RTC Adaptor for HP QualityCenter

cm-logic—JazzConnect for JIRA

• IDEs and development

Eclipse

IBM Rational Application Developer

IBM Rational Software Architect

Microsoft Visual Studio IDE

• Modeling, code generation, and asset reuse

IBM Rational Rhapsody

IBM Rational Software Modeler

IBM Rational Asset Manager

• Project management and governance

IBM Rational Project Conductor

IBM Rational Method Composer

QSM

WebLayers

Black Duck

• Quality management and security testing

IBM Rational Quality Manager

IBM Rational Software Analyzer

• Requirements management and requirements definition

IBM Rational DOORS

IBM Rational Requirements Composer

IBM Rational RequisitePro

iRise

Ravenflow

• Version control

IBM Rational ClearCase

Subversion

Git

CVS

To learn about each of these integrations visit the Rational Team Concert Integrations page:

IBM Rational, “Rational Team Concert Integrations,” jazz.net/projects/rational-team-concert/integrations/ (accessed February 24, 2011).

6.3.3. Building a New Jazz Integration

This section describes how to build integrations to Jazz work items. In version 1.0 the work item Java API was presented and it is still supported. In version 2.0 the focus is on the work item REST API.

6.3.3.1. Jazz Integration Architecture (JIA)

The goal of the Jazz Integration Architecture (JIA) is to enable diverse tools to be used together, providing an integrated experience to their users.

At the center of JIA is the Jazz Team Server (JTS). The JTS provides the Jazz Foundation Services (JFS) that enable groups of tools to work together.

The main elements powering much of JIA are

• Standard RESTful APIs

• Standard resource definitions

• Reusable building blocks

• Specifications

The API and resource definitions enable participating tools to easily share data. The reusable elements speed the development of new projects and the adoption of existing tools, and the specifications enable better integration of, and navigation between, the user interfaces of the various tools.

The tool exposes its data and services through a resource-oriented Web service called RESTful Web Services.

A REST API provides three key things:

• Stable URLs for the tool data resources

• Documented representations for those data resources

• A protocol and operations for manipulating those data resources based on standard HTTP methods

Figure 6.26 on the next page is a schematic visualization of the OSLC services that will be exposed to the Jazz repository.

A detailed description of JIA can be found in the Jazz Community Site; select Projects > Jazz-foundation > Jazz-integration-architecture.

6.3.3.2. Rest API

This section describes the Resource Oriented Work Item API 2.0. The API allows you to get, create, modify, and query work items using standard HTTP methods, allowing integrations with minimal requirements for the clients. The API adheres to the OSLC CM specification.

Here are some things that can be done with the API:

• Load work items in different formats such as JSON, XML, ATOM, HTML, and in different levels of granularity.

• Update work items by modifying the JSON or XML representation and storing it back.

• Create work items by obtaining an HTML creation dialog module.

• Create work items by posting their JSON or XML representation to a factory URL.

• Add or remove links.

• Query work items (full text and structured queries).

Figure 6.26. RTC REST API and OSLC services Courtesy Edward J. Gentry

For example, if you want to get the title, state, and severity of a work item whose ID equals 27, you can use the following call:

https://<your-jazz-server-name>:9443/jazz/oslc/workitems/27.json?
 oslc_cm.properties=dc:title,rtc_cm:state,oslc_cm:severity

The return result is demonstrated in the next lines. Notice that for the severity and state the enumeration is returned.

{"dc:title":"Pop-Up in IE is not identical to FireFox",
"rdf:resource":"https://server-name:9443/jazz/resource
/itemOid/com.ibm.team.workitem.WorkItem/_tSWJgC6iEd-IPrWkm3if_A",
"rtc_cm:state":{"rdf:resource":"https://localhost:9443/
jazz/oslc/workflows/_RBPUELlhEd61VPTKNlAXiw/states/
bugzillaWorkflow/2"},
"oslc_cm:severity":{"rdf:resource":"https://localhost:9443/
jazz/oslc/enumerations/_RBPUELlhEd61VPTKNlAXiw/severity/3"}}

More information about OSLC can be found at http://open-services.net, and more on OSLC change management at

Speicher, Steve, “Change Management,” http://open-services.net/bin/view/Main/CmHome, December 14, 2010 (accessed February 23, 2011).

More information on the Resource-Oriented Work Item API 2.0 can be found here:

Streule, Patrick, “Resource Oriented Work Item API 2.0,” https://jazz.net/wiki/bin/view/Main/ResourceOrientedWorkItemAPIv2, April 13, 2010 (accessed February 23, 2011).

6.4. Resources

This section includes various resources to complete the integration picture for ClearQuest and for the Jazz-based products. If you are about to create an integration, we suggest looking at the relevant additional readings proposed.

6.4.1. ALM

Gothe, Mats, Carolyn Pampino, Philip Monson, Khurram Nizami, Katur Patel, Brianna M. Smith, and Nail Yuce, Collaborative Application Lifecycle Management with IBM Rational Products: IBM Redbook (Poughkeepsie: IBM, International Technical Support Organization, 2008), www.redbooks.ibm.com/abstracts/SG247622.html (accessed February 22, 2011).

Forziati, Rich, and Mats Gothe, “Collaborative ALM Interoperability,” IBM White Paper, www-01.ibm.com/support/docview.wss?uid=swg27017757, 2010 (accessed February 22, 2011).

6.4.2. Jazz

Lemieux, Jean-Michel, “Integrating and Extending Rational Team Concert (the SDK),” https://jazz.net/wiki/bin/view/Main/RtcSdk20, November 19, 2010 (accessed February 22, 2011).

Lemieux, Jean-Michel, “Extending Rational Team Concert 2.0,” presentation SDP023 delivered at the Rational Software Developer Conference, Orlando, FL, May 31–June 4, 2009, https://jazz.net/wiki/pub/Main/RtcSdk20/RSDC2009-extendingrtc.ppt (accessed February 22, 2011).

“Jazz Integration Architecture Overview,” http://jazz.net/projects/DevelopmentItem.jsp?href=content/project/plans/jia-overview/index.html, September 22, 2008 (accessed February 22, 2011).

6.4.3. ClearQuest

Padgett, Samuel, “ClearQuest OSLC CM REST API,” https://jazz.net/wiki/bin/view/Main/RcmRestCmApi, December 7, 2010 (accessed February 22, 2011).

Exum, Mike, “A Primer on ClearQuest Integrations,” IBM developerWorks, www.ibm.com/developerworks/rational/library/1051.html, 2003 (accessed February 22, 2011).

Drexler, Michael, “Hook to Perform Lookup on External Databases Not under IBM Rational ClearQuest Control,” IBM developerWorks, www.ibm.com/developerworks/rational/library/4388.html, 2004 (accessed February 22, 2011).

Hicks, Leesa, “ClearQuest CRM Synchronization Solution,” IBM developerWorks, www.ibm.com/developerworks/rational/library/4678.html, 2002 (accessed February 22, 2011).

6.4.4. General Information

Speicher, Steve, and Samuel Padgett, “Get to Know Open Services for Lifecycle Collaboration Change Management,” IBM developerWorks, www.ibm.com/developerworks/rational/library/10/openservicesforlifecyclecollaborationchangemanagement/index.html, 2010 (accessed February 22, 2011).

Allamaraju, Subbu, RESTful Web Services Cookbook (O’Reilly Media, 2010), http://oreilly.com/catalog/9780596801694 (accessed February 22, 2011).

6.5. Summary

In this chapter we described different types of integrations to work items. In the first part we introduced product integrations and the advantages they provide to the organization. The ClearQuest integration section started with a description of the ClearQuest packaged (built-in) integrations with other Rational products like ClearCase and RequisitePro, and with third-party products like Microsoft Visual Source Safe and Microsoft Project. We discussed several methods for building a new integration and explained the advantages of each method.

In the second part of the chapter we focused on integrations of the Jazz-based products, mainly Rational Quality Manager and Rational Team Concert. We discussed integrations between one Jazz product and another Jazz product and continued with integrations from Rational Jazz products to Rational legacy products such as ClearQuest, ClearCase, and RequisitePro. An explanation was provided of the Open Services for Lifecycle Collaboration (OSLC) REST API. Rational is building the integrations with this standard, and it allows business partners and customers to build integrations to Jazz work items as well as to ClearQuest records.