Clone an ALMRequest

Jirong Hu (jirong.hu@gmail.com)

December 21 2009

1 The Requirement

The first requirement came from our deployment team. After a new release of an application is built, they are normally required to be deployed to different environments for different purposes. The deployment team requires a separate ALMRequest to be submitted for each deployment request to each environment. However, there is a lot common information among these ALMRequests including associated ALMTasks. So the deployment team is asking for a way to clone these ALMRequests. The requirements are:

1. Have a way to clone such an ALMRequest.
2. All fields in the original request must be coped, including ALMTasks.

2 The Design

There is a similar function available in the ALM schema for ALMProject as shown below:

It’s implemented as a record hook as shown below:

However, I am following this tech-note to implement my function to clone the ALMRequest:

Clone a defect (http://www.ibm.com/developerworks/rational/library/4379.html)

3 The Implementation

3.1 Add UI

Following the exact same way of Copy Project, we can copy these UI controls from ALMProject record and paste them here in the form of ALMRequest.

3.2 Add a New Field

Add a new filed for the headline of the cloned request if user wants to enter a new headline during the copy.

3.3 Add a Record Script

The Copy Request button will call the Record Hook, ALM_CopyRequest.

4 Source Code

Attached is the Perl source code for the record script:

Here are a few comments regarding the script:

1. CloneRecord function from the tech-note is used to clone all fields of ALMRequest.
2. However, the referenced field such as ALMTask and Comments canèt be cloned because one ALMTask can only be associated with one ALMRequest.
3. So all referenced fields have to be cloned individually as well.
4. After the referenced field is cloned, they also need to be modified to point to the new cloned ALMRequest.

ClearQuest Hook (Perl) to Limit the Size of Attachement

The VB version explains the logic and can be found here: http://www.ibm.com/developerworks/rational/library/3883.html

In ALM, three types of records have the attachement, ALMRequest, ALMTask and ALMActivity. A base action validation hook needs to be created for each of these record types.

sub ALMRequest_Validation {
    my($actionname, $actiontype) = @_;
    my $result;
    # $actionname as string scalar
    # $actiontype as long scalar
    # $result as string scalar
    # action is AttachmentzSizeLimit
    # record type name is ALMRequest
    # Start User Code
    # Return a non-empty string explaining why the action cannot commit
    # with its current values. If it is valid, return an empty string.
    # Example:
    #    my $value_info = $entity->GetFieldValue("some field");
    #    if (length($value_info->GetValue()) < 10) {
    #        $result = "Must be at least 10 chars long";
    #    }

    my ($attachmentFields, $attachmentField, $attachments, $attachment, $numfield, $numattach);
    my ($af, $a, $filename, $filesize);

eval {
    $attachmentFields = $entity->GetAttachmentFields();
    $numfields = $attachmentFields->Count();
    $session->OutputDebugString("numfields= $numfields\n");
}; if ($@) {  $session->OutputDebugString("GetAttachmentFields failed: $@\n");}

eval {
    for ($af = 0; $af < $numfields; $af++) {
     $attachmentField = $attachmentFields->Item($af);
     $attachments = $attachmentField->GetAttachments();
     $numattach = $attachments->Count();
     $session->OutputDebugString("numattach is: $numattach\n");

     for ($a = 0; $a < $numattach; $a++ ) {
     $attachment = $attachments->Item($a);
     $filename = $attachment->GetFileName();
     $filesize = $attachment->GetFileSize();
     # file size is always 0 before a first commit
     if ($filesize == 0) {
     #If it returns 0, we know that the file has been added during the current action, and is still on the local drive, so we check the FileSystemObject's filesize
     $filesize = -s $filename;
     }
     $session->OutputDebugString("filename=" . $filename . "filesize=" . $filesize . "\n");
     if ($filesize > 15000000) {
     $result = "$filename is too big, the limited size is 15M."
     }
     }
    }
}; if ($@) {  $session->OutputDebugString("GetAttachment failed: $@\n");}

    # End User Code
    return $result;
}

Bulk Load ClearQuest Users from a CSV File Using CQ Perl API

The format of CSV file is as follows:

Login  Name,User Name,Email,Role
orna.rabinovitz,Orna Rabinovitz,orna.rabinovitz@rci.rogers.com,STManager
madhava.reddy,Madhava Reddy,madhava.reddy@rci.rogers.com,STTester
nikhil.srivastava,Nikhil Srivastava,nikhil.srivastava@rci.rogers.com,STTester



These 3 Roles in this sample, being STManager, STLead and STTester, are already exist in CQ. The following Perl script will create a new user in CQ and set their:

• UserID and Password (empty)
• Full Name and Email Address
• LDAP enabled.
• Group

#!/usr/local/pure/releases/ClearQuestClient.2001.03.00/sun5/bin/cqperl
use Text::CSV;
$csv = Text::CSV->new();
open (AMDOCSUserInfo, "< C:\\Rogers2009\\ExportImport\\amdocs-users-cq.csv");

use CQPerlExt;

1. Create a Rational ClearQuest admin session

my $adminSession = CQAdminSession::Build();

1. Logon as admin

$adminSession->Logon( "admin", "", "7.0.0" );

1. Get the database object

$dbObj = $adminSession->GetDatabase("Roger");
die "Unable to get database!\n" unless $dbObj;

#Get the group "STManager" object
$groupSTManager = $adminSession->GetGroup( "STManager" );
$groupSTManagerName = $groupSTManager->GetName();
print ("STManager:$groupSTManagerName\n");

#Get the group "STLead" object
$groupSTLead = $adminSession->GetGroup( "STLead" );
#Get the group "STTester" object
$groupSTTester = $adminSession->GetGroup( "STTester" );

$n = 0;
while () {
#discard the first line of Request file
if ($n == 0) { $n++; next; }
my ($line) = $_;
chomp($line);
print "$line\n";

$status = $csv->parse($line); # parse a CSV string into fields
@columns = $csv->fields(); # get the parsed fields

# Login Name,User Name,Email,Role
$loginName = $columns[0];
$userName = $columns[1];
$emailAddress = $columns[2];
$roleName = $columns[3];
print ("$columns[0];$columns[1];$columns[2];$columns[3];\n");

eval {
# Create the user object
$newUserObj = $adminSession->CreateUser( $loginName );
die "Unable to create the user!\n" unless $newUserObj;
};

if ($@ =~ /is already in use/) {
next;
}

# Set the new user's password to secret
$newUserObj->SetPassword("");
$newUserObj->SetFullName($userName);
$newUserObj->SetEmail($emailAddress);
# $newUserObj->SetLDAPAuthentication($userName);
$newUserObj->SubscribeDatabase($dbObj);

# Add user to Group
#$groupSTTester->AddUser($newUserObj);
if ($roleName eq "STManager"){
$groupSTManager->AddUser($newUserObj);
}
elsif ($roleName eq "STLead"){
$groupSTLead->AddUser($newUserObj);
}
elsif ($roleName eq "STTester"){
$groupSTTester->AddUser($newUserObj);
}
}


$dbObj->UpgradeMasterUserInfo();

1. All done.

CQAdminSession::Unbuild($adminSession);

Installing a Web Application to an Existing IIS Website using Wix3

Removed upon request.

Setup VirtualBox Linux on Windows Vista

Jirong Hu

August 22, 2009

I used to work in large organizations and when a new colleague told me about VMWare, I said “What VM, get a new machine, we have pretty of money.” After a few years, it turned out that I was wrong. Now I started to work in small companies and have to constantly evaluate some new tools. VM is so much helpful in this case.

 

1 Microsoft VPC and Hyper-V

Early this year, I started using VPC and Hyper-V when I had to work on the Microsoft Team Foundation Server. While I was trying hard to install Windows 2003, SQL Server, TFS, MSVS 2008, I found this baby, a VPC image with everything in it: Visual Studio® Team System 2008 Team Foundation Server SP1 VPC Image (Trial), (http://www.microsoft.com/downloads/details.aspx?FamilyID=72262ead-e49d-43d4-aa45-1da2a27d9a65&displaylang=en)

By a simple installation of Microsoft Virtual PC, (http://www.microsoft.com/windows/virtual-pc/default.aspx), I have more than everything I want, and it’s all free! After this, I felled in love with these pre-loaded images. Whenever I need a new Windows 2003 for testing, I just create another copy of this VPC or Hyper-V image on Windows 2003 or 2008 servers.

 

2 Installing a Linux on Windows Vista

Today I need to have a Linux on my own laptop, so again I am looking into the VM solution.

2.1 VMWare Player

I knew there was free VMWare Player so I tried it first. After I installed the VM image for Ubuntu-7.10-server-i386 I downloaded somewhere, I found no login and password. Right, one of the problem I am having is there are so many varieties of Linux images out there, don’t know which one to pick.

VMWare Player can be downloaded from here: http://www.vmware.com/download/player/. The pre-loaded image with different guest OS can be downloaded from Virtual Appliances: http://www.vmware.com/appliances/

2.2 Sun VirtualBox

Then while I was searching Internet for other images, I found many people recommended this free VirtualBox from Sun. http://www.virtualbox.org/wiki/Downloads

Pre-loaded images can be found here: http://virtualbox.wordpress.com/images/

At first, I download this copy from here: http://virtualboximages.com/Mandriva-Linux-Free-KDE-2009.1-Beta. But I got a few errors as shown below:

This kernel requires the following features not present on the CPU:pae

Unable to boot – please use a kernel appropriate for your CPU.

I tried run this command with administrator privilege, seems not working still.

BCDEdit /set PAE forceenable

Then I downloaded this image, because I got a 64bit Vista installed. I got it run but it always crashes on GUI. Don’t know why.

http://virtualboximages.com/mandriva-free-2010-alpha-2-64bit

Then I go back to the previous 2009 version. http://virtualboximages.com/Mandriva-Linux-Free-KDE-2009.1-Beta

Finally I fixed the above error by enabling this setting shown below:

And also made the networking running by following this instruction (acutally not, in my case, the network is not connected. I click the Monitor and make it run):

Reseting the network adapter:
From the menu:Tools->System Tools->Network Center
Select the network adapter. Click on the disconnect button. Then click connect.

So now I have a Linux running on my Vista!

Below is the settings for the VirtualBox:

username: adminuser

password: adminuser

root password: adminuser

Below is my laptop, it’s a brand new Lenovo Thinkpad T500:

Installing a Web Application to an Existing IIS Website using Wix3

July 2009

Jirong Hu

This article describes a detailed procedure for installing a new web application under an existing IIS website, when Wix3 is used to create the msi file. This can be a common requirement in a large deployment. However, I find it's a lot of work to actually get it done and I hope this article can be useful to many other people like me. A complete set of sample code is also provided.

1 The Requirement
The SFS application I am working on used to have a fixed installation directory under the Default Web Site which is "C:\inetput\wwwroot\SFS". And one day we got a message from our deployment team:

Read the full article on CMCrossroads: http://www.cmcrossroads.com/content/view/13160/745/

Getting started with Rational Robot automation framework support (RRAFS)

Jirong Hu
15 Jun 2004
Rational Robot automation framework support (RRAFS) is one of the most popular data/keyword-driven test automation frameworks available today. This article will help you get started with the framework quickly and apply it to testing Web applications.
Editor's note: This article applies to IBM® Rational® Robot version 2001 and later, and RRAFS version 2003.08.27.00 and later.
Rational Robot Automation Framework Support (RRAFS), initially developed by Carl Nagle for the SAS Institute, is one of the most popular data/keyword-driven test automation frameworks available today. Having done a few small test automation projects and a lot of online reading, we adopted RRAFS just before starting a large testing project. We knew that with the additional layer of abstraction it offers, it brings test automation within reach for testers who aren't programmers and thus was perfect for our team of nontechnical testers. Still, it took us a few weeks to really become productive with RRAFS. One of the reasons is that because it's still new, it lacks a user guide, samples, and other resources. This article will fill the gap to help you get started with the framework quickly and apply it to testing Web applications. You can visit the main support site for RRAFS for more information.
Read the full article on IBM developerWorks: http://www.ibm.com/developerworks/rational/library/5028.html

Tips for IBM Rational Robot VU scripting

Jirong Hu
10 May 2005

Learn about some important concepts in VU scripting and put the programming tips to work in your projects.

VU script is the scripting language in IBM® Rational® Robot used for load and performance testing. This article aims to demystify some important aspects of VU scripting for load testing typical Web applications. The articles in Scott Barber's two series "User experience, not metrics" and "Beyond performance testing" are the best materials available on performance testing using Robot. This article supplements those, and I will refer to them here. I will also refer to UAT_Login.s, a sample login script I recorded to illustrate points in this article. Download the script at the bottom of this article.
VU script development normally starts after you have chosen the workload model for your particular load-testing project. It consists of these steps:

1. Record and split the scripts.
2. Search through each script to replace the hard-coded values with variables.
3. Unit test the scripts.

The following tips highlight some of the areas you should pay attention to when you start to modify the scripts.
Read the full article on IBM developeWorks: http://www.ibm.com/developerworks/rational/library/05/510_robot/

Using IBM Rational Robot Test Automation Framework Support (RRAFS) to Test Mainframe Applications

Jirong Hu (jirong.hu@gmail.com), Rational tools consultant, IBM

13 Jun 2005
Updated 05 Jul 2006

This article is an extension of Getting Started: IBM Rational Robot Test Automation Framework Support (RRAFS). Here the author explores using RRAFS for automated testing of mainframe applications.

Read the full article on IBM developerWorks: http://www.ibm.com/developerworks/rational/library/04/r-3170/

Handling Binary Files in IBM Rational ClearCase

Jirong Hu (mailto:jirong.hu@gmail.com?subject=Handling)
18 Jan 2007
Learn about certain circumstances where storing binary files in IBM® Rational® ClearCase® helps automate the build-and-release process in large organizations and make it smoother. This article also discusses issues with binary files and practical solutions to managing them in ClearCase implementations.
Over the years, we continue to face the increasing demand for a highly automated software build-and-release process within large organizations. IBM® Rational® Build Forge® makes it possible to achieve this within all of the IBM Rational Software Delivery Platform applications. There is always a huge debate on whether it's a good idea to store binary files in IBM® Rational® ClearCase® implementations or not. For example, see the discussion titled "How bad is [it] to store deployment units in ClearCase?" on the CM Crossroads Web site (see Resources).
This article explains certain circumstances where storing binary files in ClearCase can make the build-and-release process smoother. It also discusses merge problems with binary files and practical solutions to managing them in ClearCase environments.
Read the full article in IBM developerWorks: http://www.ibm.com/developerworks/rational/library/07/0424_hu/

Using mainline projects and composite baselines to manage large-scale J2EE development with IBM Rational ClearCase

 Jirong Hu (jirong.hu@gmail.com)

24 Jan 2006

In this article, Jirong Hu discusses how managing the release of large-scale development projects can be simplified by using some specialized ClearCase techniques.

Introduction
This article discusses some practical solutions to the management of large-scale J2EE development using IBM Rational ClearCase as the central of software configuration management system. Topics such as using a mainline approach together with composite baselines and some other useful techniques are discussed.
Note: The term "J2EE" refers to the Java 2 platform, Enterprise Edition, now more commonly referred to as "Java EE." For more detailed conceptual information on ClearCase, Unified Change Management (UCM) and Software Configuration Management (SCM) in general, readers can refer to the highly recommended resources in the References section.
In this article, a large-scale workplace is considered as a development environment if it is characterized with the following features. (A large bank is a good example.)

• Enterprise-level J2EE development with dozens of running projects
• Hundreds of releases from different projects that have to be coordinated
• Hundreds of end users
• Architecture-oriented design with dozens of interdependent subsystems

Read the full article on IBM developerWorks: http://www.ibm.com/developerworks/rational/library/06/0124_hu/

Migrating from Base ClearCase to UCM

Jirong Hu
December 15, 2008

1 Base ClearCase and UCM

The main objective of this article is to help readers do the actually migration, not to help them decide if UCM is more suitable for their environment. However, I think it is a good idea to have a bit comparison between Base ClearCase and UCM.
Let’s start with some good definitions about Base ClearCase and UCM I found from the Internet:
Base ClearCase consists of a collection of tools to establish an environment in which developers can work in parallel on a shared set of files, and project managers can define policies that govern how developers work together.

UCM is an out-of-the-box implementation of a development process layered upon base ClearCase. Adopting UCM makes it possible to manage your projects with ClearCase more quickly in an efficient manner without needing to master the details of base ClearCase.

UCM offers the convenience of a readily available management process; base ClearCase offers the flexibility to implement virtually any configuration management process that you deem appropriate for your environment.
To me, UCM is a later technology and more Object-Oriented. During implementation, this characteristic makes UCM easier for a ClearCase architect to map the ClearCase structure into modern programming methods such as C++ and Java, both conceptually and practically.
However, there are limitations in UCM, and also in many circumstances Base ClearCase is more suitable. We are not going to elaborate this topic in this article. Interested readers can find some good discussions in ClearCase Forum in developerWorks: http://www.ibm.com/developerworks/forums/thread.jspa?threadID=227980. The fact is, most likely we will see both Base ClearCase and UCM co-exist for a long time. And occasionally, we may need to migrate some projects from Base ClearCase to UCM or vice versa.
A real SCM environment in a large organization can be very complicated, e.g. multisited globally, ClearQuest or other products integrated, etc., to achieve a heavy weight process. Migrating ClearCase VOBs in such an environment is no longer a simple ClearCase job. In this article, we will not trying to cover all these complexities, but to give a general idea about what can be expected during such a migration from perspective of ClearCase. In the rest of sections, we will use a simply but real project as an example. This is a C/C++ project in telecommunication industry called HWC.

2 Business Requirements

Below is a list of Base ClearCase VOBs to be migrated into UCM in project HWC. VOB BMcore contains the project’s in-house developed source code, and the rest are mostly 3^rd party libraries.
* /vobs/projects/builds /data/storage/vobs1/builds.vbs
* /vobs/projects/BlueCat4_0 /data/storage/vobs1/BlueCat4_0.vob
* /vobs/projects/linuxIXAedu /data/storage/vobs1/linuxIXAedu.vob
* /vobs/projects/enp_cygmon /data/storage/vobs1/enp_cygmon.vob
* /vobs/projects/BMcore /data/storage/vobs1/BMcore.vob
* /vobs/projects/NPE_Firmware /data/storage/vobs1/NPE_Firmware.vob
* /vobs/projects/Doc /data/storage/vobs6/Doc.vbs
* /vobs/projects/HWC_3rd_Party_Lib /data/storage/vobs6/HWC_3rd_Party_Lib.vbs

2.1 Performance

This project has been run for a long time and the main source code VOB, BMcore, has been grown to more than 60G. The size of this VOB makes some of maintenance work extremely hard in our environment, so one purpose of this migration is to shrink this VOB.

2.2 Data Integrity

Except VOB BMcore, all history data has to be kept in other VOBs.

2.3 No Breaking Anything

An important requirement of this project is that the new ClearCase structure shouldn’t break any existing build/release/processes. Due to the time constrain and many hard-coded directory path in the build scripts, we can’t re-write the build scripts, although I think it’s a perfect time to re-structures it. In terms of ClearCase migration, we will not be able to redefine the VOB/Component structure, in order to keep the path name unchanged.

2.4 Live Branches Need to be Migrated

This is a live project and has many customers out there using a few major releases. These releases are currently maintained in a few branches in base ClearCase, and patches are released constantly. These branches therefore also need to be migrated into the new UCM structure.

2.5 Minimum Downtime

Usually such a migration will require minimum or even no downtime.

3 Solution

Based on the above requirements, we come out the following solution for this migration:

1. Define a UCM PVOB/VOB structure for this project and lay out a good foundation for further development.
2. We can not keep the in-house source code VOB BMcore in the new UCM environment. The solution is to create a new UCM VOB and copy certain code base to it.
3. For the rest of Base ClearCase VOBs, we will convert them into UCM component VOBs.
4. A method has to be developed to maintain the old build path so that the existing build script will still work.
5. Establish a good process to manage all new UCM projects.
6. Create new UCM projects/streams to replace live branches in Base ClearCase.

4 A New UCM Structure for HWC

4.1 Differences between UCM and Base ClearCase

If you are new to UCM, actually there are quite some differences between UCM and Base ClearCase. Here is my understanding:

1. UCM is OO based. Most of its terminologies are abstract concepts, just as in OO design. For example, whatever you see in the Project Explorer are OO objects. This is very important.
2. You are going to use more GUI based interface tools than in Base ClearCase. They are helpful.
3. In UCM, there are additional layers on top of VOBs in Base ClearCase. You use PVOB, projects and components to manage the assets. The Project in UCM can be mapped to the real project team, and component mapped to the sub-systems.
4. While in Base ClearCase, branches are mostly created implicated by a view config spec, you have to create streams in UCM explicitly.
5. A view is a super view in Base ClearCase, and you can use that to look into any VOBs by just changing config specs. This is not the case in UCM. You’ll have to create different views into the streams you want to look into. You don’t manage config spec directly. UCM does it for you.
6. There is no label in UCM, instead, you use baselines. Although there are still in the system, label is a Base ClearCase concept.

4.2 Naming Standards

A good naming convention can help you organize a clearly structured projects and streams and make users easy to read. Below is the naming convention I always advocate for most of organizations.

4.2.1 Admin VOB: <OrganizationName_Admin>

This is the organization wise Admin VOB for all VOBs, to share global types.

4.2.2 Line of Business Name: <LoB>

During to process, security and other reasons, projects are organized into different groups, different PVOBs in terms of ClearCase UCM implementation. The organization structure is a good place to find criteria in this case. This name will usually be mapped to PVOB names.

4.2.3 Official Project Name: <ProjectName>

Every project should have an official name defined by the Project Management Office. Strictly use this name with the exact case and spelling for easy communication and understanding among different groups across the organization. Use short term if possible.
The same should be applied for the <LoB> and <application_name>.

4.2.4 PVOB Name: <LoB>_PVOB

Projects in one organization group will likely share the same process. In this case, we put all components and projects under HWC_PVOB.

4.2.5 Component VOB Name: <LoB>_cvob

We group all applications in a few component VOBs for easy management and better performance.

4.2.6 UCM Component Name: <LoB>_<ApplicationName>_<ComponentName>_<ComponentType>

With <LoB> name attached, it’s easy to identify the component, especially in a multisited environment.
<component_type> can be one of these: src, docs, bin, model, etc. to identify the type of content stored inside the component.

4.2.7 UCM Project Name: <ProjectName>_mainline, <ProjectName>_<PhasesName>

With a naming standard, it’s a lot easy to find projects and components in ClearCase project explorer where all UCM objects are sorted by names.

4.2.8 UCM Project Folders: <BusinessFunction>

When there are too many projects in a PVOB, we can group them into different folders according to the business functions they belong to.

4.2.9 UCM Composite Baseline Name: <ProjectName>_CBL

CBL stands for “Composite Baseline”. This is the rootless component storing the project’s composite baseline. Every project will have only one, and shared by the mainline and all phase projects.

4.3 HWC UCM Design

As a result, we come out such a simple design in UCM as shown below:

1. HWC_PVOB will be the project and admin VOB for this project.
2. Create a new component VOB called BMnew, and a new component inside this VOB called BMcore to migrate certain code base from the old BMcore VOB.
3. Convert all the rest of Base ClearCase VOBs into UCM component VOBs.
4. Create a mainline project, hwc_mainline, as the bootstrap project.
5. Create another project, others_mainline, to manage all 3^rd party libraries.
6. Create new development project for each working branch in the old BMcore.

We will explain the details afterwards.

Figure 1: A New UCM Structure for HWC

4.3.1 Creating HWC_PVOB

To set up the above UCM structure, we have to create the project VOB first. Launch the VOB Creation Wizard and following the steps as shown below to create the new PVOB:

Figure 2: Create a New PVOB

4.3.2 Convert Base ClearCase VOBs to UCM Components

The next step is to convert VOBs in Base ClearCase to the new UCM environment. There are many ways you can do this step based on different requirements. In this project, because the existing build script doesn’t allow us to have any changes in the directories structure, so we will simply convert the existing VOBs in Base ClearCase to a component VOB in UCM. Other scenarios you may have are:

1. Converting multiple VOBs into a single component
2. Converting multiple VOBs into separate components in a single VOB
3. Converting VOB directories to separate components in a single VOB

You can find more information in Frank’s wiki on developerWorks:
http://www.ibm.com/developerworks/wikis/display/cm/How+to+migrate+from+ClearCase+VOBs+to+UCM+components
The following steps show how to convert all 3^rd party Base ClearCase VOBs into UCM component VOBs (single component VOB) in HWC_PVOB.

Figure 3: Convert Base ClearCase VOB to UCM Component

Figure 4: Choose the VOB List You Want to Convert

4.3.3 BMcore

For BMcore, we don’t want to simply convert the whole VOB into a UCM component as other VOBs, because we want to reduce the size of the VOB. What we will do is copy a few released code base into the new UCM environment and leave all the rest of history in the old Base ClearCase VOB BMcore.
We will create a new component BMcore@HWC_PVOB in a newly created component VOB BMnew, and copy certain released baselines over to the new mainline project. Afterwards, new phase projects will be created off these baselines.
There are a few things required:

1. Create a new multi-component VOB called BMnew.
2. Create a new component called BMcore inside the above VOB.

The rest of sections will describe how we set up the project in the new UCM environment.

4.3.4 Mainline Approach

We will adopt the mainline approach for the branching strategy in the new UCM structure. Please refer to Reference section for the difference between a mainline and cascading approach, and how you can implement a mainline approach in UCM.
Basically, each project will have a mainline project called <ProjectName>_mainline, and all subsequent phase projects will be created directly off the mainline, no cascading is allowed for any development projects.
A standard application/project will have the following set of UCM projects:

4.3.4.1 Mainline Project: <ProjectName>_mainline

The only purpose of the mainline is as the bootstrap project/stream for all other phase projects. In our case, the mainline for HWC will be called hwc_mainline.

4.3.4.2 Phase/Sibling Projects: <ProjectName>_<PhaseName>

For example, the version 5 release 1 project will be called hwc_v5r3. In this example, they are simply called v5r3.

4.3.5 HWC UCM Projects and Streams

A few new UCM projects will be created to manage all these applications. Official application/project names will be used as the UCM project name.

4.3.5.1 Mainline Project

This is the mainline project which will have the BMcore as the modifiable component and other components as read-only. It will be the boostrap project for other development projects.

Figure 5: Modifiable and R/O Components in Mainline
A composite baseline will be used to manage the projects:

4.3.5.2 Build Project

There will be a build project for each phase/development project. All components in this project should be read-only, and used only by build engineers. As an exception, this project can be created off each phase project since no development will happen here.
For example, the build project for release 5 project will be called v5r3_build.

4.3.5.3 others_mainline

We can manage the rest of converted component VOBs in one project. Let’s call it others_mainline in this example. This should be a single-stream project with all the rest of components as modifiable. All updated to these 3^rd party libraries can be performed in this project.

4.3.6 Build Root

This section is just to show you how symlinks can help when you are in a similar situation.
In order not to break the existing build scripts, we’ll have to keep the original file structure. Due to the additional VOB path of the new component for BMcore (now it’s /BMnew/BMcore in your view vs. /BMcore in Base ClearCase), we’ll have to find a workaround to keep the original file structure.
We can create another new component called buildroot inside BMnew and below that have a set of symlinks pointing to all converted components required by hwc_mainline.
Buildroot will be the root directory where developers and build engineer find there code as shown below. Ignore the rest they see in the view. Only this buildroot is required to be loaded into the snapshot view.

Figure 6: Use symlink to "relocate" components
The rest can be hided in their development view by not loading the other components as shown below (the screen below still loading the code):

Figure 7: Load only "buildroot"

Figure 8: Only buildroot is seen in a view

5 Processes

The purpose of this section is to provide a consistent process to manage the ClearCase projects’ lifecycles to ensure that:
v All software development groups have a common understanding.
v ClearCase UCM projects’ lifecycle fits into the software development process.
v This process is required when:
a. A system is ready to release to production.
b. A new development phase to be started.
c. A ECR fix starts
d. Changes need to be merged between running projects.

5.1 Process Flow Diagram

The diagram below takes the HWC project as an example to describe some common scenarios for a parallel software development environment.

5.2 Roles and Responsibilities

The table below lists the major responsibilities of each role in this process. The actual person who fit in the roles can be from either CM team or a project team.

Role	Responsibilities
Project Team	- Analysis project requirements - Raise change requests
ClearCase Administrator	- Analysis project requests - Propose/Test/Implement Rational solutions - Post-implementation actions
CM Team	- Review and approve the proposed Rational solution internally

5.3 Process Details

This section discusses each step in details.

5.3.1 Step1: Start Project

When a new software project/program launches, we always create a new ClearCase mainline project as the project’s foundation, with initial code base loaded onto mainline if there is any. In this case, the new project will be hwc_mainline.

The Project Team will request to CM team before the project launches.

5.3.2 Step2: Start v6

After that, the v6 project is created with that initial code. In the above diagram, v6 project was created with an initial baseline on hwc_mainline.
The Project Team will request to CM team to create the new project.

5.3.3 Release v6 to Production

Code to be released to production can be taken from a stable baseline from the development project. For example, baseline Release 6.1 from the project v6 will be released directly to production.
After production release, a new development project will be created for the following phase so that the existing project can be used for later ECR fix.
Project Team will request CM team to promote the production baseline to promotion level PRODUCTION after release.

5.3.4 Merge v6 back to mainline

The released baseline in v6 will be merged back to hwc_mainline, to be ready to start v7.
Project Team will request to CM team for a proper merge solution.

5.3.5 Start a v7 Project

Development work can continue with the v6 project as the maintenance project after the first release to production. In case a new v7 development project is required, the v7 project with be created with the merged baseline in mainline. In the above diagram, v7 will be created from the baseline Release1.1 in hwc_mainline.
Project Team will identify a baseline to start the new development project and CM team will help in find a proper solution to start the new phase project.

5.3.6 Deliver changes from v6 to v7

Changes should be delivered directly from v6 to v7 if required, not going though mainline.

Project Team will request to CM team for a proper merge solution.

5.3.7 Merge v7 to mainline

Code in v7 will also be merged back to mainline when required.

Project Team will request to CM team for a proper merge solution.

5.3.8 Group or feature streams

A group of developers can work in the same development stream to minimize the deliver/rebase overhead. There will be no deeper level streams created of this type of group stream.
A feature stream can be created to isolate some long-lived tasks that can’t be merged into the active integration stream in a short time. Different from a group stream, developers will join a feature stream to create sub-streams. Avoid feature streams depends on each other.

Project Team will request to CM team for a proper merge solution

5.3.9 Merge feature streams to v6

Feature steams should only be merged back to v6. Defer the integration of feature streams could make merge more difficult.

Project Team will request to CM team for a proper merge solution.

6 Migrating Branches

The project we are migrating is a running project and there are customers out there using a few versions of this product. This requires us to migrate a few running branches into the new UCM structure, so developers can do the maintained work for these released versions out there. This section describes how we can migrate these branches into UCM.

6.1 Cannot Compare Two Imported Baselines

There is this particular issue you need to be aware of during such a migration: two imported baselines can not be compared. The consequence is that later on they can not be used in an inter-project deliver/rebase or any action comparing two baselines are required.

Figure 9: Import Label as Baseline

Figure 10: Both Baselines Are Imported
The following error message will pop-up if you try to compare the above two imported baselines:

Figure 11: Error Message

6.2 Migration Approach for BMcore

Because we want to reduce the size of old BMcore VOB in base ClearCase, so we don’t want to directly convert this VOB into a UCM component in the new structure. Instead, we will just copy the code from each branch to the new corresponding UCM projects.
In order to make future inter-project deliver work in the new UCM structure, all sibling projects to be created in the new UCM structure have to be inherited from the same foundation baseline in the mainline so that they will have a common ancestor.
Here are live branches in base ClearCase we need to migrate. They all used to develop or maintain early releases.

1. v4_maint
2. v4r2_maint
3. v5_int
4. v5_maint
5. v5r1_int
6. v5r1_maint

There are labels in each branch, e.g.

1. “AS_V4R1_0_24”
2. “AS_V4R1_1_10”
3. “AS_V5R0_10033_0”
4. “AS_V5R0_10034_0”

For each live branch, we decide only to migrate the latest label and LATEST code to its new corresponding UCM projects in the new structure.
Based on the process described in Section 4, the following approach will be used to create all new projects:

1. clearfsimport the latest label on v4_maint branch, “AS_V4R1_0_10” , into BMcore component on mainline, create a new baseline, “AS_V4R1_0_10_Import”. This is the first baseline on the new mainline.
2. Use the above baseline as the foundation, create a new project, v4_maint, to be used for v4 release maintenance. This project is corresponding to the old v4_maint branch.
3. clearfsimport the LATEST code from branch v4_maint onto the above project, so now the code base on the new project is synchronized with the old branch, and developers can start further coding from there.
4. clearfsimport the latest label on next branch v4r2_maint on top of baseline “AS_V4R1_0_10_Import” on mainline and create a new baseline, v4r2_maint_Import.
5. Create a new project v4r2_maint. This project will replace the old v4r2_maint branch.
6. clearfsimport the LATEST code from branch v4r2_maint onto the new project, so now the code base on the new project is synchronized with the old branch, and developers can start further coding from there.
7. Repeat 4,5,6 for the rest of branches.

Because we always use clearfsimport to import the code, therefore all created baseline on mainline are comparable. The earliest baseline “AS_V4R1_0_10_Import” is their command ancestor.
Another approach is to create all new projects from the same foundation baseline on mainline:

1. clearfsimport the latest label on v4_maint,“AS_V4R1_0_10”, into BMcore component on mainline, create a new baseline, “AS_V4R1_0_10_Import”.
2. Create all new UCM projects for all branches from the above baseline, so that all these projects start from this same baseline. The new projects are:

1. v4_maint
2. v4r2_maint
3. v5_int
4. v5_maint
5. v5r1_int
6. v5r1_maint

1. Then clearfsimport latest label and LATEST onto each new project from their corresponding branch in base ClearCase, and make a new baseline.

The key to make the above approach work is always using clearfsimport to move the code, so that all baselines created in the process has a relationship.
Use the first imported baseline as the foundation for the mainline.

Figure 12: The Foundation Baseline for Mainline

6.2.1 Import label AS_V4R1_0_24

To import a label, create two views, a base ClearCase view to the base ClearCase and set the config spec as follows, and a dynamic view to the newly created UCM project.

Here is an example of clearfsimport command:
clearfsimport -recurse -nsetevent -rmname M:\jhu_view_mism122b\BMcore\* M:\jhu_hwc_mainline_int\BMnew\BMcore > C:\temp\import\import_AS_V4R1_0_24.out

6.3 Migration Approach for Other Projects

The import part is easier for the rest of 3^rd party component VOBs, because we can keep these VOBs. The process will be as follows:

1. Convert the Base ClearCase VOBs into components.
2. Import the latest label as a baseline in each component. Please note this is an imported baseline.
3. Set up the new project, others_mainline, as described in Section 3, using the above imported baseline as the foundation for the new project.
4. Import the Latest code from each branch in Base ClearCase to these new components, and create a new baseline.
5. Further update to these 3^rd party libraries will be performed in this new others_mainline project.

7 Reference

· Using mainline projects and composite baselines to manage large-scale J2EE development with IBM Rational ClearCase
· What is a mainline approach?

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.