Apply rules to workflow states (Inheritance process)

Azure Boards | Azure DevOps Server 2020 | Azure DevOps Server 2019

After you add or modify your workflow states for a work item type, you may 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
  • 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
  • Automate state transitions of parent work items

Important

This article applies to Azure DevOps Services and Azure DevOps Server 2019 and later versions. To customize any project defined on a collection for TFS 2018 or earlier, see On-premises XML process model.

Important

You can only use the Inheritance process model for projects defined on a project collection configured to support the Inheritance process model. 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. To learn more, see Customize work tracking, Choose the process model for your project collection.

To customize any project defined on a collection for TFS 2018 or earlier, see On-premises XML process model.

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.


Condition

Supported Actions


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

Conditions, work item is created

Actions, work item is created


Restrict a transition based on State

Condition, work item is moved

Actions, restrict a transaction based on State.


Restrict a transition based on State and user or group membership

Condition, user group membership

Actions, restrict a transaction based on State and membership.


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

Conditions, work item is created

Actions, work item is created


Note

As you customize an inherited process, all projects that use that process are updated automatically to reflect the customizations. For this reason, we recommend that you create a test process and test project when you have a number of customizations to make in order to test the customizations prior to rolling them out to your organization. To learn more, 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 WITs you define.

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: Kanban 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

Prior to defining a rule based on workflow states, make sure you first define the following elements:

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 prior to 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

Agile Process, User Story, default workflow state

Rule requirements

To ensure approval prior to active work, the following rules must be defined:

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

Example of restricting state transitions and Approved state

In keeping with the terminology used by a business group, 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 additional States are defined: Investigate, Design, and Approved. These States should follow the sequence as shown in the following image.

User Story, workflow states

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 (Additional 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 eleven 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 Kanban browser.

For the rules defined in the previous table, you should see the following State drop-down menus. Open the Kanban board and check the ability to move from one State to another.

Proposed Research Design Approved
Proposed menu Research menu Design menu Approved menu
Active In Review Closed Cut
Active menu In Review menu Closed menu Cut menu

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.

Automate state transitions of parent work items

To automate State transitions of parent work items based on the State assignments made to their child work items, you can add a web hook and use the code and configuration provided in the Automate State Transitions GitHub project.

Note

The Automate State Transitions GitHub project is not a supported feature of Azure Boards and therefore not supported by the product team. For questions, suggestions, or issues you have when using these extensions, raise them in the GitHub project page.

Automate reassignment based on state change

The Agile process bug work item type previously had a rule which reassigned the bug to the person who created it. This rule has been removed 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.

Note

You can review changes made to an inherited process through the audit log. To learn more, see Access, export, and filter audit logs.