A Step by Step Guide to IBM Rational ClearQuest Tool

For each and every project, as per the Client’s requirement and ease, various tools are recommended and used.

For example, few projects prefer ‘Quality Center’ for managing the project’s data whereas few others prefer Rational ClearQuest tool.

Rational ClearQuest is a defect management and workflow automation software from IBM Rational software division. 

The main purpose and use of this IBM ClearQuest tool is a Bug and Change Request tracking tool for testing related projects. With this tool, you can track the present stage and situation of a project development at any point.

IBM Rational ClearQuest Software Guide

Here is a quick intro to Rational ClearQuest (CQ) tool.

Few uses and points about IBM ClearQuest:

1) Defects details and CRs (Change Request) of a project are maintained and managed with ClearQuest.

2) The CQ tool works in a Client- Server environment (Group of computers termed as clients contact a server through the internet).

3) With CQ, you can view the project’s current status and analytics through running queries (Queries – Used to view the project’s reports and charts).

4) The important terminology used in CQ is Schema and Schema Repository.

Schema – Structure for a database which helps model or organize the data, processes etc., of a project. The schema includes the structure of data, record type definitions, states of a record, actions to modify the state of a record, forms to submit a record etc.

Schema Repository – A database with one or more Schemas is termed as Schema Repository.

Generally, CQ has several predefined schemas which you can use as they are or can modify it as per your requirement.

Few examples of predefined schemas are ‘Defect Tracking Schema’ – contains the fields required to start tracking the defects, ‘Blank Schema’ – contains the system fields- you can use this to create a new schema from scratch.

5) A project’s daily activities can be managed through ClearQuest tool.

6) The CQ tool makes everyone’s work easier and simpler as it unites developers, testers, project leaders, project managers, Clients etc.,

7) Based on your process in the project you can customize CQ as per your needs.

How to Install IBM ClearQuest:

IBM Rational ClearQuest can be downloaded from here.

Note:  If you want to download CQ software from the above link first you need to create an IBM id. Then can proceed with the download process. The product installation files also include IBM Installation Manager and there is no need to download it separately.

To install CQ you need to install IBM installation Manager on your computer first.

‘Installation manager’ is a program used for installing and updating the IBM applications. It keeps track of all the IBM apps that are installed on your computer.

Installation manager

(Note: Click on any image for enlarged view)

Installation manager 1

Step #1) Installation Manager can be installed from Launchpad program.

Launchpad is a web application. Launchpad is located in the DVD of the software. If the DVD is inserted then launchpad starts automatically. We should run the ‘launchpad.exe’ file as administrator.

A sample of Launchpad application is shown in the below screenshot.

Launchpad application

Once the launchpad program starts, the installation manager starts too. And, the product installation starts automatically.

Step #2) We can also get the Installation manager from the folder of product installation files by running the ‘install.exe’ file.

Manually installing the Installation Manager,

  1. Run the file ‘install.exe’ and click ‘Next’ on the install page.
  2. On the License Agreement Page accept the terms and conditions and click ‘Next’.
  3. Proceed with the installation and on the summary page click on install. This completes the installation process of Installation Manager and a confirmation message will be displayed.
  4. Now click on Finish and the IBM Installation Managers gets opened.

To install Rational CQ you need to follow the below steps,

  1. Plan before deployment for when you are going to install, what components you need (how many schemas, Data Bases, Repositories etc) and ensure that all the servers and Databases are shut down.
  2. Open the Installation Manager Start page and click Install.
  3. The install page displays the list of all IBM products available for installation.
  4. Click / Select the product that you want to install. In our case, we need to select ClearQuest. Then click on next and proceed with the installation.
  5. On the license page, accept the terms & conditions and then click ‘Next’.
  6. Follow few other steps like selecting the language, the features that are required for you based on the corresponding configuration.
  7. Now click on Install. This completes the installation process of ClearQuest and a confirmation message gets displayed.

Note: A CQ installation generally has one Schema Repository with one or more user databases. Each project has separate user database.

How to open ClearQuest:

To open CQ, click on Start Menu -> Rational ClearQuest

To login into CQ, a unique login ID is required. For every team member, a CQ unique login ID will be created by the required authorities (Like Administrator).

Note: Default username to login into CQ is ‘admin’ and do not require any password for this admin login.


