IBM Rational ClearCase and IBM Rational ClearQuest evaluation guide

A tutorial for Version 7.1


Before you start

In this tutorial, you will learn some of the basic tasks for using IBM® Rational® ClearCase® and IBM® Rational® ClearQuest® for team software development, and the organizational roles associated with those actions. You will learn how these tools are used by project managers to assess and assign changes, by developers to implement new changes and deliver them to the team, and by build and quality managers to test, promote and release new builds.

About this tutorial

This series is for users interested in trying some of the change and configuration management capabilities of Rational ClearCase and Rational ClearQuest without installing or configuring the tools. This evaluation provides both tools in a ready to use state from inside a single Eclipse-based shell. By the end of the evaluation, you should have a feel for how Rational ClearCase and Rational ClearQuest work together to provide a complete change and configuration management solution.


This tutorial provides a basic introduction to Unified Change Management using Rational ClearCase and ClearQuest to manage the software development lifecycle. Part 2, presents an overview of Rational ClearQuest and how it is used alone to manage defects, enhancements and other changes. Part 3 describes how to perform the basic tasks within Rational ClearCase.


In this tutorial you will be fulfilling the role of several stakeholders in the software development process including: project lead, developer, integrator and release engineer. By acting in these roles, you will work a defect through the development lifecycle; from submission to completion. Along the way you will observe how Rational ClearCase and Rational ClearQuest work together to control and manage the process of change in software development.


Basic knowledge of Rational ClearQuest and/or Rational ClearCase or configuration management concepts is helpful, but not required. Once you start the trial, you have three hours to explore the application. We recommend that if you are new to Rational ClearCase and/or Rational ClearQuest, you use our evaluation guide to explore some core features.

System requirements

The online trial program uses the Citrix® Access Gateway™ platform to provide you a connection from your workstation to a remote server running the IBM product you are evaluating. You will need to download Citrix client software before using the online trial program. You can download the Citrix MetaFrame Presentation Server client at no charge from the Citrix site; many versions, including versions for Microsoft® Windows and Linux® platforms, are available. After you install the client, you will be asked to restart your browser. If you do not have the Citrix client installed when you attempt to acce

Get started

Welcome to GlobalCorp's newest development site in Dublin. This manual is designed to bring new employees up to speed on our development toolset. Every developer who works at this site should follow this training step by step to become familiar with GC's development policies and procedures.

All of GC's remote development sites use IBM Rational ClearCase and IBM Rational ClearQuest though the Rational ClearCase Remote Client. GC recently upgraded to the newest release, Version 7.1, and the improvements to the interface and the small install footprint make it really easy to get started. The ClearQuest V7.1 and ClearCase V7.1 releases strengthen the ways that these tools help us improve productivity, effectively unify distributed teams, automate processes, improve quality, gain better visibility into projects, and provide traceability across the software development life cycle for fast delivery of high-quality software.

Before beginning on your training, read through this background information on these tools from IBM:

  • Rational ClearCase software provides sophisticated version control, workspace management, and parallel development support to improve productivity.
  • Rational ClearQuest software provides flexible defect and change tracking, process automation, reporting, and life cycle traceability for better review and control of the development life cycle.

Let's get started by opening the updated Rational ClearCase Remote Client interface (sometimes referred to as CCRC). It is built on the Eclipse Rich Client Platform, so chances are that most developers are familiar with the look and feel. Because the new version of of the remote client provides both ClearQuest and ClearCase data, GC developers need to work from only a single IDE. You will do all the rest of this training from this one view.

Find and assign high-priority defect reports

GC's remote development sites are smaller then the rest of the organization, so you'll be doing some tasks that are more typical for a project lead. Our projects are organized by the project lead back in the States and broken down into multiple components. You'll start with these tasks.

  • Logging on to the ClearCase Remote Client and running a query
  • Examining charts to gauge the team's workload
  • Modifying a record and assigning a new owner for a defect report

Log on and run a query

  1. Select the ClearCase menu and then click Connect.
  2. Enter the user name and password: alex, alex
  3. If the server URL is not listed, enter this: http://localhost:12080/TeamWeb/Services/Team
Figure 1. Logging in to ClearCase
image of log-in screen
image of log-in screen

On the left, there is a menu named the ClearCase Navigator (Figure 2). Data is broken into two sections: one named My Views and one named for the connection.

