Rational Build Forge and Rational ClearQuest

BuildForge can work with Rational ClearQuest to update build records.

Build Forge has two integrations with ClearQuest:

These capabilities are completely independent of each other. In particular, the adaptor is associated with an environment created for it. The variables in that environment are independent of variables set to activate automatic build records.

Setting up automatic generation of build records

The system can automatically create build records in your IBM Rational® ClearQuest® database, with links to the log data. Furthermore, when a job passes, the system can update the ClearQuest database, noting that the job is complete, recording the end time and a summary of the steps that were accomplished. This feature requires Rational ClearQuest version 7.0 or later.

When you configure a project to update a ClearQuest database, the system performs creates or updates build records as follows:
Job start
When the system launches a job, the system creates a ClearQuest build record. The build record is in the Submitted state and includes the job log URL, the start time, release name, and ID as well as a log entry indicating "Build XYZ started." If a source control adaptor cancels the job (because no source changes are found, for example), no ClearQuest build record is created.
Note: If a project chains another project, the new project gets its own unique ClearQuest build ID.
Job pass/fail
When a job passes or fails, the system changes the build state within ClearQuest to Completed or Failed, sets the build end time, and stores a summary of the job's steps in the ClearQuest build log. The summary includes the name, result status, and server for each step.
Job restart
When a job is restarted, the system changes the build state within ClearQuest to Submitted and creates a ClearQuest build log entry indicating “Build XYZ restarted.”

You configure the automatic build record update through special environment variables. To link a project to a ClearQuest database, make sure the variables in the following table are included in the project's environment.

Note: These variables must be present in the project environment. Adding them to a step is not sufficient. However, you can use a variable that is set to type Include that includes these variables through another environment. Also, because the CQ_RELEASE_NAME value is the only one likely to vary per project, you may want to create an environment that contains the other variables, then use a variable of type Include to include that environment in the project environment, where you can also specify CQ_RELEASE_NAME as a project-specific environment variable.

In order to activate automatic updates of build records from Build Forge jobs, the following environment variables must be set for the project. They do not work at the step level.

Variable

Description

CQ_DBNAME

Required. Name of the ClearQuest database you want to update.

CQ_DBSET

The ClearQuest database set value. Not required. Defaults to blank.

CQ_INTERACTION

If your project environment has the correct environment variables defined to enable the creation of a ClearQuest build record but you do not want to create the build record, set this variable to OFF to disable build record creation.

To enable build record creation, set this environment variable to ON.

Note: If you are using one of the ClearQuest adaptors, set this environment variable to OFF. The adaptor interacts with the build records directly.

CQ_PASSWORD

Required. Password to use when logging into the ClearQuest database. Not required; defaults to blank.

CQ_RELEASE_NAME

Required. The name of the release within the ClearQuest database that you want to update.

CQ_USER

Required. Username to use when logging into the ClearQuest database.

Additional setup requirements for ClearQuest adaptors

The ClearQuest adaptor template samples provide methods of scanning ClearCase and updating build records in ClearQuest. This is typically linked to the success or failure of builds run in Build Forge. See Adaptor requirements for general requirements. In addition the following configuration needs to be done.

Do the following:

  1. Install a Build Forge agent on a host that can connect to the ClearCase server.
  2. Install the ClearCase full client on the agent host.
  3. Set up the environment for the agent so that commands can be run through the ClearCase client.
  4. Install the ClearQuest full client on the Build Forge console host.
  5. Add the cqperl (ClearQuest Perl API) directory to the system path.
  6. Define a connection that the ClearQuest client on the Build Forge host can use to access the ClearQuest database. Perform these actions on the ClearQuest client host.
    1. Use the cqreg command to add the database set (cqreg add_dbset).
    2. Use the CQ Maintenance Tool to set up a connection to the ClearQuest database.
  7. Determine how to implement and how and when to start the ClearCase views that are required.
Artwork showing the relationship of Build Forge, ClearCase, and ClearQuest installations.

You do not need to install an agent. The ClearQuest adaptor communicates directly to ClearQuest through the client, using the ClearQuest Perl API.

