clear quest user guide

Rational ® ClearCase and ClearQuest

Guide to Deployment Tracking

Version 7.0.0

Windows, UNIX, and Linux

GI11-6713-00

��

Before using this information, be sure to read the general information under “Notices,” on page 35.

7th edition (May 2006)

This edition applies to Version 7.0 of IBM Rational ClearCase and ClearQuest and to all subsequent releases and

modifications until otherwise indicated in new editions.

© Copyright International Business Machines Corporation 1992, 2006. All rights reserved.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract

with IBM Corp.

Contents

Figures . . . . . . . . . . . . . . . v

Tables . . . . . . . . . . . . . . . vii

About this book . . . . . . . . . . . ix

Who should read this book . . . . . . . . . ix

Related information . . . . . . . . . . . . x

Rational ClearCase documentation roadmap . . . x

Rational ClearCase LT documentation roadmap xi

Typographical conventions . . . . . . . . . xi

Contacting IBM Customer Support for Rational

software products . . . . . . . . . . . . xii

Downloading the IBM Support Assistant . . . xii

Chapter 1. Introduction to deployment

tracking . . . . . . . . . . . . . . . 1

Benefits of deployment tracking . . . . . . . . 1

Using Rational ClearCase and Rational ClearQuest to

track deployments . . . . . . . . . . . . 2

Chapter 2. Hardware and software

requirements for deployment tracking . . 5

Hardware requirements . . . . . . . . . . . 5

Software requirements . . . . . . . . . . . 5

Required configuration steps . . . . . . . . . 5

Chapter 3. Defining a release . . . . . 7

About releases . . . . . . . . . . . . . . 7

Creating a release . . . . . . . . . . . . . 7

Chapter 4. Defining roles . . . . . . . 9

About roles . . . . . . . . . . . . . . . 9

Why roles are important . . . . . . . . . . 9

Creating a role . . . . . . . . . . . . . . 9

Chapter 5. Defining environments . . . 11

About environments . . . . . . . . . . . 11

Creating environments . . . . . . . . . . 11

Chapter 6. Defining builds . . . . . . 13

About builds . . . . . . . . . . . . . . 13

Creating builds . . . . . . . . . . . . 13

State transition model for build records . . . . 13

Chapter 7. Tracking a deployment . . . 15

Using Rational ClearCase deployment units . . . 15

Introduction to deployment units and

deployment unit templates . . . . . . . . 15

About deployment unit template files . . . . 15

About deployment units . . . . . . . . . 16

Using Rational ClearQuest deployment records . . 17

About deployment records . . . . . . . . 17

Creating a deployment record . . . . . . . 17

State transition model for deployment records . . 18

Rational ClearQuest MultiSite considerations . . 20

About approvals and approval records . . . . . 20

State transition model for approval records . . . 20

Enabling e-signatures for approval authentication 20

Approving or rejecting an approval record . . . 21

Automatically notifying approvers using e-mail 21

Chapter 8. Running deployment

tracking queries and reports . . . . . 23

Running queries . . . . . . . . . . . . . 23

Running reports . . . . . . . . . . . . . 23

Chapter 9. The Tivoli Provisioning

Manager integration with Rational

ClearCase and ClearQuest . . . . . . 25

About Tivoli Provisioning Manager . . . . . . 25

Using workflows to model business processes . . 25

About data centers and data center assets . . . 25

About the integration . . . . . . . . . . . 26

Installing and configuring the integration . . . . 26

Using the integration to track and automate

deployment tasks . . . . . . . . . . . . 28

Importing versioned file artifacts into Tivoli

Provisioning Manager . . . . . . . . . . 28

Verifying deployment approval in Rational

ClearQuest . . . . . . . . . . . . . 29

Creating and updating Rational ClearQuest

workflow records . . . . . . . . . . . 29

Finding which version of a release has been

deployed . . . . . . . . . . . . . . 29

Workflows provided with the integration . . . . 29

Appendix. Notices . . . . . . . . . . 35

Index . . . . . . . . . . . . . . . 39

© Copyright IBM Corp. 1992, 2006 iii

iv IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking

Figures

1. An iteration of a development and deployment

lifecycle . . . . . . . . . . . . . . 1

2. State transitions for build records . . . . . 14

3. State transitions for deployment records 18

© Copyright IBM Corp. 1992, 2006 v

vi IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking

Tables

1. Rational ClearQuest built-in deployment

tracking queries . . . . . . . . . . . 23

2. Rational ClearQuest built-in deployment

tracking reports . . . . . . . . . . . 23

3. Workflows provided with the integration 30

© Copyright IBM Corp. 1992, 2006 vii

viii IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking

About this book

This manual describes how to use Rational ClearCase and Rational ClearQuest to

implement a role-based approval process for managing and tracking artifacts

through the build and deployment lifecycles.

In this manual, Rational ClearCase refers to both Rational ClearCase and Rational

ClearCase LT unless otherwise noted. References to Windows apply to all

Microsoft Windows platforms on which Rational ClearCase and Rational

ClearQuest are supported. References to the UNIX system apply to all platforms

running the UNIX system on which Rational ClearCase and Rational ClearQuest

are supported. References to Linux apply to all Linux platforms on which Rational

ClearCase and Rational ClearQuest are supported. For more information about

operating systems currently supported by Rational ClearCase, see the IBM Rational

ClearCase, ClearCase MultiSite, and ClearCase LT Installation and Upgrade Guide. For

more information about operating systems currently supported by Rational

ClearQuest, see the IBM Rational ClearQuest and ClearQuest MultiSite Installation and

Upgrade Guide.

Who should read this book

This book is intended for experienced project managers, build managers, and

release engineers who need to manage their build and deployment process. This

book assumes familiarity with basic Rational ClearCase operations such as using

views and versioned object bases (VOBs), and with basic Rational ClearQuest

operations such as applying packages to database schemas, working with record

types, and transitioning records between different states.

© Copyright IBM Corp. 1992, 2006 ix

Related information

Rational ClearCase documentation roadmap

More InformationCommand Reference

Online documentationHelp files

Installation and Upgrade Guide

Administrator's Guide(Rational ClearCase/

Rational ClearCase LT)

Administrator's Guide(Rational ClearCase MultiSite)

Platforms Guide(Rational ClearCase)

ProjectManagement

Orientation

SoftwareDevelopment

BuildManagement Administration

Guide to Managing Software Projects

IntroductionRelease NotesOnline tutorials

Developing Software (online help)

Guide to Building Software

OMAKE Guide(Windows platforms)

Administrator's Guide

Guide to Deployment Tracking(Rational ClearCase/Rational ClearQuest)

x IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking

Rational ClearCase LT documentation roadmap

More Information

Online documentationHelp files

Command Reference

Administration

ProjectManagement

Orientation

SoftwareDevelopment

Installation and Upgrade Guide

Administrator's Guide

Guide to Managing Software Projects

Online tutorials

Release Notes

Introduction

Developing Software (online documentation)

Typographical conventions

This manual uses the following typographical conventions:

v ccase–home–dir represents the directory into which Rational ClearCase, Rational

ClearCase LT, or Rational ClearCase MultiSite has been installed. By default, this

directory is /opt/rational/clearcase on the UNIX system and Linux, and

C:\Program Files\Rational\ClearCase on Windows.

v cquest-home-dir represents the directory into which Rational ClearQuest has been

installed. By default, this directory is /opt/rational/clearquest on the UNIX

system and Linux, and C:\Program Files\Rational\ClearQuest on Windows.

v Bold is used for names the user can enter; for example, command names and

branch names.

v A sans-serif font is used for file names, directory names, and file extensions.

v A serif bold font is used for GUI elements; for example, menu names and

names of check boxes.

v Italic is used for variables, document titles, glossary terms, and emphasis.

