Defining custom actions for state transitions

I heard this question few times: “I see the action named Microsoft.VSTS.Actions.Checkin to resolve work items in my tools, what other actions are available and how to use this feature to define my own”.


What is a “custom action”? Suppose you are building a tool that will take shelveset from users and resolve workitems after running tests. Each work item type has its own set of states and rules and resolution means different for each work item type. So Resolve for task might be to move state to “Closed”, while for bug it is moving to “Resolved”. Custom actions defines this transition in work item type.


Here is syntax from msdn link (it also has documentation on this) :


<TRANSITION from=”Working” to=”Ready To Build”>


                                <ACTION value=”Microsoft.VSTS.Actions.Checkin”/>

                                <ACTION value=”ADatum.Actions.Complete”/>




Let us take the example of resolving a bug again. We do it in the pending changes window (or checkin dialog) where work items can be associated with changesets before checking in, and upon checkin the work item will be resolved. Here is sample code piece that will do it:


                string nextState = wi.GetNextState(“Microsoft.VSTS.Actions.Checkin”);

                if (!String.IsNullOrEmpty(nextState))


                                wi[CoreFieldReferenceNames.State] = nextState;

                                wi.History = “Work item resolved by tool xxx for reason yyy associated with changeset ccc”;



This basically calls GetNextState of a work item and passes the action. Next state is returned if the action is valid and the next state is possible with given rules. You can programmatically move the work item to next state.


This technique can be used in automated tools to work across various work item types in common way. This solves the problem for consistently handling state transitions and to check if a work item type can handle a specific action. We are thinking in the lines of extending this with features such as: ensuring a certain groups or categories of workitemtypes have specified set of fields, rules etc so that tools can handle groups of types consistently and automate wide range of functions.

Comments (5)

  1. Hosam Kamel on Get up to speed on Visual Studio 2008. The US ISV Developer Evangelism Team Blog on Hierarchical…

  2. Bertrand says:

    The checkIn action is nice but most people remove it from the process template because you cannot set the default to be associate instead of it going directly to resolve.

    Could we change the code for that to happen instead?

  3. Daniel says:


    Thanks for your post. However, i still haven understod how to create a custom action (and i havent found anything on the net either).  Is the custom action only to be configured in xml or is the custom action a piece of .net code?

    If a custom is only to be configured in xml, where can i do that. From my understanding, the above xml snippet only shows how an action is assigned to a transition.

    If a custom action is a piece of code, where can i find the documentation concerining that topic. which interfaces have to be implemented, how is the piece of code to be integrated into tfs?

    i am grateful for any answer

  4. Mike Cheel says:


    A little late but my guess is that one way to accomplish this is to first define the action inside the work item template, Next write code that subscribes to the tfs workitemchanges event ( and then write code that calls GetNextState (…/microsoft.teamfoundation.workitemtracking.client.workitem.getnextstate(v=vs.100).aspx)