BuildForge can work with Rational ClearQuest to update
build records.
Build Forge has two integrations with ClearQuest:
- Automatic build record creation or update based on job status.
This capability is automatically activated when the required environment
variables are set in the project environment.
- ClearQuest adaptors
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.
- Access to ClearCase in order to scan the source. During a job
run, the adaptor runs cleartool commands through an agent and the
ClearCase client. The adaptor runs commands using the ClearQuest Perl
API (cqperl).
- Access to ClearQuest in order to update build records. During
the job run, the adaptor runs cqperl scripts directly on the console
host. They are interpreted by the Cqperl utility and run through the
ClearQuest client, which are both installed on the console host.
Do the following:
- Install a Build Forge agent on a host that can connect to the
ClearCase server.
- Install the ClearCase full client on the agent host.
- Set up the environment for the agent so that commands can be run
through the ClearCase client.
- Install the ClearQuest full client on the Build Forge console
host.
- Add the cqperl (ClearQuest Perl API) directory to the system path.
- 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.
- Use the cqreg command to add the database set (cqreg add_dbset).
- Use the CQ Maintenance Tool to set up a connection to the ClearQuest
database.
- Determine how to implement and how and when to start the ClearCase
views that are required.

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
- Queries a ClearCase view for changes between two dates. The default
dates are the current timestamp and the timestamp of the previous
adaptor execution.
- 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.
- 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
- Finds ClearQuest defect records associated with a list of ClearCase
activities.
- 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.
- 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
- 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.
- 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.