Apply rules to workflow states (Inheritance process)
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
After you add or modify your workflow states for a work item type, you might want to define one or more rules that are applied depending on the workflow state change. Adding rules to workflow states supports the following scenarios:
- Support an approval process
- Prevent unauthorized users from setting an invalid state
- Make a field required or read-only or other value based on State changes
- Restrict transition from one state to another
- Restrict or allow State transitions to specific users or groups
- Maintain a controlled workflow process to support auditing requirements
- Automate closure of parent work items
- Support an approval process
- Prevent unauthorized users from setting an invalid state
- Make a field required or read-only or other value based on State changes
- Restrict transition from one state to another
- Automate closure of parent work items
- Support an approval process
- Make a field required or read-only or other value based on State changes
- Automate closure of parent work items
Review this article to understand how to define rules that apply when you change a workflow state.
- Understand the types of workflow rules
- Workflow state and rule limits and best practices
- Set a field value or make a field read-only or required based on State selection
- Restrict state transitions
- Restrict or allow State transitions to specific users or groups
- Automate state transitions of parent work items
- Understand the types of workflow rules
- Workflow state and rule limits and best practices
- Set a field value or make a field read-only or required based on State selection
- Restrict state transitions
- Automate state transitions of parent work items
- Understand the types of workflow rules
- Workflow state and rule limits and best practices
- Set a field value or make a field read-only or required based on State selection
- Automate state transitions of parent work items
Important
The Inheritance process model is available for projects configured to support it. If you’re using 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 Choose the process model for your project collection.
Workflow rules
The following table indicates the three groups of workflow rules you can define. The first group applies standard actions when a work item is created, in a selected state, or is moved from one state to another. These standard actions set the value of a field or makes a field read-only or required. In this group, you can specify one or two conditions and several actions.
The second and third groups support restricting state transitions. These two groups allow you to specify one and only one condition indicating the state a work item has moved to. You can then specify one or more actions to restrict the transition from that state to other states.
The following table indicates the two groups of workflow rules you can define. The first group applies standard actions when a work item is created, in a selected state, or is moved from one state to another. These standard actions set the value of a field or makes a field read-only or required. In this group, you can specify one or two conditions and several actions.
The second group supports restricting state transitions. In this second group, you can specify one and only one condition indicating the state a work item has moved to. You can then specify one or more actions to restrict the transition from that state to other states.
Note
Certain features require installation of Azure DevOps Server 2020.1 update. For more information, see Azure DevOps Server 2020 Update 1 RC1 Release Notes, Boards.
Workflow conditions and actions you can set are illustrated in the following images. You can apply standard actions when a work item is created, in a selected state, or is moved from one state to another. These standard actions set the value of a field or make a field read-only or required. For this set of rules, you can specify one or two conditions and several actions.
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 and user or group membership, set a field attribute or restrict a State transition
Note
When you customize an inherited process, any projects using that process automatically reflect the customizations. To ensure a smooth transition, we recommend creating a test process and project, which allows you to test your customizations before you implement them organization-wide. For more information, see Create and manage inherited processes.
Workflow state and rule limits
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 defining workflow states and rules, we recommend that you consider the following guidance in order to minimize performance issues.
- Minimize the number of rules you define for a WIT. While you can create multiple rules for a WIT, addition rules can negatively impact performance when a user adds and modifies work items. When users save work items, the system validates all rules associated with the fields for its work item type. Under certain conditions, the rule validation expression is too complex for SQL to evaluate.
- Minimize the number of custom work item types.
Workflow rules are applied when adding or modifying 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
Define a rule
Before you define a rule based on workflow states, define the following elements:
- The workflow states that you want as described in Customize a workflow
- If your rule requires specification of a custom field, add that field to the work item type as described in Add and manage fields
- If your rule requires specification of a security group to grant or restrict changes based on user or group membership, define that security group as described in Add or remove users or groups, manage security groups.
For the basics of defining rules, see Add a custom rule. You must meet the prerequisites defined in that article.
Set field value or make field read-only or required
With 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 is worked on until approved by a team lead. The default workflow states are in use and only a single custom field, Approved By, and security group, Team Leads Group, are added.
Default workflow states
Rule requirements
To ensure approval before active work, define the following rules:
- Require the Approved By field be filled in when the State moves from New to Active
- Restrict users who don't belong to the Team Leads Group to fill 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 specifying the condition, A work item state moved from ...
, you can specify only that condition. You can specify up to 10 actions.
Note
This feature requires Azure DevOps Server 2020.1 update or later version.
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: Investigate, Design, and Approved. These States should follow the sequence as shown 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 would support the following forward and reverse state transitions on the User Story work item type.
- 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 restricting state transitions, consider those cases where a user moves a state in error. You want users to be able to recover gracefully.
Additionally, the business group wants to apply rules for required fields:
- Require the Approved By field be filled in when the State moves from Approved to Active
- Only allow users who belong to 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 is filled in when the State moves to Active
Rule definitions
To implement the above restrictions, the process administrator adds a custom Approved By identity field, an Authorized Approvers security group, and the following 11 rules.
Rule name
Condition
Actions
Proposed state
When A work item state moved 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 moved 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 moved from Design
Then Restrict the state transition to Proposed
And Restrict the state transition to Research
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 moved from Approved
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 In Review
And Restrict the state transition to Closed
Active state
When A work item state moved 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
In Review state
When A work item state moved 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 moved from Closed
Then Restrict the state transition to Proposed
And Restrict the state transition to Cut
Cut state
When A work item state moved 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
Once the rules are defined for the process and the project updated with the process, refresh your browser and check the operations through the work item form and from the browser.
For the rules defined in the previous table, you should see the following State drop-down menus. Open the board and check the ability to move from one State to another.
Proposed | Research | Design | Approved |
---|---|---|---|
![]() |
![]() |
![]() |
![]() |
Active | In Review | Closed | Cut |
![]() |
![]() |
![]() |
![]() |
Restrict state transition based on user or group membership
When specifying 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 condition. Also, if specifying the action Restrict the transition to state...
, you can only specify one action.
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 had a rule that reassigned the bug to its creator. We removed this rule from the default system process. You can reinstate the rule or add a similar rule to other work item types using the following condition and action:
When A work item state changes to
Resolved Then Copy the value from
Created By to Assigned To.
Related articles
Note
Review changes made to an inherited process through the audit log. For more information, see Access, export, and filter audit logs.