Rules and rule evaluation
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
Rules are used to set or restrict value assignments to a work item field. There are two main types of rules, auto-generated rules and custom rules defined for a process or project. Auto-generated rules minimize the need to add custom rules for areas that should work in a standard way.
You define custom rules in order to support your business use cases. Depending on a field's data type, you can set various restrictions on what data can be entered into that field. You can specify values for a pick list (drop-down menu), set default values, clear entries, or restrict changes. With conditional rules, you can apply rules to a field based on dependencies between different fields' values. You can also restrict who can modify a field or scope a rule to only apply to a group.
Read this article to understand the following:
- How the system applies auto-generated rules
- Restrictions placed on definition of custom rules on system fields
- The different types of custom rules you can apply
- How rules are evaluated
- Difference between rules defined for an Inheritance process versus an On-premises XML process
- Why you should minimize the number of custom rules you define
Prior to defining custom rules, read Configure and customize Azure Boards to gain a broad understanding of how to customize Azure Boards to meet your business needs.
Tip
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.
Auto-generated rules
Auto-generated rules minimize the need to add custom rules for areas that should work in a standard way.
State transition rules
Inherited processes generate the entire set of any-to-any state transition rules dynamically for each custom work item type and custom state added to a workflow. A transition from any state to any state is valid.
For On-premises XML processes, you must specify the valid transitions within the WORKFLOW section of the work item type definition.
State transitions and By/Date field rules
By/Date fields correspond to Created By/Date, Activated By/Date, Resolved By/Date, and Closed By/Date.
For inherited processes, these fields are automatically set or cleared when you transition a work item from one state to another. The Changed By/Date fields aren't included as they are updated with each work item save and are unrelated to state transitions.
Default rules and behaviors that govern these fields include:
- The Closed state is always contained in the Completed state category.
- The Completed state category is not configurable, and is associated with one and only one State.
- This Closed state is always Closed for Agile and CMMI processes, and always Done for Scrum and Basic processes.
- Auto-generation of these rules are affected by locale as the rule condition contains the State name, which is localized. The system generates different rules for different locales.
- Auto-generated rules for these fields are only specified for work item types that include these fields. It is possible for a work item type to not include one or more of these fields.
- These rules are needed when a work item type has custom states, or the work item type is a custom work item type.
- These rules only apply to inherited processes; they are never generated for the Hosted XML or On-premises XML processes.
Workflow states are associated with state categories to support the workflow on Kanban boards. To learn more, see How workflow states and state categories are used in Backlogs and Boards.
State Change Date field rules
These rules are technically a lot simpler than Closed By/Closed Date rules because they are not dependent on any particular state. For any work item type, the same rules will always work. They need to be auto-generated because some OOB work item types do not contain the State Change Date field, so when the user adds this field to a custom work item type, these rules need to be auto-generated as well. The same principles for Closed By/Closed Date rules apply here as well.
Custom rules
All custom rules are optional. For an inherited process, you specify a rule which consists of a condition plus action. For an On-premises XML process, you specify rules for a field or within the workflow.
There isn't a one-to-one mapping between the two processes. In some cases, the XML element rule is defined within the Edit field dialog for the inherited process and not as a rule. Other XML elements, such as FROZEN, MATCH, NOTSAMEAS, aren't supported in the inherited process.
Note the following:
- 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.
- Inherited process entries specify conditions and actions to make a complete rule. XML elements don't make those distinctions.
- Field rules don't support assigning values that are the sum of two other fields or performing other- mathematical calculations. 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.
- You may find additional solutions to applying custom rules to fields using a Marketplace extensions, such as the Work item form control library extension.
Rule composition
For an inherited process, 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. For most rules, 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.
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
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.
The following table summaries the Actions that are available with the selected Conditions.
Condition
Supported Actions
Set field value or make required or read-only
Restrict a transition based on State
Hide field or make field read-only or required based on State and user or group membership
Based on and user or group membership, set field attribute or restrict a State transition
What happens if too many rules are defined
A single SQL expression is defined per project to validate work items whenever they are created or updated. This expression grows with the number of rules you specify for all work item types defined for the project. Each behavioral qualifier specified for a field results in an increase in the number of sub-expressions. Nested rules, rules that apply only on a transition or conditioned on the value of some other field, cause more conditions to be added to an IF statement. Once the expression reaches a certain size or complexity, SQL can't evaluate it any more and generates an error. Removing some WITs or eliminating some rules, can resolve the error.
You can specify values for a pick list (drop-down menu), set default values, clear entries, or restrict changes. With conditional rules, you can apply rules to a field based on dependencies between different fields' values. You can also restrict who can modify a field or scope a rule to only apply to a group.
Work item rules do not exist as a single collection. The rules are actually dynamically generated and merged from different data sources. The merge logic is a simple one, consolidate identical rules, but don't trim conflicting rules.
Bypass rules
In general, all work items are validated by the rule engine when users modify the work item. However, to support certain scenarios, users assigned the Bypass rules on work item updates project-level permission can save work items without rules being evaluated.
Rules can be bypassed in one of two ways. The first is through the Work Items - update REST API and setting the bypassRules parameter to true. The second is through the client object model, by initializing in bypassrules mode (initialize WorkItemStore with WorkItemStoreFlags.BypassRules).
System fields and custom rules
System fields have System.Name reference names, for example System.Title and System.State.
The following system fields are required to have a value: Area ID, Changed Date, Created Date, Created By, State, and Reason.
The rule engine restricts setting conditions or actions to system fields except as follows:
- You can make State and Reason fields read-only.
- You can apply most rules to the Title, Assigned To, Description, and Changed By fields.
If you don't see a field listed in the drop-down menu of the rule user interface for the Inheritance process, this is why. For example, if you try to make Area Path (System.AreaPath) read-only based on a condition, the Area Path field isn't available for selection. Even if you're able to specify a system field, the rule engine may restrict you from saving the rule.
Default and copy rules
Default and copy rules modify the values of work item fields. They define run-time behavior and constraints, such as specifying default values, clearing fields, requiring fields to be defined, and more.
You can restrict application of these rules based on the current user's group membership as described in User or group membership rule restrictions.
Most of these rule actions can be applied with the selection of any condition.
Inherited process action
Description
Copy the value from...
Specifies another field that contains a value to be copied into the current field.
Clear the value of...
Clears the field of any value that it contains.
Use the current time to set the value of ...
Sets the time for a field based on the current user's time setting.
Constraint rules
Constraint rules restrict changing the value of a field. They define the valid states for a work item. Each constraint operates on a single field. Constraints are evaluated on the server on work item save, and if any constraint is violated the save operation is rejected.
You can restrict application of these rules based on the current user's group membership as described in User or group membership rule restrictions.
Most of these rule actions can be applied with the selection of any condition.
Inherited process action
Description
Hide the field...
Only available when a group membership condition is selected.
Specifies to not show the field on the work item form, essentially removing the ability for the current user to change the field's value.
Make read-only
Prevents a field from being modified at all. You might want to apply this rule under certain conditions. For example, after a work item is closed, you want to make a field read-only to preserve the data for reporting purposes.
To specify the field default is read-only, specify in Edit field dialog, Options tab.
Make required
Requires a user to specify a value for the field. Users cannot save a work item until they have assigned values to all required fields.
To specify the field default is required, specify in Edit field dialog, Options tab.
Pick lists
Pick lists define the values that a user can or can't choose for a String or Integer field. Values defined in a pick list appear on a work item form and the query editor.
For an Inherited process, pick lists are defined through the Edit field dialog.
Edit field dialog
Description
Definition tab for a picklist field
Defines a list of allowed values for the field. Allowed values are values that are available for selection in a field list on work item forms and in the query builder. You must select from one of these values.
Check the Allow users to enter their own values checkbox within the Options tab to allow users to specify their own entries
Defines a list of suggested values for the field. Suggested values are values that are available for selection in a field list on work item forms and in the query builder. You can enter other values additionally to the ones in the list.
Conditional field values or changes
Conditional rules specify an action based on the value of a field equaling or not equaling a specific value, or if a change was or wasn't made to the value of a specific field. In general, conditional rules are applied first over unconditional rules. When multiple conditional rules evaluate to true, the order of execution is: When, WhenNot, WhenChanged, WhenNotChanged.
You can specify multiple conditional rules per field. However, you can only specify a single driving field per conditional rule.
Inherited condition
Description
The value of ... (equals) [When]
Specifies one or more rules to apply to the current field when another field has a specific value.
A change was made to the value of ... [WhenChanged]
Applies one or more rules to the current field when a specific field's value is changed.
The value of ... (not equals) [WhenNot]
Applies one or more rules to the current field when another field does not have a specific value.
No change was made to the value of ... [WhenNotChanged]
Applies one or more rules to the current field when a specific field's value is not changed.
Inherited action
Description
Clear the value of ...
Copy the value from ...
Make read-only ...
Make required ...
Set the value of ...
Use the current time to set the value of ...
Use the current user to set the value of ...
Specifies the action to take on a specific field.
User or group membership rule restrictions
You can restrict application of a rule based on the current user's membership. We recommend you scope the rule to an Azure DevOps security group, and not a single user, although you can specify the latter. To have the rule scoped to multiple groups, you must create a parent Azure DevOps group that includes the set of groups that you want to use.
Process implementation
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.
As indicated in the following table, to restrict a rule based on the current user's membership, you specify one of two conditions for an Inherited process. These rules are active for Azure DevOps 2020 and later versions.
Applies to
Rule
Condition
Current user is a member of group ...
Current user is not member of group ...
Action
Hide the field ...
Make read-only ...
Make required ...
Restrict the transition to state ...
Use tokens to reference users or groups
Identity or people-picker fields can accept values that reference both users and groups. When you restrict a rule to a group, you indicate the domain or scope of the group. For some values, you can use tokens.
Examples of tokens include the following:
- [ProjectName], such as [Fabrikam], [FabrikamFiber], [MyProject]
- [OrganizationName], such as [fabrikam], [myorganization]
- [CollectionName], such as [fabrikam], [myorganization]
To learn about the scopes available for your project or organization, go to the Project Settings>Permissions>Groups or Organization Settings>Permissions>Groups page, you can filter the list as needed. For example, the following image shows the first four entries to a filtered list based on Azure DevOps. To learn more, see Change project-level permissions or Change project collection-level permissions.
To learn more about default security groups, see Permissions and groups
Rule evaluation
Rules that specify a condition based on the user or group membership of the user modifying a work item are evaluated in one of two ways. When the rule is evaluated, the application needs to determine whether the rule applies to the current user by checking if that user is or isn't a member of the specified group.
- When modifying the work item from the web portal, REST API, or azure boards command, a request to the Microsoft Entra ID or Active Directory is made. No problems occur for this operation.
- When modifying the work item from Visual Studio, Excel or other custom tool using the WIT Client Object Model, the request to evaluate membership is based on a client cache. The client cache is not aware of Active Directory groups.
Note
Visual Studio 2019 Team Explorer for projects using GIT has been re-written to use REST APIs.
To avoid problems with users updating work items from various clients, specify Azure DevOps security groups instead of Active Directory groups. You can easily create an Azure DevOps security group to correspond to an Active Directory group. To learn how, see Add or remove users or groups, manage security groups.
Note
The WIT Client OM is deprecated. As of January 1, 2020, it no longer is supported when working against Azure DevOps Services and Azure DevOps Server 2020.
Order in which rules are evaluated
Rules are typically processed in the sequence in which they are listed. However, the complete sequence for evaluation of all rules isn't fully deterministic.
This section describes the expected behavior and interactions when you apply conditional, copy, and default rules.
The following steps show, in the correct sequence, the interactions that Azure DevOps performs and by the user of a work-item form. Only steps 1, 8, and 13 are performed by the user.
From an Azure DevOps client--such as the web portal or Visual Studio Team Explorer--a user creates a new work item or edits an existing work item.
Fill in field defaults. For all fields, apply any defaults assigned to the field that aren't part of a conditional clause.
Copy or set field values. For all fields, apply any rules to copy a value or set the value of a field that aren't part of a conditional clause.
For all fields with a When conditional rule that matches, apply rules to set or copy a field value.
For all fields with a When Not conditional rule that matches, apply rules to set or copy a field value.
The system always processes When rules before When Not rules.
For all fields that have had their values changed since step 1 and that contain When Changed rules, apply rules to set or copy a field value.
Allow the user to start editing.
The user changes a field value and then moves focus from the field.
Process any When rules for that field that match the new value.
Process any When Not rules for that field that match the new value.
Process any When Changed rules for that field that match the new value.
Return editing ability to the user.
The user saves the changes to the data store.
For all fields, apply any
Use the current time to set the value of ...actions that are defined for the field either directly or indirectly under a conditional rule.
Related articles
- Sample rule scenarios
- Work item field index
- Work item fields and attributes
- Change project-level permissions
- Change project collection-level permissions
- Permissions and groups
- Inherited process
- On-premises XML process
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for