v A monospaced font is used for examples. Where user input needs to be

distinguished from program output, bold is used for user input.

v Nonprinting characters appear as follows: <EOF>, <NL>.

v Key names and key combinations are capitalized and appear as follows: Shift,

Ctrl+G.

About this book xi

v [ ] Brackets enclose optional items in format and syntax descriptions.

v { } Braces enclose a list from which you must choose an item in format and

syntax descriptions.

v | A vertical bar separates items in a list of choices.

v ... In a syntax description, an ellipsis indicates you can repeat the preceding item

or line one or more times. Otherwise, it can indicate omitted information.

Note: In certain contexts, you can use “...” within a pathname as a wildcard,

similar to “*” or “?”. For more information, see the wildcards_ccase

reference page.

v If a command or option name has a short form, a “slash” ( / ) character

indicates the shortest legal abbreviation. For example:

lsc/heckout

Contacting IBM Customer Support for Rational software products

If you have questions about installing, using, or maintaining this product, contact

IBM Customer Support as follows:

The IBM software support Internet site provides you with self-help resources and

electronic problem submission. The IBM Software Support Home page for Rational

products can be found at http://www.ibm.com/software/rational/support/.

Voice Support is available to all current contract holders by dialing a telephone

number in your country (where available). For specific country phone numbers, go

to http://www.ibm.com/planetwide/.

Note: When you contact IBM Customer Support, please be prepared to supply the

following information:

v Your name, company name, ICN number, telephone number, and e-mail

address

v Your operating system, version number, and any service packs or patches

you have applied

v Product name and release number

v Your PMR number (if you are following up on a previously reported

problem)

Downloading the IBM Support Assistant

The IBM Support Assistant (ISA) is a locally installed serviceability workbench that

makes it both easier and simpler to resolve software product problems. ISA is a

free, stand-alone application that you download from IBM and install on any

number of machines. It runs on AIX, (RedHat Enterprise Linux AS), HP-UX,

Solaris, and Windows platforms.

ISA includes these features:

v Federated search

v Data collection

v Problem submission

v Education roadmaps

For more information about ISA, including instructions for downloading and

installing ISA and product plug-ins, go to the ISA Software Support page.

xii IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking

http://www.ibm.com/software/rational/support/

http://www.ibm.com/planetwide/

IBM Support Assistant: http://www.ibm.com/software/support/isa/

About this book xiii

http://www.ibm.com/software/support/isa/

xiv IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking

Chapter 1. Introduction to deployment tracking

This chapter introduces deployment tracking concepts, and explains how Rational®

ClearCase® and Rational ClearQuest® facilitate the deployment tracking process.

Benefits of deployment tracking

The focus of software configuration management has historically been on

managing changes to software assets during the development phase of your

project. Your project artifacts, however, run on limited sets of hardware and

software with specific environment and configuration requirements. Therefore,

after your development phase is complete, you need to move your software

artifacts from your software configuration environment to your test environment,

and ultimately to your production environment. Examples of organizations who

need to do this include:

v An IT company running software in a data center with servers, firewalls, and an

application middleware stack

v A Systems Engineering company whose software is deployed to embedded

devices

Organizations who follow iterative software development processes need to

continually deploy software. An example phase of an iterative development and

deployment process is shown in Figure 1.

In a given iteration of your development process, your team performs functional

testing, where your software is deployed to test servers and tested. During testing,

defects are found, reported, and fixed, with the newly built application deployed

back to the test servers for additional testing. This cycle is repeated in each

SubmitRelease

ImplementBuild &Stage

Provisions &ValidateServers

SystemTest

ApproveRelease

IntegrationTest

PerformanceTest

Pre-productionTest

Production

E-Signature E-SignatureE-Signature

Source BuildArtifacts

Project Manager

Developer

Build Engineer

Deployer

Tester

Figure 1. An iteration of a development and deployment lifecycle

© Copyright IBM Corp. 1992, 2006 1

subsequent iteration of your development process. During this process, it is critical

for your team to know exactly which versions of your build artifacts you need to

deploy.

Using Rational ClearCase and Rational ClearQuest to track

deployments

Many organizations have multiple test environments through which their release

must pass before going into production; for example, required testing phases for a

release could consist of system testing followed by integration testing, performance

testing, and preproduction testing. In this model, when the release has met quality

standards for a given test phase, it moves forward to the next testing phase in the

sequence. If a problem with the release is discovered in any testing phase, the

deployment is rejected and the cycle repeats again, with developers correcting

defects in the product. As more software defects are fixed and your release

becomes more stable, you can implement more specialized and more rigorous

testing phases that your software must pass before it is deployed into a production

environment.

Some organizations require a release to be approved before it moves from one

testing environment to the next. Companies who must comply with regulatory

standards track and audit build processes and approvals of software deployments;

for example, these companies may require that a project manager keep records of

builds and approve releases using e-signatures. Rational ClearCase features build

auditing capabilities that enable you to keep bills of materials for your builds and

to access and reproduce previous build artifacts as needed. You can implement a

process for managing the deployment of your release through your test

environments using a Rational ClearQuest deployment record. A Rational ClearQuest

deployment record enables you to track the set of build artifacts that you want to

deploy through a link to a Rational ClearCase deployment unit. Each time you build

your release, you create a new deployment unit in Rational ClearCase that contains

a list of which versions of the build artifacts will be deployed. The Rational

ClearQuest deployment record uses the Rational ClearCase deployment unit to

track which build artifacts are deployed to which test environment at any point in

the project lifecycle.

Therefore, using Rational ClearQuest and Rational ClearCase to facilitate the build

and deployment process minimizes errors and inconsistencies that can arise during

the course of your deployment. Rational ClearCase provides you with build

management capabilities that enable you to identify the latest build at any time

and to access and reproduce previous builds as needed. Rational ClearCase and

Rational ClearQuest enable you to track your software deployment through your

specified test environments and to approve the deployment as needed, providing

audit trails for your software assets that satisfy regulatory compliance

requirements. You could then deploy your application to a production system by

integrating Rational ClearCase and Rational ClearQuest with a software

provisioning solution such as Tivoli® Provisioning Manager. This integration

automates your deployment process for your specific servers.

The following chapters illustrate how to use Rational ClearCase and Rational

ClearQuest to track deployments. All procedures described in the remainder of this

manual require that your Rational ClearCase administrator and your Release

Engineering manager have set up your development and build environments, and

that your Rational ClearQuest administrator has configured your schema

repository and user databases for deployment tracking. For more information

2 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking

about implementing a development and build environment using Rational

ClearCase, see the IBM Rational ClearCase Administrator’s Guide and the IBM

Rational ClearCase Guide to Building Software. For more information about applying

deployment tracking packages to your Rational ClearQuest schema repository, see

the Rational ClearQuest Help for Schema Developers.

Chapter 1. Introduction to deployment tracking 3

Chapter 2. Hardware and software requirements for

deployment tracking

Hardware requirements

Deployment tracking is supported on all platforms on which Rational ClearCase

and Rational ClearQuest are supported. For more information about operating

systems currently supported by Rational ClearCase, see the IBM Rational ClearCase,

ClearCase MultiSite, and ClearCase LT Installation and Upgrade Guide. For more

information about operating systems currently supported by Rational ClearQuest,

see the IBM Rational ClearQuest and ClearQuest MultiSite Installation and Upgrade

Guide.

Software requirements

Deployment tracking is a feature of Rational ClearCase and Rational ClearQuest

7.0. You must have Rational ClearCase and Rational ClearQuest 7.0 installed on

machines on which you plan to perform deployment tracking tasks.

For more information about installing Rational ClearCase, see the IBM Rational

ClearCase, ClearCase MultiSite, and ClearCase LT Installation and Upgrade Guide. For

