Introducing ClearCase Report Builder

Jirong Hu (jirong.hu@gmail.com)
April 25, 2007
There are two reporting tools available from Rational for ClearCase: Report Builder in ClearCase and Rational SoDA. SoDA can be a good choice if your organization decided to use SoDA for reporting across all Rational products. However it requires additional licenses to run.
This article demonstrates how to use ClearCase Report Builder to generate various reports for your projects.

1 Installation

The Report Builder by default includes many standard reports. No additional installation and configuration is required for using these standard reports. The tool is located at Start à All Programs à IBM Rational à IBM Rational ClearCase à Administrator à Report Builder.

1.1 Sample Package

This package contains some reporting scripts customized for our organization. It shows you how to develop your own reports for your organization. You don’t have to install this package in order to use The Report Builder and it does not affect any standard features provided by Report Builder.

Extract the above zip file under C:\Program Files\Rational\ClearCase\reports\scripts. It will create the following additional “Sample” directory structure. Please note these customized reports depend a lot on our UCM design and you may not able to run them directly at your site.
Please create folder C:\Temp\ if you don’t have it. Some debugging logs will be created here. If you want to copy some data from the results, they are usually captured in the log files.

Figure 1: Sample package
When you develop your own reports later on, you can also create additional directory structure or store new scripts in any of these directories under /scripts.

2 Report Generation

Start the ClearCase Report Builder from Start à All Programs à IBM Rational à IBM Rational ClearCase à Administrator à Report Builder.
The Report Builder by default provides many standard reports as shown below. Online help is also available.

Figure 2: Report Builder

2.1 A Sample Report

The reports are listed in “The Tree Pane” (left), click one of the folders will list all available reports in that folder. Choose a report you want to run in “The Report Pane (top right), and fill in all required parameters in “The Parameter Pane”.
For example, the following example lists all “Activities Delivered Since Jan 1, 2007” in project/stream BNS_App_Common_Wave3:
Launch ClearCase Report Builder, select folder “UCM Streams” in the Three Pane and click on report “Activities Delivered Since Date” as shown below:

Figure 3: Sample Report: Activities Delivered Since Date
Click on parameter “Integration Stream” as shown blue in the Parameter Pane and select stream BNS_App_Common_Wave3_int from the screen below:

Figure 4: Choose an integration stream
Click on parameter “Date” as shown blue in the Parameter Pane and enter the Date and Time information:

Figure 5: Pick Date and Time
Then click “Run Report” button on top-left to generate the report:

Figure 6: With parameters

Figure 7: The result
You can right-click on each entry to get more details about each activity. This right-click feature is available in most of reports.

Figure 8: Property of selected activity

3 Creating Your Own

Quite often, your organization requires more than these reports as provided. Sooner or later you will have to develop your own reports. Fortunately it’s not that difficult with some knowledge in Perl scripting and ClearCase commands. This section shows you how to write a customized report.
The best available resource for Report Builder can be found in Appendix C of a ClearCase document named “IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects”. This appendix explains how Report Builder works with detailed information on workflow, interface and customization procedures. Have that appendix at hand while reading this section is a must. This article will not repeat information already covered in that appendix, but more focus on some clarifications from the author’s own experience using that appendix.
The following sections explain two customized reports for my organization and we will use that to point out some key areas in developing your own reports.

3.1 Sample1: Find the PRODUCTION baseline for my project

One constant issue comes back to ClearCase Administrators in our organization is: developers don’t know where is their production baseline when they need to fix an ECR. The reason is usually there are quite a few phases going on in parallel for one single project and some developers may not know exactly which one is in production at that moment.
There can be many solutions to resolve this issue, but in short, we use a promotion level called “PRODUCTION” to identify the baseline currently in production. So we want to provide a tool to let developers quickly find their production baseline, and from there they can fix an ECR.

Figure 9: A project in many phases
# Purpose: find the production baseline for my project, search any waves and phases.
# Input: the case-sensitive standard project name, e.g. STEPWeb. This is not a complete UCM project name because a project can has many UCM projects in different phases. The name has to be right and no validation will be done. The script actually looks for all baselines created on the shared rootless component used for composite baseline.
# Output: 1, the project/stream where the baseline is; 2, the rootless component where the baseline is created; 3, the production baseline name; 4, the promotion level of that baseline, which is PRODUCTION.


