How to perform ClearQuest record transitions with CMI

Answer

The ClearCase Change Management Integration (CMI) is able to perform state transitions on ClearQuest records. This is done using the default transition for a given record type defined in the ClearQuest schema being used with CMI.

Example:
Using the out of the box UCM schema and the BaseCMActivity record type, there are several default transitions defined for the states Submitted, Assigned, Opened, and Resolved:
Submitted > Assigned, Assigned > Opened, Opened > Resolved, Resolved > Closed

Note: For CMI it does not matter what the transition action is called as long as there is a transition marked as the default action for the state.

In order to utilize transitions with CMI and ClearQuest, they must be defined in the CMI configuration by using mkcmprovider.

Example for UCM ClearCase:
cleartool mkcmprovider -stream trans_proj_dev@/trans_pvob -options validate:true,activityFormat:TEST%task-id_%stream-name -context "userdb:CQWAN,dbset:CQWAN,queryuri:http://qwin319:12080/cqweb/oslc/repo/CQWAN/db/CQWAN/query/?rcm.name=Public%20Queries/testquery,cmtrans:[vobOp:set_activity;recordType:BaseCMActivity;startState:Ready;endState:Complete][vobOp:deliver_complete;recordType:BaseCMActivity;startState:Active;endState:Complete][vobOp:set_activity;recordType:BaseCMActivity;startState:Submitted;endState:Ready][vobOp:set_activity;recordType:BaseCMActivity;startState:Complete;endState:Submitted]" -enable "true" CQ_PROV


Example for Base ClearCase:
cleartool mkcmprovider -brtype main -context "userdb:CQWAN,dbset:CQWAN,queryuri:http://qwin319:12080/cqweb/oslc/repo/CQWAN/db/CQWAN/query/?rcm.name=Public%20Queries/testquery,cmtrans:[vobOp:checkout;recordType:BaseCMActivity;startState:Ready;endState:Complete][vobOp:checkout;recordType:BaseCMActivity;startState:Active;endState:Complete][vobOp:checkout;recordType:BaseCMActivity;startState:Submitted;endState:Ready][vobOp:checkout;recordType:BaseCMActivity;startState:Complete;endState:Submitted]" CQ_PROV


Note: The 4-tuple key:value pairs are separated by semi-colons (;) instead of commas (,). You can also use the -data option for mkcmprovider, and specify the configuration in a file. The transition entry line in that file for the Base ClearCase example above would be

cmtrans=[vobOp:checkout;recordType:BaseCMActivity;startState:Ready;endState:Complete][vobOp:checkout;recordType:BaseCMActivity;startState:Active;endState:Complete][vobOp:checkout;recordType:BaseCMActivity;startState:Submitted;endState:Ready][vobOp:checkout;recordType:BaseCMActivity;startState:Complete;endState:Submitted]

For both Base and UCM ClearCase, the transition keys are identical:

cmtrans:[vobOp:<operation>;recordType:<record type>;startState:<record state>;endState:<another record state>][...]

The cmtrans and its sub-keys must go in the -context in the mkcmprovider command on the branch type or stream. Each [...] block represents one transition rule. As many [...] blocks as necessary can be specified with the cmtrans: key.

In order for the keys within cmtrans to be valid, they must contain the 4 key:value pairs below:

1. vobOp - This is the ClearCase VOB operation for which the transition will occur. Valid choices for UCM are: set_activity and deliver_complete. Valid choices for Base ClearCase are: checkout.
   
   
2. recordType - This specifies the ClearQuest record type to transition for the given vobOp.
   
   Examples:
   
   Defect, BaseCMActivity, etc.
   
   If you'd like to have the same transition defined for both Defect and BaseCMActivity they must each be specified individually.
   
   
3. startState - This indicates the starting state that a ClearQuest record must be in for a CMI transition to occur. If a record is not in the state specified when CMI attempts to perform a transition on the record then there will be no action taken for that record.
   
   Examples:
   
   Submitted, Assigned, Opened, or Resolved
   
   
4. endState - This is the destination state that CMI will attempt to reach by using each record's default transitions. It can involve as many actions as are necessary to complete the transition and get to the destination state.
   
   Examples:
   
   Assigned, Opened, Resolved, or Closed
   
   Note: CMI will stop performing transitions on a record if any of the following occur:
• There is no default action for the current state.
• There are unpopulated fields that must be populated in order to perform the default action.
• There is an error from ClearQuest when performing a transition.
• The record ends up back in the startState.
• More than one vobOp, recordType, and startState triplet with the same values is defined.
  
  If one of the 4 above key:value pairs does not exist for a given transition it will be ignored.
  
  Examples:
  
  Valid transition:
  [vobOp:set_activity;recordType:BaseCMActivity;startState:Ready;endState:Complete]
  
  Invalid transitions:
  [vobOp:set_activity;startState:Ready;endState:Complete]
  [vobOp:set_activity;recordType:BaseCMActivity;endState:Complete]
  [recordType:BaseCMActivity;startState:Ready;endState:Complete]
  [vobOp:set_activity;recordType:BaseCMActivity;startState:Ready]