Lessons learned in implementing Rational ClearQuest ALM in two large companies

Using the IBM® Rational® ClearQuest® ALM package for change management is still new to many software developers. Find out what experts learned in implementing this Application Lifecycle Management capability in two large companies


Jirong Hu (jirong.hu@gmail.com), Senior Consultant

Jirong Hu is an independent software configuration management (SCM) consultant and an IBM Rational business partner. He works with Rational service engineers in many large SCM implementations of Rational ClearCase, Rational ClearQuest, and Rational BuildForge software.

01 February 2011

Also available in Chinese

Adding Application Lifecycle Management (ALM) introduced a new paradigm in IBM® Rational® ClearQuest®. Based on IBM's many years of internal and field experience, it is designed to handle complex requirements in large organizations. These are among the advantages that it has over the standard version of ClearQuest:

  • Makes it easy to have different project areas that use different processes
  • Significantly reduces time to roll out the software
  • Minimizes the schema changes

For an introduction to Rational ClearQuest ALM, see the excellent three-part series of developerWorks articles by Carolyn Pampino and Robert Pierce, titled Application lifecycle management with Rational ClearQuest

The experience described here comes from working with two very large companies, one in the U.S., the other in Canada. Both have more than 1000 users.

Access control

The diagram in Figure 1, from the IBM Information Center, shows how access control works within ALM. To restate some of the concepts:

  • The Security Context feature can be used to separate large project areas. For example, if the company has some sensitive projects and data that they want to be accessed only by a certain group of people, you can create a separate security policy for them and have all projects and related configurations under that security policy.
    It is still best to keep databases physically isolated when storing sensitive data, such as payroll information.
  • Roles must be defined in each project created in ClearQuest, but they can be copied to define a new project's roles.
  • Rational ClearQuest users and groups can be added to each role to define who can play that role in that project.
  • A role can be initialized with a predefined set of Approved Actions defined in a referenced Role Label. A role can also be customized to fit specific needs of the project. Therefore, if the Role Label definition changes in the future, the changes are not propagated to the role.
  • Approved Actions are defined in each Role Label, which is a systemwide setting. When you create a new project, the list of Approved Actions is taken from the Role Label. However when you update the approved actions in Role Labels, ClearQuest does not update the existing Approved Actions for the existing roles in existing projects.
Figure 1. Access control object model
Diagram of the object map for access control

Consider the example shown in Figure 2:

  • The project is called "WinOnline (R510)."
  • A Development Manager role has been created for this project.
  • Two ClearQuest user groups, WinOnlineDev and WinOnlineLead, are added into this role.
  • A list of Approved Actions is added for this role.
Figure 2. A sample project setup for access control
Details of Team Members, Members, Approved Actions

Larger view of Figure 2.

The result is that whoever belongs to either the WinOnlineDev or WinOnlineLead groups can perform the Approved Actions within this project.

As you can see, the mechanism provided here can implement a very fine-grained type of access control. It's very powerful but it is important to define only what you need. For example:

  • ClearQuest Groups might have to be created for each project unless they are reused from other projects.
  • The Groups need to be added to each ALM role (ALMRole).
  • Approved actions must be defined and updated for each role unless you take advantage of the Role Label and reuse that across projects.
  • Team membership can change, so ClearQuest Groups might need to be updated frequently.
  • The same person might play different roles at different times for different projects, yet you need to use Members and Groups at the same time for every project.

Note for clarification:
From the middle image of Figure 2, you can see you can add either Members or Groups into the Role. However, sometimes it's not enough to use just Groups (which is preferable), because you might need to add someone as a member directly. Otherwise, you need to add that member to the relevant group, which requires the Windows domain administrator's assistance.

In an organization that has thousands of users and hundreds of projects, the time necessary is to keep everything up-to-date and the turnaround time that it takes to fix such an access-related issue can be considerable.

