How to configure ClearCase UCM to use the Change Management Integration with RTC

Answer

Terminology

• Activity - ClearCase UCM activity
• Task – Change Management object; i.e., RTC work item.
• Association – linking of activity to task.
• Dissociation – unlinking of activity from task.
• Change Management Adapter – Change management provider’s client in ClearCase.
• Change Management Server – Change management provider’s server; e.g., RTC server.
• Change Management Provider – Change Management adapter and server.

Change Management Integration (CMI)

The CMI provides a loosely-coupled integration of ClearCase with Change Management Providers such as RTC. The ClearCase administrator must configure VOBs and UCM streams for the integration as described in the following sections.

CMI authentication and use (End User)

1. Use the cmiregister utility to store your login credentials for the RTC Provider. (See the section on “CMI End User commands” below.) This utility is included with a standard ClearCase installation. CM Provider operations for this user will fail if credentials are not registered with cmiregister.
   
   
2. Use cleartool mkact -task to create a UCM activity with a task association, or use cleartool chact -tasks to add or manage tasks associated with existing activities on a stream that has been configured for the Change Management Integration. (See the section on “CMI End User commands” below.)

After completing these steps, you may work normally in your UCM views and VOBs. If your administrator has configured the VOB and the stream(s) you are modifying, the integration will create and modify task associations on ClearCase activities, and will modify the corresponding work items in the RTC database.

Change Management Integration end user commands

Commands for setting and modifying task associations

The cleartool mkactivity -task command creates a new UCM activity, associates a task or list of tasks with it, and sets the new activity to the current view. It also adds an association to the new activity on the links page of the relevant work item at the RTC server. If you do not specify a name for the new activity, the integration will generate a name, using the CMI configuration options defined on the stream.

Usage:
mkactivity [-tasks task-selector[,...]] [activity-selector ...]


Examples:

1. Create an activity with a specified name and associate it with a task that is located at provider RTCPROV, in the current view:
   
   cleartool mkact -tasks 1234@RTCPROV myyact1
   
   
2. Create an activity with an auto-generated name and associate it with a task that is located at provider RTCPROV, in the current view:
   
   cleartool mkact -tasks 1234@RTCPROV

The cleartool chactivity command allows you to manage the task(s) associated with a UCM activity. Changes you make to the tasks associated with a UCM activity will cause updates at the RTC provider as well. If a UCM activity's stream has been configured for CMI you cannot remove the last task associated with the activity, unless the integration has been disabled for the stream or the stream is configured to not require a task for each provider.

Usage:
chactivity -tasks {-add_task task-selector[,...] |
                  -remove_task task-selector[,...] |
                  -rmall} activity-selector[,...]

Examples:

1. Add a task to an activity:
   
   cleartool chact -tasks -add_task 5678@RTCPROV myact1
   
   
2. Remove a task from an activity:
   
   cleartool chact -tasks -remove_task 1234@RTCPROV myact2

The cleartool lsactivity -find command allows you to run a predefined query at the RTC provider, to obtain a list of work items available to be associated with your activity.

Usage:
lsactivity -find [-provider provider_name]  
                [-in stream-selector | -view view-tag | -cview | activity-selector]

Examples:

1. List all the tasks associated with activity myact1:
   
   cleartool lsact -l myact1
   
   Output will include
   
   CMI Associated Tasks:
   1234@RTCPROV
   5678@RTCPROV
   
   
2. Get a list of work items at RTCPROV that you can associate with activity myact2:
   
   cleartool lsact -find -provider RTCPROV
   
   

The cleartool setactivity -tasks command allows you to set the activity associated with a specified task. You cannot use -tasks with -none or when specifying an activity. If the task does not exist, the command fails.

Usage:
setactivity {-none | -tasks task-selector[,...] | activity-selector}

Example:

1. Set the activity associated with task task1@RTCPROV:
   
   cleartool setact -tasks 1234@RTCPROV

The cleartool rmactivity command will clear all tasks associated with the activity being removed, and will update the RTC provider. There are no changes to the command line options for this command.

Using the cmiregister utility to manage RTC credentials configuration

