Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022
Workflows are central to how Azure Boards tracks work items. Each work item type has its own workflow that defines states, transitions, and reasons. Transitions move work items forward and backward between states. When you add a custom state, Azure DevOps adds default transitions based on process rules.
Azure Boards uses state categories to apply workflow behavior consistently across backlogs, boards, and widgets. This article explains how states map to categories and how that mapping affects item visibility, board columns, and reporting behavior.
Workflow states
Workflow states define how a work item moves from creation to closure. In the Agile process, a user story typically moves through New, Active, Resolved, and Closed. To remove a work item from the backlog, use the Removed state. For more information, see Move, change, or delete work items.
The following diagram shows the typical progression and regression paths for common work item types: user story (Agile), issue (Basic), product backlog item (Scrum), and requirement (CMMI).
Workflow states: User Story, Agile process
Category states
State categories standardize how Agile planning tools and dashboard widgets interpret workflow states. Teams map workflow states to these category states: Proposed, In Progress, Resolved, and Completed.
The following table shows how default inherited states map to category states across the four system processes, including Test Plan work item types. Test Case, Test Design, and Test Suite workflows use the same mappings across all four processes.
Categories
Work tracking
Test tracking
Proposed: Use this category for newly added work item states. Items appear on the backlog, and the first column on boards and Taskboards maps to Proposed.
New
Design (Test Case)
In Progress: Use this category for active work states. Items appear on the backlog (unless hidden) and map to middle board columns.
Active (Bug, Epic, Feature, User Story)
Active (Test Plan); In Planning (Test Suite); In Progress (Test Suite); Ready (Test Case)
Resolved: Use this category for states where a solution is implemented but not yet verified (commonly for bugs). Resolved items appear on the backlog by default, can be included in burndown charts, and behave like In Progress in many tools.
Resolved (Bug)
n/a
Completed: Use this category for finished-work states. Items don't appear on the backlog and map to the final board column. Each work item type can have only one state mapped to this category.
Closed (Bug, Epic, Feature, User Story)
Closed (Test Case); Completed (Test Suite); Inactive (Test Plan)
Removed: Use this category with the Removed state to hide items from backlog and board experiences.
Removed (Epic, Feature, User Story)
n/a
Where work item types appear
Use the following table as a quick reference for where each work item type category appears.
| Work item type category | Appears on |
|---|---|
| Requirement | Product board only |
| Feature | Feature portfolio board only |
| Epic | Epic portfolio board only |
| Custom | Custom portfolio board only |
Tip
Map each workflow state to a board column. If a state isn't mapped, it doesn't appear on the board.
Note
- Backlogs and boards hide completed or closed work items when their Changed Date is older than 183 days (about six months).
- Find hidden items by running a query.
- Show an item again on a backlog or board by making a minor update to refresh its Changed Date.
Note
- Backlogs and boards hide completed or closed work items when their Changed Date is older than one year.
- Find hidden items by running a query.
- Show an item again on a backlog or board by making a minor update to refresh its Changed Date.
Activated By/Date and Resolved By/Date fields
The system updates these fields—Activated By, Activated Date, Resolved By, and Resolved Date—based on workflow category state changes:
- When the workflow state changes to an In Progress category, the system updates Activated By and Activated Date.
- When the workflow state changes to a Resolved category, the system updates Resolved By and Resolved Date.
For more information about how workflow states map to state categories, see How workflow states and state categories are used in Backlogs and Boards.
Note
This logic applies to Azure DevOps Services, Azure DevOps Server 2020.1 update, and later versions.
Because these fields reference workflow state categories, any custom workflow states you add also trigger field updates. For more information, see Customize the workflow for a process.
Additional notes
- The fields update anytime a work item moves from a category state other than the one being set. For example, if you move a work item from New to Fixed, the Resolved By/Resolved Date fields update. If you move from Fixed to Ready for Testing—which are in the same category state—the Resolved By/Resolved Date fields don't update.
- When you transition backward, such as from a Resolved to an Active state, the system clears the Resolved By/Resolved Date fields. If you move from Active to New, the system clears the Activated By/Activated Date fields.
- Don't manually change these field values. These fields are system fields governed by system rules, and Azure DevOps overwrites any manual values.
When to add a State versus a column
Use states and columns together to track work status, but use each one for a different scope:
- State: Project-level workflow logic shared across teams.
- Column: Team-level board visualization.
Users with process-edit permissions (typically Project Collection Administrators or delegated process editors) can add custom states. Team Administrators and Project Administrators can add board columns.
Add custom states when teams need a shared workflow definition for queries, reporting, and cross-team consistency. Custom states propagate to work item types that reference the process.
Add or adjust columns when a team needs a board-specific view of work without changing the shared workflow.
To avoid confusion, keep work item ownership aligned to team area paths, or standardize shared workflows with custom states when multiple teams follow the same process.
Automatically complete work items with pull requests
When you link a work item to a pull request (PR), Azure DevOps can automatically complete the linked work item when the PR completes. For more information, see Auto complete work items with pull requests.
Automate work item state transitions
Azure DevOps can automatically update a parent work item's state based on the state of its child tasks. For details, see Automate work item state transitions.
Related content
Inheritance process model
On-premises XML process model
Dashboard widgets