Available Field Rules
Field rules define the behavior and constraints on fields. Field rules are additional elements that are listed inside <FIELD></FIELD> blocks. For example, if a field is required, the XML that defines the field might look as follows:
<FIELD refname="System.Priority" name="Priority" type="String">
<HELPTEXT>Enter the business priority of the bug</HELPTEXT>
<REQUIRED />
</FIELD>
Available Field Rules
You can use the following field rules to change the behavior of a field:
<REQUIRED />
This field cannot be empty. You can mark any field type as required. This element accepts for and not attributes. For more information, see REQUIRED Element (Work Item Type Definition Schema).
<READONLY />
The field cannot be modified. This element accepts for and not attributes. For more information, see READONLY Element (Work Item Type Definition Schema).
<EMPTY />
The field value is cleared on commit and the user cannot enter any value. This rule is primarily used during state transition to clear fields that apply to the transitioned-to state. This element accepts for and not attributes. For more information, see EMPTY Element (Work Item Type Definition Schema).
<FROZEN/>
As soon as a field has a value after a commit the value can no longer be modified. However, the field can be cleared by using an <EMPTY/> constraint. The user can manually clear the field, save the work item, and then specify a different value upon reload. This element accepts for and not attributes. For more information, see FROZEN Element (Work Item Type Definition Schema).
<CANNOTLOSEVALUE/>
After a field has acquired a value, it cannot be cleared or made empty. This element accepts for and not attributes. For more information, see CANNOTLOSEVALUE Element (Work Item Type Definition Schema).
<NOTSAMEAS field="MyCorp.Reviewer" />
The field value cannot have the same value as the value in another field; in this case, the "MyCorp.Reviewer" field. The field value must be a valid field reference name. For more information, see Field Reference Names.
Examples of using the NOTSAMEAS field rule:
Two fields cannot be empty at the same time.
The "code reviewer" field value cannot exactly match the "assigned to" field value.
Use this rule for fields of like type. You cannot use it for PlainText or HTML fields. This element accepts for and not attributes. For more information, see NOTSAMEAS Element (Work Item Type Definition Schema).
<VALIDUSER group="group" />
The field value must be a valid user who is a member of the Team Foundation Valid Users group.
This rule supports the optional group attribute for specifying that the user must be a direct or indirect member of the specified group. By default, the rule enables all users who are members of the Team Foundation Valid Users group. For more information, see Using Tokens to Reference Users and Groups. This element accepts for and not attributes. For more information, see VALIDUSER Element (Work Item Type Definition Schema).
Note
If the <REQUIRED/> rule is not specified, this field will accept an empty value. Used for String field types.
Note
Work item fields do not distinguish between user identities in different domains. Therefore, "Example1\jaepak" and "Example2\jaepak" are treated as the same user when entered into a field that uses the <VALIDUSER /> rule. However, user identities are distinguished by domain elsewhere in Team Foundation Server.
<ALLOWEXISTINGVALUE/>
Allows for a field to retain an existing value, even if that value is no longer enabled. The alternative and default behavior is to force the user at edit time to match the latest enabled values for that field. This element has a modifying effect only on the elements in the same block. This element cannot accept for or not attributes. For more information, see ALLOWEXISTINGVALUE Element (Work Item Type Definition Schema).
<ALLOWEDVALUES/>
An enumerated list of values that is presented to the user as a list. Users must select one of the values on this list. This element accepts for and not attributes. For more information, see ALLOWEDVALUES Element (Work Item Type Definition Schema).
<SUGGESTEDVALUES/>
An enumerated list of values that is presented to the user as a list. Users can select any one of the values. Users can also enter their own value which is not one of the suggestions. This element accepts for and not attributes. For more information, see SUGGESTEDVALUES Element (Work Item Type Definition Schema).
<PROHIBITEDVALUES/>
Users cannot save a work item if the field contains any prohibited values. Prohibited values are typically used when a value was previously allowed but is no longer valid. This element accepts for and not attributes. For more information, see PROHIBITEDVALUES Element (Work Item Type Definition Schema).
<DEFAULT>
When a user creates a new work item or edits a work item, the <DEFAULT> element fills in a field value if that field is empty. If a field already has a value, the default rule is ignored. This element accepts for and not attributes. For more information, see DEFAULT Element (Work Item Type Definition Schema).
Note
When changing a work item, this element rule is nondeterministic with regards to selecting the current or previous value from another field.
<COPY>
When a user creates a new work item or changes a work item, the <COPY> element fills in a field value regardless of any exiting value already in the field. This element accepts for and not attributes. For more information, see COPY Element (Work Item Type Definition Schema).
Note
When changing a work item, this element rule is nondeterministic with regards to selecting the current or previous value from another field.
<SERVERDEFAULT>
Unlike <DEFAULT> and <COPY> that fill in values at the start of editing, the <SERVERDEFAULT> rule fills in a value when the work item is committed to the database. This occurs at save time, and the user cannot override the value. Such fields appear read-only on the form. This rule is used for fields such as "Last Changed By" and "Last Changed On" to support secure audit trails. This element accepts for and not attributes. For more information, see SERVERDEFAULT Element (Work Item Type Definition Schema).
<MATCH pattern="<pattern>"/>
Enforces basic pattern matching for strings only. <pattern> should be replaced with the match pattern. Valid values are "A," "N," "X." All other values are taken as literals. "A" represents an alphabetical character. "N" represents a numeric character. "X" represents any alphanumeric character. This pattern is only supported for String type fields. This element accepts for and not attributes. For more information, see MATCH Element (Work Item Type Definition Schema).
Pattern Matching Examples
The following examples illustrate successful and unsuccessful pattern matches for a variety of field uses:
Release number
Pattern: ANN.NN.NN
Validates |
R01.03.04 or V05.08.99 |
Fails validation |
1.3.4 or V5.8.99 or v1.3 |
A flexible identifier
Pattern: XXX-XXX
Validates |
001-abc or a00-b02 |
Fails validation |
1-abc or 001.abc |
Priority
Pattern: PN
Validates |
P1 or P5 or P9 |
Fails validation |
1 or P10 |
Match tags are case insensitive, so that "PN" matches both P1 and p1.
Note
You can specify multiple <MATCH> elements. If at least one element succeeds, the field has a valid value.