Add a rule to a work item type (Inheritance process)

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

Custom rules provide support for a number of business use cases, allowing you to go beyond setting a default value for a field or make it required. Rules allow you to clear the value of a field, copy a value into a field, and apply values based on dependencies between different fields' values.

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.

With a custom rule, you can define a number of actions based on specific conditions. For example, you can apply a rule to support these types of scenarios:

  • When a value is defined for Priority, then make Risk a required field
  • When a change is made to the value of Release, then clear the value of "Milestone"
  • When a change was made to the value of Remaining Work, then make Completed Work a required field
  • When the value of Approved is True, then make Approved By a required field
  • When a user story is created, make the following fields required: Priority, Risk, and Effort
  • When current user is a member of "Project Administrators", then make Priority required
  • When current user is not a member of "Project Administrators", then hide the Priority field

Note

You make a field required and specify a field default through the Options tab for the field.

Rule composition

Each rule consists of two parts: Conditions and Actions. Conditions define the circumstances which must be met in order for the rule to be applied. Actions define the operations to perform. You can specify a maximum of two conditions and 10 actions per rule. All custom rules require all conditions to be met in order to be run.

Note

Currently, only one condition is supported for state-transition rules. If you're applying rules based on State, see Apply rules to workflow states.

As an example, you can make a field required based on the value assigned to the state and another field. For example:    (Condition) When a work item State is *Active*    (Condition) And when the value of *Value Area* = *Business*
   (Action) Then make required *Story Points*

Supported conditions Supported actions
list of conditions list of actions
Supported conditions Supported actions
list of conditions list of actions
Supported conditions Supported actions
list of conditions list of actions

Rules are always enforced, not only when you are interacting with the form but also when interfacing through other tools. For example, setting a field as read-only not only applies the rule on the work item form, but also through the API and Excel Azure DevOps Server Add-in.

Tip

You can't define a formula using a rule. However, you may find a solution that fits your needs via the TFS Aggregator (Web Service) Marketplace extension. See also Rollup of work and other fields.

Prerequisites

Prior to customizing a process, we recommend that you review Configure and customize Azure Boards, which provides guidance on how to customize Azure Boards to meet your business needs. For a description of the different backlogs and boards, see Tasks supported by Backlogs, Boards, Taskboards, and Plans.

Open Settings>Process

You create, manage, and make customizations to processes from Organization settings>Process.

  1. Choose the Azure DevOps logo to open Projects. Then choose Organization settings.

    Open Projects>Organization settings.

  2. Then, choose Process.

    Then, choose Process.

    Important

    If you don't see Process, then you're working from TFS-2018 or earlier version. The Process page isn't supported. You must use the features supported for the On-premises XML process model.

You create, manage, and make customizations to processes from Collection Settings>Process.

  1. Choose the Azure DevOps logo to open Projects. Choose the project collection whose processes you want to customize, and then choose Collection Settings.

    Open Projects>Organization settings

  2. Then, choose Process.

    Then, choose Process.

You create, manage, and make customizations to processes from Admin settings>Process.

  1. Choose the Azure DevOps logo to open Projects. Then choose Admin settings.

    Open Project>Organization settings.

  2. Then, choose Process.

    Then, choose Process.

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.

Add a custom rule

You add fields to a selected work item type.

  1. Select the WIT to which you want to add a rule, choose Rules, and then choose New rule.

    Process, WIT, Bug, Layout, New rule

    If you can't fill out the New work item rule dialog, you don't have the necessary permissions to edit the process. See Set permissions and access for work tracking, Customize an inherited process.

  2. Name the rule and select the condition(s) and action(s) from the dropdown menus.

    Tip

    Specify a name that builds off the field(s) you're acting on, or the conditions you're setting.

    Here we define that the Acceptance Criteria field is required when the State changes to Active and it is currently empty.

    New rule form

    The sequence of actions you specify doesn't impact the behavior of the rule itself or its behavior with respect to other rules defined for the same WIT.

  3. Once you've added a custom rule, open a work item and verify that the rule works as you intended.

Delete or disable a rule

You can temporarily disable a rule or delete it altogether.

You delete or disable the rule from the actions menu of the rule.

Delete or disable a rule

Hide or restrict modification of a field based on a user or group

When you select the Current user is a member of group... or Current user is not a member of group..., you can hide a field, make a field read-only, or make a field required.

For example, the following condition indicates that the Justification field is hidden for members who don't belong to the Fabrikam Fiber\Voice group.

Custom rule, Current user is not a member of a group, Hide Justification field

Restrict modification of select fields based on a user or group

For the Inheritance process model, you can customize work item types to restrict who can modify a specific field for a work item type. You restrict modification by adding a custom rule to the work item type.

Using one of the following two conditions, you can make select fields required for a user of a security group or who are not a member of a security group.

  • current user is a member of a group...
  • current user is not a member of a group...

For example, you can make the Title or the State field Read-only for select users or groups.

For example, the Priority field, for the User Story work item type, becomes read-only for members of the Fabrikam Fiber\Voice group. When a user of this group opens a User Story, they are unable to change the value on the Priority field.

Custom rule, Current user is not a member of a group, make Priority field read-only

To learn more, see Add a rule to a work item type (Inheritance process).

Restrict modification of closed work items

Depending on your business processes, you may want to prevent users from continuing to modify or update work items that have been closed or completed. You can add rules to work item types to prevent users from re-opening closed work items.

For the Inherited process, you can add a rule that restricts state transition. For example, the following rule restricts transitioning from closed to the other two States, New and Active.

Custom rule, Current user is not a member of a group, disallow transitions to New or Active state from Closed

Note

The A work item state moved from ... condition is only available for Azure DevOps Services and only to those participating in the Private Preview. For details, see State transition restriction rules (private preview).

For more information on applying rules to a workflow, see Apply rules to workflow states (Inheritance process).

Note

Depending on the rule action you specify, either the Save button on the work item form may be disabled, or an error message displays when a restricted user attempts to modify the work item.

Note

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