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, define rules that apply based 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 another 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, supporting auditing requirements
• Automate closure of parent work items

Prerequisites

To apply rules to workflow states in Azure DevOps, you need specific permissions and access levels:

• Permissions:

  • Be a Project Administrator to manage security groups and permissions at the project level, which includes setting rules for workflow states.
  • Have Work Item Tracking permission, which allows you to manage the work tracking area, which can be granted to members of the Project Administrators group or through specific permissions.

• Access levels:

  • Have 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 table outlines the three groups of workflow rules you can define:

1. 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.

2. Restricting state transitions (group 1):

   • Specify one condition indicating the state a work item moved from.
   • Define actions to restrict transitions from that state to other states.

3. Restricting state transitions (group 2):

   • Similar to the first group, specify one condition indicating the state a work item moved from.
   • Define actions to restrict transitions from that state to other states.

---

Condition

Supported Actions

---

Set field value or make read-only/required based on State

---

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.

Understand workflow state and rule limits

Workflow rules get applied 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 can help 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 that are 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

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 gets worked on until approved by a team lead. The default workflow states are used, 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: 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 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 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 you define the rules for the process and update the project, refresh your browser. Verify the operations through the work item form and the browser.

For the rules defined in the previous table, check the State drop-down 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

When you specify 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 only specify one condition. Additionally, if you specify 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 that are 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

• Add a custom rule
• Work item form caching
• Access, export, and filter audit logs
• Customize a workflow