How to use workflow states and state categories in Azure Boards backlogs and boards
Azure Boards | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018 - TFS 2013
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 from its creation to closure. The four main states that are defined for the User Story (Agile process) describe a user story's progression. The workflow states are New, Active, Resolved, and 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.
State categories 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.
The Basic process is available when you add a project to Azure DevOps Services or Azure DevOps Server 2019 Update 1. For earlier on-premises deployments, choose Agile, Scrum, or CMMI process.
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.
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 (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 aren't 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.
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. You can't modify states in this category nor can you add states to this category.
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.
Completed or closed work items don't display on the backlogs and boards once their Changed Date is greater than a year old. You can still list these items using a query. If you want them to show up on a backlog or board, then you can make a minor change to them which resets the clock.
Activated By/Date and Resolved By/Date fields
The system updates these fields—Activated By, Activated Date, Resolved By, and Resolved Date—when a change occurs based on corresponding workflow category states. When the workflow state changes to a Proposed state category, Activated By and Activated Date are updated. When the workflow state changes to a Resolved state category, Resolved By and Resolved Date are updated.
To learn more how workflow states map to state categories, see How workflow states and state categories are used in Backlogs and Boards.
The logic governing the fields described here applies to Azure DevOps Services, Azure DevOps Server 2020.1 update, and later versions.
Because these fields reference the workflow state categories, custom workflow states that you add are referenced when updating the fields. To learn more about customization, see Customize the workflow for a process.
- The fields get updated anytime a work item moves from any category state other than that being set. For example, if you update a work item from New to Fixed, the Resolved By/Resolved Date fields are updated. However, if you update from Fixed and Ready for Testing—which are in the same category state—the Resolved By/Resolved Date fields aren't updated.
- When you transition backwards, such as going from a Resolved to an Active state, the system clears the values for Resolved By/Resolved Date fields. If you got from Active to New, the system clears the values for Activated By/Activated Date fields.
- Don't manually change the values for these fields. They are system fields that are governed by system rules. Any value you attempt to set will get over written.
When to add a State versus a Kanban column
Use both States and Kanban columns 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.
Adding custom states to support workflow states that multiple teams want to track, helps avoid the resulting confusion of different teams creating queries based on a Kanban column. Because each team can customize the Kanban board columns and swimlanes, the values assigned to work items that appear on different boards might not be the same. The primary workaround for this issue is to maintain single ownership of work items by team area path. Another workaround is to formalize the columns by adding custom states that can be shared across teams.
Auto completion of work items with pull requests
When you link a work item to a pull request (PR), you can automatically complete those work items when you complete the PR. To learn how, see Auto complete work items with pull requests.
Inheritance process model
On-premises XML process model