more information about installing Rational ClearQuest, see the IBM Rational

ClearQuest and ClearQuest MultiSite Installation and Upgrade Guide.

Required configuration steps

If you have performed a standard installation of Rational ClearCase or if the path

to the cleartool executable has been specified in your PATH environment variable,

no further configuration steps are necessary.

If you have performed a non-standard install of Rational ClearCase or if the path

to the cleartool executable has not been specified in your PATH environment

variable, an extra configuration step is required. The deployment tracking feature

includes a Perl module called RD_utils.pm, which specifies the location of the

cleartool executable file. You need to edit the RD_utils.pm file to specify the path

to the cleartool executable. The cleartool executable is located in

ccase–home–dir\bin on all supported platforms. RD_utils.pm is located in

ratl-home-dir\common\lib\perl5\site_perl\ClearCase on all supported platforms.


Chapter 3. Defining a release

This chapter provides a definition of a release, and describes how to create a

release in Rational ClearQuest.

About releases

In Rational ClearQuest, a release is defined as the project on which you are

currently working or the application you are currently developing. A release is

represented as a record type in Rational ClearQuest. A release is used as a

foundation to track a deployment; all information related to your deployment will

be associated with the release record you create in Rational ClearQuest. Because a

release is critical to the deployment process, it is instrumental in meeting

compliance standards that require you to keep detailed records of your

deployment. You can track deployments for multiple releases within your

organization; for example, you may need to track deployment for multiple

products or multiple releases of those products.

Creating a release

A release is represented as a record of type DTRelease in Rational ClearQuest. Use

the following procedure to create a DTRelease record.

1. Click Actions > New DTRelease.

2. Fill in the required Name field.

3. Fill in the optional fields:

v Description. Provide a brief description of your application.

v UCM project. You can use this field to associate your release with your UCM

project. To specify the name of your UCM project in this field, click Add. A

dialog in which you can run a query is displayed. Run the UCMProjects

query to list all of the UCM projects that are defined in the current database.

Select the name of your UCM project from the list, then click OK.

v TPMServer. You can create a record of type TPMServer to represent your

deployment server host. To specify the name of your deployment server host

in this field, select its TPMServer record from the field's drop-down list. This

associates your release with your deployment server.4. Click OK.


Chapter 4. Defining roles

This chapter describes what function roles serve in deploying your release, and

how to define roles in Rational ClearQuest.

About roles

A role identifies an individual who is assigned to approve a deployment to move

from its current test environment into the next test environment in the

environment sequence that you have defined for a given release. You assign team

members to roles, and then associate the roles with releases. It is possible to define

many roles per release; for example, you could authorize a project manager to

approve a deployment to move from the system test environment to the

integration test environment, and an operations manager to approve the

deployment from the integration test environment to the preproduction test

environment and then finally to the production environment. It is also possible for

a given team member to be assigned to multiple roles that have been defined for

multiple releases; for example, a project manager authorized to approve

deployments for release X could also be authorized to approve deployments for

release Y. Rational ClearQuest supports this model by enabling you to create a

dynamic list of named roles for use across all of your organization’s releases.

For more information about how to create a list of roles, see “Creating a role” on

page 9.

For more information about managing approvals for a release, see “About

approvals and approval records” on page 20.

Why roles are important

Roles are needed in projects where approval is required to move a release from

one environment to the next. Examples of roles are Project Manager, Operations

Manager, Release Manager, and Test Manager. Roles are particularly important in

organizations where regulatory compliance is an issue. Assigning project team

members to roles; that is, authorizing people to approve releases, enables you to

create an audit trail for your deployment process. Additionally, an individual

acting in an assigned role is responsible for defining and verifying quality criteria

that your release must meet as it moves between environments during the

deployment process.

Creating a role

Prior to creating roles, you need to create role names modeled on the role hierarchy

in your organization. You can create a dynamic list of role types or role names in

Rational ClearQuest that can be used across all your releases. Use the following

procedure to create a list of roles.

1. Click Edit > Named List > Role_Names.

2. Right click to add a role name. Enter the name.

3. Press Return.

4. Click OK.


Repeat this procedure to create more role names as needed, then use the following

procedure to specify a role for a particular release.

1. Create a new record of type DTRole by clicking Actions > New > DTRole.

2. Fill in the required fields:

v Name. Choose a role name from the drop-down menu, which is populated

with role names from the dynamic list that you previously created.

v Release. Associate your role with a release record.

v Define Role members by selecting one or more Rational ClearQuest users.

These users will be accountable for approvals in the release that you have

specified.3. Click OK.


Chapter 5. Defining environments

This section describes the value of environments in the deployment process. It

provides instructions on how to set up environments for your release and how to

transition your deployment through your defined environments during release

testing.

About environments

An environment represents a phase of testing that your release needs to pass before

it is sent to production. You define a specific set of environments for a particular

release. An example of environments that you could have for your release are unit

test, functional test, integration test, and preproduction test. It is important to

define the correct sequence of environments for a release. The tests that your

release must pass in one environment should hold your release to higher quality

standards than the tests that it passed in its previous environment, so that your

release improves in quality and stability as it advances from one environment to

the next environment in your sequence.

Creating environments

Use the following procedure to create environments for your release.

1. Create a new record of type DTEnvironment by clicking Actions > New >

DTEnvironment.


v Environment name. Give the environment a name.

v Release. Associate the environment with a release.

v Environment sequence. This field specifies the order of environments

through which your release can transition. The set of environments defined

for a release must be a unique sequence.3. Choose the optional Roles_for_approval field to enable approvals for

deployment to this particular environment. You can only select roles defined

for the release with which you have associated your environment. If

deployment to this environment does not require any approvals, then no roles

are selected.

4. Click OK.


Chapter 6. Defining builds

This section describes how to associate your release with a build so that you can

track the status of your builds throughout the deployment process.

About builds

A build represents a particular instance of a build of your release. Builds are

defined in Rational ClearQuest by records of type BTBuild. You can use build

records to track information about your build through your deployment lifecycle,

such as the dates that the build started and ended, whether or not the build was

successful, and with what release the build is associated.

Creating builds

Use the following procedure to create a build for your release:

1. Create a new record of type BTBuild by clicking Actions > New > BTBuild.

2. Rational ClearQuest automatically populates the following fields in the build

record:

v ID. A unique ID is assigned to the build record.

v Start_DateTime. The date and time at which you started your build is

recorded.

v End_DateTime. The date and time at which your build ended is recorded.3. Fill in the required ReleaseName field. This associates your build with the

release on which you ran the build.

4. Fill in the optional fields:

v Build_System_URL. This provides a link to the build system Web page, if

applicable.

v Build_System_ID. Give your build an ID.5. Click OK.

After the build record is submitted, a new field called BuildLog is added to the

record. You can use this field to record notes about your build.

State transition model for build records

The available actions between states defined for the BTBuild record type are shown

in Figure 2.


You can create a build record at the start of a build process for your application.

When a build record is created, it is in the Submitted state. After the build has

completed successfully, the Complete action is run on the build record. This action

can be run either manually by a build engineer or automatically through a build

script. After the Complete action has been taken, the state of the build record is

transitioned to Completed. The build record can then be transitioned from the

Completed state to the Retired state to indicate that it is out of date and no longer

required.

If the build does not complete successfully, the Failure action is run on the build

record. This action transitions the build record from the Submitted state to the

Failed state. The build record can be transitioned from the Failed state to the

Retired state to indicate that it is no longer needed.

Failed

CompletedSubmitted Retired

Failure Retire

Complete Retire

BuildAborted

BuildNo longerneeded

SubmitNewBuild

Resubmit

Figure 2. State transitions for build records


Chapter 7. Tracking a deployment

To track your release through the deployment process, you create a deployment

unit based on the results of your most recent build, associate it with a deployment