Use the cmiregister utility to store your login credentials for a Rational Team Concert Provider. This utility is included with a standard ClearCase installation. CM integration operations that rely on an RTC Provider will fail if credentials are not registered with cmiregister prior to performing a ClearCase operation resulting in communication with the provider. This utility manages credentials only for the ClearCase user invoking cmiregister.

Usage of cmiregister (for CQ and RTC providers):

cmiregister help [command_name] [command name] = [add][remove][replace][help]
cmiregister add  {-cq -name <provider-name> -dbset <dbset-name> -userdb <userdatabase-name> -username <username> | -rtc -name <provider-name> } -username <username> [-password <password>]
cmiregister remove -cq {-name <provider-name> -dbset <dbset-name> -userdb <userdatabase-name> | -all}
cmiregister remove -rtc {-name <provider-name> | -all}
cmiregister remove -all
cmiregister replace {-cq -name <provider-name> -dbset <dbset-name> -userdb <userdatabase-name> | -rtc -name <provider-name> } [-username <username> ] [-password <password>]
cmiregister list -cq -name <provider-name> -userdb <userdatabase-name> -dbset <dbset-name>
cmiregister -rtc -name <provider-name>
cmiregister list -cq -rtc


cmiregister help
This command is used to display general usage or command specific usage of the cmiregister utility..

Examples:

1. cmiregister help
   
   
2. cmiregister help add

cmiregister add
This command is used to cache credential information for a user for an RTC provider. Use this command for each combination of provider name, user name and password. Note that the provider-name must match the provider configuration for the ClearCase stream participating in the integration.

Usage:
cmiregister add  -rtc -name <provider-name>  -username <username> [-password <password>]

• -rtc specifies an RTC CM Provider. Credential details can differ with provider type.
• <provider-name> specifies the name of the RTC Provider configured for the integration. Use cleartool lsprovider to find the associated provider name.
• <username> is the username to log in to RTC. This username will be used for all RTC operations for integration with this provider. A username is required for all RTC connections.
• <password> is the password associated with the above username. This argument is optional if the username is configured in RTC without a password. If specified, the password is saved in an encrypted format.

Examples:

1. cmiregister add -rtc -name RTCPROV -username rtcuser
   
   
2. cmiregister add -rtc -name RTCPROV2  -username rtcuser -password rational

cmiregister remove

Usage:
cmiregister remove {-rtc -name <provider-name>  | -all}

This command is used to remove cached Rational Team Concert provider credentials. This command may be used to remove one or a set of credentials. If the -all option is specified then the name option is ignored. This will remove all registered RTC credentials stored for the ClearCase user invoking cmiregister.

Examples:

1. cmiregister remove -rtc -name RTCPROV 
   
   
2. cmiregister remove -rtc -all

cmiregister replace

Usage:
cmiregister replace -rtc -name <provider-name> } [-username <username> ] [-password <password>]

This command is used to replace existing cached credential entries. Only the RTC username and/or the password can be changed with this command.

Examples:

1. cmiregister replace -rtc -name RTCPROV -username newuser
   
   
2. cmiregister replace -rtc -name RTCPROV2 -username newuser2 -password newpassword

cmiregister in interactive mode

The cmiregister utility may also be run in interactive mode:
cmiregister>list
cmiregsiter>add -name RTCPROV1 -username myname -password mypass
cmiregister>exit

exit or quit commands can be used to exit the utility in this mode.


ClearCase VOB and UCM stream configuration (Administrator)

1. Gather the list of UCM streams and associated VOBs that will participate in the integration. Integration information is specified on the participating stream.
   
   
2. Configure each VOB participating in the integration as follows:
   
   Create the attribute CC_CMI_PROVIDERS of type string in the PVOB or Admin VOB:
   
   cleartool mkattype -vtype string CC_CMI_PROVIDERS
   
   Use the -shared option to create the type in replicated PVOBs, if more than one replica will be using the integration.
   
   If the attribute type is created in an admin VOB, a local copy of the attribute type must be created in all participating client PVOB families. The local copy of the type must be created at the site which masters the global type. A local copy can be made using the following command:
   
   cleartool cptype -nc attype:CC_CMI_PROVIDERS@\adminvob CC_CMI_TASK@\clientvob
   
   
