Work Item States in Azure DevOps

I am often asked about the states of a work item in Azure DevOps. Can I add new states. Can I add a state just for my team? How do I stop my users from changing the state from New and going directly to closed?

So I thought I would talk a bit about Work item states. I’ll organize this article into 4 separate components.

State Category: The categories of states built into the product that you cannot change, but an build on.

States: The states defined my the process template that you can customize and change in your inherited process.

State Rules: How to set up rules that allow you to restrict the transition from one state to another.

Board Columns: A team level configuration that allows a team to create a KANBAN board with multiple variants of a State.

State Category

The state categories for a work item are built right into the product. For example the state categories of a User Story in the Agile template are Proposed, In Progress, Completed, Removed, this is the same for a Product Backlog Item in the Scrum template. However in the Basic and CMMI templates the base states for an Issue and a Requirement are Proposed, In Progress and Completed.

So to understand what the state categories are just navigate to Organization Settings > Process. Select the process template you are using, open the work item type you want to see, and go to the states tab.

The categories can’t be changed. You can however customize the states within these by editing the Process Template.

States

Azure DevOps comes with four process templates to choose from as a starting point Basic, Agile, Scrum and CMMI.

To do any customizations to a process template (including state changes) you must first inherit from the base template and create your own. Click on the ellipsis that appears when you hover over the base template you want to inherit from and select Create Inherited Process.

You will see the Process Template defines states within each category:

In your inherited process you can hide these and add your own. You cannot however edit the states defined in the base process template you inherited from. For example if you want to change the Agile template to include a state called Approved under the Proposed category you can just click on the New State at the top and fill out the form. Selecting which category it should belong under.

You can select move up or move down from the ellipsis to change the order of the states within a category. If you wanted to replace New with Approved you can hide New. As I mentioned before it cannot be deleted, but it can be hidden.

State Rules

If you would like to customize the template to only allow certain transitions between states. You can do this by defining a rule. Within the work item customization screen you will see a tab called Rules. Select that and click New Rule. As an example; lets say we don’t want users of the system to be able to change the state directly from New to Resolved or Closed.

To do that create a rule using the Condition A work item state moved from and the Action Restrict the transition to state.

With this rule in place this, a new work item of this type can only transition to Active or Removed, but nor Resolved or Closed.

Side note: Removed and Closed are two different things. This is great from an audit perspective, and to maintain traceability of what we have done. Closed means we completed this work. Removed means we were going to do this and abandoned the idea at some point in the process.

Board Column

What if one team wants to make changes to the state of a work item but others like it the way it is now.

For example: lets say we are using the Scrum template and one team wants to split the In Progress Category into Development and Testing instead of just Committed. If we do that it affects everyone, perhaps other teams are further along the Agile transformation path and are very happy with a single state of committed under the In Process Category.

Another example is to split New, so the Product Owner can show what is proposed vs what is currently in detailing or zooming. Items he/she is working on so they are ready for the team to commit to.

Board Columns help in these scenarios. They are configurable for each team in Azure DevOps. If you hit the gear above a teams KANBAN board you can make these changes to their board. Lets use our first example to show you how.

When you open a teams board each column will map to each different state of the work items defined in the Requirement backlog under Backlog levels in the Process template. Also to the bug if you have selected the option Bugs are managed with requirements. For the purpose of our example we’ll use the Scrum process and set working with bugs to Bugs are not managed on backlogs and boards. Therefore all that will show up in the boards are Product Backlog Items.

It should look something like this:

At the top right click on the gear to open the Team settings page and navigate to Columns under the Board section of this page.

for our example lets split Committed into two Board Columns Development and Testing.

Select the Committed column. There are two things we need to think about here. What to name it and it’s State Mapping.

Lets change the Name to Development and leave the mapping as Committed.

Now add a column using the “+ Column” button at the top. Set the Name to “Testing” and map it to the Committed State and drag it over so it shows up after Development.

Save your changes and check out your board now.

Committed is now split into Development and Testing. However they both map to the committed state, so if anyone queries for all the committed stories they will see everything from both Development and Testing.

However you can now query for everything in Development or Testing by searching on the Board Column field. Or just add Board Column to your query results.

As you can see there is more to work item states than how Azure DevOps behaves out of the box. I hope this helps to explain it for those who have not delved into these configurations.