|
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:
- As a ClearCase project manager, you specify the conditions under which users are prompted to associate versions with change requests. You can specify VOBs, branches, and element types for which users can or must associate change requests.
- As a ClearQuest administrator, you add ClearCase definitions to a ClearQuest schema. These definitions enable change requests in databases that use the schema to contain and display associated change sets.
- As a ClearCase developer, you can:
- Associate a version with one or more change requests at the time you check in or check out the version.
- View the change set for a request.
- Submit queries to identify the change requests that are associated with a project over a period of time.
Configuring ClearQuest and ClearCase
Before developers can associate ClearCase versions with ClearQuest change requests, you need to configure ClearQuest and ClearCase as follows:
- 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 their related forms. Each form then contains a ClearCase tab that displays the change set for a change request.
- 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.
- 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.
- The integration uses ClearCase triggers to allow developers to associate change requests with versions. If you use the V2 trigger, you need to modify a configuration file to set database connectivity information and additional policy parameters. See for details about triggers.
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:
- Click Start > Programs > Rational Software > Rational ClearQuest > ClearQuest Designer.
- In ClearQuest Designer, click Package > Package Wizard.
- 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.
- If you are enabling a schema to use the ClearCase-ClearQuest integration for the first time, select ClearCase 1.0, and click Next. 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.
- Select the schema for the ClearQuest user database that you want to use in the integration with ClearCase. Click Next.
- If you use the V1 trigger, 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. If you use the V2 trigger, you can specify multiple record types. Click Finish.
- Click File > Check In to save the new version of the schema.
- 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 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:
- In ClearCase, click Start > Programs > Rational Software > Rational ClearCase > Administration > Integrations > ClearQuest Integration Configuration.
- In ClearCase LT, click Start > Programs > Rational Software > Rational ClearCase LT > 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:
- CQCC_SERVER: name of the host where the ClearQuest Web server resides
- CQCC_SERVERROOT: root directory where the ClearQuest Web Interface files are installed
- CQCC_WEB_DATABASE_SET: name of the database set
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:
On UNIX:
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. | 