How to perform Rational Team Concert work item transitions with CMI

Answer

The ClearCase Change Management Integration (CMI) is able to perform state transitions on Rational Team Concert work items. This is done using default transition actions defined by CMI or user-defined default transition actions for a given work item type defined in the Rational Team Concert Project workflow being used with CMI.

Using the out-of-the-box scrum project template and the Defect work item type, CMI defines default transition actions for the states New, In Progress, and Resolved:
New > In Progress, In Progress > Resolved (Fixed), Resolved > Verified

Configuring state transitions for RTC:

In order to utilize transitions with CMI and Rational Team Concert, they must be added to the CMI configuration by using the mkcmprovider command. The key “cmtrans” indicates a desired state transition, while the key “actions” indicates a user-defined default action. Both keys are discussed in detail below.

Example for UCM ClearCase:
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


Example for Base ClearCase:
cleartool mkcmprovider -brtype main -context "queryUri:web/projects/cmi%20project%20(Change%20Management)#action=com.ibm.team.workitem.runSavedQuery&id=_rwGz4FeIEeOjR5YNkvoFJg&refresh=true,cmtrans:[vobOp:checkout;workItemType:Task;startState:New;endState:In Progress][vobOp:checkout;workItemType:Defect;startState:New;endState:In Progress]" RTC_PROV


Note: The 4-tuple key:value pairs are separated by semi-colons (;) instead of commas (,).

Example using a datafile for input:

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;workItemType:Task;startState:New;endState:In Progress][vobOp:checkout;workItemType:Defect;startState:New;endState:In Progress]

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

cmtrans:[vobOp:<operation>;workItemType:<work item type>;startState:<work item state>;endState:<another work item state>][...]

The cmtrans key 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. workItemType - This specifies the Rational Team Concert work item type to transition for the given vobOp.

Examples:

Defect, Task, Story, etc.

If you'd like to have the same transition defined for both Defect and Task they must each be specified individually.

3. startState - This indicates the starting state that a Rational Team Concert work item must be in for a CMI transition to occur. If a work item is not in the state specified when CMI attempts to perform a transition on the work item then there will be no action taken for that work item.

Examples:

New, In Progress, Resolved, etc.

4. endState - This is the destination state that CMI will attempt to reach by using each work item's default actions and transitions. It can involve as many actions as are necessary to complete the transition and get to the destination state.

Examples:

In Progress, Resolved, Verified, etc.

Note: CMI will stop performing transitions on a work item if any of the following occur:

• There is no default action defined for the current state.
• There is an error from Rational Team Concert when performing a transition.
• The work item ends up back in the startState.
• The work item is in the same state it previously was after attempting to perform an action.
• More than one vobOp, workItemType, 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;workItemType:Defect;startState:New;endState:In Progress]

Invalid transitions:
[vobOp:set_activity;startState:New;endState:In Progress]
[vobOp:set_activity;workItemType:Defect;endState:In Progress]
[workItemType:Defect;startState:New;endState:In Progress]
[vobOp:set_activity;workItemType:Defect;startState:New]

Note: You may have multiple transitions defined for the same vobOp and workItemType with different startStates. Only one transition will be performed for each task when a ClearCase vobOp occurs for the matching workItemType and startState.

To summarize, the example valid transition above:

[vobOp:set_activity;workItemType:Defect;startState:New;endState:In Progress]

will perform a transition on a ClearCase activity's associated Rational Team Concert work items (ClearCase tasks) when set_activity is performed on it. The transition will happen for each work item that is of the work item type Defect and is currently in the state New. CMI will use each work item's default actions (defined by CMI or by you) in an attempt to reach the In Progress state. CMI will either finish with each valid record in the In Progress state or it will stop performing transitions for one of the five reasons seen above for the endState key.

Default actions:

CMI provides several default actions for transitions. The defaults are listed below for each supported work item type in the format startState : defaultAction (readable name):

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 brtype or stream. They are included with CMI whether or not you have defined any default actions of your own. The CMI-provided default actions will always be used unless they are overridden by your configuration. If an applicable user-defined default action is found, the CMI-provided default action will be ignored.

Defining default actions:

If you want to utilize actions that are not provided by CMI, you can also define your own and those actions will override the predefined CMI default actions. Defining actions to be used for RTC state transitions is similar to defining the state transitions:

Example:
actions:[workItemType:Defect;startState:In Progress;defaultAction:com.ibm.team.workitem.defectWorkflow.action.resolve;resolution:3;resolutionComment:Works as Designed]


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 actions entry line in that file for the example above would be:

actions=[workItemType:Defect;startState:In Progress;defaultAction:com.ibm.team.workitem.defectWorkflow.action.resolve;resolution:3;resolutionComment:Works as Designed]

Note: 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. See the additional note following the 4-tuple key definitions.

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

actions:[workItemType:<work item type>;startState:<work item state>;defaultAction:<RTC action to perform>;resolution:<optional resolution choice>][...]

The actions key and its sub-keys must go in the -context in the mkcmprovider command on the branch type or stream (see the examples at the beginning of this technote). Each [...] block represents one action rule. As many [...] blocks as necessary can be specified with the actions: key.

In order for the keys within actions to be valid, they must contain the 3 key:value pairs below with an optional 4^th key:
1. workItemType - This specifies the Rational Team Concert work item type to apply the action to.

Examples:

Defect, Task, Story, etc.

If you'd like to have the same action defined for both Defect and Task they must each be specified individually.

2. startState - This indicates the starting state that a Rational Team Concert work item must be in to perform the given action. If a work item is not in the state specified when CMI attempts to perform the action on the work item then there will be no action taken for that work item.

Examples:

New, In Progress, Resolved, etc.

3. defaultAction - This is the default action that will 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 and must be accessed through the Eclipse Client.
To access the Process Configuration Source, open the RTC client and open the relevant Project Area. There is a tab in the Project Area named “Process Configuration Source” that contains XML for the Project Workflow.
The actions
For the work item type Defect (using 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>

The action id is used to define the defaultAction in CMI. In order to perform the “Start Working” action above the defaultAction would be “com.ibm.team.workitem.defectWorkflow.action.startWorking”, the startState would be “New”, and the workItemType would be “Defect”.

4. resolution - When an action would result in a state that also has a Resolution (e.g. Defect's Resolved state), users can specify the Resolution RTC should use. If you do not specify a Resolution, RTC will use the first Resolution in the list. For the work item type Defect, the available resolutions for the action “Resolve” are:
<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 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:
<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"/>

This means that Resolution “r1” is “Fixed” and Resolution “r4” is “Works for Me”.

Note:

Given that the resolution and action ids are not always human-readable, it is possible to add comments within each actions sub-key. As long as one of the 4 reserved keywords (workItemType, startState, defaultAction, and resolution) is not used then additional key:value pairs can be added. Refer back to the first example listed for UCM ClearCase to see the “resolutionComment:Works as Designed” key:value pair in the actions. Since resolutionComment is not a key used by CMI it and its value will be 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 document will show up when running an lsprovider -long command on the stream or brtype:

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:

Once you have configured transitions and any default actions on your stream or brtype, the appropriate transitions will occur automatically whenever the given conditions match. 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.