mkcmprovider

Configures a change management task provider

Applicability

Product

Command type

VersionVault

cleartool subcommand

Platform

UNIX®

Linux®

Windows®

Synopsis

  • Integration of Base VersionVault or VersionVault UCM with a CM task provider-configure a VOB:
    mkcmprovider { -vob vob-selector | -replica replica-selector } [ -replace ]
    { -data provider-info-file | -type cm-type -version cm-version -description cm-description -connection connection-information }
    provider-name
  • Integration of Base VersionVault with a CM task provider-configure a branch:
    mkcmprovider { -brtype brtype } [ -replace ]
    { -data context-info-file | -context context-string [ -options cmi-options ] } provider-name
  • Integration of VersionVault UCM with a CM task provider-configure a stream:
    mkcmprovider { -stream stream-name } [ -replace ]
    { -options cmi-options -context context-options | -data [ provider-info-file ] }
    { -enable [ true | false ] } provider-name

Description

This command configures a change-management task provider. To configure a task provider
  1. Configure the provider for the VOB or replica
  2. Configure the provider for
    • A branch, if you use Base VersionVault
    • A stream, if you use UCM
You can supply the configuration parameters in a file or specify them interactively.

Restrictions

None.

Options and arguments

Specifying the configuration targets

-vob vob-selector
The VOB that is to be configured.
-replica replica-selector
The VOB replica that is to be configured.
-brtype brtype
The Base VersionVault branch type that is to be configured.
-stream stream-name
The VersionVault UCM stream that is to be configured.

Specifying the task provider

provider-name
The task provider that is to be established: CQ, RTC, or JIRA

Modifying configuration parameters

-replace
Modifies one or more of the VOB, replica, branch, or stream configuration parameters for the specified provider.

Configuration parameters

-connection connection
For Compass and JIRA, specify the connection information in this form: baseurl:server-url. For RTC, specify the information in this form: baseUrl:server-url.
You can add the key:value pair disableRTCBridge:true to the connection string to disable the UCM RTC bridge with VersionVault Explorer. This disables the bridge for all users on a VOB or replica that is configured with CMI. The key name disableRTCBridge is case-sensitive; its value is case-insensitive.
Note: When the disableRTCBridge key is set at the stream level, it overrides the setting at the VOB level.
-context context-string
A context string of the form, key:value,...
  • For Compass: userdb:CQWAN,dbset:SAMPL,queryuri:query
  • For JIRA: queryuri:query
  • For Rational® Team Concert: queryUri:query
Note the difference in case between queryuri (for Compass and JIRA) and queryUri (for RTC).
Also note that query must be enclosed in quotation marks and special characters must be escaped, as in the following example where the query name includes spaces (HTML character code %20):
"queryuri:rcm.name=Public%20Queries/All%20Defects"
You can add the key:value pair disableRTCBridge:true to the context string to disable the UCM RTC bridge with VersionVault Explorer. This disables the bridge for all users on a stream that is configured with CMI. The key name disableRTCBridge is case-sensitive; its value is case-insensitive.
Note: When the disableRTCBridge key is set at the stream level, it overrides the setting at the VOB level.
-data provider-info-file
Specifies a file that contains the configuration parameters in the following format:
type=cm-type
version=cmi-library-version
description=description
connection.baseurl=base-url #To configure Compass or JIRA
connection.baseUrl=base-url #To configure RTC
connection.disableRTCBridge=true or false #To disable or enable the UCM RTC bridge with VersionVault
Explorer
Note the difference in case between baseurl (for Compass and JIRA) and baseUrl (for RTC).
-description cm-description
A text description of the CM task provider server.
-enable [ true | false ]
Enables or disables the integration for the specified stream. An explicitly enabled child stream remains enabled after its parent stream has been disabled. However, if the child stream inherited enablement from its parent, it is disabled when its parent is disabled.
-options cmi-options
CM provider options of the form, key:value,...
  • Stream configuration for UCM: activityFormat:format,validate:true,reqProvTask:true. If reqProvTask is set to TRUE, UCM chactivity operations that would remove an activity's last task association are blocked.
  • Branch configuration:
    • ciVerifyProv: if set to true, blocks base-VersionVault checkin operations if the provider cannot be reached. Default: false
    • ciVerifyUser: if set to true, blocks base-VersionVault checkin operations if user authentication fails. Default: false
    • reqProvTask: if set to true, blocks base-VersionVault checkin operations if the version does not have a task association.
    For information on the effects of policy enforcement on VersionVault operations, see CMI policies for UCM and CMI policies for base VersionVault
