What is ClearQuest?

  • IBM ClearQuest is a Bug Tracking system
  • It provides change tracking, process automation, reporting and life cycle tractability.
  • It gives you better visibility and control of the software development lifecycle or any management process.
  • It enables us to customize the tool to our process instead of adjusting our process to match the tool utilities.
  • It is not just a change management tool. It also enables us to create tracking records and process workflow that better match our customer and business needs.
  • It acts as an integration hub for software development tools.
  • Some of the tools are ClearCase, ReqPro, Rational Team Concert, Rational Quality Manager, Rational DOORs, etc.

In this tutorial, you will learn-

Advantage of ClearQuest

  • Enhance Software Quality
  • Customize and Automate workflows
  • Simplify Compliance Management
  • Gain visibility into projects
  • Exploit enhanced integrations

Software Development Hub

ClearQuest can keep track of all the following information inside itself:

  1. Software Requirement Analysis
  2. Software Design
  3. Software Implementation and Coding
  4. Software Testing details
  5. Software Release Notes
  6. Software Maintenance

  • It can link out to the external products from ClearQuest such as,
    1. Rational Quality Manager
    2. Rational Team Concert
    3. Rational Build Forge
  • Third-party applications and tools can also be integrated easily into the ClearQuest.


  • ClearQuest is the enterprise capable system.
  • It supports many different kinds of clients, such as
    • Preferred client in your system
    • Web client across the internet.

  • Web servers that use the ClearQuest product support different platforms like UNIX, LINUX, and WINDOWS.
  • Data for the change management records are stored in the ClearQuest database.
  • It allows you to customize the records. Which means you can customize the workflow of your process.
  • It has user administrative tools and command line utilities for the administrator.
  • It has desktop clients for people who want to work directly on your LAN instead of the web.

System Requirements

System requirement is classified into two categories.

Requirements by Platform:

  • AIX
  • Solaris
  • Linux
  • Windows

Requirements by Components:

  • CQEC
  • ClearQuest Administrative tools
  • ClearQuest Client
  • ClearQuest Client for Windows
  • ClearQuest Database Host
  • ClearQuest Server Components
  • ClearQuest Web Client

Installation Workflow

  • Get a detailed Sketch for your Deployment
    • Choose the clients to deploy
    • Plan for the feature level schemas and repositories
    • Plan for the architecture
    • Administrating Multisite
    • Administrating Web
    • Manage User Account & LDAP
    • Integrating ClearQuest with other products
    • Identify hardware and software requirements
    • Prerequisite for the platform
    • Configure and maintain the full-text search
    • Plan for the environment to be reported
    • Vendor Database
    • License for the ClearQuest
  • Configure the tasks

    Make sure that the user ID meets the privileges for the installation.

  • Retrieve and extract installation support
    • Passport Advantage
    • Installation DVDs
  • Install ClearQuest
    • Install Installation Manager using the Installation Manager installer.
    • Get the copy of the product response file and update it for your environment.
    • Run a silent install of the Rational product using the Installation Manager.
  • IBM Rational ClearQuest has been Installed Successfully!

Roles of the User




  • Create a plan for the Change Management Process
  • Maintain databases
  • Create and customize schemas
  • Troubleshoot the entire system.


Design and customize the schema to match with the change management process.

Project Manager

Allocate changes requests to the members of the team.


Create, update and reports on process records in the Client Interface

Documentation Setup

  • ClearQuest Documentation consists of hard copy and soft copy of the task-oriented information.
  • This documentation supports the administrators, designers, developers and the user.
  • Some of the online documentation are:
    • Help: Help Menu, Help Button, F1 key
    • Reference: From Rational Software, you can select Rational ClearQuest-> Rational ClearQuest API Reference
    • Tutorials: From Rational Software, you can select Rational ClearQuest-> Rational ClearQuest Designer Tutorial
    • PDF Manuals.

ClearQuest Components

  • ClearQuest Component helps to work in the Client-Server environment.
  • Depending on which ClearQuest components are installed and configured, platforms like Windows, LINUX, UNIX will provide different services.

ClearQuest Package and Integration

  • ClearQuest Package is a set of components, which can be added to a Schema in order to support complex functions.
  • Integration Package integrates external products with ClearQuest.
  • To install a package, you have to use the Package Wizard included in the Designer.

The following table describes the list of integration packages available for ClearQuest:

