BuildForge Help

Updating ClearQuest Build Records

You can integrate the system with Rational ClearQuest to automatically create and update build records within a ClearQuest database.

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 the following:
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 ClearQuest integration via special environment variables. To link a project to a ClearQuest database, make sure the following variables 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 the .include command within an environment variable to add an environment that includes these variables to another environment, and use that group as the project environment. Also, since 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, and use .include to include it in the project environment, where you can also specify CQ_RELEASE_NAME as a project-specific environment variable.
Table 1. Environment Variables Required for ClearQuest Integration

Variable

Description

CQ_DBNAME

Name of the ClearQuest database you want to update.

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.

CQ_USER

Username to use when logging into the ClearQuest database

CQ_RELEASE_NAME

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

CQ_PASSWORD

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

CQ_DBSET

The ClearQuest database set value. Not required; defaults to blank.