-type cm-type
The type of the CM task provider; one of the following values: cmcq, cmjira, cmrtc.
-version cm-version
The version of the CM task provider library.

CMI policies for UCM

CMI supports the following policy keywords for UCM:
  • enable Default: none.
    • Turns the integration on or off for this and all child streams. If enable=TRUE, CMI operations will be performed for this provider; if enable=FALSE, the provider is disabled.
  • reqProvTask Default: True.
    • Enforces or relaxes the policy that for every CM provider configured on a stream an activity must have a task association. This allows you to have activities that participate in CMI and activities that do not.
  • validate Default: True.
    • Governs whether the provider server is contacted during a setactivity operation to verify the existence of an associated task.
  • reqAnyTask Default: False.
    • Enforces or relaxes the policy that for every CM provider configured on a stream, an activity must have a task association. This allows you to have activities that participate in CMI and activities that do not. This policy is superseded by the reqProvTask policy. If any provider has reqAnyTask enabled and all providers have reqProvTask disabled, then one task from any provider will satisfy reqAnyTask on the stream. If reqProvTask is enabled on a provider then reqAnyTask is ignored for all providers on the stream.
These policies affect UCM operations as follows:
  • mkactivity -task
    • If enable=TRUE and the task exists at the provider, the activity is created with a task association, setactivity succeeds, and the provider is updated. If the task doesn't exist, the activity is created but not set.
    • If enable=FALSE, -task warns that the provider is disabled, but creates and sets the view. No task association is created on the activity.
    • If reqProvTask=TRUE and enable=TRUE, you must specify the -task form of the command. If reqProvTask=FALSE, specifying -task is not required.
    • If reqAnyTask=TRUE, reqProvTask=FALSE, and enable=TRUE, you must specify the -task (using any provider) form of the command. If reqAnyTask=FALSE, specifying -task is not required.
  • setactivity -task
    • If enable=TRUE and validate=TRUE and the task exists at the provider, this command succeeds.
    • If enable=FALSE, an error is returned indicating that an activity associated with the task could not be found.
    • If reqProvTask=TRUE, you must specify -task if enable=TRUE, or you must specify an activity that has a task for this provider.
    • If reqProvTask=FALSE, you can set an activity that has no task association.
    • If reqAnyTask=TRUE and reqProvTask=FALSE, you must specify -task (using any provider) if enable=TRUE, or an activity that has a task for any provider.
    • If reqAnyTask=FALSE, you can set an activity that has no task association.
    • If validate=FALSE and enable=TRUE, the provider does not validate the task.
  • lsactivity -find
    • If enable=TRUE, this command succeeds.
    • If enable=FALSE, no data is returned.
    • The values of validate, reqProvTask, and reqAnyTask are ignored.
  • chactivity -tasks -add
    • If enable=TRUE, this command succeeds.
    • If enable=FALSE, this command returns a warning that the provider is not enabled on the stream and no task association is created.
    • The values of validate, reqProvTask, and reqAnyTask are ignored.
  • chactivity -tasks -remove
    • When the activity has multiple tasks for a provider, this operation succeeds if enable=TRUE.
    • If enable=FALSE, it succeeds, but the provider is not updated.
    • If reqProvTask=TRUE for a configured provider (enable=TRUE), then the activity must have at least one task association for this provider.
    • If reqProvTask=FALSE (enable=TRUE), this restriction is not enforced.
    • If reqAnyTask=TRUE for any configured provider and reqProvTask=FALSE for all configured providers (enable=TRUE), then the activity must have a task association for at least one provider.
    • If reqAnyTask=FALSE (enable=TRUE), this restriction is not enforced.
    • When the activity has no tasks, this command succeeds if enable=TRUE, but it displays a warning that there are no tasks to remove.
    • In an attempt to remove the last task, this command fails if enable=TRUE and reqProvTask=TRUE.
    • Attempting to remove the last task among all providers fails if enable=TRUE, reqAnyTask=TRUE for any provider, and reqProvTask is false for all providers.
    • If enable=TRUE, reqProvTask=FALSE, and reqAnyTask=FALSE for all providers, the last task is removed and the provider is updated.
    • If enable=FALSE, the task is removed from the activity, but the provider is not updated.
    • The value of validate is ignored.
  • rmactivity (CMI never blocks this command)
    • If enable=TRUE, the provider is updated.
    • If enable=FALSE, the provider is not updated.
    • The values of reqProvTask, validate and reqAnyTask are ignored.
    .

CMI policies for base VersionVault