Package Description
AMBaseActivity Supports ClearQuest Project Tracker.
AMStateTypes Supports for Change Management and its state types. Maps schema states to its types: Waiting, Ready, Active, and Complete.
AMWorkActivitySchedule Helps in query records being created and updated with Rational ClearQuest Project Tracker.
BaseCMActivity Support for the BaseCMActivity record type. Alternative for Defect record type.
IBM Rational ClearCase (read-only) Support for the BaseRational ClearCase integration.
CrossPlatformSCM (CPSCM) Allows you to use Rational ClearQuest as a single point of control for running coordinated builds and promoting operations.
Deployment tracking packages The following packages enable deployment tracking:
  • Deployment Tracking
  • TPM
  • eSignature
  • AuditTrail
  • Email
  • Build Tracking
PQC (read-only) Support for integration with IBM Rational Purify®, IBM Rational Quantify®, and IBM Rational PureCoverage®.
Project Allows you to track records according to a project.
Project Tracker Rational ClearQuest Project Tracker is an add-in to Microsoft Project that integrates Rational ClearQuest functionality.
IBM Rational Portfolio Manager Links development activities with planning and tracking
Repository (read-only) Supports IBM Rational RequisitePro®, IBM Administrator, and IBM TeamTest.
Rational RequisitePro (read-only) Supports integration with Rational RequisitePro.
TeamTest (read-only) Supports integration with IBMTeamTest.
UCMPolicyScripts Supports Unified Change Management (UCM) package by adding some global scripts.
UnifiedChangeManagement (UCM) (read-only) Supports UCM process by enabling integration with IBM Rational ClearCase 4.0 and higher.

ClearQuest Schema, Schema Repositories, Database and Connections

ClearQuest Schema

The schema contains metadata that describes how to use the records in the ClearQuest. It includes

  • Type definitions
  • Submit and modify records
  • Field definitions
  • States
  • Modify or change state
  • Hooks to customize fields and actions

Schema Repository

ClearQuest stores Schema in Schema Repository.

If your team has developers working on different projects, you can store the user database schema for those projects in the same repository.

The above diagram shows that multiple ClearQuest user databases are stored in the same repository.


A database is a collection of data given by the user in the process model. We can relate the databases to its corresponding schema. It stores data in records and it has records for each request.

Here is the detailed view of how the databases are laid out. It is divided into two major parts.

  • Master database sets
  • Replicated database sets


Connection is nothing but a database set, a schema repository and its associated databases are connected to each other. One connection is associated with several projects, and a project can have several connections.

It can be managed by the command line utility cqreq. It is stored in <INSTALLDIR>ClearQuest/bin directory.

Following are the attributes of command line cqreq,

  • cqreg show: View all connections.
  • cqreg initialize: Creates necessary file structures.
  • cqreg drop_dbset: Drops a dbset.
  • cqreg add_dbset: Add a dbset
  • To Update, you need to drop and add a dbset.

Rational ClearQuest Test Management

  • ClearQuest provides Test Management that allows us to plan, organize and define tests.
  • It enables us to keep track of the testing progress.
  • It is used to manage and schedule the test phases.
  • It allows us to measure the quality according to the metrics.

Rational ClearQuest Test Manager

  • Test Manager is used to managing the testing environment.
  • It manages the following Components
    • Test Plans
    • Test cases
    • Test Requirements
    • Test Configurations
    • Test Scripts
    • Test results
  • It supports the following phases
    • Planning
    • Authoring
    • Execution
  • It supports the following Clients
    • Rational ClearQuest for Windows Client
    • Rational ClearQuest Web Client
    • Rational ClearQuest Client for Eclipse
    • Rational ClearQuest Client

Change Management Process

  • Change Management Process is used to customize the predefined schema and to create a new schema to better match your process
  • By using the change management process, you can implement and manage different process models
  • For each change request type you can do the following:
    • Define a process model
    • Program customized rules
    • Create forms to access change requests, communicate and to perform requested actions
    • Build reports and queries for better visibility
  • It provides tools to assign workloads, track changes and improves teamwork.
  • Change management process has two major parts
    • State – Current Status of the change request
    • Action – Activity that transforms the state from one stage to another.

    The following diagram better describes the change management process model.,

    • State is shown in ovals
    • Action is shown in arrows

Concepts of using ClearQuest

Basic concepts of using ClearQuest are:

  • Submit a change request.
  • Work with change requests.
  • Track change requests.
  • Gather project metrics

To get Start with the ClearQuest

  1. Start-> Rational ClearQuest
  2. Login to ClearQuest, type UserName and no need to type the Password
  3. Click on 'OK' Button.

The ClearQuest main window looks like this and consists of

  • Workspace
  • Query Builder
  • Record Form

  1. The workspace displays the queries, charts, and reports that are available
  2. Double click a query to locate records in the database
  3. Query Builder displays the results of a query. Click a record to display its data in the record form
  4. Use the record from to view and modify the records.

Submit a Change Request

Step 1) Submitting a change request is the first step, and it creates a record in the user database.

  • This record can be tracked by every developer and the tester of the project team.
  • To submit a change request, you have to click in the toolbar.
  • For more information, you can use the reference pages Help -> Contents -> Working with Records