Figure 2. ClearCase Navigator
image of workspace
  1. Click the plus sign to expand the connection group, and you will see a heading for ClearCase and one for ClearQuest.
  2. Click the plus sign for ClearQuest to expand the schema repository connections available Under ClearQuest there will be a database icon labeled 7.1. This represents your schema connection. A Rational ClearQuest schema is a complete description of the process model for one type of change request. It includes a description of the states and actions of the model, the structure of the data, hook code, forms, reports, and queries.
  3. Click the plus sign next to 7.1. Under 7.1 you will find another database icon labeled CLSIC. This icon represents the Rational ClearQuest database, which is where the actual records, queries, and more are stored.
  4. Click the plus sign next to CLISIC.
  5. In the navigation pane, expand Public Queries > Classics PointOfSale Project > Submitted High Severity Defects.
Figure 3. Running a Rational ClearQuest query
image of workspace
image of workspace

Performing bug triage has never been easier. By running saved queries, the project lead can quickly identify which change requests or defects need immediate attention. And by looking at distribution charts, you can identify the workloads of your teammates and assign the defects to those who have the time available to resolve them.

View a chart of defects by owner

  1. From the left-hand menu, select Submitted High Severity Defects. These are the defects that have been submitted but not yet opened by Engineering.
  2. In the ClearCase Details pane (Figure 4), you see that the defect report for "Fix spelling error in Readme.html" has yet to be assigned, because it is still in the Submitted state.
Figure 4. Examining the list of defects
image of workspace
image of workspace
  1. Next, run the query Distribution Charts > Defects by Priority > Owner, which brings up a chart of the defects assigned to each engineer. You can use this information to decide to whom this defect can be assigned.
  2. Select Public Queries > ClassicsPointOfSaleProject > Distribution Charts > Defects by Priority > Owner.
Figure 5. Distribution charts
image of workspace
image of workspace

On the chart shown in Figure 5, you see that team member Alex only has a few activities that are in the Opened or Assigned state, so you can assign this defect to Alex.

Modify a record to assign a new owner

Now that you've found a high-priority defect, you can modify the record and set the appropriate fields on the change request form. All of the fields on a Rational ClearQuest form are completely customizable.

You will use the Assign action to enter Alex as the Owner and then set the Priority field and enter a note saying to further explain the change request. After you have recorded all of this information, you will save the changes to update the record:

  1. In ClearCase Navigator pane, double-click Submitted High Severity Defects again.
  2. Right-click on the CLSIC00000058 record, and select Show ClearQuest Record.
  3. In the top-right pane, click the Change button and select Assign.
  4. Under Priority, select 1 - Resolve immediately.
  5. Under Owner, select alex.
Figure 6. Modify (record) dialog box, Main tab
image of workspace
image of workspace
  1. Click the Notes tab.
  2. Under New Note, type meaningful descriptive text for the new owner.
  3. Click in the Notes Log area to see your note added to this field.

ClearQuest hooks can fire when an action is performed. One very important hook is the e-mail notification hook. In this example, after the Modify action is complete, the notification hook could run any e-mail rules associated with the change request. For example, you may want the e-mail rules set to watch for changes made to the Owner field and, when the value changes, to automatically generate and send e-mail to the new owner about the change.

  1. Click the Audit Trail tab.
  2. Verify that all of the the audit information is captured in this record.
  3. Click Commit to save your changes.
Figure 7. Commit your changes
image of workspace

To comply with regulatory requirements, ClearQuest keeps a record of every action performed on a defect report. The audit trail tab automatically keeps this information as long as the defect exists.

In summary, in this section you have seen several ways that you can use Rational ClearQuest:

  • Assess the project status and progress through standard and customized queries and charts
  • Effectively allocate change requests to engineering resources
  • Use customizable solutions or "hooks" to assign changes requests and automatically communicate project status to the team

As a developer, identifying and managing the work that you are expected to do and informing others of the work that you have done can be one of the biggest challenges in team-based development. With strong organization and communication channels, the development team can stay in sync and react quickly to new information.

Review your tasks

Now you can use Rational ClearQuest directly from within the ClearCase Remote Client to review the tasks that you need to complete. In this section you will learn how to do these two tasks:

  • Join a Unified Change Management (UCM) project
  • Deliver an activity to an integration stream

The Rational ClearCase and ClearQuest change management products work together to enable you to define and manage changes to software assets as activities. Through the UCM capability, file versions in ClearCase are associated with activities in ClearQuest. You can then perform operations directly on the activities rather than on the collections of files associated with them. This activity-based approach to change and configuration management helps you focus on what's important: working on the right versions of the right files. It enables you to create collections of file versions, or change sets, for each change. That way, you work at the task level rather than managing individual files. This also helps build engineers ascertain that the right files are incorporated into the build. Plus, testers can easily confirm that the right functionality and builds are tested, quality assurance (QA) engineers can quickly see and validate what has changed between builds, and project managers back in the States can more easily track and assess project status.

  1. Click the Join a UCM Project button on the toolbar.