A project manager or the CQ administrator will create the Databases required for the project and configures the same as per the project requirements.

To connect to any desired schema repository of your project then follow the below steps:

From the File menu of the above ClearQuest Window select Database -> Connect -> New Connection

New Connection

After selecting the New Connection a Schema Repository dialog box gets opened. On that box select your desired Database Set and Click Next

Schema Repository dialog box

Now another dialog box ‘Additional Connection Information’ gets opened. Enter ‘Admin’ as the User ID and click Finish.

Additional Connection Information

Finally, on Connect dialog box click OK. This Completes the CQ Connection with your desired database.

Connect dialog box

Now the main screen of CQ will be displayed.

main screen of Rational ClearQuest

Main Window of CQ has Workspace, Query Builder, and record form.

Main Window of ClearQuest

Let’s see the significance of each:

#1) Work Space: Workspace contains the list of queries both ‘Personal and public’, defects, charts, and reports.

Personal Queries are restricted to a specific project and cannot be accessed by other projects members until they have the permissions to access them.

Public Queries make it to the default queries list. They also include queries & reports of other projects that have made them public. One can copy the same to their respective folder and can modify them as per their project’s requirement.

#2) Query Builder: This displays the results of a query. If we click on any record then its corresponding data will be displayed in a Record Form. We can modify and view the data in the records.

Query Builder

#3) Record Form: Through this, you can modify and view the records.

Record Form

How to create a Change Request:

Before proceeding with the development and testing activities of a project, its corresponding Change Request (CR) needs to be created in IBM ClearQuest. Mainly the Change Request will be created for an issue in the software or for a defect or can be for an enhancement in any software. This CR can be created by the administrator or the project manager. The layout or format of a Change Request is termed as ‘record type’.

This CR can be created by the administrator or the project manager. The layout or format of a Change Request is termed as ‘record type’.

To create a Change Request, click on ‘New Defect’ button from the toolbar.

New Defect

By filling the necessary data in all mandatory and required fields we can submit a CR. We can even attach any documents to a CR so that anyone can view the same for further information regarding the CR.

If the respective configurations have been set by the administrator then the team members can receive the email notification regarding any CR submission or modification.

By default, a CR will be in ‘Submitted’ state. We need to assign (Actions -> Assign) the same to an engineer who is going to work on it. Then the CR state changes to ‘Assigned’.


If any data in CR needs to be modified then go to Actions -> Modify and then update or change any information of CR. During this process, the state of the CR remains the same.

Before starting work, the engineer assigned with the CR has to change the record state to ‘Open’ (Actions -> Open) so that everyone will come to know that he is working on it. Once his work gets completed then he needs to update the state of CR to ‘Resolved’ (Actions -> Resolve).

Once the developer or the engineer changes the CR state to Resolved then a mail gets triggered to the tester or quality assurance team. Then, they will test and verify whether the CR is working properly and fixed correctly by the engineer. If so the CR state is changed to ‘Closed’ (Actions -> Close).

How to Create a New Defect:

Generally, a defect is a flaw in the software that is going to be developed or that has been delivered. A Defect may also be an imperfection in the software. Mainly it means a deviation from the expected outcome of the software.

The main purpose and intention of logging a Defect is to communicate the details of the issue or problem to the concerned team or department.

General details of a defect include Name or ID, description, project, project release, detected by, status or state, assigned to etc. Please note that the different tools have different terminology.

To create a New Defect in ClearQuest follow the below steps,

Step #1) Click on the menu File -> New -> Defect

New Defect in ClearQuest

Step #2) ‘Create Defect’ window gets displayed. Red fields in that window are mandatory fields.

Step #3) Enter data in all the fields as needed. Attachments can also be added in the ‘Attachments’ Tab.


Step #4) Fill in all the required data in the respective fields and click on OK. The defect record gets created.

Step #5) To view the defect that you have created you can run a query which returns the defect record into the result-set pane or you can also use the list of recently submitted records in IBM CQ. For this, expand the ‘Recently Submitted’ folder and double click on the record you want to view.

Recently Submitted folder

How to use Queries:

On your first CQ launch, you may not have any predefined queries. With more and more exposure to the tool, you will become familiar with this client and will have few queries, reports, and charts executed automatically for your login.

