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

Azure Boards | 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

To customize a project collection that uses the On-premises XML process model, available only for on-premises deployments, see On-premises XML process model. This article applies to Azure DevOps Services and Azure DevOps Server only.

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 has been 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.

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 based Add-in.

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

Note

"When current user is member of group..." and "When current user is not member of group ..." rules are currently only available in the Azure DevOps Service.

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

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 Organization settings

  2. Then, choose Process.

    Organization Settings, Process page

    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 Admin settings>Process.

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

    Open Organization settings

  2. Then, choose Process.

    Organization Settings, Process page

    Important

    If you don't see Process, then the collection you've created is set to work with the On-premises XML process model. You must use the features supported for the On-premises XML process model.

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

    Tip

    You can specify the State field by entering System.State. While you'll see a message that indicates it isn't a valid field, if the Save button is active, then you can save the rule.

    	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

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.

To learn how, see this blog post, Prevent reopening work item once closed.

Note

The blog post addresses how to add a custom rule to an Inherited process, however, the idea can be equally applied by adding one or more custom rules to an Online XML process and work item type definitions. To learn more, see Apply a field rule.

Restrict modification of work items based on a user or group

You can customize work item types to support these restriction requests:

  • Restrict who can create or modify a work item
  • Restrict who can create specific work item types, such as Epics or Features
  • Restrict who can modify a specific field for a work item type
  • Hide field from the form

For example, the following condition indicates that the State field, for the Initiative custom work item type, becomes read-only for members of the Fabrikam Fiber\Voice group. When a user of this group opens a new Initiative, they are unable to save it as the State field can't automatically be set to New.

Custom rule