title	titleSuffix	description	ms.technology	ms.prod	ms.assetid	ms.manager	ms.author	author	ms.topic	monikerRange	ms.date
Apply a field rule	VSTS & TFS	Overview of XML elements you can use to modify field settings, such as pick lists, default value, copy value, or conditional rules	devops-agile	devops	6dd08cfa-d039-4946-8528-b8c40d12c800	douge	kaelli	KathrynEE	reference	vsts \|\| >= tfs-2013	05/10/2017

Add a rule to a work item type

VSTS (Hosted XML) | TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013

Important

This topic applies to team project customization for Hosted XML and On-premises XML process models. For the Inheritance process model, see Add a rule to a work item type. For an overview of process models, see Customize your work tracking experience.

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.

All of these rule elements can be defined within the FIELD definition of a work item type (WIT) definition, subject to some restrictions for System fields. And, with the exception of HELPTEXT, you can specify these rules to take affect during a workflow transition or as child elements within a FIELD (Global workflow) element.

You can define any combination of rules to a field, subject to the constraints as described in this topic.

Help text: Use to specify tool-tip text to appear in a work item form for a field
Pick list: Use to specify a drop-down menu or pick list of allowed, suggested, or prohibited values
Assign value: Use to define run-time behaviors and constraints that clear field values, copy values, match a pattern, make a field read-only and more
Conditional: Use to specify when a set of rules will be applied to a parent field.

Field rules are one component you have to customize work item tracking. To learn more, see Customize work tracking objects to support your team's processes.

For information on modifying fields or adding field rules to a WIT definition file, see Add or modify a field.

[!INCLUDE temp]

## Help text

You can customize the help text or tooltip text that appears when a user points to a field that appears on a work item form. You can customize and localize the Help text for the same field that appears in different WITs and different team projects. Help text is restricted to 255 Unicode characters.

The following example shows the assignment of Help text to a custom Business Justification field:

[!div class="tabbedCodeSnippets"]

<FIELD name="Business Justification" refname="Fabrikam.BusinessJustification" type="String">
   <HELPTEXT>Only required when you set the Urgencyfield to Need Immediately. </HELPTEXT>
</FIELD>

To provide users guidance that exceeds the 255 characters limit, see Provide help text, hyperlinks, or web content on a work item form.

Note

The presence of HELPTEXT adds to the size of your data store and can impact scalability. If you support several hundreds of team projects within a single TFS collection or instance, be conservative in your use of HELPTEXT rules.

## Pick list rules

Pick list rules define the values that a user can or can't choose for a String field. Values defined in a pick list appear on a work item form and the query editor. You can combine lists, and expand or contract lists. You can also use the for and not attributes to apply or ignore these rules, based on who is modifying the work item.

Rule	Usage
ALLOWEDVALUES	Limits the values a user can choose based on the specified values.
ALLOWEXISTINGVALUE	Allows a field to retain an existing value, even if it is no longer in a pick list. Including this rule is recommended when you change the field values in a pick list or for pick lists that contain person names.
GLOBALLIST	Specifies the name of a global list that contains values maintained for a team project or project collection.
PROHIBITEDVALUES	Prevents specified values from being assigned. The work item can't be saved if the field contains a prohibited value.
SUGGESTEDVALUES	Defines a list of values that users can choose from, but are not restricted to selecting. Users can specify values other than those in this list.

For examples of using pick lists, see Define pick lists.

## Assign value rules

Assign value rules define runtime behavior and constraints, such as specifying default values, clearing fields, requiring fields to be defined, and more. You can apply or ignore these rules based on who is modifying the work item using the for and not attributes.

### Clear, set defaults, copy, or match a pattern

These rules support setting defaults, copying values from one field to another, or enforcing a field value to match a prescribed pattern.

Rule	Usage
COPY	Copies a specified value to a field when a user creates or modifies a work item.
DEFAULT	Specifies a value for a field that is empty when a user creates or modifies a work item. If a field already has a value, the DEFAULT rule is ignored.
EMPTY	Clears the field of any value that it contains and then makes the field read-only when a user saves the work item. You shouldn't use EMPTY with READONLY. EMPTY is primarily used [during state transition](transition-xml-element.md) to clear fields that apply to the state to which the item is transitioning.
MATCH	Forces entries made to a String field to conform to a [specified pattern of characters or numbers](apply-pattern-matching-to-string-field.md).
SERVERDEFAULT	Copies either the current user name or the server clock value to a field when a user saves a work item. These fields usually appear as read-only on the form.

For the syntax structure and examples, see Define a default value or copy a value to a field.

Note

Field rules don't support assigning values that are the sum of two other fields or performing other mathematical calculations.

### Require, read-only, and restrict values

These rules specify restrictions on specifying or changing the value of a field.

