Bemærk
Adgang til denne side kræver godkendelse. Du kan prøve at logge på eller ændre mapper.
Adgang til denne side kræver godkendelse. Du kan prøve at ændre mapper.
Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022
After you add or modify workflow states for a work item type, define rules that apply based on state changes. Workflow state rules support the following scenarios:
- Support an approval process.
- Prevent unauthorized users from setting an invalid state.
- Make a field required, read-only, or set to another value based on state changes.
- Restrict transitions from one state to another.
- Restrict or allow state transitions to specific users or groups.
- Maintain a controlled workflow process that supports auditing requirements.
- Automate closure of parent work items.
- Support an approval process.
- Prevent unauthorized users from setting an invalid state.
- Make a field required, read-only, or set to another value based on state changes.
- Restrict transitions from one state to another.
- Automate closure of parent work items.
Important
The Inheritance process model is available for projects that are configured to support the model type. If you use an older collection, check the process model compatibility. If your on-premises collection is configured to use the on-premises XML process model, you can only use that process model to customize the work tracking experience. For more information, see Organization-level process customization.
Tip
You can use AI to help with this task later in this article, or see Enable AI assistance with Azure DevOps MCP Server to get started.
Prerequisites
| Category | Requirements |
|---|---|
| Permissions | - To manage security groups and permissions at the project level, which includes setting rules for workflow states: Project Administrator. - To manage the work tracking area: Project Administrator or specifically assigned the Work Item Tracking permission. |
| Access levels | Basic access, which is typically sufficient for most users who need to manage work items and apply rules to workflow states. |
Understand workflow rules
The following list outlines the three groups of workflow rules:
Standard actions:
- Apply when a work item is created, in a selected state, or moved from one state to another.
- Actions include setting the value of a field, making a field read-only, or making a field required.
- You can specify one or two conditions and several actions.
Restricting state transitions:
- Specify one condition indicating the state a work item moved from.
- Define actions to restrict transitions from that state to other states.
Restricting state transitions based on user or group membership:
- Specify one condition based on user or group membership.
- Define one action to restrict a transition from one state to another.
The following list outlines the two groups of workflow rules:
Standard actions:
- Apply when a work item is created, in a selected state, or moved from one state to another.
- Actions include setting the value of a field, making a field read-only, or making a field required.
- You can specify one or two conditions and several actions.
Restricting state transitions:
- Specify one condition indicating the state a work item moved from.
- Define one or more actions to restrict transitions from that state to other states.
Condition
Supported actions
Set field value or make read-only/required based on State
Restrict a transition based on State
Hide field or make field read-only or required based on State and user or group membership
Based on user or group membership, set a field attribute or restrict a state transition
Note
When you customize an inherited process, any projects that use the process automatically reflect the customizations. To ensure a smooth transition, we recommend that you create a test process and project to test your customizations before you implement them organization-wide. For more information, see Create and manage inherited processes.
Understand workflow state and rule limits
Workflow rules apply when you add or modify work items through any of the following interfaces:
- Web portal: Work item form, bulk updates, updates in query view
- Web portal: Board or Taskboard, move work item to column
- Visual Studio 2017 and earlier versions, work item form
- CSV file format: Bulk import or update
- Excel: Bulk import or update
- REST API: Add or modify work items
The following table summarizes the workflow state and rule limits for the Inheritance process.
| Object | Inheritance limit |
|---|---|
| Work item types defined for a process | 64 |
| Workflow states defined for a work item type | 32 |
| Rules defined for a work item type | 1024 |
When you define workflow states and rules, follow these guidelines to minimize performance issues:
- Limit the number of rules for a WIT: While you can create multiple rules for a work item type (WIT), more rules can negatively affect performance when users add or modify work items. The system validates all rules associated with the fields for the work item type when users save work items. In some cases, the rule validation expression might become too complex for SQL to evaluate.
- Limit the number of custom work item types: Reducing the number of custom work item types helps maintain optimal performance.
Define a rule
Before you define a rule based on workflow states, ensure the following elements are in place:
- Workflow states: Define the workflow states as described in Customize a workflow.
- Custom fields: If your rule requires a custom field, add it to the work item type as described in Add and manage fields.
- Security groups: If your rule requires a security group to grant or restrict changes based on user or group membership, define the security group as described in Add or remove users or groups, manage security groups.
For more information about defining rules, see Add a custom rule.
Set field value or make field read-only or required
By using the first grouping of rules, you can specify one or two conditions and up to 10 actions per rule.
Example of ensuring team lead approval before active work
In this example, development teams want to ensure that no User Story gets worked on until a team lead approves it. This example uses the default workflow states, with the addition of a custom field, Approved By, and a security group, Team Leads Group.
Default workflow states
Rule requirements
To ensure approval before active work, define the following rules:
- Require the Approved By field to be filled in when the State moves from New to Active
- Restrict users who aren't in the Team Leads Group from filling in the Approved By field
- Clear the Approved By field when the State moves to New or Removed
Rule definitions
The rule requirements translate to the following four rule definitions.
Rule name
Condition
Actions
Approved By cleared when New
When A work item state changes to New
Then Clear the value of Approved By
Approved By cleared when Removed
When A work item state changes to Removed
Then Clear the value of Approved By
Approved By Read-only
When Current user is not member of group Team Leads Group
Then Make read-only Approved By
Approved By required
When A work item state changes from New to Active
Then Make required Approved By
Restrict state transitions
When you specify the condition A work item state moved from ..., you can specify only that condition.
You can specify up to 10 actions.
Example of restricting state transitions and Approved state
The following workflow states are defined for the User Story. The New, Resolved, and Removed inherited states are hidden. Instead, Proposed, In Review, and Cut states are used. In addition, three more states are defined: Research, Design, and Approved. These states should follow the sequence in the following image.
Without any restrictions, users can move from one state to any other state, both forward and backward within the sequence.
Rule requirements
To support a more controlled workflow, the business group decided to institute rules that support the following forward and reverse state transitions on the User Story work item type.
| State | Transition rule |
|---|---|
| Proposed | Can only move to Research and Cut |
| Research | Can only move to Design and Cut |
| Design | Can only move to Research, Approved, and Cut |
| Approved | Can only move to Design, Active, and Cut |
| Active | Can only move to In Review |
| In Review | Can only move to Active (More work found), Closed or Cut |
| Closed | Can move to Research, Design, Active, In Review (Allows for cases where user closed the work item in error) |
| Cut | Can only move to Proposed |
Note
When you restrict state transitions, account for cases where a user might move a state in error. Ensure users can recover gracefully.
Additionally, the business group wants to apply the following rules for required fields:
- Require the Approved By field to be filled in when the state moves from Approved to Active.
- Allow only users in the Authorized Approvers group to fill in the Approved By field.
- Clear the Approved By field when the state moves to Cut.
- Require the Acceptance Criteria field to be filled in when the state moves to Active.
Rule definitions
To implement the previously mentioned restrictions, the process administrator adds a custom Approved By identity field, an Authorized Approvers security group, and the following rules.
Rule name
Condition
Actions
Proposed state
When A work item state moves from Proposed
Then Restrict the state transition to Design
And Restrict the state transition to Approved
And Restrict the state transition to Active
And Restrict the state transition to In Review
And Restrict the state transition to Closed
Research state
When A work item state moves from Research
Then Restrict the state transition to Proposed
And Restrict the state transition to Approved
And Restrict the state transition to Active
And Restrict the state transition to In Review
And Restrict the state transition to Closed
Design state
When A work item state moves from Design
Then Restrict the state transition to Proposed
And Restrict the state transition to Active
And Restrict the state transition to In Review
And Restrict the state transition to Closed
Approved state
When A work item state moves from Approved
Then Restrict the state transition to Proposed
And Restrict the state transition to Research
And Restrict the state transition to In Review
And Restrict the state transition to Closed
Active state
When A work item state moves from Active
Then Restrict the state transition to Proposed
And Restrict the state transition to Research
And Restrict the state transition to Design
And Restrict the state transition to Approved
And Restrict the state transition to Closed
And Restrict the state transition to Cut
In Review state
When A work item state moves from In Review
Then Restrict the state transition to Proposed
And Restrict the state transition to Research
And Restrict the state transition to Design
And Restrict the state transition to Approved
Closed state
When A work item state moves from Closed
Then Restrict the state transition to Proposed
And Restrict the state transition to Cut
Cut state
When A work item state moves from Cut
Then Restrict the state transition to Research
And Restrict the state transition to Design
And Restrict the state transition to Approved
And Restrict the state transition to Active
And Restrict the state transition to In Review
And Restrict the state transition to Closed
Approved state required fields
When A work item changes from Approved to Active
Then Make required Acceptance Criteria
And Make required Approved By
Authorized Approvers
When Current user is not a member of Authorized Approvers
Then Make read-only Approved By
Clear Approved By field
When A work item state changes to Cut
Then Clear the value of Approved By
Verify state transition restrictions
After you define the rules for the process and update the project, refresh your browser. Verify the operations through the work item form and the board.
For the rules defined in the previous table, check the State dropdown menus. Open the board and ensure you can move from one state to another.
| Proposed | Research | Design | Approved |
|---|---|---|---|
 |
 |
 |
 |
