Configuring CMI for Plan state transitions

The Change Management Interface (CMI) performs state transitions on Plan records according to the schema rules for the allowed transitions for a record type.

For example, the Plan Agile schema allows direct transitions for a workItem record from the Submitted state to several destination states, including Active and Testing_Automation. For Plan, CMI also supports the use of an actions array in configuring the stream or brtype to allow Admins to enforce a sequence of state transitions without modifying the Plan schema.

If the stream or brtype CMI configuration includes the actions keyword, CMI checks if there is a single valid action for the record’s startState and if so, takes it. CMI repeats these steps until the record reaches the configured endState (success), or revisits the startState or an intermediate state again (error), or reaches a state with no single valid action (error).

If the stream or brtype CMI configuration does not include the actions keyword, CMI checks if the configured endState is an allowed destination state for the startState and if so, makes the transition directly.

To configure CMI for state transitions, you use the mkcmprovider command to establish the rules by which a ClearCase® operation transitions a Plan record type from one state to another:
cleartool mkcmprovider ... -context "application:application,repo:repo-id,queryuri:queryuri,state-transition-rules" ...
where state-transition-rules is of the form.
cmtrans:[vobOp:operation ;workItemType:workItem-type;startState:workItem-start-state;endState:workItem-end-state][ ... ], actions:[vobOp:operation;workItemType:workItem-type;startState:workItem-start-state;defaultAction:action][ ... ]
cmtrans specifies one or more record state-transition rules, where
  • vobOp:operation specifies a ClearCase operation.
    • For base ClearCase, only checkout is valid. (Specify mkcmprovider -brtype...)
    • For UCM, only setactivity and deliver -complete are valid. (Specify mkcmprovider -stream ...)
  • workItemType:workItem-type specifies a Plan workItem type. You can define the same transition for different workItem types, but there must be a separate definition for each type.
  • startState:workItem-start-state specifies the state of the workItem that is required before the transition can take place.
  • endState:workItem-end-state specifies the destination state of the workItem.
actions specifies one or more record state-transition rules, where
  • defaultAction:desired action from the specified start-state.
Transitions are not completed if:
  • More than one vobOp;recordType;startState triplet with the same values is defined.
  • One of the four key:value pairs does not exist.
  • Plan returns some error.

Examples

Legacy (direct) transitions (the line breaks are for legibility only):

cleartool mkcmprovider  -brtype main@/var/tmp/mmarynow/mmvob1 -context
"cmtrans:
[vobOp:checkout;workItemType:Defect;startState:Submitted;endState:Active],
application:SCRUM,
repo:e65b80c7-cecb-4c2a-8380-119156c379a0,
scmConfigName:CMICFG,
scmEventType:ClearCase,
queryuri:rcm.name=Personal Queries/My Defects" 
testPlanProv2

Transitions using actions:

cleartool mkcmprovider -brtype main@/var/tmp/plan_test_vob 
-options reqProvTask:false,reqAnyTask:true,validate:false -context 
"cmtrans:
[vobOp:checkout;workItemType:Defect;startState:Submitted;endState:Testing_Automation],
actions:
[vobOp:checkout;workItemType:Defect;startState:Submitted;defaultAction:Start]
[vobOp:checkout;workItemType:Defect;startState:Active;defaultAction:Testing],
application:SCRUM,
repo:1cc72b9a-9c2f-417e-9a82-842099d64277,
scmConfigName:CMICFG,
scmEventType:ClearCase,
queryuri:rcm.name=Personal Queries/My Defects" 
-enable true PLANPROV

Configure a UCM stream:

cleartool mkcmprovider  -stream intstr1@/var/tmp/mmarynow/mmpvob1 
-options reqProvTask:false,reqAnyTask:true,validate:false,activityFormat:plan%%task-id -context 
"cmtrans:
[vobOp:set_activity;workItemType:Defect;startState:Submitted;endState:Active]
[vobOp:deliver_complete;workItemType:Defect;startState:Active;endState:Closed],
application:SCRUM,
repo:e65b80c7-cecb-4c2a-8380-119156c379a0,
scmConfigName:CMICFG,
scmEventType:ClearCase,
queryuri:rcm.name=Personal Queries/My Defects" 
-enable "true" testPlanProv2