Sample custom rule scenarios

TFS 2018

This article provides examples of custom rule definitions. All custom rules are defined for a work item type. Examples are provided for both the Inherited and On-premises XML process models.

Prior to adding custom rules, read Rules and rule evaluation and Add a rule to a work item type (Inheritance process).

Define a dependent required field

You can specify that a field is required only when another field contains a specific value. In the following example, when a customer reports an issue, the custom Customer Reported field is set to True, and the Severity field becomes required. If the issue isn't reported by a customer, a value for the Severity field isn't required.

Screenshot of custom rule to make Severity required when Customer REported field=true.

Clear the value of a dependent field

The following example illustrates defining a custom rule to clear the value for Story Points when a change is made to the Start Date.

Screenshot of custom rule to clear the value of Story Points when Start Date changes.

Set a dependent field value

The following examples illustrate how to map the values of the Size field depending on the value selected for the custom field, Tee-Shirt Size field.

The Tee-Shirt Size pick-list consists of four values Small, Medium, Large, and X-Large. Four custom rules are defined to assign the Size field when the Tee-Shirt Size field is changed to a specific value. To simplify usage, the default value of the Tee-Shirt Size is Small.

Edit field dialog for Tee-Shirt Size field

Screenshot of Edit field dialog for Tee-Shirt Size field.

Custom rule

Screenshot of custom rule to set Size value when Tee-Shirt Size is set to Small.

Four custom rules

Screenshot of four custom rule to set Size value when Tee-Shirt Size is set.

Require a field value upon State changes

The following example shows how you can require specification of the Remaining Work field when the task workflow State changes to Active.

Screenshot of custom rule to make Remaining Work required when State is changed to Active.

Clear the value of a field upon close State

To automate clearing the Remaining Work field upon closing a task, define a custom rule as indicated.

Screenshot of custom rule to zero out Remaining Work required when State is changed to Closed.

Restrict creation of work items by a group

A custom rule that restricts the transition to the Proposed state category of a work item type effectively disallows creation of work items of that type. By applying the rule to a specific group, you effectively disallow that group from creating work items of that type.

The following custom rule restricts a project team from creating work items as the Proposed state category maps to the New workflow state.

Screenshot of custom rule to restrict creation of a work item by a group.

Restrict modification of work items by a group

For an Inheritance process, you can prevent users from modifying a work item by setting the deny permission for a group on an Area Path. For an On-premises XML process, you can place restrictions on each workflow state for a group that prevents them from saving the work item in any state.

It's not possible to define a custom rule that restricts modification of work items of a specific type. You can only specify restriction by state. If the user doesn't change the state, then they can modify other fields, unless all fields are made read-only for the group.

Instead, if you want to restrict a group of users from modifying select work items of any type, you can assign those work items to an Area Path. Define a security group, and then set restrictions for editing work items for that Area Path for that group as shown in the following image. To learn more, see Set permissions and access for work tracking, Create child nodes and modify work items under an area path

Screenshot of Permissions dialog for an Area Path to restrict modifications of work items.

Restrict state transitions

For inherited processes, any-to-any state transitions are automatically defined. This allows users to advanced the workflow state from new to completed, but also to move backwards in case that is needed. When defining custom rules to restrict a transition, keep in mind that if a user makes a mistake in updating the workflow, they may not be able to correct it. For example, they could update the status by moving a work item card to a later stage on the Kanban board, but not move it back.

Tip

Consider restricting a state transition for some but not all users. That way, if a user makes a mistake, they can ask another team member to reset the State value to bypass the restriction.

Before defining state transition rules, review Rules and rule evaluation, Auto-generated rules and How workflow states and state categories are used in Backlogs and Boards.

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.

Note

The A work item state moved from ... condition is available for Azure DevOps Server 2020 and later versions.

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

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.

Restrict modification of select fields based on a user or group

You can customize work item types to restrict who can modify a specific field for a 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...

Tip

To avoid rule evaluation issues that may arise, specify Azure DevOps security groups and not Microsoft Entra ID or Active Directory security groups. To learn more, see Default rules and the rule engine.

For example, you can make the Title or the State fields 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