The Queries feature of ClearQuest is used to view and track the records that include the changes made to the CR.

In CQ, there is a folder named ‘Public Queries’ in the workspace. It contains the default queries that can be used by every CQ user.

Public Queries

From the list of queries in the Public folder select (double-click) the query required and run the same to get the data as desired. Then the query results will get displayed on the right-hand part of the screen.

Editing a Query:

If an existing query does not satisfy your requirement then copy the same query to your project folder in Personal Queries folder. Then go to ‘Query Editor’ and edit the query as per your requirement and run the query.

You can use the existing query to build a new query. To do this, on the Create New Query window select the ‘Copy the design from an existing query’ checkbox option and then select your required query from the list. You can also select the filters and display layout of the query results.

Copy the design from an existing query

Writing a new Query:

To write a new query go to ‘Query’ menu and select ‘New Query’ and then proceed further with the steps for creating a new query.

To create a query we need to follow few steps, such as:

  • Entering Query Name, selecting the required record type
  • Adding the filters needed along with their properties
  • Grouping the filters
  • Editing the result set
  • Saving the query and
  • Running the query

Step-by-step procedure of creating New Query with an example & snapshots:

Step #1) Open the menu File -> New Query, enter any name for Query, select the Record Type as Defect and click ‘Next’.

New Query

Step #2) Query Wizard window opens. From that select the filters that you want to apply to the query. Select and move your desired filters from Fields Pane to Filters Pane.


Step #3) You can also select the desired values for your filters as shown in the below screen.

desired values for filters

Step #4) For the display of your Query, you can select the result-set display fields as shown below and Click on Finish.

result-set display fields

Step #5) Now your Query is ready in the left pane under Personal Queries folder.

Personal Queries folder

Example: Query to get the details of defects based on their state or severity.

  1. Select the fields ID and Headline to be displayed.
  2. Then Select ID, STATE and SEVERITY fields for filters. You can do this selection by double-clicking on them. (As per your requirement you can mention any values against the filters like STATE = OPEN or SEVERITY = 1-Critical etc).
  3. By default, there will be AND condition between all the fields.
  4. To change AND condition between any two fields you need to group them. In our example, to group the STATE & SEVERITY fields right click on STATE field, click Group and next click the SEVERITY field. With this, there develops AND condition between them.
  5. To change this AND condition to OR, right click on AND condition and change it to OR condition. Now we get the results from the query in which you have the defects with the mentioned STATE and SEVERITY.

Import DATA from an EXCEL:

We can import the data into ClearQuest from an Excel.

For this, open the Excel from which you want to import the data. Go to the menu Data -> Import External Data -> New Web Query. Now select the data that you want to import into CQ and click on Import. Also, mention the location where you want to save the data and click on OK.

Exporting DATA from CQ:

With this export feature, you can get the result set of a query into a file so that you can use this for offline access. For this, click on the arrow next to the Export icon on result set toolbar and select the option for exporting the data into a file as Export as .txt or Export as a .xls format.

You can mention the path for the export file to be saved on your PC.

How to use Charts in CQ:

In ClearQuest, you can find existing charts which can be used for your project by making few modifications to them as per your project’s requirement.

Charts show the graphical view of the records data of CQ. There are two types of charts, Distribution charts, and Aging charts.

Distribution charts are used to view the present status of the data.

Aging charts are used to view the historical data of the project.

Aging charts

To modify the predefined charts from the public folder, open your desired chart and go to menu Edit -> Properties. Now you can change the data display format of the chart and also change the fields or parameters that you want to include for the graphical view.

The second way to modify the charts is to go to the Query Editor and then modify your required records and data.

How to create Reports in CQ:

By default, CQ does not have the feature to create new reports or edit them. To enable this one’s CQ needs a licensed version of Crystal Reports Designer.

The project data available in CQ can be viewed in the form of Report and you can export the same to other formats of the document and can use them.

A report mainly consists of two things, the result set of records that are returned when a query is run and the report format file used to set the layout of the report.

At first, run the query for which you want to create a report. Then click on Create Report button in the toolbar (a button with book symbol on it). Create Report dialog box gets opened. From that box, choose the report format, select it and click on OK.

report format

This will create your report in the selected report format with the data of the query which you have executed. You can even export this report in your desired format and can use it further.