Rule	Usage
CANNOTLOSEVALUE	Prevents users from clearing a field of a value once a value has been specified.
FROZEN	Prevents users from changing the value of a field once it contains a value. As soon as a user saves the work item with a value in that field, the value can no longer be modified.
NOTSAMEAS	Prevents a field from being assigned the same value as that which was assigned to another field.
READONLY	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. Do not use READONLY with the EMPTY element because EMPTY also makes a field read-only. If you combine these elements, results will be inconsistent. In addition, you can make a field appear as read-only from the work item form using the `Control` element `ReadOnly` attribute. The field can be written to by other clients, but not through the work item form.
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.

For the syntax structure, see All FIELD XML elements reference.

## Conditional rules

Conditional rules let you specify when a set of rules will be applied to a parent field. You can set conditions based on whether another field is assigned (or not assigned) a specified value or when another field changes (or doesn't change). You can include pick list and assign value rules within a conditional rule element.

Rule	Usage
WHEN	Specifies the rules to apply to the parent field when another field is assigned a specified value.
WHENNOT	Specifies the rules to apply to the parent field when another field isn't assigned a specified value.
WHENCHANGED	Specifies the rules to apply to the parent field when a specified field's value changes.
WHENNOTCHANGED	Specifies the rules to apply to the parent field when a specified field's value doesn't change.

You can specify multiple conditional rules per field. However, you can only specify a single driving field per conditional rule. You can't nest conditional rules. For the syntax structure and examples, see Assign conditional-based values and rules.

## Apply or ignore rules based on user or group You can make a pick list or assign value rule to apply or not apply to a group of users by using the **for** or **not** attributes. Scope the rule to a group. To have the rule scoped to multiple groups, you must create a parent TFS group that includes the set of groups that you want to use.

Make a field required only for a specified group:

Use for to apply a rule to a group. This example requires any user in the Junior Analysts group to complete the Second Approver field.
```
<FIELD name="Second Approver">
<REQUIRED for="Example1\Junior Analysts"/>
</FIELD>
```
Restrict modification of a field to a group of users:

Use not to exclude a group from a rule. This example defines the Triage Description field as read-only for everyone except those users in the Triage Committee group.
```
<FIELD name="Triage Description">
<READONLY not="[Project]\Triage Committee" />
</FIELD>
```
Make a field required for some users and not for others:

Use a combination of for and not to simultaneously apply a rule to some and not for others. This example defines Severity as a required field for users in the Project Members group, but not for those in the Project Admins group.
```
<FIELD name="Severity">
<REQUIRED for="[Project]\Project Members" not="[Global]\Project Admins"/>
</FIELD>
```
If a user is in both groups, the "for" statement would be enforced, and the field would be required.

### Use tokens to reference groups

When you restrict a rule to a group, you must indicate the domain or scope of the group. For some values, you can use tokens.

Person-name fields can accept values that reference both users and groups. Field attributes, for and not, apply to groups. You can use the following tokens when specifying values for these items.

Scope to a group within a team project —[Project]:

The [Project] token is used to specify a group that is defined for a team project. This could correspond to a team, built-in TFS group, such as the [Project]\Contributors group, a custom TFS group you create at the project level, or a Windows group that you added to a TFS group.

[!NOTE]
[Project] is used as is. You don't replace it with the name of your team project.

Some examples:
- Team: [Project]\Fabrikam Team
  
  When you create a team, a TFS group is created that contains the members assigned to the team.
- Team project group: [Project]\Contributors
- Windows group added to a team project: [Project]\Triage Committee
[!TIP]
You can view a list of valid groups by opening the Security page in the web portal administration context.
Scope to a project collection —[GLOBAL]:

Use [GLOBAL] to reference a collection-scoped TFS group, such as the Project Collection Administrators group or a Windows group you add to a collection. For example:
```
<FIELD name="Title">
<READONLY for="[GLOBAL]\Project Collection Valid Users"/>
</FIELD>
```
Scope to a server instance —[Team Foundation]:

Use the [Team Foundation] token to reference a server-scoped TFS group, such as a built-in group or a Windows group you add to a server-level group. For example:
```
<FIELD name="Title">
<READONLY for="[Team Foundation]\Team Foundation Valid Users"/>
</FIELD>
```
Specify a domain qualified account or group:

Domain-qualified account name, such as the one shown in the following example, can be used to reference a domain user or group. Note that some rules only support groups and do not support referencing domain users.
```
<LISTITEM value="FABRIKAM\Christie Church's Direct Reports"/>
```

All users and groups must be qualified by one of these tokens. For example, the following XML isn't valid because it doesn't qualify the specified group with a valid token.

<FIELD name="Title">
<READONLY for="Dev Team"/>
</FIELD>

To learn more about built-in groups, see Permissions and groups

##System field rules

System fields have System.Name reference names, for example System.Title and System.State. TFS restricts customization of these fields, except for these instances:

HELPTEXT rule can be assigned to all fields.
READONLY rule can be assigned to the State and Reason fields.
Most rules can be assigned to the Title, Assigned To, Description or Changed By System fields.

<FIELD name="Assigned To" refname="System.AssignedTo" type="String" syncnamechanges="true" reportable="dimension">
      <HELPTEXT>The user who is working on this work item</HELPTEXT>
      <ALLOWEXISTINGVALUE />
      <VALIDUSER />
      <ALLOWEDVALUES expanditems="true" filteritems="excludegroups">
      <LISTITEM value="Active" />
      <LISTITEM value="[project]\Contributors" />
      </ALLOWEDVALUES>
      <DEFAULT from="field" field="System.CreatedBy" />
</FIELD>

Apply rules to State and Reason fields

The State and Reason fields are defined within the WORKFLOW section of the WIT definition. You can specify most field rules to apply to a field during a change of state, selection of a reason, or for a specific transition. To learn more, see Change the workflow for a work item type.

Where to apply a field rule

When you want a rule to apply to a field throughout the life of the work item, specify it within the FIELD definition. For example, a field that is required for a bug that is new and active remains required until the bug is closed.

Otherwise, specify a rule to be evaluated only during a change in state. These rules are defined within the WORKFLOW section under the STATE, REASON, or TRANSITION elements. All rules, except for HELPTEXT, can be applied within a FIELD (Workflow) element.

Field rules are additive. That is, you can specify four sets of rules for the same field which will all be evaluated by the rule-engine.

Work item type-specific rules apply regardless of the location of a work item in its state model. For example, a <REQUIRED \> rule performs the following check:

"MyField Value" != NULL
State-specific rules are scoped to a work item instance when it is in a certain state. A state-specific rule is enforced when the following condition is true:

State field value == "MyState" && "MyField Value" != NULL
Transition-specific rules that you specify for a specific transition are scoped to a work item that is undergoing a certain transition. These rules are enforced when the following conditions are true:

State field value == "ToState" &&

"Previous State Before Edit/New" == "FromState"

&& "MyField Value" != NULL
Reason-specific rules that you specify for a specific reason are scoped to a particular reason for a particular transition. They are processed when the following conditions are true:

Reason field == "MyReason" &&

State field value == "ToState" &&

"Previous State Before Edit/New" == "FromState" && "MyField Value" != NULL

The following example restricts modification of the customer severity field when the work item is in the Active state.

[!div class="tabbedCodeSnippets"]

<STATE name="Active">
      <FIELDS>
      <FIELD refname="MyCorp.Severity" >
         <READONLY />
      </FIELD>
      </FIELDS>
</STATE>

Order in which rules are evaluated

Rules are typically processed in the sequence in which they are listed. However, when you use the WHEN, DEFAULT, and COPY elements, additional behaviors may apply.

You can gain some idea of how rules are evaluated when you apply multiple rules to a field. How rules are evaluated is not completely deterministic. This section describes the expected behavior and interactions when you are using the WHEN, DEFAULT, and COPY rules.

The following steps show, in the correct sequence, the interactions that TFS performs and by the user of a work-item form. Only steps 1, 8, and 13 are performed by the user.

From a Team Foundation client—such as the web portal, Visual Studio, Team Explorer, or Team Explorer Everywhere—a user creates a new work item or edits an existing work item.
Fill in field defaults. For all fields, use any DEFAULT rules that are outside WHEN rules.
Copy field values. For all fields, use any COPY rules that are outside WHEN clauses.
For all fields with a WHEN rule that matches, first do DEFAULT and then COPY rules inside.
For all fields with a WHENNOT rule that matches, first do DEFAULT and then COPY rules inside.

The system always processes WHEN rules before WHENNOT rules.
For all fields that have had their values changed since step 1 and that contain WHENCHANGED rules, first do DEFAULT and then COPY rules inside.
Allow the user to start editing.
The user changes a field value and then moves focus from the field.
Raise any WHEN rules for that field that match the new value.
Raise any WHENNOT rules for that field that match the new value.
Raise any WHENCHANGED rules for that field that match the new value.
Return editing ability to the user.
The user saves the changes to the database.
For all fields, perform SERVERDEFAULT operations that are defined for the field either directly or indirectly under a WHEN or a WHENNOT rule.

Keystroke entries and rule evaluation

The system sets a new value for a field every time a user enters a keystroke within a field through the UI work item form. This means that a conditional rule can occur unexpectedly whenever the rule's prerequisite conditions are met.

In the following XML example, SubStatus will be emptied as you type "Approved Again" into the Status field because the WHEN rule occurs as soon as the user types the letter "e" in Approved, even if the intended final value is not "Approve". For this reason, think carefully when you are using conditional rules.

[!div class="tabbedCodeSnippets"]

<FIELD refname="MyCorp.SubStatus" />
   <WHEN field="MyCorp.Status" value="Approve" >
      <EMPTY />
   </WHEN>
</FIELD>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

apply-rule-work-item-field.md

apply-rule-work-item-field.md

Add a rule to a work item type

Related articles

Person-named fields and validation errors

Apply rules to State and Reason fields

Where to apply a field rule

Order in which rules are evaluated

Keystroke entries and rule evaluation

Files

apply-rule-work-item-field.md

Latest commit

History

apply-rule-work-item-field.md

File metadata and controls

Add a rule to a work item type

Related articles

Person-named fields and validation errors

Apply rules to State and Reason fields

Where to apply a field rule

Order in which rules are evaluated

Keystroke entries and rule evaluation