How to customize TFS 2010 work items and workflows

There are a lot of project templates available for Team Foundation Server, but you often need to tweak them to suit your team. This post explains how to customize work item types and workflows.

Team Foundation Server 2010 and add-ons

We use Team Foundation Server (TFS) 2010 to manage our projects including source control, product backlogs, tasks, and bug tracking.

Our setup consists of:

Customize a TFS work item

When you install TFS Power Tools you get an additional menu option called Process Editor under Tools in Visual Studio 2010:

Process Editor menu option in Visual Studio

The Process Editor allows you to edit work item types, either globally or for a specific TFS project.

For example, we can modify the Task work item type to add a custom field by clicking Work Item Types and selecting Open WIT from Server:

Work Item Types menu in Visual Studio

This brings up a dialog with the available TFS projects. So, if we want to modify the Task work item type for our website’s TFS project we’ll simply expand its node and select the Task work item type:

Work item selector dialog

We click New on the Fields tab to add a custom field:

New field button

Next, we give our new field a name, a reference name, and optionally a description:

Work item field properties dialog

Next, let’s add a rule for specifying available value options for this field. We click the Rules tab and click the Add button:

New rule button

We’ll select the SUGGESTEDVALUES option in the next dialog…

Field rule type dialog

…and then we set group restrictions (optional) and click the New button to add our options:

Suggested field value

Rule dialog

When we’re done we can switch to the Layout tab to add our field to the work item editor:

Work item editor layout dialog

We’ll set a label for the control and select the field we created earlier:

Work item field properties

Now, if we create a new Task work item…

New work item menu

…we’ll be able to see our new custom field in action:

New work item editor

Modify a TFS work item workflow

To modify a workflow you open up the work item associated with the workflow. We could for example modify the workflow for the Bug work item type in order to add additional states to make it fit our work process:

Work item type selector dialog

We click the Workflow tab to edit the workflow associated with the Bug work item type:

Workflow tab

The original workflow for the Bug item type in the Visual Studio Scrum 1.0 template takes bugs from New to Approved to Committed and finally to Done – unless they are Removed:

Diagram illustrating workflow for bug items in TFS

We want to rename some of these different states, and also add a few new ones. We do this by pulling up the standard Visual Studio toolbox which, when a workflow is being displayed, gives a few basic – but useful – artifacts to customize the workflow:

Workflow toolbox

Renaming a workflow state

First off we want to rename the somewhat confusing “Approved” state to “Verified” (indicating that the reported bug is indeed a bug), so we simply double-click the red state object and change its name to “Verified”:

State object

We also change the name of the “Committed” state to “In progress”:

State object

When the bug is done we consider it to be in need of approval, so we change the name of the “Done” state to “Awaiting approval”:

In order to allow a product manager, or other similar role, to approve the resolution of a bug we need to add two additional states: “Accepted” and the less popular “Not accepted”. We do this by adding a new State object to the workflow:

Adding new workflow state

We double-click the new State object and name it “Accepted”. We repeat this process for the “Not accepted state:

Renaming workflow state names

To connect the workflow states we click the Transition Link tool in the toolbox and then we click the “Awaiting approval” state followed by the “Accepted” state. We repeat this for the “Not accepted” state:

Adding transition links

When two state objects have been connected by a transition link we see a new blue transition object. We can click the downwards-pointing double arrow to modify the transition object:

Modifying transition links

Each transition must be given a reason which explains why the workflow progressed from one state to the next.

To set the reason why the workflow goes from “Awaiting approval” to “Accepted” we double-click the transition object connecting them. This brings up the Workflow Transition dialog:

Workflow transition dialog

We switch to the Reasons tab to set the reason(s) the change in state can occur. Simply click New to add a new reason:

Creating a new reason

In this case we’ll say that there are two reasons a Bug item can go into the “Accepted” state: 1) the customer has accepted the resolution (this is the default), or 2) the bug was accepted and given the OK by a developer.

First we’ll add the default reason, when the customer has accepted the fix:

Describing transition rule

Note that field rules can be applied on the Fields tab if necessary.

We’ll also add the second reason a Bug can become “Accepted”, when a developer gives it the OK:

Describing transition rule

So, we now have two reasons for a Bug going into the “Accepted” state:

Workflow transition reasons

We’ll repeat this process for the transition from “Awaiting approval” to “Not accepted”.

We will also add another transition link to allow the Bug item to go from “Not accepted” to “In progress” to allow us to have another go at fixing the bug.

All in all, our revised workflow looks like this:

Diagram of customized workflow

Once a Bug is “In progress” it can be set as “Awaiting approval” (because we believe it has been fixed). The customer can agree which would make the bug resolution “Accepted”. If the customer does not agree, the Bug will go into a state of “Not accepted” which in turn means we can start working on it again by setting the state to “In progress”.

We can now try and modify the State field for a Bug item to see the workflow in action. For example, we see that from the “Awaiting approval” state we can go to the “Accepted” or “Not accepted” states:

Work item field

Note: The workflow could optionally be complemented with a transition link from “Accepted” to “Not accepted” with a reason saying the bug was re-opened.