However, you can simplify the process:

  • Create larger ClearQuest groups. Rather than having a ClearQuest group for each project, create a group for a large project area. For example, for a bank, you can create a group called "Domestic Developers" to include all developers in domestic banking applications and another group called "Investment Developers" for all developers in investment banking applications. This way, for all applications or projects in the domestic banking area, you simply need to add the large group, and all relevant developers will have access to all projects, no matter how they jump from one project to another.
  • Right-size the sets of Approved Actions according to RoleLabel. We started to use an Excel spreadsheet for defining approved actions for each role in a very detailed manner, as Figure 3 shows. For example, only someone in the Development Lead role could create tasks, not just developers. But we soon received a lot of requests to move people from the developer group to the development lead group, because lots of people working on small projects don't want to have such restrictions. So later on, for some projects, we also gave developers the permission to create their own tasks. Another approach is to move developers into the Development Lead roles.
Figure 3. Sample Approved Action matrix
A matrix to define actions approved for each role

Larger view of Figure 3.

Project management

Here is the situation we have in a large telco (telephone) company:

  • The software delivery is very much release-based. There are major releases for each month, a total 12 a year plus weekly cycles, as well as stand-alone, emergency, and urgent test releases.
  • There are over 1200 applications, starting with more than 100 to move into ClearQuest.
  • Each of those applications can be changed in each release, managed by different IT projects or programs, and in a different phase at the same time.

Following the standard ALM approach, we have used these methods

  • Release labels, such as R510, MR610, TR710, and so forth, to track the major releases.
  • IT projects (modeled as ALMProject in ClearQuest) to track the changes to applications from project or program management perspectives.
  • For applications, initially we create an ALMProject for each of the applications, and the release label is attached to the ALMProject as shown in Figure 4.
Figure 4. A sample project
Project AA (R510)

Because the release label is embedded in each project, we have to append the release name after the application name to identify the project name. We ended up with duplicating the same application for each release, as Figure 5 shows.

Figure 5. One project for each release
Screen capture of 5-column table

These are the problems of this approach:

  • There are major releases for each month, a total 12 a year. We had to duplicate all applications for each release, with hundreds applications in each release. That's a huge amount of work.
  • When new projects are added to one release, they have to be duplicated to other releases. It's difficult to keep all of them in sync.

And conceptually, Figure 6 shows, there are these factors to consider:

  • The IT project is used to manage programs driven by business. The owner is a project or program manager.
  • Each application should have its own life cycle, which should be independent of releases and programs. The owner is the application or product manager.
  • A baseline identifies the set of application changes to be included in each release. The owner is the release manager.
Figure 6. Release, project, and application
workflow diagram

The fundamental issue here is that ClearQuest lacks support to model a product in ALM. To resolve that problem, we made a small change in ALM: move the release label from ALMProject to ALMRequest.

So now the Application type of a project does not have a release label tied to it (see Figure 7), and it will last across all releases as long as it still exists

Figure 7. Remove release information from the project
A project without a release label

Larger view of Figure 7.

Release information will be moved into each request, so that anyone who submits a request must fill in the release label there (see Figure 8).

Figure 8. A request with a release label
Result set shows release info moved to the request

Larger view of Figure 8.

With this change, we make the model conceptually correct, and we do not need to duplicate the application projects from one release to another anymore.

Using the Copy Project function

There are several things to configure to create a new ALMProject, including roles and ALMWorkConfigurations. It's time-consuming to create a new project from scratch. That's why this Copy Project function is very useful.

This function copies most of the necessary project information, except the iterations. It also copies the Audit Trial, which is normally not required.

Figure 9. The Copy Project button on the View ALMProject screen
The Copy Project button on the right side

Larger view of Figure 9.

This function calls the ALM_CopyProject record script (see Figure 10). If you modify the script a little bit, you can make it as a stand-alone script to be run outside of ClearQuest to do a batch copy to create multiple new projects. (In our case, we needed to duplicate projects for each release, and each consists of more than 200 projects.)

Figure 10. ALM CopyProject record script
Screen capture of the ClearQuest Designer