record, and then transition the deployment record through your defined

environments, enabling you to track your versioned artifacts as they progress

through your test phases. This chapter describes how to achieve these tasks using

Rational ClearCase and Rational ClearQuest.

Using Rational ClearCase deployment units

Introduction to deployment units and deployment unit

templates

A deployment unit is an instance of a deployment unit template. A deployment unit

template file stores information in XML format about files in your VOB that you

want to deploy. Data included in the deployment unit template file are a history

entry noting when your template file was created, who generated the template file,

and the paths of files in the VOB that you want to deploy.

A deployment unit, which is also represented in Rational ClearCase as an XML file,

is then created from the deployment unit template. Data included in the

deployment unit are a history entry noting who generated the deployment unit,

when the deployment unit was created, and version URIs of files in your VOB that

you want to deploy. A file's version URI uniquely identifies the file in such a way

that it can be located through any view in any replica of the VOB in which it is

stored.

At this point you can optionally configure a provisioning solution, such as Tivoli

Provisioning Manager, to extract the versions of the files specified in the

deployment unit from your VOB onto a deployment system. For information about

how to integrate Rational ClearCase and Rational ClearQuest with Tivoli

Provisioning Manager, see Chapter 9, “The Tivoli Provisioning Manager integration

with Rational ClearCase and ClearQuest,” on page 25.

The deployment unit template and deployment units are managed using a Rational

ClearCase command-line utility called du_tool. The du_tool utility is used to

perform a number of different operations on deployment units. For a detailed

explanation about usage options for du_tool, see the du_tool reference page in the

IBM Rational ClearCase Command Reference.

About deployment unit template files

This section describes how to create deployment unit template files and verify that

they consist of valid XML.

Creating a deployment unit template file

The first step in the deployment process is to create a deployment unit template

XML file. The deployment unit template XML file captures the path names of files

in your VOB that you want to deploy.

You can use handwritten XML to manually create a deployment unit template that

lists all the versioned files that you want to deploy. The deployment unit template


must conform to the XML schema as defined in the deployment_unit.xsd file that

is shipped with Rational ClearCase. The deployment_unit.xsd file is located in the

directory ccase–home–dir\etc on all supported platforms.

To verify that a deployment unit template consists of valid XML, run du_tool with

the verify option on the deployment unit template XML file. For an example of

how to run du_tool with the verify option to validate your deployment unit

template file, see Verifying a deployment unit template file.

Alternatively, you can create your deployment unit template using du_tool with

the generate option. In the following example, an XML file called myApp_du.xml

that lists all build artifacts in \testvob that will be deployed is created by running

du_tool with the generate option:

Z:\testvob>RATLPerl "C:\Program Files\Rational\ClearCase\etc\du_tool.pl"^

--generate --directories \testvob --name "My Test App" --version 1.0^

--tag my_view --out myApp_du.xml

After you have created the deployment unit template file, add it to version control:

Z:\testvob\deployment_units>cleartool mkelem^

-c "creating deployment unit template" myApp_du.xml

Verifying a deployment unit template file

If you did not use du_tool to create your deployment unit template file, you can

verify that the file contains valid XML by running du_tool with the verify option.

In the following example, the XML content of the deployment unit template

myApp_du.xml is verified :


--verify myApp_du.xml

About deployment units

After your build and release engineers have built and staged the files that need to

be updated for your release, create a deployment unit to manage version

information about the files stored in your VOB that you want to deploy.

To create a deployment unit, run du_tool on your deployment unit template file

with the decorate option. This operation, which is called decorating the

deployment unit, creates version URIs that link each file listed in the deployment

unit template with a specific version of that file in the VOB.

After you have decorated the deployment unit, run du_tool with the resolve

option. This operation, which is called resolving the deployment unit, resolves the

version URIs of the files listed in the deployment unit to version-extended path

names. These version-extended path names enable your deployment tool to access

the correct version of each file through the Rational ClearCase view that is being

used in the deployment process, ensuring that you deploy the correct version of

each file to your deployment system.


Creating (decorating) a deployment unit

In the following example, a deployment unit called myApp_du_decorated.xml is

created by running du_tool with the decorate option on the template file that you

created in Creating a deployment unit template file:


--decorate myApp_du.xml --tag my_view --out myApp_du_decorated.xml

Check out myApp_du.xml, and create a new version of myApp_du.xml from your

decorated deployment unit. Check myApp_du.xml in to your VOB.

Resolving a deployment unit

In the following example, a deployment unit file called myApp_du_resolved.xml is

created by running du_tool with the resolve option on myApp_du_decorated.xml,

the decorated file that you created in Creating (decorating) a deployment unit:


--resolve myApp_du_decorated.xml --tag my_view --out myApp_du_resolved.xml

Check out myApp_du.xml, and create a new version of myApp_du.xml from your

resolved deployment unit. Check myApp_du.xml in to your VOB.

Using Rational ClearQuest deployment records

About deployment records

Rational ClearQuest supports a deployment approval process through creation of

deployment records; that is, records of type DTDeployment. You associate each

deployment record you create in Rational ClearQuest with a release record. If

approvals are required in your deployment process, each deployment record will

be associated with one or more approval records. You then use Rational ClearQuest

to transition the deployment record through the ordered testing environments in

your release’s deployment process, obtaining approval from the appropriate role

(or roles) before the deployment record moves from its current environment into

the next environment in the series.

The optional Rational ClearQuest TPM (Tivoli Provisioning Manager) package

enables you to associate the location of a Tivoli Provisioning Manager server with

a release. When this association is configured, each instance of a deployment

record in Rational ClearQuest will have a URL link to the Tivoli Provisioning

Manager Web interface. You can click on this link to display the Tivoli Provisioning

Manager Web interface in an external Web browser. This provides a user interface

integration between Rational ClearQuest and Tivoli Provisioning Manager.

Creating a deployment record

Use the following procedure to create a deployment record in Rational ClearQuest.

Note: You cannot use this procedure if you are using the Rational ClearQuest Web

interface. Creation of deployment records is not supported in the Rational

ClearQuest Web client.

1. Create a record of type DTDeployment by clicking Actions > New >

DTDeployment.


Chapter 7. Tracking a deployment 17

a. Headline. Provide a short description of your deployment.

b. Release. Associate this deployment record with the release that you are

deploying. After the release is specified, the Environment field is populated

with the name of the first environment in your defined sequence.

c. Owner. Designate a Rational ClearQuest user as the owner of this

deployment.

d. Deployment_unit_reference. Associate the deployment record with a

deployment unit.

Note: The deployment unit referenced in this field must be a versioned file

in a VOB.

1) Click the Browse button. This will launch a File browser window.

2) Choose the deployment unit XML file that you created in “Creating

(decorating) a deployment unit” on page 17.

You have now established an association between your deployment

record and your deployment unit. This association enables you to track

your build artifacts through your testing environments over the course

of your deployment process.

3) Click OK.

State transition model for deployment records

The DTDeployment record type typically has at least one state transition path that

includes the following transitions: Ready > Deployed > Retired. Available

actions between states defined for the DTDeployment record type are shown in

Figure 3.

You can create a customized state transition model for your environment. For more

information about customizing state transition models, see the Rational ClearQuest

Help for Schema Developers.

When a deployment record is submitted, it is in the Ready state.

Ready Deployed Retired

Failed

Deploy Retire

Ready

Fail

Figure 3. State transitions for deployment records


v If an approval is required for this deployment, Rational ClearQuest

automatically creates an approval record for every role associated with the

current environment. The Approval status field in the deployment record is set

to Not Approved.

v If no approval is required for this deployment; that is, if no roles have been

defined for the current environment, Rational ClearQuest sets the Approval

status field in the deployment record to No approvals required.

The following sections explain how to transition a deployment record through

