How to use the Change Management Integration (CMI) Policy Keywords

Answer

The Change Management Integration (CMI) supports a number of policies to customize integrations with base ClearCase or UCM. These policies are configured by setting predefined keywords in the mkcmprovider -stream or mkcmprovider -brtype commands.

• The reqProvTask option enforces or relaxes the policy that a version must have a task for a CM provider configured on the brtype. This allows users to have both versions that participate in CMI and versions that do not. The default value is true.
• The ciVerifyUser option enforces the policy that checkin should be blocked if the user authentication fails. The default value is false.
• The ciVerifyProv option enforces the policy that checkin should be blocked if the CM provider server (CQ server or RTC server) is unavailable. The default value is false.
• The reqAnyTask (available starting with 8.0.0.15 and 8.0.1.8) option enforces or relaxes the policy that a version must have a task association for any CM provider configured on the brtype. This allows users to have both versions that participate in CMI and versions that do not. The default value is false. 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 brtype. If reqProvTask is enabled on a provider then reqAnyTask is ignored for all providers on the brtype. (Introduced in 8.0.0.15, 8.0.1.8)
• The validate keyword governs whether the provider server is contacted during checkin to verify the existence of an associated task. The default value is false. (Introduced in 8.0.0.16, 8.0.1.9)

checkin :
• If reqProvTask is true for any provider on a brtype, CMI will block checkin if the version does not have a task for that provider.
• If reqProvTask is false and reqAnyTask is false for all providers on a brtype, CMI will allow checkin even if the version does not have tasks for all providers.
• If reqProvTask is false for a provider on a brtype but a checkedout version on a branch of that type has a task for the provider, CMI will allow checkin and update the provider.
• If enable is true and validate is true and the task exists at the provider, checkin succeeds.
• If validate is false and enable is true, the provider does not validate the task.
• If validate is true for at least one provider on a branch type, CMI, blocks checkin operations if the associated task does not exist at the provider server.
  
mkelem -ci or mkelem -mkpath -ci :
• If reqProvTask is true for any provider on a brtype, CMI will allow mkelem to succeed but will block checkin unless a current task has been set.
• If reqProvTask is false and reqAnyTask is false for all providers on a brtype, CMI will allow checkin to succeed even without a set current task.
• If enable is true and validate is true and the task exists at the provider, checkin succeeds.
• If validate is false and enable is true, the provider does not validate the task.
• If validate is true for at least one provider on a branch type, CMI, blocks checkin operations if the associated task does not exist at the provider server.
  
chtask:
• If reqProvTask is true for any provider on a brtype, CMI will block chtask -remove of the last task for that provider on checkedin versions.
• If a version is checkedout, you can always remove all tasks on it, even when reqProvTask is true.
  
  

checkin :
• If reqAnyTask is true for any enabled provider on a brtype and reqProvTask is false for all providers on a brtype, CMI will block checkin unless the version has at a task for at least one provider enabled on the brtype.
• If reqAnyTask is false and reqProvTask is false for all providers on a brtype, CMI will allow checkin even if the version does not have tasks for any provider.
• If reqAnyTask is false and reqProvTask is false for all providers on a brtype but a checkedout version on a branch of that type has a task for the provider, CMI will allow checkin and update the provider.
  
  
mkelem -ci or mkelem -mkpath -ci :
• If reqAnyTask is true for any provider on a brtype and reqProvTask is false for all providers on a brtype, CMI will allow mkelem to succeed but will block checkin unless a current task has been set.
• If reqAnyTask is false and reqProvTask is false for all providers on a brtype, CMI will allow checkin to succeed even without a set current task.
  
  
chtask :
• If reqAnyTask is true for any provider on a brtype and reqProvTask is false for all providers on a brtype, CMI will block chtask -remove of the last task among all providers on checkedin versions.
• If a version is checkedout, you can always remove all tasks on it, even when reqAnyTask is true.

The validate keyword affects only checkin.
• If enable is true and validate is true and the task exists at the provider, this command succeeds.
• If validate is false and enable is true, we do not contact the provider to validate the task.