Larger view of Figure 10.


In ALM, we don't use a states transition matrix to implement a process or workflow anymore. Instead, the process is embedded in the type of tasks and activities to handle a request.

Work configuration

Although each stateful record type still has a state, it shouldn't be used to implement the workflow. We shouldn't add or remove these default states.

Take the following defect (ALMRequest) as an example:

  1. When a defect report is submitted to the application, CSS (R510), the development lead for the CSS application will create an analysis task and assign it to a developer to analyze the defect.
  2. If a code change is required, a development type of task will be created and assigned to a developer.
  3. Then a deployment type of request will be sent to the environment team to deploy the fix into proper test environments.
  4. When the deployment is completed, the system will create a ReadyForRetest task and assign it to the tester who submitted the defect report.
  5. The tester then reruns the test to verify that it is fixed.
  6. If the retest fails, the development team continues creating tasks to fix this defect, and then sends it to retest again.
Figure 11. A sample request with a list of tasks
Screen capture of the Request tab view

Larger view of Figure 11.

The defect management process shown here needs to be documented outside of ClearQuest. And within ClearQuest, all proper types and work configurations need to be defined for this project. That's how a process in implemented in ALM.

However, the challenge is that it's difficult to find out the real status of the defect. You'll need to define the status of the defect based on the states of different tasks beneath it.

Figure 12. All work configurations in a project
ALM Work Configurations view

Larger view of Figure 12.

Primary and secondary records

To make users' lives easier, this configuration is extremely helpful. Based on the process, we can define the primary and secondary types of record to be created when these CreateTask and CreateActivity utility functions are accessed (see Figures 13 and 14).

Figure 13. Select the CreateTask function from the drop-down menu
Request view, CreateTask selected
Figure 14. CreateActivity function in the Task view
CreateActivity option on the drop-down menu

What follows is an excerpt from the Rational ClearQuest 7.1 Information Center that explains how it works:

Each WorkConfiguration record can list a set of Primary Children configs and Secondary Children configs. These lists are used by theCreateTaskaction (on the ALMRequest record) and theCreateActivityaction (on the ALMTask record). The CreateTask or CreateActivity action creates a set of records that are listed in the Primary Children Configs the first time that the CreateTask/Activity action is performed. Subsequent CreateTask/Activity actions use the Secondary children config list to create more records.

For example, as the setting is shown in Figure 15, the first time any user runs Utilities > CreateTask on a defect that is an ALMRequest, an Analysis type of ALMTask will be created for this defect. Subsequently, any invoking of this function again will create a development type of task. They can also change the type of task to suit their needs.

Figure 15. A work configuration with primary and secondary types
Where to add primary and secondary types

This can save time for the users then they are creating new tasks from scratch (if they need to manually add projects or related request, and such).

Utilities menu

There are quite a few functions provided in the utility menu, as Figure 16 shows. CreateTask and Delete are easy to understand. Invoking QuestionOrComment will create a new comment for this record, and then you must go back to the comment to add your own comments.

Figure 16. Functions available from the utility menu
Options on the utility drop-down menu

Behind the scene, these functions are invoking the record scripts, as Figure 17 shows.

Figure 17. Record scripts for the utility functions
Where to find the corresponding record scripts

Larger view of Figure 17.

Also, you must create a project named ALL for the Reject_Request, Unreproducible, and WorksAsDesigned functions to work (see Figure 18). It is best that the ALL project have a category and release of "ALL," as well, and that it be associated with the "Everyone" security policy, which is associated with the ClearQuest "Everyone" group.

Figure 18. The ALL project
The ALL project details view

Otherwise, you will get the Exception error shown in Figure 19.

Figure 19. An error results without the ALL project
An ALL Project is required (for) this action

MarkAsDuplicate and DuplicateComplete

These two functions, together, can be used to duplicate a request.

