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 (;).

The next example shows a configuration for base ClearCase (again, the line breaks are for legibility only):
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
You can also use mkcmprovider -data to 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 ClearCase and UCM, the transition keys are identical:
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.

The cmtrans keys must always contain the following key:value pairs:
  • 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.
Transitions are not completed if any of the following conditions is true:
  • 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

CMI provides several default actions for transitions. The defaults are listed below for each supported work item type in the format startState : defaultAction (human-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 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

You can define your own actions that override the predefined CMI default actions. Defining actions to be used for RTC state transitions is similar to defining the state transitions; for example,
actions:[workItemType:Defect;startState:In Progress;defaultAction:com.ibm.team.workitem.defectWorkflow.action.resolve;resolution:3;resolutionComment:Works as Designed]
You can also use mkcmprovider -data to 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]

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.

For both Base and UCM ClearCase, the actions keys are identical:
actions:[workItemType:type;startState:state;defaultAction:RTC-action;resolution:optional_resolution_choice][...]
The actions key and its sub-keys must be the argument to mkcmprovide -context on the branch type or stream. Each [...] block represents one action rule. As many [...] blocks as necessary can be specified with the actions key. For the keys within actions to be valid, they must contain the three key:value pairs below with an optional fourth key:
  • 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:
    <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"/>
    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:
    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 branch type, the appropriate transitions occur whenever the 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.