Configuring CMI for Rational Team Concert state transitions
You can configure the ClearCase® Change Management Integration (CMI) to perform state transitions on Rational® Team Concert (RTC) work items using default transition actions that are defined by CMI or the user-defined default transition actions for a specified work item type that is defined in the RTC Project workflow.
For example, for the RTC scrum project template and the defect work item type, CMI defines the following default transition actions for the states New, In Progress, and Resolved:
- New > In Progress
- In Progress > Resolved (Fixed)
- Resolved > Verified
To use transitions with CMI and Rational Team Concert, add them to the CMI configuration using the mkcmprovider command. The key cmtrans indicates a desired state transition, while the key actions indicates a user-defined default action. The following example shows a configuration for ClearCase UCM (the line breaks are for legibility only):
cleartool mkcmprovider -stream trans_proj_dev@/trans_pvob
-options validate:true,activityFormat:TEST%task-id_%stream-name
-context "queryUri:web/projects/cmi%20project%20(Change%20Management)
#action=com.ibm.team.workitem.runSavedQuery&id=_rwGz4FeIEeOjR5YNkvoFJg&refresh=true,
cmtrans:
[startState:New;endState:In Progress;vobOp:set_activity;workItemType:Defect]
[startState:In Progress;endState:Resolved;vobOp:deliver_complete;workItemType:Defect]
[startState:Reopened;endState:In Progress;vobOp:set_activity;workItemType:Defect],actions:
[workItemType:Defect;startState:In Progress;defaultAction:com.ibm.team.workitem.defectWorkflow.action.resolve;resolution:3;resolutionComment:Works as Designed]
[workItemType:Defect;startState:Reopened;defaultAction:com.ibm.team.workitem.defectWorkflow.action.startWorking]"
-enable "true" RTC_PROV
Note that the 4-tuple key:value pairs are separated by semi-colons (;).
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;workItemType:Task;startState:New;endState:In Progress]
[vobOp:checkout;workItemType:Defect;startState:New;endState:In Progress]"
RTC_PROV
cmtrans=
[vobOp:checkout;workItemType:Task;startState:New;endState:In Progress]
[vobOp:checkout;workItemType:Defect;startState:New;endState:In Progress]
cmtrans:
[vobOp:operation;workItemType:type;startState:state;endState:state][...]
The transition key
The cmtrans key and its sub-keys must go in the mkcmprovider -context argument on the branch type (for Base ClearCase) or the stream (for UCM). Each [vobOp ...] block represents one transition rule and you can specify as many blocks as you need.
- vobOp: The VOB operation that causes the transition. Valid choices for UCM are set_activity and deliver_complete. For base ClearCase, only checkout is valid.
- workItemType: The RTC work item type that is to be transitioned for the specified VOB operation. Examples: Defect, Task, Story, and so on. To define the same transition for both Defect and Task, you must specify the work item types individually.
- startState: The initial state that is required for the CMI transition to occur. If a work item is not in the specified starting state, no transition occurs. Examples: New, In Progress, Resolved, and so on.
- endState: The destination state that CMI attempts to realize using the work item's default actions and transitions. It can involve as many actions as are necessary to complete the transition and realize the destination state. Examples: In Progress, Resolved, Verified, and so on.
- No default action is defined for the current state.
- One of the four key:value pairs does not exist.
- The work item would transition to the startState.
- The state of the work item does not change after an attempt to perform an action.
- More than one vobOp, workItemType, and startState triplet with the same values is defined.
- RTC returns an error.
Default actions
- Defect defaults: New : com.ibm.team.workitem.defectWorkflow.action.startWorking (Start Working) In Progress : com.ibm.team.workitem.defectWorkflow.action.resolve (Resolve) Resolved : com.ibm.team.workitem.defectWorkflow.action.verify (Verify)
- Task defaults: New : com.ibm.team.workitem.taskWorkflow.action.startWorking (Start Working) In Progress : com.ibm.team.workitem.taskWorkflow.action.resolve (Resolve)
- Story defaults: New : com.ibm.team.apt.story.define (Start Working) In Progress : com.ibm.team.apt.storyWorkflow.action.a2 (Complete Development) Implemented : com.ibm.team.apt.storyWorkflow.action.a7 (Complete Testing)
- Epic defaults: New : com.ibm.team.apt.epic.workflow.action.a1 (Start Working) In Progress : com.ibm.team.apt.epic.workflow.action.a7 (Complete) Adoption Item defaults: Proposed : com.ibm.team.rtc.workflow.adoption.action.a2 (Approve) Approved : com.ibm.team.rtc.workflow.adoption.action.a3 (Complete)
Using the CMI-provided default actions
The CMI-provided default actions require no extra configuration beyond specifying the desired state transitions in the configuration of a branch type or stream. They are included with CMI whether or not you have defined any default actions of your own. The CMI-provided default actions are always used unless they are overridden by your configuration. If an applicable user-defined default action is found, the CMI-provided default action ise ignored.
Defining default actions
actions:[workItemType:Defect;startState:In Progress;defaultAction:com.ibm.team.workitem.defectWorkflow.action.resolve;resolution:3;resolutionComment:Works as Designed]
actions=[workItemType:Defect;startState:In Progress;defaultAction:com.ibm.team.workitem.defectWorkflow.action.resolve;resolution:3;resolutionComment:Works as Designed]
The example above is actually a 5-tuple due to the addition of a comment key. This key is not part of the integration nor is it a reserved key.
actions:[workItemType:type;startState:state;defaultAction:RTC-action;resolution:optional_resolution_choice][...]
- workItemType: The RTC work item type to apply the action to. Examples: Defect, Task, Story, and so on. To define the same action for both Defect and Task, you must specify them individually.
- startState - The starting state of the RTC work item that is required to perform the action; for example, New, In Progress, Resolved, and so on.
- defaultAction - The default action that is to be taken
for all transitions that use the workItemType and startState defined
above. This must come from the Process Configuration Source of the
RTC Project Area. The Process Configuration Source cannot be accessed
through the RTC web client; it must be accessed through the Eclipse
client. To access the Process Configuration Source, open the RTC client
and open the relevant Project Area. The Process Configuration Source
tab (in the Project Area) contains XML for the Project Workflow. The
actions For the work item type Defect (from the out-of-the-box scrum
project template configuration) and the state New, some example actions
are:
<state group="open" icon="processattachment:/workflow/open.gif" id="s1" name="New" showResolution="false"> <action id="com.ibm.team.workitem.defectWorkflow.action.startWorking"/> <action id="com.ibm.team.workitem.defectWorkflow.action.resolve"/> </state>
- resolution - When an action would result in a state that also has a Resolution (e.g.
Defect's Resolved state), you can specify the Resolution that RTC is to use. If you do not specify a
Resolution, RTC uses the first Resolution in the list. For the work item type Defect, the available
resolutions for the action "Resolve"
are:
The resolutions are designated with numbers (in the default workflow) when specifying them in the CMI configuration. So using resolution id "r1" would be "1" in the actions. The readable names for the resolutions are also contained in the Process Configuration Source:<action icon="processattachment:/workflow/resolve.gif" id="com.ibm.team.workitem.defectWorkflow.action.resolve" name="Resolve" state="s3"> <resolution id="r1"/> <resolution id="r2"/> <resolution id="r3"/> <resolution id="r4"/> <resolution id="r5"/> <resolution id="r8"/> </action>
The resolution and action identifiers are not always human-readable; you can add comments within each actions sub-key to explain them. As long as one of the four reserved keywords (workItemType, startState, defaultAction, and resolution) is not used, you can add more key:value pairs. Refer to the first example listed for UCM ClearCase in this topic to see the "resolutionComment:Works as Designed" key:value pair in the actions. Since resolutionComment is not a key used by CMI, it is ignored and you can use it (or another key of your choosing) to help define which Resolution is being used. This is also applicable with defaultActions or for any other reason. This only applies to the cmtrans and actions sub-keys. The resolutionComment key used in the example at the start of this topic is displayed when you run the lsprovider -long command on the stream or branch type:<resolution icon="processattachment:/workflow/reject.gif" id="r5" name="Invalid"/> <resolution icon="processattachment:/workflow/works.gif" id="r4" name="Works for Me"/> <resolution icon="processattachment:/workflow/wontdo.gif" id="r3" name="Works as Designed"/> <resolution icon="processattachment:/workflow/duplicate.gif" id="r2" name="Duplicate"/> <resolution icon="processattachment:/workflow/close.gif" id="r1" name="Fixed"/> <resolution icon="processattachment:/workflow/unresolve.gif" id="r0" name="Unresolved"/> <resolution icon="processattachment:/workflow/close.gif" id="r8" name="Fixed Upstream"/>
actions : [{defaultAction:com.ibm.team.workitem.defectWorkflow.action.resolve,resolution:3,resolutionComment:Works as Designed,startState:In Progress,workItemType:Defect}] cmtrans : [{endState:Resolved,startState:New,vobOp:set_activity,workItemType:Defect},{endState:In Progress,startState:New,vobOp:deliver_complete,workItemType:Task}]
Using default actions
- For transitions, the conditions are the work item type, start state, and VOB operation.
- For actions, the conditions are the work item type and start state when a transition is being performed.