Figure 8. Joining the UCM project
image of workspace
image of workspace
  1. In the Join a UCM Project window, expand the Web server, then the ClearCase menu, then the Project VOBs, then CLSICS_pvob. Select the UCM Project CLSICS_CD and click Next.
Figure 9. Selecting a project
image of workspace
image of workspace
  1. In the "Set up a ClearCase UCM Development Environment" step of the wizard, select the check box to Create a new development stream. Under Stream name, enter alex_task_stream and then click Next.
  2. Be sure that the check box for "Create a Development View" is selected. You can keep the default name for the view.
Figure 10. Creating a new project stream
image of workspace
image of workspace
  1. In the "Create a ClearCase UCM integration view" step, select the check box to Create a ClearCase integration view.
  2. Under "Copy area path name," enter this path:
    C:\Documents and Settings\Administrator\alex_CLSICS_CD_int
  3. Click Finish.
  4. When the wizard completes you will be prompted to use the Edit Configuration tool to load the views.
Figure 11. Loading the views
image of workspace
image of workspace
  1. In the "Edit Configuration" dialog box, click the check box to Show private VOBs.
  2. Expand the plus sign next to VOBs, and then select the root of the CLSICS_comp VOB, click Add and click OK.

After choosing your view's configuration, you must select which assets you want to work on. When you have done that, your local workspace becomes populated with those files and directories.

Now you need to find the activity that you are going to be working on:

  1. In ClearCase Navigator, expand the My Views section, and then expand the alex_task_stream view.
  2. Select My Activities under the newly created Task view.
Figure 12. Activities associated with the view
image of workspace
image of workspace

Work on "My Activities"

  1. Select the activity Fix spelling error in Readme.html, right-click, and click Work on.
Figure 13. Selecting an activity to work on
image of workspace
image of workspace
  1. To verify the defects that you will be working on, navigate to the Readme.html file (in the ClearCase Navigator pane) by selecting CLSICS_comp > MyHomePage > WebContent.
  2. Right-click the file Readme.html file and click Open.
  3. You should see the file displayed at the bottom of the ClearCase Remote Client window.
  4. Verify the two spelling errors in the headline and then close the browser window.
  5. Next, open the index.html file in the same way. The headline says "The Ultimate A Company" but should say "The Ultimate B Company.”

Edit the Readme.html and index.html files

First, you need to check out the files to hold reserve copies in your view before you can make changes. This ensures that no one else on the team makes changes to a version while you hold it reserved.

  1. Right-click on Readme.html and select Check out.
  2. Click Show Details on the dialog that opens to verify that the defect that you are working on is CLSIC00000058.
  3. Click OK to complete the checkout.
  4. Repeat this step for the index.html file.
Figure 14. Check out the files
image of workspace
image of workspace
  1. In the ClearCase Details pane, navigate to the Readme.html file (in the WebContent directory under MyHomePage).
  2. Right click and select Open With, then Text Editor.
Figure 15. Editing the files
image of workspace
image of workspace
  1. Find the line that starts with <h2 (a second-level html header tag). From there, you can see the spelling errors that need to be corrected.
  2. Correct the spelling errors by removing the extra letter d in "Readme" and the letter i from "Home."
  3. Save the changes by closing the editor window and clicking Yes when you see the Save prompt.
  4. Back in the ClearCase Details pane, navigate to the index.html file (also in the WebContent directory under MyHomePage).
  5. Right-click and select Open With, then Text Editor.
  6. Change the headline from "The Ultimate A Company" to "The Ultimate B Company" on the line that starts with <title>.
  7. Save the changes by closing the editor window and clicking Yes in response to the Save prompt.

Now you need to check in your changes. The ClearCase Remote Client in Version 7.1 includes a feature that allows developers to check in multiple files at once.

  1. Right-click on the WebContent folder, and select Aggregated and then Check In.
  2. Accept all defaults in the "Checkin" dialog box and click OK.
Figure 16. Checking the files back in
image of menu
image of menu

Now the file is checked into the VOB.

Deliver the activity to the integration stream

Although you've made the necessary changes in your own work area, the changes haven't yet been propagated to the project. Moving changes made for an activity (or activities) from a development work area to a project integration work area is called a deliver operation.