these typical states.

Moving a deployment record through the deployment and

approval process

Transitioning a deployment record from the Ready State to the Deployed state

Use the following procedure to transition a deployment record’s state from Ready

to Deployed:

1. Select your deployment record.

2. Click Actions > Deploy.

3. Click Apply.

4. If the deployment record’s Approval status field is set to Approved or to No

Approvals Required, the record gets transitioned to the Deployed state to

indicate that the Deploy action was successful. If the approval status field value

is set to Rejected or Not Approved, a message will be produced saying that one

or more approvals are not complete. In this case, you need to approve all

approval records associated with your current environment before continuing

with the deployment process. For information about how to approve an

approval record, see “Approving or rejecting an approval record” on page 21.

After you have approved all approval records associated with your

environment, click Actions > Deploy again to continue.

Transitioning a deployment record from its current environment to the next

environment

After all approvals have been completed for your deployment record, you can then

move it to the next environment in your sequence; that is, you can transition the

state of the record from the Deployed state for its current environment to the

Ready state for the next environment.

Use the following procedure to transition the deployment record’s state from

Deployed to Ready:

1. Select your deployment record.

2. Click Actions > Ready. After this action is applied, the environment field is

populated with the name of the next environment in the sequence.

3. Click Apply. The deployment record’s state changes to the Ready state in the

next environment for your release.

After you have moved your deployment record through all your environments;

that is, when there are no more environments in which further deployment actions

can be performed, then you can retire your deployment record. Alternatively, if

your deployment fails tests in any one environment, you can indicate that your

deployment has failed.

Note: When you have retired the deployment record or indicated that the

deployment has failed (that is, when the deployment record is either in the


Retired or Failed state) you can no longer transition the deployment record

to any other state. If you need to restart a deployment on a particular

release, you will need to create a new deployment record.

Retiring a deployment record

To retire a deployment record, select it and click Actions > Retire, then click

Apply. The state of the record changes to Retired.

Note: A record cannot be transitioned from Retired or Failed to another state. To

restart a particular deployment, you must create a new deployment record.

Indicating a failed deployment

To indicate that a deployment has failed, select your deployment record and

choose Actions > Failure, then click Apply. The state of the deployment record

changes to Failed.

Rational ClearQuest MultiSite considerations

Rational ClearQuest deployment records and their associated approval records

must be mastered by the same replica. If these records are not mastered by the

same replica, Rational ClearQuest will produce an error when you try to approve

the approval record.

About approvals and approval records

Implement an approval process for your organization if you want one or more

people to manage and maintain control over the quality engineering process. This

ensures that as your release moves forward in the deployment process, the

release’s level of quality increases appropriately.

Approvals are represented in Rational ClearQuest as records of type DTApproval.

When you transition a deployment record from one state to another (for example,

from the Deployed state to the Ready state) the value of the record’s Environment

field changes to the next test environment in the sequence that you have defined

for that release’s approval process. If the environment requires approval, a record

of type DTApproval is created by Rational ClearQuest for each role defined for

your release.

State transition model for approval records

Possible state transitions for the DTApproval record type are Submitted >

Approved or Submitted > Rejected.

Enabling e-signatures for approval authentication

You can mandate that approvers for a given release authenticate themselves when

approving or rejecting an approval record by requiring them to use an e-signature.

Use the following procedure to require e-signatures for approvals:

v Create an e-signature record by clicking Actions > New > eSig_Config.

v Enter DTApproval in the Record_Type field.

v Choose Approve and Reject in the Sign_By_Action field.

v Click OK.


After you have configured e-signatures, an approver will be required to enter their

user name and password before approving or rejecting an approval record.

Rational ClearQuest compares these credentials with the values with which the

approver logged in to the Rational ClearQuest client. If they match, then the

change is accepted and the signature is logged. If they do not match, an error

message is displayed and no change is made to the Rational ClearQuest database.

Approving or rejecting an approval record

Use the following procedure to approve an approval record; that is, to transition an

approval record from the Submitted state to the Approved state:

1. Log in to the Rational ClearQuest client with your credentials and run the My

Approvals query.

2. Select your approval record.

3. Click Actions > Approve.

4. Click Apply.

Use the following procedure to reject an approval record; that is, to transition an

approval record from the Submitted state to the Rejected state if your release fails

tests at any stage in the testing process:

1. Click Actions > Reject.

2. Click Apply.

3. Fill in the mandatory comments fields to explain why the approval record has

been rejected.

4. Click Apply.

Automatically notifying approvers using e-mail

You can configure e-mail rules to send messages to approvers when approval

records require their attention. For more information about how to configure e-mail

rules, see the Rational ClearQuest Help for Administrators.

Note: In order to receive e-mail notifications through e-mail rules, you need to

enable e-mail notifications in your Rational ClearQuest client. For more

information on enabling your Rational ClearQuest client to receive e-mail

notifications, see the Rational ClearQuest Help for Users.


Chapter 8. Running deployment tracking queries and reports

Running queries

Rational ClearQuest provides built-in queries to retrieve information about roles,

environments, deployments, and approvals from the Rational ClearQuest user

database. These queries are located in the Deployment Queries folder under the

Public Queries folder. Table 1 lists and describes deployment tracking queries that

are built in to Rational ClearQuest.

Table 1. Rational ClearQuest built-in deployment tracking queries

Query Description

ActiveDeploymentsForRelease Displays all active deployment records (that

is, records whose states are not Retired or

Failed) for one or more releases

ApprovalsForDeployment Displays all approvals for one or more

deployments

DeploymentsForRelease Displays all deployment records for one or

more releases

EnvironmentsForRelease Displays all environment records for one or

more releases

MyApprovals Displays approvals assigned to the current

user that are in the Submitted state

RolesForRelease Displays all role records for one or more

releases

UCMProjects Selects all UCM projects in the current

database

You can also create your own customized queries as needed. For more information

about creating customized queries in Rational ClearQuest, see the Rational

ClearQuest Help for Users.

Running reports

Rational ClearQuest provides built-in reports that enable you to retrieve

information about the status of your deployments and approvals from the Rational

ClearQuest user database. These reports are located in the Reports folder under the

Public Queries folder. The associated report formats are located in the Report

Formats folder under the Public Queries folder. Table 2 lists and describes

deployment tracking reports that are built in to Rational ClearQuest.

Table 2. Rational ClearQuest built-in deployment tracking reports

Report Description

ActiveDeployments (All) Reports the status of all active deployments

(that is, deployments whose states are not

Failed or Retired) for a release

Approvals (Status) Reports the status of all approvals for a

deployment


You can also create your own customized reports as needed. For more information

about creating customized reports in Rational ClearQuest, see the Rational

ClearQuest Help for Users.


Chapter 9. The Tivoli Provisioning Manager integration with

Rational ClearCase and ClearQuest

This chapter describes how to use the Tivoli Provisioning Manager with Rational

ClearCase and Rational ClearQuest to facilitate deployment of your release to a

production server.

About Tivoli Provisioning Manager

Tivoli Provisioning Manager is a resource management solution that provides core

automated provisioning capability for corporate and Internet data centers. It

coordinates and provisions assets based on your defined business processes. You

can use Tivoli Provisioning Manager to provision, configure, and deploy a release

into your production environment.

Using workflows to model business processes

To model your business processes, Tivoli Provisioning Manager introduces the

concept of workflows. You can use workflows to automate and consistently repeat

configuration and deployment tasks that you currently perform manually. Tivoli

Provisioning Manager provides workflows that you can customize to support your

existing tools and processes. You can also create new workflows.

Workflows can automate processes from configuring and allocating servers, to

installing, configuring, and patching software, and can be either large and complex

or can consist of a single command. The automation of configuration tasks is called

automated provisioning.

About data centers and data center assets