CMI supports the following policy keywords for base VersionVault:
  • reqProvTask Default: True.
    • Enforces or relaxes the policy that a version must have a task for a CM provider that is configured on the branch type. This allows you to have versions that participate in CMI and versions that do not.
  • ciVerifyUser Default: False.
    • Enforces the policy that checkin operations are to be blocked if user authentication fails.
  • ciVerifyProv Default: False.
    • Enforces the policy that checkin operations are to be blocked if the CM provider server (CQ server or RTC server) is unavailable.
  • reqAnyTask Default: False.
    • Enforces or relaxes the policy that a version must have a task association for any CM provider configured on the branch type. This allows you to have versions that participate in CMI and versions that do not. This policy is superseded by the reqProvTask policy. If any provider has reqAnyTask enabled and all providers have reqProvTask disabled, one task from any provider satisfies reqAnyTask on the branch type. If reqProvTask is enabled on a provider, reqAnyTask is ignored for all providers on the branch type.
    • validate Default: False.
      • Governs whether the provider server is contacted during checkin to verify the existence of an associated task. The default value is true.
These policies affect base VersionVault operations as follows:
  • checkin
    • If reqProvTask = TRUE for any provider on a branch type, the checkin operation is blocked if the version does not have a task for that provider.
    • If reqProvTask = FALSE for all providers on a branch type, the checkin operation is allowed even if the version does not have tasks for all providers.
    • If reqProvTask = FALSE for a provider on a branch type but a checked out version on a branch of that type has a task for the provider, the checkin operation proceeds and the provider is updated.
    • If ciVerifyUser=TRUE for one or more providers on a branch type, the checkin operation is blocked if authentication to any of the providers fails.
    • If ciVerifyProv=TRUE for one or more providers on a branch type, the checkin operation is blocked if any of the provider servers cannot be reached.
    • If reqAnyTask=TRUE for any enabled provider on a branch type and reqProvTask=FALSE for all providers on a branch type, the checkin operation is blocked unless the version has a task for at least one provider enabled on the branch type.
    • If reqAnyTask=FALSE and reqProvTask=FALSE for all providers on a branch type, the checkin operation succeeds even if the version does not have tasks for any provider.
    • If reqAnyTask=FALSE and reqProvTask=FALSE for all providers on a branch type, but a checked-out version on a branch of that type has a task for the provider, the checkin operation succeeds and the provider is updated.
  • checkout
    • reqProvTask has no impact: the policy is not enforced.
  • uncheckout
    • reqProvTask has no impact: the policy is not enforced.
  • mkelem -ci or mkelem -mkpath -ci
    • If reqProvTask = TRUE for any branch type, the operation succeeds but blocks a checkin operation (-ci) unless a current task has been set.
    • If reqProvTask = FALSE for all providers on a branch type, mkelem -mkpath -ci succeeds even without a set current task.
    • If reqAnyTask=TRUE for any provider on a branch type and reqProvTask=FALSE for all providers on a branch type, the mkelem operation succeeds but checkin (-ci) is blocked unless a current task has been set.
    • If reqAnyTask=FALSE and reqProvTask=FALSE for all providers on a branch type, the operation succeeds even without a set current task.
  • chtask -remove
    • If reqProvTask = TRUE for any provider on a branch type, this operation blocked for the last task for that provider on checked-in versions.
    • If a version is checked out, you can remove all tasks on it, even if reqProvTask = TRUE.
    • If reqAnyTask=TRUE for any provider on a branch type, and reqProvTask=FALSE, this operation is blocked for the last task among all providers on checked-in versions.

Examples

The UNIX system and Linux examples in this section are written for use in csh. If you use another shell, you may need to use different quoting and escaping conventions.

The Windows examples that include wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you may need to change the wildcards and quoting to make your command interpreter process the command appropriately.

In cleartool single-command mode, cmd-context represents the UNIX system and Linux shells or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.

  • Configure the replica myvob for Compass.

    cmd-context  mkcmprovider -replica original@/var/tmp/myvob -version v1_0
    -description "CMI CQ provider" -type cmcq
    -connection baseurl:https://hostname.com/cqweb/oslc CQPROV

  • Configure Compass with a data file.

    cmd-context  mkcmprovider -vob /var/tmp/myvob -data prov-info-file CQPROV

    The data file contains the following information, formatted as shown:

    type=cmcq
    version=v1_0
    description=CMI CQ Provider
    connection.baseurl=http://hostname.com/cqweb/oslc

  • Configure the branch type bugfix for Compass:

    cmd-context mkcmprovider -brtype bugfix -context Contextkey1:abcd CQPROV