Step 2)

  • This will open a new window, enter all the information in the new window.
  • Click "Save as Default" from the Value drop-down list.
  • Click OK.

Working with Change Requests

ClearQuest allows us to modify the state of the change request records. By doing this, we can modify and change the state of the action records.

Step 1) Click on Actions drop-down list. It will give the list of options that we can do with the change request records.

Step 2) From the Actions list, you can select your desired option.

For instance, Assign action changes the state to Assigned.

Track Change Requests

ClearQuest helps to get a clear picture of the change records. Every member of the project team can keep track of the changing requests.

  • Public Queries
    • ClearQuest has predefined Public Queries to simplify the task.
    • You can choose the predefined query to match your task.
    • For example,
      1. To find defects Public Queries -> All Defects
      2. To find specific word Keyword Search

  • Building Queries

ClearQuest allows us to create a new Query from the beginning or to create it as a subquery from the existing query.

Step 1) By selecting Query-> NewQuery, ClearQuest Query Wizard appears and it helps in creating a new query.

  • Modifying Queries

ClearQuest allows us to modify a query.

Step 1) Drag and drop your queries into the Personal Queries Folder

Step 2) Use Query Editor tab to change the filtering criteria for a query.

Step 3) Then select the Display Editor to set up how the queries result to be displayed

Gather Project Metrics

ClearQuest Charts

  • ClearQuest gives us charts and reports to get a detailed view of our project.
  • ClearQuest is used to graphically picture the recorded data
  • Charts are mainly divided into two parts
    • Distribution Charts – current status of the project
    • Aging Charts – Historical Information
  • ClearQuest allows us to modify the charts in two ways
    • Edit -> Properties
    • Quality Editor

Following are the steps to see charts and reports.

Step 1) Drag a chart from your queries into the Personal Queries Folder before modifying it

Step 2) Double click the Chart you wanted to display it.

Step 3) Now, right click and select "drill down" option from the menu.

ClearQuest Reports

ClearQuest has reports and report formats to use on your data.

Step 1) To create a report first, you have to run a query and then click on button.

Step 2) This opens the Create Report dialog box as below. Click on the button to export the report to your desired format such as HTML, Excel, etc.

The report will look something like below.

Administrating and Customizing ClearQuest

ClearQuest allows us to do the following administrative and customizing tasks:

  • Designing a Schema
  • Working with Repositories
  • Exporting Data
  • Importing Data

Designing a Schema

  • ClearQuest Schema can be designed by using the ClearQuest Designer. The Designer allows us to choose the design and to modify the schema.
  • To open the ClearQuest Designer Start -> Programs -> Rational Software -> Rational ClearQuest -> Rational ClearQuest Designer as follows.,

Working with Repositories

ClearQuest has ClearQuest Maintenance Tool

  • Maintenance Tool is used to performing the following actions
    • Create and Manage Repositories
    • Create Database
    • Move Schema Repository
    • Upgrade Schema Repository

Exporting ClearQuest Data

  • ClearQuest Export Tool is used to export the data
  • To open the export tool, Start -> Programs -> Rational Software -> Rational ClearQuest -> ClearQuest Export Tool
  • Enter the path and file names to export as shown below:

Importing ClearQuest Data

  • ClearQuest Import Tool is used to import the data
  • To open the import tool, Start -> Programs -> Rational Software -> Rational ClearQuest -> ClearQuest Import Tool

  • Check whether the summary has the right information before importing.
  • After validating, Click Import.


  • ClearQuest
    • Workflow application development System.
    • Provides process automation, tracking and tracing the software development lifecycle or any management process.
  • Software Development Hub – controls and tracks the change management system.
  • It supports different platforms and customizes the records and flow of the process.
  • It has its components divided into two major types
    • Client Tools
    • Administrative Tools
  • ClearQuest Integration packages are used in integrating with external products.
  • A schema contains metadata to work with records
  • It has two types of database sets
    • Master Database Sets
    • Replicated Database Sets
  • cqreq command line is used in connections and it has four following attributes
    • cqreg show
    • cqreg initialize
    • cqreg drop_dbset
    • cqreg add_dbset
  • ClearQuest has Test Manager to manage the testing environment.
  • Change Management Process is used to customize the predefined schema and to create a new schema to better match your process
  • Basic concepts of using ClearQuest are:
    • Submit a change request.
    • Work with change requests.
    • Track change requests.
    • Gather project metrics
  • ClearQuest allows us to do the following administrative and customizing tasks:
    • Designing a Schema
    • Working with Repositories
    • Exporting Data
    • Importing Data

This article is contributed by Nandhini Sundar