The workflow framework enables you to manage your data center infrastructure. A

data center infrastructure is made up of devices and integrated systems, called data

center assets. Data center assets include both physical and logical assets, such as:

v Servers that support managed applications

v Network devices such as switches, routers, load balancers, and firewalls that

support communication between servers and applications

v Logical assets such as subnetworks and ports

v Service access points and access control lists that support secure data

transmission

v Software products, software stacks, and software service releases

v Storage devices

Tivoli Provisioning Manager manages a virtual representation of your data center

in a data center model. Virtualization exists on several levels to provide flexible

configuration in different contexts:

v Each asset is represented by a data center object. When you make a change to an

asset with Tivoli Provisioning Manager, the data center object is updated in the

data center model. If a change is made outside of Tivoli Provisioning Manager,

the external change can be identified by comparing it with the data center object

in the data center model.


v For some data center assets, the data center model stores data about the asset

and data about deploying or provisioning the asset separately to provide a range

of implementation options. For example, when a software package is added to

the Tivoli Provisioning Manager software catalog, you define the software

package as an installable file. You can then create software definitions that

describe different configuration requirements and configuration options for

installing the same software package.

v You can create templates that define standard configurations. For example, you

can create a server template that includes the routing, software, and storage

configuration for a particular application tier. When a server is added to the

application tier, the defined configuration is automatically applied.

v You can define application topologies that describe requirements for an

application. You can then deploy an application based on the defined application

requirements.

For more information about Tivoli Provisioning Manager workflows, data center

assets, and data center models, see the IBM Tivoli Provisioning Manager Workflow

Developer's Guide.

The following sections describe how the Tivoli Provisioning Manager integration

with Rational ClearCase and Rational ClearQuest can help you automate the

deployment of your artifacts into production and track the status of your

deployment process.

About the integration

The Rational ClearCase integration with Tivoli Provisioning Manager enables you

to extract versioned file elements from Rational ClearCase and import them into

the Tivoli Provisioning Manager deployment environment, ensuring that the

correct versions of your files are deployed.

The Rational ClearQuest integration with Tivoli Provisioning Manager does the

following:

v Enables Tivoli Provisioning Manager to check for deployment approval status in

Rational ClearQuest, ensuring that your deployed release meets established

quality standards.

v Enables workflows to be represented as Rational ClearQuest records, facilitating

deployment tracking and reporting.

v Enables traceability between workflows and Rational ClearQuest deployment

records, providing an audit trail that helps satisfy your organization's process

and regulatory compliance requirements.

Installing and configuring the integration

This section describes installation and configuration steps you need to follow to

integrate your Rational ClearCase and Rational ClearQuest environment with

Tivoli Provisioning Manager.

1. If you have not already done so, apply the TPM package to your Rational

ClearQuest database schema. This package enables the Rational ClearQuest

integration with Tivoli Provisioning Manager. For information about how to

apply packages to your database schema, see the Rational ClearQuest Help for

Administrators.

2. Install and configure Tivoli Provisioning Manager by following the instructions

in the IBM Tivoli Provisioning Manager Installation Guide.


3. Download the Rational Deployment Automation Package that enables the

integration from the IBM Tivoli Open Process Automation Library (OPAL) Web

page at http://catalog.lotus.com/wps/portal/topal/. This automation package

installs workflows, scripts, and other utilities for use with the integration. For

information about workflows that are provided with this integration, see

“Workflows provided with the integration” on page 29.

4. Follow these steps to install the automation package:

a. Copy the Rational Deployment Automation Package file,

<automation-package-name>.tcdriver, to the %TIO_HOME%/drivers

directory.

b. Navigate to the %TIO_HOME%/tools directory.

c. Run the command:

v On hosts running Windows®:

tc-driver-manager.cmd installDriver <automation-package-name>

v On hosts running Linux® or the UNIX® system:

tc-driver-manager.sh <automation-package-name>

5. Install Cygwin, an interface that provides the look and feel of Linux, and

Secure Shell (SSH), a command-line interface used for secure remote

communication, on all hosts that run Windows and that run Rational

ClearCase, Rational ClearQuest, or both for deployment tracking.

Cygwin and SSH are automatically installed with Tivoli Provisioning Manager,

so you do not need to install it on Rational ClearCase and Rational ClearQuest

hosts on which Tivoli Provisioning Manager is also installed.

Follow these steps to install Cygwin and SSH:

a. Install Cygwin by following the instructions in the IBM Tivoli Provisioning

Manager Installation Guide. The installation process shows SSH as an

optional network component. Clear this option if it is selected.

b. Create a system environment variable called CYGWIN and give it the value

tty ntsec.

c. Assign the directory path where Cygwin is installed to the PATH

environment variable. For example, if you installed Cygwin in the default

installation directory, C:\cygwin, you would enter this directory as the

value of the PATH environment variable.

d. Invoke a Cygwin window and run the command ssh-host-config.

e. Follow the prompts to set up a user in Cygwin. Grant this user write access

to the directory into which Rational ClearCase has been installed.6. Enable workflows to access versioned file artifacts in Rational ClearCase by

creating a File Repository DCM object to represent your Rational ClearCase

installation. Follow these steps to create this DCM object:

a. In the left frame of the Tivoli Provisioning Manager Web interface, click

Configuration > Workflows.

b. Select RRD_CreateCCfileRepository. Click on the workflow and select

Run. The workflow creates a file repository DCM object that has attributes

whose values you specify when you run the workflow. For information

about required arguments for this workflow, see “Workflows provided with

the integration” on page 29.

To view information about the File Repository DCM object, click Inventory

> Infrastructure Management > File Repositories.7. Enable workflows to use Rational ClearQuest deployment tracking features by

creating a Server DCM object to represent your Rational ClearQuest

installation. This object is created within the ClearQuest Servers resource pool.

Chapter 9. The Tivoli Provisioning Manager integration with Rational ClearCase and ClearQuest 27

To create the DCM object and the resource pool, run the workflow

RRD_CreateCQserver. For information about required arguments for this

workflow, see “Workflows provided with the integration” on page 29.

To view information about the ClearQuest Server DCM object, click Inventory

> Servers > Physical Servers > Resource Pools > ClearQuest Servers.

8. Run the workflow RRD_VerifySetup. This workflow checks that the required

DCM objects have been created and that the required scripts have been copied

to the proper location for use by ClearCase file repositories and ClearQuest

servers. This workflow also identifies your default ClearCase file repository and

your default ClearQuest server.

Using the integration to track and automate deployment tasks

This section describes how to use the integration to facilitate deployment tasks. For

information about usage and required arguments for workflows described in this

section, see “Workflows provided with the integration” on page 29.

Importing versioned file artifacts into Tivoli Provisioning

Manager

With the integration, you can import your versioned file artifacts from your

Rational ClearCase VOB into the Tivoli Provisioning Manager deployment

environment. This section describes several ways you can do this.

Importing using the Rational ClearCase deployment unit ID

This section describes how to import versioned files into Tivoli Provisioning

Manager using attributes of your deployment unit. You can use this method if you

have created a decorated Rational ClearCase deployment unit that lists the file

artifacts that you want to deploy. Follow these steps to perform the import

operation:

1. Get the version URI of your deployment unit by invoking RatlPerl to run the

script get_uri_from_file.pl.

2. In the Tivoli Provisioning Manager Web interface, run the workflow

RRD_ImportDUfromURI.

The system parses the deployment unit with the specified version URI, then

copies the files listed in the deployment unit from Rational ClearCase to

tio-home\repository\RapidDeploy\<build-name> within the local file repository.

DCM objects are created for each file listed in the deployment unit, with

references to the deployment unit version URI for traceability purposes.

The workflow uses the device model name, if specified, to install the

deployment unit.