3. Configure the PVOB participating in the integration by using the mkcmprovider command. (See the following section on Commands for configuring VOB and UCM streams for a CM Provider.)
   
   
4. Configure streams for the integration by using the mkcmprovider command. Note that a child stream inherits its parent stream's integration configuration, and you do not have to configure the integration for every UCM stream. (See the following section on Commands for configuring VOB and UCM streams for a CM Provider.)

After completing these steps, Users may create activities with task associations, and the CM Integration will update records in the RTC database.


Commands for configuring VOB and UCM streams for a CM Provider

cleartool mkcmprovider
The mkcmprovider command creates or replaces a change management provider. It creates the provider on the vob/replica object or the branch type object.

Usage:
cleartool mkcmprovider {-vob vob-selector | -replica replica-selector} [-replace]
                    {-data prov-info-file | -type <cm-type> -version <cm-version> -description <cm-description>
                    -connection <connection_info>} provider_name

cleartool mkcmprovider {-brtype <brtype-name>} [-replace]
                    [{-data context-info-file | -context <context-string>}] provider_name

cleartool mkcmprovider {-stream <stream name>} [-replace]
                    {-options <cmi_options> -context <context-options> | -data [info_file]}
                    {-enable [true | false]} provider_name

The administrator must create the attribute type in the VOB manually if it does not exist before running the mkcmprovider command. Refer to previous section for commands to create attribute types.

In the context of RTC, the RTC server's URL would be part of the connection information, and the query uri would be part of the context information.


Configuring a CM provider on a VOB

• -vob vob-selector
  Creates the change management provider on the local replica of the given vob-selector, adding the new provider to any existing list of providers configured on this VOB.
  
  
• -replica replica-selector
  Creates the change management provider on the given replica-selector, adding the new provider to any existing list of providers configured on this VOB.
  

The following arguments can be provided via command line arguments or an input file:

• -type <cm-type>
  Specifies the CM provider type
  For RTC, <cm-type> = cmrtc
  
• -version <cm-version>
  Specifies the version of the CM provider library.
  For RTC, <cm-version> = v1_0
  
• -description cm-description
  A description of the CM provider e.g. “RTC server in Boston”
  
• -connection connection-info
  Connection details for this CM provider.
  For RTC, connection information includes the OSLC URL for the RTC server.
  The "baseUrl" key is case-sensitive.
  
  Format for RTC : baseUrl:<server url>
  
  Example: baseUrl:http://rtcservername:9443/ccm
  
  
• Input file:
  -data prov-info-file
  
  prov-info-file is the path name to the text file which contains the CM provider configuration.
  
  Contents of a sample file prov-info-file for RTC:
  
  version=v1_0
  type=cmrtc
  description=RTC server in Houston
  connection.baseUrl=http://rtcservername:9443/ccm

queryUri=<query uri>
cmi_options.validate=true
cmi_options.activityFormat=%task-id_%stream-name

Notes: Enclosing quotes are not required in this file.
The example above also includes the correct syntax for the queryUri and cmi_options that will be used to configure streams; see the following section for further details.
When configuring the VOB, the -data option cannot be used in conjunction with -type, -version and -description.

• Provider-name
  A unique id for the provider. This provider name will be used to configure streams for the integration and used by a ClearCase user to cache CM provider credentials. This name should be unique within a ClearCase deployment.

Configuring a CM provider on a stream

-stream stream-name
Configures a CM provider on a stream participating in the CM integration, adding this provider to any existing CM providers configured on this stream. Child streams will inherit this configuration, unless they are explicitly configured otherwise.

The following required argument can be provided via command line argument or an input file
-context context-info
context-info is CM provider specific information which is consumed only by the CM provider. It is a string of key:val pairs separated by commas.


For RTC, context-info must contain the uri for a predefined query at the server:
queryUri:<query uri>

The queryUri key is case-sensitive. A valid queryUri is required by CMI for RTC. For details on how to determine the query uri, review the section titled Determining the RTC query URI in techdoc 7036887: Configuring the IBM Rational ClearCase Change Management Interface (CMI) for the UCM-RTC integration for more details.

