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

Technote (FAQ)


Question

How do you configure the IBM Rational ClearCase (CC) UCM and IBM Rational Team Concert (RTC) integration to use the Change Management Integration (CMI)?

Cause

The UCM-RTC integration is supported by the new ClearCase Change Management Integration (CMI) on ClearCase local clients (cleartool and native GUIs) in ClearCase versions 8.0.0.7, 8.0.1.1, and later. ClearCase communicates with RTC using its OSLC interface.

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.

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 is no change to the commandline 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 c miregister (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 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 file prov-info-file for RTC:

    version=v1_0
    type=cmrtc
    description=RTC server in Houston
    connection.baseUrl=
    http://rtcservername:9443/ccm

    Notes:
    Enclosing quotes are not required in this file.
    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 branch types for 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 a comma.


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 using the cleartool mkcmprovider -stream command.

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.

Note: Modifying the change management provider information on a VOB or replica may cause inconsistencies with streams previously configured for "provider-name". 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".

Again the new details can be either given on the command line or in a input file using -data.

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):

    type=cmrtc
    version=v1_0
    description=CMI RTC Provider
    connection.baseUrl=http://hostname.com:9443/ccm
    queryUri=<query uri>

  3. cleartool mkcmprovider -vob /var/tmp/myvob -replace -version v2_0 RTCPROV

  4. 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 pathname.
  • -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
  • -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 branch types 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.

Rate this page:

(0 users)Average rating

Add comments

Document information


More support for:

Rational ClearCase
Integrations

Software version:

8.0.0.7, 8.0.1.1

Operating system(s):

AIX, HP-UX, Linux, Solaris, Windows

Reference #:

1640748

Modified date:

2014-03-20

Translate my page

Machine Translation

Content navigation