Importing using Rational ClearQuest deployment record ID

This section describes how to import versioned files into Tivoli Provisioning

Manager using attributes of your deployment record. You can use this method if

you have created a decorated Rational ClearCase deployment unit that is

associated with a Rational ClearQuest deployment record. Follow these steps to

perform the import operation:

In the Tivoli Provisioning Manager Web interface, invoke the workflow

RRD_ImportDUfromRecordID.

The system queries the Rational ClearQuest database for the version URI of the

deployment unit associated with the specified deployment record. The system then

parses the deployment unit with the specified version URI and copies the files


listed in the deployment unit from Rational ClearCase to tio-home\repository\RapidDeploy\<build-name> within the local file repository. DCM objects are created

for each file listed in the deployment unit, with references to the deployment unit

version URI for traceability purposes.

The workflow uses the device model name, if specified, to install the deployment

unit.

Importing using the Tivoli Provisioning Manager Simple Object

Access Protocol (SOAP) command-line interface

You can import versioned files into Tivoli Provisioning Manager using its SOAP

command-line interface instead of its Web interface. You can invoke any workflow

by running CreateDeploymentRequest with its required arguments on the

command line. For more information on using the SOAP command-line interface,

see the IBM Tivoli Provisioning Manager Operator's Guide.

Verifying deployment approval in Rational ClearQuest

You can run the RRD_ApprovalCheck workflow to check the approval status of a

particular deployment that is represented by a deployment record in Rational

ClearQuest. To automate this approval status check, include a call to this workflow

in your user-defined workflows. The workflow queries Rational ClearQuest to see

whether that deployment record has been approved for deployment to a particular

environment.

Creating and updating Rational ClearQuest workflow records

You can include a call to RRD_StatusUpdate in your user-defined workflows to

create records in Rational ClearQuest to represent and track the status of the

workflows you have written. This creates a workflow record with the ID and

status of the Tivoli Provisioning Manager workflow, or updates the record if it

already exists.

Finding which version of a release has been deployed

You can use workflows to verify that the correct version of your release has been

deployed. After you determine which version of your release has been deployed,

you can determine which versions of the files that make up the release have been

deployed by extracting this information from the associated deployment unit. Use

the following procedure to do this:

1. In the Tivoli Provisioning Manager Web interface, navigate to the server onto

which you have deployed your release or type the name of the server in the

Find box.

2. From the Server page, click the Software page and go to the Details frame. A

list of all installed software modules on the server is displayed. Selecting a

software module displays detailed information about it, including the version

of the software that it represents, the version URI of its associated deployment

unit, and the name and ID of the ClearCase File Repository.

3. Run the workflow RRD_GetFileFromURI. This workflow retrieves the

deployment unit with the Version URI that you specify and copies it into the

Tivoli Provisioning Manager environment.

Workflows provided with the integration

This section describes workflows that are included in the integration. You can use

these workflows in triggers and in user-defined workflows to automate

deployment tasks.


The workflows, their options and arguments, and descriptions of their usage are

listed in Table 3.

Table 3. Workflows provided with the integration

Workflow Usage description Options and arguments

RRD_CreateCCfileRepository Creates a ClearCase File

Repository DCM object.

v File repository name. Give

the File repository object a

name.

v Is_default. If this object

represents the default

Rational ClearCase file

repository, set the value of

this parameter to Yes;

otherwise, set it to No.

v IP Address. The IP address

of the machine where

Rational ClearCase is

installed.

v View Type. The type of view

you are using on the

machine where Rational

ClearCase is installed. Set

this parameter to Dynamic if

you are using a dynamic

view or Snapshot if you are

using a snapshot view.

v View Info. Specify your view

tag if you are using a

dynamic view, or a view

path if you are usign a

snapshot view.

v Install Path. The full path in

which Rational ClearCase is

installed (ccase–home–dir).

v SAP User name. The user

name of an SSH user that

SAP (the Service Access

Point of Tivoli Provisioning

Manager) uses to access the


ClearCase is installed.

v SAP Password. The

password of the SAP user

whose name you specified

above.


Table 3. Workflows provided with the integration (continued)


RRD_CreateCQServer Creates a ClearQuest

Server DCM object.

v Server name. Give the Server

DCM object a name.

v Is_default. If this object

represents the default

Rational ClearQuest

installation, set the value of

this parameter to Yes;

otherwise, set it to No.

v IP Address. The IP address

of the machine where

Rational ClearQuest is

installed.

v Install Path. The full path in

which Rational ClearQuest is

installed (cquest–home–dir).

v Schema repository. Your

Rational ClearQuest schema

repository connection name.

v Database. The name of your

Rational ClearQuest user

database.

v ClearQuest User name. The

name of the Rational

ClearQuest user with which

you run queries.

v ClearQuest Password. The

password of the user whose

name you specified above.

v SAP User name. The user

name of an SSH user that

SAP (the Service Access

Point of Tivoli Provisioning

Manager) uses to access the


ClearQuest is installed.

v SAP Password. The

password of the SAP user

whose name you specified

above.




RRD_GetFileFromURI Given the version URI of

a file and the ID of your

ClearCase File

Repository DCM object,

this workflow invokes a

script on the server that

is specified by the DCM

object. The script

retrieves the

version-extended path

name of the file with the

specified version URI

and places it onto the

ClearCase server.

If values are specified for

target device ID, target

path, and target file

name, the workflow

extracts the file to the

specified location. If

these parameters are not

specified and the value

of the Remove Source

parameter is set to No,

the file is copied into the

view on the ClearCase

file repository host. The

location of the file is

recorded in the workflow

execution output log.

v ClearCase File Repository

DCM object ID. Leave this

field blank to specify the

default File Repository. This

ID is recorded in your

software module.

v The version URI, path name,

and name of the file you

want to extract from Rational

ClearCase.

v Target device ID (optional).

The device ID of the host

onto which you want the file

to be extracted. Leave this

field blank if you do not

want the deployment unit to

be copied onto any host. In

this case, the deployment

unit is copied to your

Rational ClearCase view.

v Target path (optional). The

path into which you want

the file to be extracted.

v Target file name (optional). If

you want the deployment

unit file that is copied to

your target device to have a

different name than it does

in Rational ClearCase,

specify the new name as the

value of this parameter.

Doing so can be useful to

minimize errors in

environments where

multiple builds produce

multiple versions of

deployment units with the

same name.

v Remove source (optional).

This parameter is useful only

if you are using a snapshot

view to access Rational

ClearCase. If this is the case,

the workflow copies the file

to the snapshot view and to

the target that you specify. If

you want the deployment

unit to be removed from the

snapshot view, set this

parameter to Yes. If you

want to keep the file in the

snapshot view, set it to No.

If you leave this field blank,

default value of No is used.




RRD_ImportDUfromURI Given the version URI of

a deployment unit, this

workflow copies the

deployment unit from

Rational ClearCase into

the local Tivoli

Provisioning Manager

file repository.

v Deployment unit version

URI. The version URI of the

deployment unit you want

to import into the ClearCase

File Repository.

v ClearCase File Repository

DCM object ID (optional).

The ID of the ClearCase File

Repository into which you

want to import the

deployment unit. If this field

is left blank, the default File

Repository is used.

v Device model name

(optional)

RRD_ImportDUfromRecordID Given the ID of a

deployment record and

the ID of a ClearQuest

Server DCM object, this

workflow runs a script

on the specified

ClearQuest server that

retrieves the version URI

of the deployment unit

that is associated with

the deployment record. It

then copies the

deployment unit into the

local Tivoli Provisioning

Manager file repository.

v Deployment record ID. The

ID of the deployment record

that is associated with the

deployment unit whose files

you want to import to the

ClearQuest Server.

v ClearQuest Server DCM

object ID (optional). The ID

of the ClearQuest Server