-enable [true|false]
Turns the integration ON or OFF for this stream and all of its child streams, unless overridden by child streams.

-options <cmi-options>
This option is available for all CM Providers. For RTC there are two options: activityFormat and validate. A value of true for the validate option causes the integration to verify with the provider that a specified task exists before allowing the User to set to an activity using setact. The validate option is set to true by default in 8.0.0.7 and 8.0.1.1. The activityFormat option specifies a format for auto-generated activity names. It has no default and must always be specified. Two built-in macros are provided (see the examples below):
%task-id
%stream-name
Since ClearCase does not support using all numerals as a valid activity name, if you specify only “%task-id”, ClearCase will generate an activity name of the form “<provider-name>%task-id”.

provider-name
A CM provider named “provider-name” must exist on the parent replica .

Note: The CM provider information configured on the parent VOB is duplicated on the stream. Any modifications to the provider configuration on the VOB must be reflected on the stream. See the following section.
Again, the stream configuration details can be either given on the command line or in a input file using -data. See the section above or Example 2 below for the correct syntax to use when specifying the stream configuration options in a data file.
When configuring a stream, the -data option cannot be used in conjunction with -options or -context.

Replacing CM provider configuration on a VOB

-replace
Use -replace with -vob or -replica to replace/modify an existing CM provider configuration on a VOB.

One or more of the configuration parameters, except the provider name, may be modified using this command.

Notes: Modifying the change management provider information on a VOB or replica may cause inconsistencies with streams previously configured for "provider-name". Prior to ClearCase releases 8.0.0.11 and 8.0.1.04, to avoid failures of change management actions, you must manually run
mkcmprovider -stream <stream-name> -replace provider-name and make the same changes on all streams configured for "provider-name". For ClearCase releases 8.0.0.11 or 8.0.1.04 or later, running mkcmprovider -vob -replace will automatically update any streams or brtypes in that VOB that are configured to use the same change management provider.

Again, the new details can be either given on the command line or in a input file using -data. See the section above or Example 2 below for the correct syntax to use when specifying the stream configuration options in a data file.

When modifying a stream configuration, the -data option cannot be used in conjunction with -options or -context.

Replacing CM provider configuration on a stream

-replace
Use -replace with -stream to replace/modify an existing CM provider configuration on a stream. Use this command to
• Update CM provider configuration modified on the parent VOB.
• Replace/modify CM provider context information (context-info) for this stream for one or more of the configured CM providers..

Examples:

1. cleartool mkcmprovider -replica original@/var/tmp/myvob -version v1_0 -description "CMI RTC provider" -type cmrtc -connection baseUrl:https://hostname.com/:9443/ccm RTCPROV
   
   After a successful mkcmprovider if we do a describe on the replica object the value of attribute CC_CMI_PROVIDERS is "{"cmprovider":[{"provContext":{"baseUrl":"https:/hostname.com:9443/ccm"},"provDescription":"CMI RTC provider","provName":"RTCPROV","provType":"cmrtc","provVersion":"v1_0"}]}"
   
   
2. cleartool mkcmprovider -vob /var/tmp/myvob -data prov-info-file RTCPROV
   
   Contents of file prov-info-file (NOTE the syntax required for queryUri and cmi_options):
   
   type=cmrtc
   version=v1_0
   description=CMI RTC Provider
   connection.baseUrl=http://hostname.com:9443/ccm
   queryUri=<query uri>
   cmi_options.validate=true

cmi_options.activityFormat=%task-id_%stream-name

1. cleartool mkcmprovider -vob /var/tmp/myvob -replace -version v2_0 RTCPROV
   
   
2. Configure intStream1 to use the RTCPROV provider.
   
   Note: You can use -data and provide an input file as in Example 2, which also shows the required syntax for the queryUri keyword.
   
   cleartool mkcmprovider -stream  intStream1 -context “queryUri:<query uri>" -enable true  -options activityFormat:ACT_%task-id_%stream-name,validate:true  RTCPROV

Command to browse CM provider configuration

cleartool lsprovider
The lsprovider command lists CM provider(s) on a given VOB, branch type, or stream.