Before you start, we suggest you read through the sample customizations included in Appendix C to make yourself a bit familiar with the customization procedures.
Here is a high level procedure:

1. Design the report procedure interface specifications.
2. Decide the fields to be displayed in Report Viewer.
3. Find a proper “cleartool desc” command to get the information to be displayed.
4. Decide the right-click behavior.

3.1.1 The Script: Interface Definition

Now let’s take a close look on how to write this Report Procedure.
Code Block 1 defines the interface. Here we just need to take in a parameter telling us the project name. The parameters we can use are defined in Appendix C Table 9: Parameters supplied with Rational ClearCase Reports. Since there is no one listed fit into my requirement, I used the “STRING” parameter for our project name. Code Block 3 demonstrates how to get that parameter into variable $project inside the Perl script.
This project name is not a single UCM project name but the same name we used across all different phases. For example, the project “STEPWeb” can have multiple UCM projects called “STEPWeb_Wave1”, “STEPWeb_Wave3”, etc. to represent different development projects in different phases. However, they all share the same rootless component “_STEPWeb_CBL” to store the composite baselines as shown below.

What we need to do is just search all baselines created on this rootless component to see if their promotion level has been set to “PRODUCTION”. That’s how we specify a production baseline for a project.
Interface definition seems simple but probably the trickiest part of this report customization. It’s actually difficult to just make your own report appear in the Report Pane. If there is anything wrong with the interface definition or something else we don’t know, your report won’t be listed there and you don’t know why and there is nothing you can do! The Appendix C mentioned an ifaces.prl tool in package T0046 to verify your interface definition, but that won’t work and Rational is fixing that.
Our suggestion is when you start, take an existing report and start to modify little by little from there.

3.1.2 The Script: Output Field

Next you need to decide what kind of information you want to display to the user. In this example, the developers want to know which project/stream this baseline is created. So we give them The project/stream name where the production baseline is create, the rootless component name, the baseline name and the promotion level which should be just “PRODUCTION”. Standard fields are listed in Table11: Field type supplied with Rational ClearCase Reports. Use “string” if you can’t find anything fit. For example, I use “string” to display components, baseline, etc., as you can see in Code Block 2.

3.1.3 The Script: Get the Information

Now we know the project name and how can we find the production baseline. We just need to find some proper “cleartool” command to get the information we want. For this example, we know the rootless component name will be “_<Project_Name>_CBL” according to our naming standard in our organization. So we search all baselines created on this component with a promotion level “PRODUCTION” using the “cleartool lsbl” command (Code Block 1). The key here is how to properly use the –fmt option to get the result you want. The options are defined in “fmt_ccase”. It will be very helpful to be familiar with this command. The most important information for us is defined in Table 1: Variants for ClearCase and ClearCase LT objects and Table 2 : Variants for UCM objects.
For each baseline we found (in some cases, there can be multiple production baselines in our organization), we can find the stream they belong to by the “cleartool desc” command in Code Block 2. To display the result in Report Viewer, we just need to print them to the standard output using the “print” command in Perl.

3.1.4 The Script: Right Click Behavior

The right-click specification is a list of commands available on the right-click pop-up menu in the Report Viewer. They are usually used to provide some detailed information of the selected entry.

All right-click events are supported by a list of scripts in the \scripts_rightclick directory. In most of cases, you can simply define it in the output field and make a call to the subs defined in script script_tools\common.prl as shown in Code Block 4. Use extended property value for the field you want to provide right-click function.

3.2 Sample2: List all other projects using my baseline

In our UCM structure, a project uses other projects’ components as a read-only component. Sometimes a project team wants to know who is using their components. So this report lists out all other projects/streams use a particular baseline of a particular component.

Be Caution: This script can run long and take resources.

# Purpose: when you want to find out who's using your component.
# Input: a full baseline name, for example: baseline:BUILD_BNS_AppCommon_Wave3_7_2006_08_22.693@\Intralink_pvob
# Output: 1, the project/stream using your baseline; 2, the CBL including your baseline; 3, the promotion level of that CBL

3.2.1 The Script

Code Block 1 defines an input parameter to take in a full baseline name. Code Block 2 defines the output fields in Report Viewer. They are the composite baseline includes the input baseline, the stream where the composite baseline is and the promotion level of the composite baseline.
Now let’s see how we get the result we want to display to the user:

Code Block 1 find all composite baselines where the input baseline is a direct member. For each located composite baseline, Code Block 2 gets their streams and promotion levels.