When users find that a new request is a duplicate of an existing one, they can follow this procedure to mark the new one as a duplicate:

  1. Invoke MarkAsDupliate on the new request. This will create a new comment, as shown in Figure 20.
  2. The user then modifies the comment to add the existing request ID as the "Duplicate of Request ID."
  3. The owner of the new request should get notified and review it. (We created an email rule to notify the owner when a comment is added to a request.)
  4. The owner of the new request then invokes DuplicateComplete to close the new defect.
Figure 20. MarkAsDuplicate creates a comment
The new comment created by MarkAsDuplicate

Larger view of Figure 20.


To use this function, you must create Reject_Request resolution code for ALMTask, as shown in Figure 21.

Figure 21. Resolution code for Reject_Request
Resolution Code tab view

Otherwise, you will get the error message that Figure 22 shows.

Figure 22. Error message
Reject_Request is required to perform this action

Invoking Reject_Request will create a special task with a resolution code called Reject_Request, as shown in Figures 23 and 24.

Figure 23. Task created for Reject_Request 1
The task shown in the Requests view

Larger view of Figure 23.

Figure 24. Task created for Reject_Request 2
Resolution tab view of the task created

Larger view of Figure 24.

This function is different from the one for Change State > Reject_Solution, which will move the request to the Rejected state. Also, pre-existing tasks will be commented, requesting closure, and no additional tasks will be permitted once the ALL Task has been associated with a Request.


To use this function, WorkAsDesigned resolution code has to be created for ALMTask, as Figure 25 shows.

Figure 25. Resolution code for WorkAsDesigned
Resolution Code view for WorkAsDesigned

Otherwise, you will get the error messages that Figure 26 shows.

Figure 26. Error messages
WorkAsDesigned is required to perform this action

Figure 27 shows the task created.

Figure 27. Task created from WorkAsDesigned
The task in the Request view

Larger view of Figure 27.


To use this function, the Unreproducible resolution code has to be created for ALMTask, as shown in Figure 28.

Figure 28. Resolution code for Unreproducible
Resolution Code view

Otherwise, the result is the error message shown in Figure 29.

Figure 29. Error results if there is no corresponding resolution code
Unreproducible is required to perform this action

Reporting tools

There are two types of pull-based reporting tools supported by ClearQuest 7.1: BIRT and IBM® Rational® Insight.


BIRT reports can be created by using the Report Designer provided by the ClearQuest Eclipse client, as shown in Figure 30.

Figure 30. BIRT Report Designer
Report design in progress

Larger view of Figure 30.

Then the report design file is uploaded to the ClearQuest report server to actually run the report. That is where you see the report, as a user.

However, there are many small problems with this version of BIRT, so try it first.

Figure 31. A sample BIRT report
ClearQuest Reporting view

Larger view of Figure 31.

Rational Insight

You can use Rational Insight to report for all Rational tools. It is based on the IBM® Cognos® data warehousing tool, which can pull data from different sources and different tools. However, it also requires experts in data warehousing knowledge. It might be too heavy for a midsized or small organization. (See the Rational Insight page on IBM.com for more information.

Microsoft Excel

When neither of these solutions is ideal, you can use Microsoft® Excel®, which has been used in almost all organizations for reporting. For example, Figure 32 shows a report to show the status of software delivered for all applications changed in all ongoing projects.

Figure 32. A sample Excel report
Sample Excel report with 6 columns of data

Larger view of Figure 32.

Behind the scene, it's all Excel Visual Basic for Applications (VBA) code to call ClearQuest Visual Basic APIs (see Figure 33).

Figure 33. Excel VBA calls the ClearQuest API
Screen output to show how the report works in VBA

Larger view of Figure 33.

The advantage of this solution is that there is almost no limit to getting data from anywhere, as long as you can write the code. The drawback of this solution is the fat client has to be installed on the user's workstation to run the report. However, because most of these reports are used by management, this is not an issue.



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Rational software on developerWorks

ArticleTitle=Lessons learned in implementing Rational ClearQuest ALM in two large companies