Important: the ClearQuest adaptor can be called only with a dot command in a step. It is not a source adaptor, so an adaptor link cannot be used.

ClearQuest adaptor template samples

The following adaptor template samples are provided.

ClearQuestBaseClearCaseByDate
  1. Queries a ClearCase view for changes between two dates. The default dates are the current timestamp and the timestamp of the previous adaptor execution.
  2. For each changed file, looks for a CrmRequest hyperlink attribute that identifies a ClearQuest change ID. Attempts to resolve the change ID by adding job information to resolve the defect record in ClearQuest if the ClearQuest status allows it to be resolved.
  3. For each changed file, writes the following information to the BOM report: the file name, defect ID, defect status, and any ClearQuest errors.

Variables defined in the adaptor template:

  • CurDate
  • LAST_RUN
  • VIEW
  • VOB_PATH
  • CQ_USER
  • CQ_PASSWORD
  • BFSERVER
  • UNIXCLIENT
  • _CHAR_NATIVE
ClearQuestClearCaseByActivity
  1. Finds ClearQuest defect records associated with a list of ClearCase activities.
  2. For each defect record found, it adds job information to resolve the defect record within ClearQuest if the ClearQuest status allows it to be resolved.
  3. Writes the following information to the BOM report: files associated with ClearCase activity IDs and the ClearQuest defect status.

Variables defined in the adaptor template:

  • CurDate
  • VIEW
  • VOB_PATH
  • ACTIVITIES
  • CQ_USER
  • CQ_PASSWORD
  • PROJECT_VOB
  • BFSERVER
  • UNIXCLIENT
  • _CHAR_NATIVE
ClearQuestUCMClearCaseByDate
  1. Queries a ClearCase view for changes between two dates. The default dates are the current timestamp and the timestamp of the previous adaptor execution. It uses Rational Unified Change Management (UCM) to produce its results.
  2. For each changed file, writes the following information to the BOM report: the file name, defect ID, defect status, and any ClearQuest errors.

Variables defined in the adaptor template:

  • CurDate
  • LAST_RUN
  • VIEW
  • VOB_PATH
  • CQ_USER
  • CQ_PASSWORD
  • BFSERVER
  • UNIXCLIENT
  • _CHAR_NATIVE

ClearQuest adaptor variables

This table is a reference for the variable lists for the adaptor templates.

Table 1. Environment variables required for Rational ClearQuest integration

Variable

Description

ACTIVITIES For the ClearQuestClearCaseByActivity adaptor, a space-delimited set of activity IDs. Example: SAMPL0001@\ProjectVob
BFSERVER Set this variable to the name of the host for the Build Forge console.

CQ_PASSWORD

Required. Password to use when logging into the ClearQuest database. Not required; defaults to blank.

CQ_USER

Required. Username to use when logging into the ClearQuest database.

CurDate Supplies the current date to the adaptor, using a .date command to generate the date. Do not change this value.
LAST_RUN For ByDate adaptors, the system uses this value to determine whether any changes have occurred; the value is the date of the last successful run. You can manipulate this value when testing the adaptor to force the adaptor to run, by picking a date that you know precedes some changes. If the adaptor allows the run to continue, it automatically updates this value to the current date. The default value is 1-Jan-05.00:00:00.
UNIXCLIENT Used to set platform-specific information. Set to 0 if the client is running on Windows. Set to 1 if the client is running on UNIX or Linux.
VIEW Set this variable to the name of the ClearCase view that you want to use with the adaptor.
VOB_PATH Set this value to the name of your component VOB, and optionally, its subdirectories. Use a comma-separated list for multiple names.
_CHAR_NATIVE Used internally and always set to 1.

Restarting ClearQuest-integrated jobs

Once a ClearQuest-integrated has completed, it normally cannot be restarted in Rational Build Forge. As a simple workaround, you can start the job as a new job.

To enable restarting, you must edit the ClearQuest schema with the ClearQuest designer tool. The work flow for Build records must be modified to allow a state transition of Completed to Submit.


Feedback