Usage:
lsprovider [-long]{[-vob vob-selector[,...]] [-replica replica-selector[,...]] [-pname pname[,...]] [-stream stream-name[,...]}

• -vob vob-selector[,...]
  One or more vob-selectors. Lists all CM providers configured on this VOB.
  
• -replica replica-selector[,...]
  One or more replica-selectors. Lists all CM providers configured on this replica.
  
• -pname pname[,...]
  One or more path names. Lists all CM providers configured on the branch type associated with this path name. This is for Base CC only.
  
• -stream stream-name[,...]
  One or more stream names. Lists all CM providers configured on each specified stream.
  
• -long
  The default output of this command includes the provider name and description. Use this option to display additional configuration details for this CM provider.

Examples:

1. cleartool lsprovider -vob /var/tmp/myvob -replica original@/var/tmp/myvob -pname file
   
   vob  "/var/tmp/myvob"
          RTCPROV: CMI RTC provider
   replica  "original@/var/tmp/myvob"
          RTCPROV : CMI RTC Provider
   version  "file@@/main/bugfix/1"
          RTCPROV: CMI RTC provider
   
   
2. cleartool lsprovider -vob /var/tmp/myvob,/var/tmp/myvob_a
   
   vob  "/var/tmp/myvob"
          RTCPROV : CMI RTC provider
   vob  "/var/tmp/myvob_a"
          RTCPROV2: Another CMI RTC Provider

Command to remove CM provider configuration

cleartool rmprovider
The rmprovider command deletes the CM provider configuration from a given replica or stream.

Usage:
 rmprovider {-vob vob-selector | -replica replica-selector | -brtype brtype-selector | -stream stream-name} provider_name

• -vob vob-selector
  Deletes the CM provider configuration from the VOB's local replica.
  
• -replica replica-selector
  Deletes the CM provider configuration from the replica.
  
• -brtype brtype-selector
  Deletes the CM provider configuration from the branch type. This is for Base CC only.
  
• -stream stream-selector
  Deletes the CM provider configuration from the stream
  
  provider-name
  The name of the provider to be deleted.

Note: Deleting the change management provider information on a VOB or replica may cause inconsistencies with streams previously configured for "provider-name". To avoid failures of integration actions, the CM Provider configuration must also be removed from all associated streams using the following command:

cleartool rmprovider -stream <stream-name> provider-name 

Examples:

1. Remove provider RTCPROV2 from a VOB:
   
   cleartool rmprovider -vob /var/tmp/myvob RTCPROV2

Logging

Change Management Interface messages are logged in <CC_VAR>\log\cmi.log.
Where <CC_VAR> = <ClearCase Home>\var (Windows).

Note: The <CC_VAR>\log directory must be writable by all ClearCase users.

Any errors logged may indicate configuration and/or Change Management operation errors. As some errors may lead to potential discordance between ClearCase and RTC with respect to version association, periodic review of the log file for information usable for off-line resolution is recommended.

RTC Web Configuration

No additional configuration required.

Migrating CMI configuration for CTE-RTC integration from 8.0.0.5 to 8.0.0.7

Please read this section when you have configured CMI for CTE-RTC integration with ClearCase 8.0.0.5, and are upgrading to 8.0.0.7.

The configuration on UCM stream is slightly enhanced and different in 8.0.0.7. The configuration for 8.0.0.5 works well with CTE-RTC integration after the upgrade to 8.0.0.7. But you need to update the configuration in order to make the integration work for both ClearTeam Explorer and cleartool command line. Please read the section: “ClearCase VOB and UCM stream configuration (Administrator)” and set up the CMI configuration again with the same baseUrl, queryUri, or activityFormat values. You also may need to update "-type" from "RTC" to "cmrtc", and "-version" from "1.0" to "v1_0".

Important Considerations

Topic	Note
cleartool rmver	In 7.1.2.11, use the "-xattr" option when removing a version associated with a task. For VOBs created on a host running ClearCase 8.0.0.7, or for replicated VOBs at family feature level 7 or higher, use the “-xattr -xtask” options when removing a version associated with a task.
UCM	Does not support the CMI in 7.1.2.11. Support is available in 8.0.0.7 and 8.0.1.1.