This chapter provides an overview of the base ClearCase-ClearQuest integration and describes how to set up the integration. For information on working in the integration, see Developing Software.

Overview of the Integration

Rational ClearQuest manages change requests, which report defects or request modifications for a project or product. Rational ClearCase manages versions of the elements that represent a project or product. Each version embodies one or more changes to an element.

The integration of ClearQuest and base ClearCase associates one or more ClearQuest change requests with one or more ClearCase versions.

A single change request may be associated with more than one version. The set of versions that implement the requested change is called the change set for that request.

A single version may be associated with more than one change request. These change requests are called the request set for that version.

The integration has the following interfaces:

Configuring ClearQuest and ClearCase

Before developers can associate ClearCase versions with ClearQuest change requests, you need to configure ClearQuest and ClearCase as follows:

Adding ClearCase Definitions to a ClearQuest Schema

A ClearQuest schema contains the attributes associated with a set of ClearQuest user databases, including definitions of record types, fields, and forms. Before developers can associate ClearCase versions with ClearQuest change requests in a user database, you must add some ClearCase definitions to the schema that the database uses. To do so, use the Package Wizard within ClearQuest Designer, as follows:

If you are using a pre-2.0 release of ClearQuest, use the ClearQuest Integration Configuration application to add ClearCase definitions to a ClearQuest schema. To start the application, click Start > Programs > Rational Software > Rational ClearCase > Administration > Integrations > ClearQuest Integration Configuration. Alternatively, you can start the application by entering cqconfig at the command prompt. Click the ClearQuest tab. Click Help for instructions on completing the fields on the tab.

Installing Triggers in ClearCase VOBs

The integration uses ClearCase triggers on cleartool checkin, checkout, and uncheckout commands to allow developers to associate versions with ClearQuest change requests. To install these triggers in a VOB, use the ClearQuest Integration Configuration application.

Product Note: To start the ClearQuest Integration Configuration:

Alternatively, you can start the Configuration application by entering cqconfig at the command prompt.

Prior to ClearCase v2002.05.00, the integration used a Visual Basic trigger on Windows and a Perl trigger on UNIX. ClearCase v2002.05.00 added a new Perl trigger that runs on Windows and UNIX. (This trigger is also available in a patch to ClearCase Release 4.2). Specify which trigger you want to use by clicking V1 or V2 in the Windows Trigger Selection and UNIX Trigger Selection fields of the application. V1 refers to the old Visual Basic and Perl triggers. V2 refers to the new cross-platform Perl trigger.

The V2 trigger provides a text-based user interface for developers who use the cleartool command-line interface and a GUI for developers who use one of the ClearCase GUIs such as ClearCase Explorer (on Windows) or xclearcase (on UNIX). If you are configuring the integration for the first time, we recommend that you use the V2 trigger. If you currently use the V1 trigger, we recommend that you evaluate the V2 trigger and consider migrating to it.

The V2 trigger uses a configuration file, which specifies your local configuration parameters. When you select V2, the Configuration application fills in the Path field with CQCC/config.pl, the path to the configuration file. In this path, CQCC resolves to ccase-home-dir/lib/perl5/CQCCTrigger/CQCC on each local client. You can change the path to a UNC path name so that the integration uses one central configuration file.

For information on completing the other fields in the application, click Help within the application.

Quick Start for Evaluations (V2 Triggers Only)

The default configuration file is set to use the SAMPL user database that ClearQuest provides for evaluations. You can test the integration with the SAMPL ClearQuest user database. If ClearQuest is installed on the client machine, the integration uses the ClearQuest Perl API to communicate with the ClearQuest user database. If ClearQuest is not installed on the client machine, the integration uses the ClearQuest Web Interface to communicate with the ClearQuest user database.

Setting Environment Variables for the ClearQuest Web Interface

To enable a client to use the ClearQuest Web Interface, set the following environment variables from the command-line prompt or in the configuration file:

Database sets allow users to select from multiple schema repositories when they start ClearQuest or the base ClearCase-ClearQuest integration. You need to set the CQCC_WEB_DATABASE_SET environment variable only if your site uses more than one database set.

Setting the Environment for the ClearQuest Perl API

To enable a client to use the ClearQuest Perl API, you may need to set the CQCC_DATABASE_SET environment variable. Database sets allow users to select from multiple schema repositories when they start ClearQuest or the base ClearCase-ClearQuest integration. You need to set the CQCC_DATABASE_SET environment variable only if your site uses more than one database set.

Editing the Configuration File (V2 Triggers Only)

The configuration file contains parameters that define local policy choices and how to access ClearQuest. The configuration file is set to access the ClearQuest SAMPL user database and use the defect record type. To use the integration with a different ClearQuest user database or record type, you need to change parameters. The configuration file contains documentation that describes how to set the parameters. Additional information about the configuration file is available in the README file in the same folder as the configuration file. Before you can edit the configuration file, change its permissions to make it modifiable.

Testing the Integration (V2 Triggers Only)

After you install the triggers on one or more VOBs and edit the configuration file, you can test the connection between ClearCase and ClearQuest by entering the following command:

On Windows:

cqcc_launch CQCC\config.pl -test

On UNIX:

cqcc_launch CQCC/config.pl -test

Note: The preceding commands use the default path for the configuration file. If you specified a different path when you installed the triggers, use that path when invoking the cqcc_launch command.

The command displays output indicating whether it is able to connect to the target ClearQuest user database. For more detailed output messages, set the CQCC_DEBUG environment variable to 2.

Checking Performance (V2 Triggers Only)

The performance of the integration triggers can vary depending on how they access ClearCase and ClearQuest. You can set the CQCC_TIMER environment variable to 1 to record timing information about the trigger session. The integration writes the information to standard output and cqcc_output.log in the directory defined by the TMPDIR environment variable.

Using the Integration Query Wizard

After you establish associations between ClearCase versions and ClearQuest change requests, you can use the ClearQuest Integration Query wizard on Windows to identify the change requests that are associated with a project over a period of time. For example, you might use the wizard to answer the question, “Which change requests were associated with Release 3.1 of Project X?”

To start the wizard from the Windows Start menu, click Start > Programs > Rational Software > Rational ClearCase > Administration > ClearQuest Integration Query. Alternatively, you can start the wizard by entering cqquery at the command prompt. Click Help for instructions on completing each page of the wizard.