Note: You can even create a new report that can be used repeatedly by saving it in the Personal Queries folder.

new report

For this, go to the menu Query -> New Report. Then a dialog box gets opened to select a record type. Select a record type you need and click on OK.

Then another dialog box opens and prompts for report format and a query.

report format 1

Click on browse and select a report format that you need for your report layout. Next, browse and select the query that you want to associate with the selected report format and click on OK. This will create your desired report which you can save in your Personal Queries folder and can reuse it later.

Another way to execute the existing Reports is as follows,

Expand the Reports folder in the left pane of CQ. Select your desired report to be executed and right-click on it and select Run. The report gets displayed.

For example: From the Reports folder, select the ‘Defect Detail (All)’ right-click on it and select Run.

Defect Detail (All)

ClearQuest Favorites:

To set your favorites in CQ, first, you need to select the particular record type like query, chart, report etc.

Then Right-Click on that record type, a pop-up menu will be displayed. Select the option ‘Add to ClearQuest Favorites’. Now the item gets added to the CQ Favorites and can be viewed in the left pane.

ClearQuest Web Client:

The CQ works in two different ways, one is as Desktop Application and the other is as Web Client. The CQ desktop application means the client is installed on the system whereas the CQ web client means the browser-based interface to CQ. With CQ web, you can access the Change Requests, track the defects etc., same as CQ desktop application.

If CQ desktop client is not installed on your system then CQ Web client is used by default. And, when CQ Web is unavailable to you, CQ desktop client is used by default.

Tips on IBM CQ Usage:

1) To get any additional information on any feature of CQ you can navigate to Help -> Contents and search for the same.

For example, if you want to get any information on queries then you can go to Help -> Contents -> Working with queries.

2) Rational Clear Quest tool is a customizable tool. With this feature, you can customize the look and feel of the display format of the result set data. For example, you can change the look of the columns to be displayed in the query list.

3) Another interesting feature of CQ is that you can set any query or report or chart to run immediately when you login to CQ. For this, right-click on the record in the left-hand pane that you want to run on your start-up and choose ‘Run at Startup’.

Run at Startup

4) For any information regarding administering CQ, you can go through the Administering Rational ClearQuest guide that comes with your CQ product.


With the knowledge you gained through this Rational ClearQuest tutorial you can have a smooth hands-on guide to work on IBM Rational ClearQuest tool for testing or development activities in your project. Once you get familiar with this tool you can write complex queries with multiple filters and conditions to get the specified data on any particular record.

Once you get familiar with this tool you can write complex queries with multiple filters and conditions to get the specified data on any particular record.

It can be the best change request management tool for tracking and managing change requests and defects on any development project including enterprise level projects.

About the author: This is a guest post by Laxmi. She is having 7+ years of Software testing experience mainly in BFSI domain.

Share your comments and questions below.

Happy testing 🙂

Recommended Reading

15 thoughts on “A Step by Step Guide to IBM Rational ClearQuest Tool”

  1. Very detailed one. Thanks!

  2. good one. which other IBM tools are useful for testers?

  3. this is wonderful. Thanks very much. I would like to follow up with you at a later date. Kind of tied up right now.

  4. Thank you all.

    @Devasis – There are many other IBM tools used for testing like Rational Functional Tester & rational Performance Tester.

  5. Thank u for explanation kindly share the process for how we can add a field defect tracking

  6. very good information thanks .

  7. Very Detailed explaination. Really helpful. Thankyou so much

  8. Really helpful

  9. Very good information thank you.

    I can see that, “Once you get familiar with this tool you can write complex queries with multiple filters and conditions to get the specified data on any particular record” sentence is repeated in conclusion part.

  10. Very good information thank you.

    I could see that, “Once you get familiar with this tool you can write complex queries with multiple filters and conditions to get the specified data on any particular record” sentence is repeated in conclusion part.

  11. Can ClearQuest be integrated with Gitlab

  12. Can clearquest be integrated with gitLab?

  13. Can anyone guide me whether we can have the GitLab Integrated with the Clearquest

  14. We are looking for a tutor to train a few users. is Laxmi available to provide a couple of small sessions on the weekends !!!
    please contact me

  15. Hi Lashmi,

    I need to learn more on this tool to do administration tasks. Will you be able to give personal training on this


Leave a Comment