13.2 Configuring ClearQuest and ClearCase

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

1. Add ClearCase definitions to a ClearQuest schema. If you have ClearQuest 2.0 (or a more recent release) installed, use the ClearQuest Designer's Package Wizard to add these definitions. If you have an earlier release of ClearQuest installed, use the ClearQuest Integration Configuration application on Windows to add the definitions. You associate the ClearCase definitions with one or more record types and with one or more forms for each associated record type. Each form then contains a ClearCase tab that displays the change set for a change request.

2. Use the ClearQuest Designer to upgrade the database with the new version of the schema. See the Upgrading an existing database topic in the ClearQuest Designer help. If you move the integration to a different database, be sure to repeat this step for that database. For example, you can try out the integration on a sample database before deciding to use it on a production database.

3. Using the ClearQuest Integration Configuration application, set a policy for each VOB that determines the conditions under which users are prompted to associate versions with change requests. You can specify that users are prompted on checking out a version, checking in a version, or both. You can also specify that prompting occurs only for some branch types or element types. Associations of checked-in versions with change requests can be either optional or required.

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:

1. Click Start > Programs > Rational ClearQuest > Rational ClearQuest Designer.

2. In ClearQuest Designer, click Package > Package Wizard.

3. In the Package Wizard, look for the ClearCase 1.0 and ClearCase Upgrade 1.0 packages. If these packages are not listed, click More Packages, and add them to the list from the Install Packages dialog box.

4. If you are upgrading a schema that currently uses the ClearCase-ClearQuest integration from ClearQuest release 1.1 to release 2.0, select ClearCase Upgrade 1.0, and click Next. If you are enabling a schema to use the ClearCase-ClearQuest integration for the first time, select ClearCase 1.0, and click Next.

5. Select the schema for the ClearQuest user database that you want to use in the integration with ClearCase. Click Next.

6. Select the record type of ClearQuest records to be associated with ClearCase versions. This record type must match the record type that you specify on the ClearCase tab of the ClearQuest Integration Configuration application. Click Finish.

7. Click File > Check In to save the new version of the schema.

8. Click Database > Upgrade Database to upgrade the ClearQuest user database with the new version of the schema.

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 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:

• In ClearCase, click Start > Programs > Rational ClearCase Administration > Integrations > ClearQuest Integration Configuration.

• In ClearCase LT, click Start > Programs > Rational ClearCase LT Server > ClearQuest Integration Configuration.

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

In previous releases, the integration used a Visual Basic trigger on Windows and a Perl trigger on UNIX. This release adds a new Perl trigger that runs on Windows and UNIX. 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 Visual Basic and Perl triggers used in previous releases. V2 refers to the new Perl trigger.

The V2 trigger provides a text-based user interface for developers who use the cleartool command-line interface and a clearprompt pop-up window user interface for developers who use one of the ClearCase GUIs such as ClearCase Explorer (on Windows) or xclearcase (on UNIX). The V2 trigger does not provide a GUI for developers. For Windows client machines that have ClearQuest installed, you may want to use the V1 Visual Basic trigger, which provides a GUI for developers.

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

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:

• CQCC_SERVER: name of the host where the ClearQuest Web server resides

• CQCC_SERVERROOT: root directory where the ClearQuest Web Interface files are installed

Setting the Environment for the ClearQuest Perl API

To enable a client to use the ClearQuest Perl API, perform the following tasks:

On Windows:

• Use the ClearQuest Maintenance Tool to connect to the schema repository that stores the schema used by the ClearQuest user database. From the Windows Start menu, click Start > Programs > Rational ClearQuest Administration > Rational ClearQuest Maintenance Tool.

For Windows and UNIX:

• If the ClearQuest database set is something other than the default, set the CQCC_DATABASE_SET environment variable.

On Windows, the ClearQuest Perl API attempts to connect to the schema repository that the ClearQuest Maintenance Tool has most recently connected to. On UNIX, the API uses the default schema repository specified for your ClearQuest installation.

Database sets allow users to select from multiple schema repositories when they start ClearQuest, or the base ClearCase-ClearQuest integration, without having to use the ClearQuest Maintenance Tool.

Editing the Configuration File

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. To use the integration with a different ClearQuest user database, you need to change parameters. The configuration file contains comments that describe how to set the parameters. Before you can edit the configuration file, change its permissions to make it modifiable.

Testing the Integration

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 commands shown above 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

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.