| Active | In Review | Closed | Cut |
 |
 |
 |
 |
Restrict state transition based on user or group membership
You can specify only one of the two conditions based on user or group membership: Current user is member of group ... or Current user is not member of group ....
You can specify only one action: Restrict the transition to state....
Note
Work items are subject to rules applied to them. Conditional rules based on user or group membership are cached for your web browser. If you find yourself restricted to update a work item, you may have encountered one of these rules. If you believe you've encountered an issue that doesn't apply to you, see Work item form IndexDB caching issues.
Automate state transitions of parent work items
To automate state transitions for parent work items based on the state assignments of their child work items, see Automate work item state transitions.
Automate reassignment based on state change
The Agile process Bug work item type previously included a rule that reassigned the bug to its creator. The default system process no longer includes this rule. You can reinstate the rule or add a similar rule to other work item types by using the following condition and action:
When A work item state changes to Resolved, then Copy the value from Created By to Assigned To.
Use AI to configure workflow rules
Tip
You can use AI to help with this task later in this article, or see Enable AI assistance with Azure DevOps MCP Server to get started.
If you use GitHub Copilot, the Azure DevOps MCP Server can help you design and implement workflow state rules through natural language prompts.
Example prompts for workflow rules
| Task | Example prompt |
|---|---|
| Build an approval workflow | Create workflow rules for my Bug work item type so that when the state changes to Ready for Review, the Assigned To field is set to the team lead and the Priority field becomes read-only until it moves to Approved |
| Restrict state transitions by role | Configure rules so that only members of the Release Managers group can move User Stories from Testing to Done, and prevent anyone else from making that transition |
| Enforce required fields on state change | Add rules to my Task work item type that require the Resolution field and Root Cause field to be filled in before a task can be moved from Active to Resolved |
| Auto-close parent work items | Set up rules to automatically close a Feature when all its child User Stories reach the Done state. Explain how the auto-complete parent rule works and any limitations I should know about |
| Troubleshoot conflicting rules | I'm getting a VS1640113 error about duplicate rules with the same conditions. Help me identify which rules in my inherited process conflict and show me how to fix the overlap |
| Design a regulated workflow | Our team needs to meet SOC 2 compliance for state transitions. Design workflow rules that enforce separation of duties — the person who created a work item can't be the one to approve it, and all state changes must be auditable |
Tip
For the best results, use these prompts in agent mode with the Azure DevOps MCP Server connected. Customize the prompts with your specific work item types, fields, or compliance requirements.