States customization on Team Services

states8

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.

states2

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.

states3

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.

states9

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.

states11

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: https://www.visualstudio.com/en-us/docs/work/process/manage-process

states7

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