onto which you want to

import the deployment unit.

If this field is left blank, the

default ClearQuest Server is

used.

v The ID of the ClearCase file

repository DCM object

(optional)

v Device model name

(optional)

RRD_ApprovalCheck Given the ID of a

deployment record, the

ID of a ClearQuest

Server DCM object, and

the name of an

environment, this


on the specified


checks for approval to

deploy to the

environment. This

workflow returns no

value if approved and

displays an error

message if not approved.

v Deployment record ID. The

ID of the deployment record

to be checked for approval.


object ID (optional). The

name of the ClearQuest

Server on which the

deployment record resides.

v If no ClearQuest Server

DCM object is specified, the

default one is used.

v Environment name. The

environment name must be

specified as a string that

matches the name of the

corresponding Rational

ClearQuest environment

record.




RRD_StatusUpdate Given the ID of a

deployment record, this


on the specified


creates a workflow status

record and associates it

with the deployment

record. If a workflow

record already exists for

the specified deployment

record, the status field on

the workflow record is

updated.

v Deployment record ID. ID of

the deployment record with

which to associate a

workflow record.

v Workflow name. The name

of the workflow.

v Status. Status of the

workflow.


object ID (optional). The

name of the ClearQuest

Server on which the

deployment record resides. If

no ClearQuest Server DCM

object is specified, the

default one is used.

v Workflow record ID

(optional). ID of the

workflow record associated

with your deployment

record, if it exists.

RRD_VerifySetup Checks that the required

DCM objects have been

created and the scripts

copied to the proper

location for use by

ClearCase file

repositories and

ClearQuest servers. Also

identifies your default

ClearCase file repository

and your default

ClearQuest server.

None.


Appendix. Notices

This information was developed for products and services offered in the U.S.A.

IBM® may not offer the products, services, or features discussed in this document

in other countries. Consult your local IBM representative for information on the

products and services currently available in your area. Any reference to an IBM

product, program, or service is not intended to state or imply that only that IBM

product, program, or service may be used. Any functionally equivalent product,

program, or service that does not infringe any IBM intellectual property right may

be used instead. However, it is the user’s responsibility to evaluate and verify the

operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter

described in this document. The furnishing of this document does not grant you

any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation North Castle Drive

Armonk, NY 10504-1785

U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM

Intellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation Licensing

2-31 Roppongi 3-chome, Minato-ku

Tokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any other

country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS

PUBLICATION ″AS IS″ WITHOUT WARRANTY OF ANY KIND, EITHER

EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED

WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS

FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or

implied warranties in certain transactions, therefore, this statement may not apply

to you.

This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be

incorporated in new editions of the publication. IBM may make improvements

and/or changes in the product(s) and/or the program(s) described in this

publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for

convenience only and do not in any manner serve as an endorsement of those Web

sites. The materials at those Web sites are not part of the materials for this IBM

product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it

believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose

of enabling: (i) the exchange of information between independently created


programs and other programs (including this one) and (ii) the mutual use of the

information which has been exchanged, should contact:

IBM Corporation

Department BCFB

20 Maguire Road

Lexington, MA 02421

U.S.A.

Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.

The licensed program described in this document and all licensed material

available for it are provided by IBM under terms of the IBM Customer Agreement,

IBM International Program License Agreement or any equivalent agreement

between us.

Any performance data contained herein was determined in a controlled

environment. Therefore, the results obtained in other operating environments may

vary significantly. Some measurements may have been made on development-level

systems and there is no guarantee that these measurements will be the same on

generally available systems. Furthermore, some measurement may have been

estimated through extrapolation. Actual results may vary. Users of this document

should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of

those products, their published announcements or other publicly available sources.

IBM has not tested those products and cannot confirm the accuracy of

performance, compatibility or any other claims related to non-IBM products.

Questions on the capabilities of non-IBM products should be addressed to the

suppliers of those products.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which

illustrates programming techniques on various operating platforms. You may copy,

modify, and distribute these sample programs in any form without payment to

IBM, for the purposes of developing, using, marketing or distributing application

programs conforming to the application programming interface for the operating

platform for which the sample programs are written. These examples have not

been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or

imply reliability, serviceability, or function of these programs. You may copy,

modify, and distribute these sample programs in any form without payment to

IBM for the purposes of developing, using, marketing, or distributing application

programs conforming to IBM’s application programming interfaces.

Each copy or any portion of these sample programs or any derivative work, must

include a copyright notice as follows:

(c) (IBM) (2006). Portions of this code are derived from IBM Corp. Sample

Programs. (c) Copyright IBM Corp. 2006. All rights reserved.

Additional legal notices are described in the legal_information.html file that is

included in your Rational software installation.

Trademarks


ClearCase, ClearCase MultiSite®, ClearQuest, IBM, Tivoli, and Rational are

trademarks of International Business Machines Corporation in the United States,

other countries, or both.

Microsoft®, Windows, and the Windows logo are trademarks of Microsoft

Corporation in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other

countries.

Linux is a trademark of Linus Torvalds in the United States, other countries, or

both.

Other company, product or service names may be trademarks or service marks of

others.

Appendix. Notices 37

Index

Aapprovals

about 20

approving or rejecting approval

records 21

Bbuilds

about 13

creating build records 13

Cccase-home-dir directory xi

configuring deployment tracking 5

conventions, typographical xi

cquest-home-dir directory xi

customer support xii

Ddeployment records

creating 17

deployment trackinghow to track deployments 15

introduction 1

deployment unit templatesabout 15

deployment unitsabout 16

deployment units and deployment unit

templatesabout 15

deploymentsabout 17

Ee-mail notification

about 21

e-signaturesenabling 20

environmentsabout 11

creating environment records 11

Hhardware and software requirements 5

how to track deployments 15

Iintroduction to deployment tracking 1

MMultiSite considerations 20

Qqueries

about 23

RRational ClearQuest MultiSite

considerations 20

releasesabout 7

creating release records 7

reportsabout 23

rolesabout 9

creating role records 9

TTivoli Provisioning Manager

about 25

data centers and data center

assets 25

integration with Rational ClearCase

and ClearQuest 25

about 26

installing and configuring 26

tracking and automating

deployment with 28

workflowsabout 25

workflows provided with the

integration 29

typographical conventions xi


Readers’ Comments — We’d Like to Hear from You

ClearCase and ClearQuest

Guide to Deployment Tracking

Version 7.0.0

Publication No. GI11-6713-00

We appreciate your comments about this publication. Please comment on specific errors or omissions, accuracy,

organization, subject matter, or completeness of this book. The comments you send should pertain to only the

information in this manual or product and the way in which the information is presented.

For technical questions and information about products and prices, please contact your IBM branch office, your

IBM business partner, or your authorized remarketer.

When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any

way it believes appropriate without incurring any obligation to you. IBM or any other organizations will only use

the personal information that you supply to contact you about the issues that you state on this form.

Comments:

Thank you for your support.

Submit your comments using one of these channels:

v Send your comments to the address on the reverse side of this form.

If you would like a response from IBM, please fill in the following information:

Name

Address

Company or Organization

Phone No. E-mail address

Readers’ Comments — We’d Like to Hear from You GI11-6713-00

GI11-6713-00

��

Cut or FoldAlong Line

Cut or FoldAlong Line

Fold and Tape Please do not staple Fold and Tape

Fold and Tape Please do not staple Fold and Tape

NO POSTAGENECESSARYIF MAILED IN THEUNITED STATES

BUSINESS REPLY MAIL FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK

POSTAGE WILL BE PAID BY ADDRESSEE

IBM Corporation

Attn: Dept CZLA

20 Maguire Road

Lexington, MA

02421-3112

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

_

��

Printed in USA

GI11-6713-00

clear quest user guide

Documents