Delivering changes to the project only when appropriate enables our developers to work independently in parallel with each other while maintaining project stability.

Now, deliver your completed activity to the project. Before you begin, be sure that the target view for the delivery is up to date with the project.

  1. At the top of the ClearCase Navigator pane, right-click on the delivery target view (alex_CLSICS_CD_int) and select Refresh > Update from Repository.
  2. Click Apply to accept the defaults and update the target view. (See Figure 17.)
Figure 17. Update the view
image of menu
image of menu
  1. Right-click on Alex's development view, and then select Deliver > Default (Figure 18).
Figure 18. Begin the delivery
image of menu
image of menu
  1. Click OK on the delivery confirmation window.

ClearCase uses the information associated with your development stream to determine which activities have been worked on and are ready to be delivered. Based on that information, it detects which files need to be merged to your project's Integration stream.

As long as there are no conflicts between your changes and changes made by other developers on your project, the delivery will be completed without any further intervention. In this example, however, there is a conflict.

When there are conflicts that require you to intervene, Rational ClearCase will walk you through the process of resolving the conflicts.

  1. In the Deliver dialog box, click Yes to start the merge tool.
  2. You will receive a prompt telling you that there is 1 (one) merge point that needs to be resolved. Click OK to dismiss this dialog. You can also click Run in background to dismiss the "Delivering from stream" dialog.
Figure 19. Starting the merge
image of dialog box
image of dialog box

You are now presented with the ClearCase graphical merge client. You see that there is a conflict between the changes that you made and the version that was in your project's integration stream. But if you examine the difference, you can see that the change that you made in your private development workspace are, in fact, the correct changes, so you need to accept those changes.

  1. To resolve the differences, click the orange text that says "merge needed" in the top pane of the window.
  2. The changes that you made previously are shown in the bottom-center pane labeled 2. To accept those changes, click the 2 button on the toolbar and then click the Resolve and advance button. After clicking the 2 button, you should see that your changes are reflected in the top pane.
  3. To save your changes, click the Save button on the toolbar.
  4. Click Yes on the Confirm Close Merge View window to close the merge view.
Figure 20. Completing the merge
image of workspace
image of workspace
  1. Click the Complete Deliver button in the delivery summary pane to finish the operation.
Figure 21. Completing the delivery
image of dialog box
image of dialog box
  1. Click the Resolution tab on the ClearQuest form.
  2. From the drop-down menu, select the Fixed resolution and then click OK.
  3. Click OK at the prompt to dismiss the dialog

Before completing any deliver operations, our teams must ensure that the changes that were delivered are good and don't affect other work in the integration area. At this point, we normally recommend that teams run a build or test to ensure that everything will still work after the deliver operation. Be sure to take this step before completing the deliver operation because you can cancel rather then complete the delivery.

However, for this training, you can simply complete this deliver operation. Because this UCM project is integrated with Rational ClearQuest, you are automatically transitioning the defect to the next stage of the workflow. Teams can choose to automatically transition Rational ClearQuest defects to "Complete" states on a per-UCM project basis.

Show a version tree

You may want to show a version tree of the Readme.html file. By looking at the version tree of the file, you can get a graphical picture of what happens during the deliver process. The deliver operation automatically takes private changes from a developer's workspace and merges them into another stream. Deliver operations can be performed between developers, to task streams, to a common integration point, or even to teams working on different projects.

Follow these steps to view the version tree for this file:

  1. Select the Readme.html file.
  2. Right-click it and select Show Version Tree.
Figure 22. Showing the version tree
image of menu
image of menu
  1. By default, the version tree window will show a less-detailed version of the element's version tree. Click Show Full Version Tree to see the entire version tree.

The version tree will open with a magnifying glass icon next to the version that your view is selecting. You will also notice that the defect that you were working on (CLSIC00000058) is listed next to the version that you fixed. You can see that a merge arrow was drawn from this version to the new version created by the deliver operation.

Figure 23. Version tree details
image of workspace
image of workspace


By now, you should be mostly up to speed with the way we do development here in Dublin. However, with tools as advanced as Rational ClearCase and Rational ClearQuest, there will be more to learn as you get more comfortable with the basics. For now though, you know enough to get started working on some real defects that have been submitted by our customer support team in Australia. Thanks for taking the time to read through this manual.

Good luck and, once again, welcome aboard!

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

ArticleTitle=IBM Rational ClearCase and IBM Rational ClearQuest evaluation guide