clear quest user guide
TRANSCRIPT
Rational ® ClearCase and ClearQuest
Guide to Deployment Tracking
Version 7.0.0
Windows, UNIX, and Linux
GI11-6713-00
���
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
IBM Support Assistant: http://www.ibm.com/software/support/isa/
About this book xiii
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
4 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking
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.
© Copyright IBM Corp. 1992, 2006 5
6 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking
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.
© Copyright IBM Corp. 1992, 2006 7
8 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking
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.
© Copyright IBM Corp. 1992, 2006 9
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.
10 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking
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.
2. Fill in the required fields:
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.
© Copyright IBM Corp. 1992, 2006 11
12 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking
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.
© Copyright IBM Corp. 1992, 2006 13
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
14 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking
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
© Copyright IBM Corp. 1992, 2006 15
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 :
Z:\testvob>RATLPerl "C:\Program Files\Rational\ClearCase\etc\du_tool.pl"^
--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.
16 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking
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:
Z:\testvob>RATLPerl "C:\Program Files\Rational\ClearCase\etc\du_tool.pl"^
--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:
Z:\testvob>RATLPerl "C:\Program Files\Rational\ClearCase\etc\du_tool.pl"^
--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.
2. Fill in the required fields:
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
18 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking
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
Chapter 7. Tracking a deployment 19
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.
20 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking
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 7. Tracking a deployment 21
22 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking
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
© Copyright IBM Corp. 1992, 2006 23
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.
24 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking
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.
© Copyright IBM Corp. 1992, 2006 25
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.
26 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking
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
28 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking
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.
Chapter 9. The Tivoli Provisioning Manager integration with Rational ClearCase and ClearQuest 29
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
machine where Rational
ClearCase is installed.
v SAP Password. The
password of the SAP user
whose name you specified
above.
30 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking
Table 3. Workflows provided with the integration (continued)
Workflow Usage description Options and arguments
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
machine where Rational
ClearQuest is installed.
v SAP Password. The
password of the SAP user
whose name you specified
above.
Chapter 9. The Tivoli Provisioning Manager integration with Rational ClearCase and ClearQuest 31
Table 3. Workflows provided with the integration (continued)
Workflow Usage description Options and arguments
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.
32 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking
Table 3. Workflows provided with the integration (continued)
Workflow Usage description Options and arguments
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
workflow runs a script
on the specified
ClearQuest server that
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.
v ClearQuest Server DCM
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.
Chapter 9. The Tivoli Provisioning Manager integration with Rational ClearCase and ClearQuest 33
Table 3. Workflows provided with the integration (continued)
Workflow Usage description Options and arguments
RRD_StatusUpdate Given the ID of a
deployment record, this
workflow runs a script
on the specified
ClearQuest server that
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.
v ClearQuest Server DCM
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.
34 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking
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
© Copyright IBM Corp. 1992, 2006 35
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
36 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking
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
38 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking
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
© Copyright IBM Corp. 1992, 2006 39
40 IBM Rational ClearCase and ClearQuest: Guide to Deployment Tracking
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