title: Backlogs/boards workflow states & state categories
titleSuffix: Azure Boards
description: Understand how workflow states map to state categories and are used in boards and backlogs in Azure Boards & TFS
ms.custom: seodec18
ms.prod: devops
ms.technology: devops-agile
ms.assetid: C6FEEE5A-CD13-413E-8A3F-84A7D4F3A2C9
ms.author: kaelli
ms.manager: mijacobs
ms.manager: mijacobs
ms.topic: conceptual
monikerRange: '>= tfs-2013'
ms.date: 07/22/2019
[!INCLUDE temp]
All workflows consist of states, transitions, and reasons. Workflows are defined for a work item type (WIT). A transition supports forward and backward movement among two states. When you add a custom state, the system automatically adds transitions from the custom state to all other inherited states (except for Removed).
Each state belongs to a state category (previously referred to as a metastate). State categories support the Agile tool backlog and board views.
Workflow states define how a work item progresses upon its creation to closure. For example, the four main states defined for the User Story (Agile process) define a progression of four states, from New, Active, Resolved, to Closed. (The Removed state supports removing a work item from appearing on the backlog; to learn more, see Move, change, or delete work items.)
The natural progressions and regressions of the user story, product backlog item, and requirement WITs are as shown.
[!INCLUDE temp]
State categories, on the other hand, determine how Agile planning tools and select dashboard widgets treat each workflow state. The state categories used by the backlogs, boards and widgets are Proposed, In Progress, and Complete.
Here's how the default, inherited states map to the state categories for all three system processes plus test case management WITs. The workflow states for Test Case, Test Design, and Test Suite are the same across all four system processes.
[!INCLUDE temp]
| Categories | Work tracking WITs | Test tracking WITs |
|---|---|---|
| Proposed: Assigned to states associated with newly added work items so that they appear on the backlog. The first column on the Kanban boards and Taskboards map to a Proposed state category. | To Do | Design (Test Case) |
| In Progress: Assigned to states that represent active work. Work items assigned to states mapped to this category appear in the backlog (unless you choose to hide them) and make up the middle columns on Kanban boards. | Doing | Active (Test Plan) In Planning (Test Suite) In Progress (Test Suite) Ready (Test Case) |
| Resolved: Assigned to states that represent a solution has been implemented, but are not yet verified. Generally these states apply to bug WITs. Work items in a Resolved state appear on the backlog by default. The Agile tools treat the Resolved state category exactly the same as the In Progress state category. | n/a | n/a |
| Completed: Assigned to states that represent work that has finished. Work items whose state is in this category don't appear on the backlog and do appear in the last column of the Kanban board. Note that you can't modify states in this category nor can you add states to this category. | Done |
Closed (Test Case) Completed (Test Suite) Inactive (Test Plan) |
| Removed: Assigned to the Removed state. Work items in a state mapped to the Removed category are hidden from the backlog and board experiences. | n/a | n/a |
| Categories | Work tracking WITs | Test tracking WITs |
|---|---|---|
| Proposed: Assigned to states associated with newly added work items so that they appear on the backlog. The first column on the Kanban boards and Taskboards map to a Proposed state category. | New | Design (Test Case) |
| In Progress: Assigned to states that represent active work. Work items assigned to states mapped to this category appear in the backlog (unless you choose to hide them) and make up the middle columns on Kanban boards. | Active (Bug, Epic, Feature, User Story) | Active (Test Plan) In Planning (Test Suite) In Progress (Test Suite) Ready (Test Case) |
| Resolved: Assigned to states that represent a solution has been implemented, but are not yet verified. Generally these states apply to bug WITs. Work items in a Resolved state appear on the backlog by default. The Agile tools treat the Resolved state category exactly the same as the In Progress state category. | Resolved (Bug, Epic, Feature) | n/a |
| Completed: Assigned to states that represent work that has finished. Work items whose state is in this category don't appear on the backlog and do appear in the last column of the Kanban board. Note that you can't modify states in this category nor can you add states to this category. | Closed (Bug, Epic, Feature, User Story) |
Closed (Test Case) Completed (Test Suite) Inactive (Test Plan) |
| Removed: Assigned to the Removed state. Work items in a state mapped to the Removed category are hidden from the backlog and board experiences. | Removed (Epic, Feature, User Story) | n/a |
| Categories | Work tracking WITs | Test tracking WITs |
|---|---|---|
| Proposed: Assigned to states associated with newly added work items so that they appear on the backlog. The first column on the Kanban boards and Taskboards map to a Proposed state category. | New (Bug, Epic, Feature, Product backlog item) Approved To Do (Task) |
Design (Test Case) |
| In Progress: Assigned to states that represent active work. Work items assigned to states mapped to this category appear in the backlog (unless you choose to hide them) and make up the middle columns on Kanban boards. | Committed (Bug, Epic, Feature, Product backlog item) Open (Impediment) |
Active (Test Plan) In Planning (Test Suite) In Progress (Test Suite) Ready (Test Case) |
| Resolved: Assigned to states that represent a solution has been implemented, but are not yet verified. Generally these states apply to bug WITs. Work items in a Resolved state appear on the backlog by default. The Agile tools treat the Resolved state category exactly the same as the In Progress state category. | n/a | n/a |
| Completed: Assigned to states that represent work that has finished. Work items whose state is in this category don't appear on the backlog and do appear in the last column of the Kanban board. Note that you can't modify states in this category nor can you add states to this category. | Done |
Closed (Test Case) Completed (Test Suite) Inactive (Test Plan) |
| Removed: Assigned to the Removed state. Work items in a state mapped to the Removed category are hidden from the backlog and board experiences. | Removed | n/a |
| Categories | Work tracking WITs | Test tracking WITs |
|---|---|---|
| Proposed: Assigned to states associated with newly added work items so that they appear on the backlog. The first column on the Kanban boards and Taskboards map to a Proposed state category. | Proposed |
Design (Test Case) |
| In Progress: Assigned to states that represent active work. Work items assigned to states mapped to this category appear in the backlog (unless you choose to hide them) and make up the middle columns on Kanban boards. | Active Resolved (Epic, Feature, Requirement, Task) |
Active (Test Plan) In Planning (Test Suite) In Progress (Test Suite) Ready (Test Case) |
| Resolved: Assigned to states that represent a solution has been implemented but not yet verified. Generally these states apply to bug WITs. Work items in a Resolved state appear on the backlog by default. The Agile tools treat the Resolved state category exactly the same as the In Progress state category. | Resolved (Bug, Issue, Review, Risk) | n/a |
| Completed: Assigned to states that represent work that has finished. Work items whose state is in this category don't appear on the backlog and do appear in the last column of the Kanban board. Note that you can't modify states in this category nor can you add states to this category. | Closed |
Closed (Test Case) Completed (Test Suite) Inactive (Test Plan) |
| Removed: Assigned to the Removed state. Work items in a state mapped to the Removed category are hidden from the backlog and board experiences. | Removed | n/a |
Both States and Kanban columns are used to track the status of work. Workflow states are shared across a project while Kanban columns are shared within a team. Only project collection admins can add custom states, while team admins can add Kanban columns.
Add custom states when you want all teams to track the status according to the business workflow adopted by the organization. By customizing the process, you automatically customize the projects and WITs that reference that process.
Also, by adding custom states to support those workflow states that several teams want to track, you avoid the confusion that can arise when team's create a query based on a Kanban column. Because each team can customize the Kanban board columns and swimlanes, the values assigned to work items which appear on different boards may not be the same. The primary work around for this issue is to maintain single ownership of work items by team area path. Another work around is to formalize the columns by adding custom states which can be shared across teams.
::: moniker range=">= tfs-2018"
When you link a work item to a pull request (PR), you have the option to automatically complete those work items when you successfully complete the PR. As shown in the following image, all you have to do is check the box to Complete linked work items after merging. The system defaults to your selection for future PRs.
In the following circumstances the system won't automatically update the work item state to Done, Closed, or the state that belongs to the Closed category for the WIT:
- The work item, whose WIT is managed with the Inheritance process model, is already in a State that belongs to the Resolved category. In this instance the system won't update the State. For example, if a bug derived from the Agile process is in a Resolved state, the system won't transition it to Closed.
- The work item is already in a State that belongs to the Completed category. No further transition is required.
- The WIT associated with the work item contains one or more workflow field rules that prevent the work item being saved to a next state. For example, a rule requires that another field must be defined as part of closing the work item.
- For on-premises deployments and Azure Boards Hosted process model, you must modify the workflow to specify actions (ACTION element) to take place when transitioning the workflow. See Change the workflow for a work item type, Specify Actions.
To learn more about process models, see Customize your work tracking experience.
::: moniker-end
::: moniker range="azure-devops"
- Lead Time and Cycle Time control charts (widgets)
- Customize a workflow for a process ::: moniker-end
::: moniker range="azure-devops-2019"
- Lead Time and Cycle Time control charts (widgets)
- Change the workflow for a work item type
- ProcessConfiguration XML element reference
- Customize your work tracking experience ::: moniker-end
::: moniker range=">= tfs-2013 <= tfs-2018"