CMI supports three policy keywords in UCM:
• The enable keyword turns the integration ON/OFF for this and all child streams. A value of true means that CMI operations will be performed for this provider. There is no default value, you must always specify -enable when creating a provider using mkcmprovider -stream.
• The reqProvTask keyword enforces or relaxes the policy that for every CM provider configured on a stream an activity must have a task association. This allows users to have both activities that participate in CMI and activities that do not. The default value is true.
• The validate keyword governs whether the provider server is contacted during setactivity to verify the existence of an associated task. The default value is true. (Introduced in 8.0.0.16, 8.0.1.9)
• The reqAnyTask keyword enforces or relaxes the policy that for every CM provider configured on a stream an activity must have a task association. This allows users to have both activities that participate in CMI and activities that do not. The default value is false. 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. (Introduced in 8.0.0.15, 8.0.1.8)
  
The reqProvTask, validate, and reqAnyTask keywords are specified as part of the -options option of mkcmprovider -stream, but the enable keyword is set using the -enable option. The following example shows how to configure these keywords for an existing provider on a stream.
cleartool mkcmprovider -stream intstr -replace -enable false -options reqProvTask:false,validate:true,reqAnyTask:false,activityFormat:%task_id MYCQPROV

In UCM, the validate keyword affects only the setactivity command. The reqProvTask and reqAnyTask keywords affect mkactivity, setactivity, and chactivity -task -remove. The enable keyword affects mkactivity, setactivity, lsactivity -find, chactivity -task, and rmactivity.

Here is how enable, validate, reqProvTask, and reqAnyTask affect UCM commands in CMI:

mkactivity -task:
• If enable is true and the task exists at the provider, the activity is created with a task association, setact succeeds, and the provider is updated. If the task doesn't exist, the activity is created but not set.
• If enable is false, CMI warns that the provider is disabled, but creates and sets the view. No task association is created on the activity.
• If reqProvTask is true and enable is true, the User must specify the -task form of the command.
  If reqProvTask is false, the User is not required to specify -task.
• If reqAnyTask is true, reqProvTask is false, and enable is true, the User must specify the -task (using any provider) form of the command.
  If reqAnyTask is false, the User is not required to specify -task.
  
  
setactivity -task:
• If enable is true and validate is true and the task exists at the provider, this command succeeds.
• If enable is false we do not set the activity, but return an error that we could not find an activity associated with that task.
• If reqProvTask is true, the User must specify -task if enable is true, or must specify an activity that has a task for this provider.
• If reqProvTask is false, the User can set an activity that has no task association.
• If reqAnyTask is true and reqProvTask is false, the User must specify -task (using any provider) if enable is true, or must specify an activity that has a task for any provider.
• If reqAnyTask is false, the User can set an activity that has no task association.
• If validate is false and enable is true, we do not contact the provider to validate the task.
  
  
lsactivity -find:
• If enable is true this command succeeds.
• If enable is false, no data are returned.
• The values of validate, reqProvTask, and reqAnyTask are ignored.
  
  
chactivity -tasks -add :
• If enable is true this commands succeeds.
• If enable is 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 and you are not attempting to remove the last one, this command succeeds if enable is true.
• If enable is false this command succeeds, but CMI does not update the provider.
• If reqProvTask is true for a configured provider (enable = true), then the activity must have at least one task association for this provider.
• If reqProvTask is false (enable = true), this restriction is not enforced.
• If reqAnyTask is true for any configured provider and reqProvTask is false for all configured providers (enable = true), then the activity must have a task association for at least one provider.
• If reqAnyTask is false (enable = true), this restriction is not enforced.
• chactivity -tasks -remove (when the activity has NO tasks) succeeds if enable is true but displays a warning that there were no tasks to remove.
• chactivity -tasks -remove (attempting to remove the LAST task for a provider) fails if enable is true and reqProvTask is true.
  Attempting to remove the last task among all providers fails if enable is true, reqAnyTask is true for any provider, and reqProvTask is false for all providers.
  If enable is true, reqProvTask is false, and reqAnyTask is false for all providers, CMI allows the last task to be removed and also updates the provider.
  If enable is false, CMI allows the task to be removed from the activity, and does not update the provider.
• The value of validate is ignored.
  
  
rmactivity is never blocked by CMI.
• If enable=TRUE, CMI will update the provider. If enable=FALSE, CMI will not try to update the provider.
• The values of reqProvTask, validate, and reqAnyTask are ignored.