States customization on Team Services

Derrick Fu


The first milestone in bringing states customization to Team Services is here. With the latest deployment, you can customize the states on your inherited work item types. Let’s jump into the new functionality.

Adding custom states

Adding new states starts from the process administration page. Here you can view all the states for a work item type, and add and modify them as needed.


To add a new state, simply click “New state” on the toolbar. Provide a name, state category (more on state categories later), and color for your state.


When typing a name in the dialog, the dropdown offers suggestions on states used by other work item types within the process. This allows process administrators to optionally standardize on the same states across work item types. This is purely a suggestion so you can choose to have different colors or state categories for the same state name if you wish.


Once you have added a custom state, the state will now appear in the states dropdown for the work item type as well as in the query editor. A couple things to note here: 1) you may have to do a full page refresh before you will see your new state and 2) the states currently appear in alphabetical order in the dropdown.

The color you specify will appear throughout the product including on the work item form, backlog, boards, query results, and more.


Removing custom states and hiding inherited states

In addition to adding custom states, you can remove custom states. To do this simply, open the context menu and click remove. Inherited states (denoted by thestates6 icon to the left of the color) cannot be edited, but they can be hidden. You can learn more about process inheritance here:


The impact of removing a state and hiding a state are equivalent:

  • The state no longer appears in the states dropdown for that work item type nor does it appear in the query editor dropdown for the state field.
  • New work items cannot move into the state.
  • Existing work items maintain their state value, but are in an invalid state. If you want to make a change to the work item, the state values must be updated. If you add the state back to the work item type, these work items will become valid again.
  • Work item history is left unchanged.

State categories

State categories are a new concept we are introducing. They are a named grouping for a set of states that allow experiences such as the backlog and board to work with customized states. The product currently supports five state categories:

  1. Proposed – These states represent work items that are not yet being worked on and will appear on the backlog. The first column on the Kanban or Task board must map to a Proposed state.
  2. In Progress – These states represent active work. These states will appear on the backlog, and make up the middle columns of your Kanban board.
  3. Resolved – These states represent work items that have a solution, but are not yet verified. Generally applicable to bug work item types. Work items in a Resolved state will now appear on the backlog by default.
  4. Completed – The Completed state category represents finished work items. You cannot modify states in this category nor can you add states to this category at this time.
  5. Removed – Work items in a state that is mapped to the Removed category are hidden from the backlog and board experiences.

Still to come

In this initial release, we focused on enabling the most common scenarios of adding custom states. There are still a few more we have on our backlog that we will pick up later in the year:

  • Ordering – We want to make order a first class property of states and have the states dropdown reflect this. This will enable users to reorder states within a state category.
  • By/Date fields – One of the top customizations customers do today with states is to write rules that track who performed a state transition as well as when the transition was performed. We want to make this a first class part of custom states by enabling this automatically.
  • Transition restrictions – We’ve seen many enterprises have specific workflows that enforce certain state transitions (e.g. the work item must be Resolved before it can be Closed) as well as business logic on transitions (e.g. only the PO can make a work item Active)

Please comment or email with any feedback or questions.

Derrick Fu Progam Manager, VSTS


Discussion is closed. Login to edit/delete existing comments.

  • Evan Masters 0

    Thanks Derrick, seems straight forward enough.

    The ‘New State’ option in my view is present but disabled. Any thoughts on why this might be? I’m the Organization owner if that makes a difference.


  • Mykola Fedchyk 0

    Hi Derrick!
    These five categories are covering most statuses in Agile development, but sometimes we (customers) are an attempt to use the Azure DevOps for other relevant processes such as staff recruiting f.e.
    Have you any plans to create an ability customizing not only states but state categories? Or at least to rename a state category visible label?
    Or maybe there any reasons why it isn’t implemented?

    • Steffen Dyhr-Nielsen 0

      I 100% agree.. The sole basic of an agile process is to be agile, hence customization according to context. The lock to these 5 categories is to rigid for a flexible setup. It surprises me that this blog post is nearly 4 years old and nothing has happened in that regard.

Feedback usabilla icon