All FIELD XML elements reference
Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018 - TFS 2013
Use this topic to look up the syntax of the FIELD element or one of its child elements.
You specify these elements in the FIELD (Definition) element container. You add a field for a work item type (WIT) by specifying a FIELD (Definition) element within the FIELDS (Definition) element. You can specify these elements within the definition of a WIT or as part of a global workflow.
You can add child elements to specify the behavior of a field, define default values, or define a pick list of values. You can use field rule elements in combination with each other. You can scope most rules to apply to one or more users or groups or to be ignored for one or more users or groups.
FIELD (Definition) container element
You use the following syntax to define the data fields for a type of work item. This example shows the format of the FIELD (Definition) element and all optional child elements. For more information, see FIELD (Definition) element reference.
Note
The Boolean data type is supported for Azure DevOps Services (Hosted XML) and for TFS 2017.2 and later versions (On-Premises XML).
<FIELD name="fieldDisplayName" refname="fieldReferenceName" type="String | Integer | Double | DateTime | PlainText | HTML | History | TreePath | GUID | Boolean"
syncnamechanges="true | false" reportingname="reportingDisplayName" reportingrefname="reportingReferenceName"
reportable="Dimension | Detail | Measure" formula="avg" >
<ALLOWEDVALUES> . . . </ALLOWEDVALUES>
<ALLOWEXISTINGVALUE />
<CANNOTLOSEVALUE />
<COPY />
<DEFAULT />
<EMPTY />
<FROZEN />
<HELPTEXT> . . . </HELPTEXT>
<MATCH />
<NOTSAMEAS />
<PROHIBITEDVALUES /> . . . </PROHIBITEDVALUES>
<READONLY />
<REQUIRED />
<SERVERDEFAULT />
<SUGGESTEDVALUES /> . . . </SUGGESTEDVALUES>
<VALIDUSER />
<WHEN>> . . . </WHEN>
<WHENNOT> . . . </WHENNOT>
<WHENCHANGED> . . . </WHENCHANGED>
<WHENNOTCHANGED> . . . </WHENNOTCHANGED>
</FIELD>
FIELD child elements
Use child elements to set various restrictions on what data can be entered into a field. You can specify values for a pick list (drop-down menu), set default values, clear entries, or restrict changes. The following table provides the syntax structure for each child element.
To learn how to use these elements, see Rules and rule evaluation. Restrictions exist on applying most rules to system fields. All child elements are optional.
Element
Description and syntax
ALLOWEDVALUES
Defines a list of values that users can specify in a field list on work item forms and in the query editor. Users must specify one of the values that you list.
<ALLOWEDVALUES for="userGroupName" not="userGroupName"
expanditems="true | false" filteritems="excludegroups">
<GLOBALLIST name="globalListName">
<LISTITEM value="Name" />
. . .
</GLOBALLIST>
</ALLOWEDVALUES>
For more information, see Define pick lists .
ALLOWEXISTINGVALUE
Specifies that a field can retain an existing value, even if it is no longer in a pick list. All new field values must be in the list.
<ALLOWEXISTINGVALUE />
For more information, see Define pick lists .
CANNOTLOSEVALUE
Specifies that users cannot clear a field of all values after a value has been specified. After the field contains a value, that field must always contain a non-NULL value.
<CANNOTLOSEVALUE for="userGroupName" not="userGroupName" />
For more information, see Apply a field rule.
COPY
Copies a specified value to a field when a user creates or modifies a work item.
<COPY for="userGroupName" not="userGroupName"
from="value | field | clock | currentuser"
value="valueToCopy" field="fieldReferenceName" />
For more information, see Define a default value or copy a value to a field.
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.
<DEFAULT for="userGroupName" not="userGroupName"
from="value | field | clock | currentuser"
value="value to copy" field="field reference name" />
For more information, see Define a default value or copy a value to a field.
EMPTY
Clears the field of any value that it contains. The EMPTY rule also makes a field read-only, and you should not be use it with the READONLY rule.
The field value is cleared when a user saves the work item, and you cannot specify any value. This rule is primarily used during state transition to clear fields that apply to the state to which the item is transitioning.
<EMPTY for="userGroupName" not=" userGroupName" />
For more information, see Apply a field rule.
FROZEN
Specifies that you cannot change the field to a non-empty value after changes are committed. As soon as a user saves the work item with a value in that field, the value can no longer be modified.
<FROZEN for="userGroupName" not="userGroupName" />
For more information, see Apply a field rule.
HELPTEXT
Defines the text to appear when a user points to the field in the work item form.
tooltipText: A string of text that contains between 1 and 255 characters.
<HELPTEXT>tooltipText </HELPTEXT>
For more information, see Apply a field rule.
MATCH
Defines a pattern that values of String type fields must match.
<MATCH pattern="patternValue" for="userGroupName" not="userGroupName" />
For more information, see Apply pattern matching to a string field.
NOTSAMEAS
Specifies that a field is not assigned the same value as that to which another specified field is assigned. The value of the field attribute must be a valid reference name of a field.
<NOTSAMEAS field="fieldReferenceName" for="userGroupName" not="userGroupName" />
For more information, see Apply a field rule.
PROHIBITEDVALUES
Defines a list of values that a field cannot contain. Users cannot save a work item if the field contains a prohibited value.
<PROHIBITEDVALUES for="userGroupName" not="userGroupName"
expanditems="true | false" filteritems="excludegroups">
<GLOBALLIST name="globalListName">
<LISTITEM value="Name" />
. . .
</GLOBALLIST>
</PROHIBITEDVALUES>
For more information, see Define pick lists.
READONLY
Specifies that you cannot modify the value to which the field is assigned.
<READONLY for="userGroupName" not="userGroupName" />
Note: Do not use this element together with the EMPTY element because EMPTY also makes a field read-only. If you combine these elements, results will be inconsistent.
For more information, see Apply a field rule.
REQUIRED
Specifies that users must specify a value for the field. Required fields cannot be empty. Users cannot save a work item until they have assigned values to all required fields.
<REQUIRED for="userGroupName" not="userGroupName" />
For more information, see Apply a field rule.
SERVERDEFAULT
Copies a specified server value to a field when a user saves a work item. These fields usually appear as read-only on the form.
<SERVERDEFAULT for="userGroupName" not="userGroupName"
from="clock | currentuser" />
For more information, see Define a default value or copy a value to a field.
SUGGESTEDVALUES
Defines a suggested list of values that users can specify in a field list on work item forms and in the query editor. Users can specify values other than those that you suggest.
<SUGGESTEDVALUES for="userGroupName" not="userGroupName"
expanditems="true | false" filteritems="excludegroups">
<GLOBALLIST name="globalListName">
<LISTITEM value="Name" />
. . .
</GLOBALLIST>
</SUGGESTEDVALUES>
For more information, see Define pick lists.
VALIDUSER
Restricts work items from being modified by users who belong to the group that you specify. The default group is the Team Foundation Valid Users group.
All attributes are optional. All attributes must consist of a string of text that contains between 1 and 255 characters. You can use tokens to specify groups.
< VALIDUSER group="groupName" for="userName" not="userName" />
For more information, see Apply a field rule.
WHEN
Specifies one or more rules to apply to the current field when another field has a specific value. The parent FIELD element defines the current field.
<WHEN field="fieldReferenceName" value="value">
<ALLOWEDVALUES> . . . </ALLOWEDVALUES>
<ALLOWEXISTINGVALUE> . . . <ALLOWEXISTINGVALUE>
<CANNOTLOSEVALUE> . . . </CANNOTLOSEVALUE>
<COPY> . . . </COPY>
<DEFAULT> . . . </DEFAULT>
<EMPTY> . . . </EMPTY>
<FROZEN> . . . </FROZEN>
<MATCH> . . . </MATCH>
<NOTSAMEAS> . . . </NOTSAMEAS>
<PROHIBITEDVALUES> . . . </PROHIBITEDVALUES>
<READONLY> . . . </READONLY>
<REQUIRED> . . . </REQUIRED>
<SERVERDEFAULT> . . . </SERVERDEFAULT>
<SUGGESTEDVALUES> . . . </SUGGESTEDVALUES>
<VALIDUSER> . . . </VALIDUSER>
</WHEN>
For more information, see Assign conditional-based values and rules.
WHENNOT
Specifies one or more rules to apply to the current field when another field does not have a specific value. The parent FIELD element defines the current field.
<WHENNOT field="fieldReferenceName" value="value">
<ALLOWEDVALUES> . . . </ALLOWEDVALUES>
<ALLOWEXISTINGVALUE> . . . <ALLOWEXISTINGVALUE>
<CANNOTLOSEVALUE> . . . </CANNOTLOSEVALUE>
<COPY> . . . </COPY>
<DEFAULT> . . . </DEFAULT>
<EMPTY> . . . </EMPTY>
<FROZEN> . . . </FROZEN>
<MATCH> . . . </MATCH>
<NOTSAMEAS> . . . </NOTSAMEAS>
<PROHIBITEDVALUES> . . . </PROHIBITEDVALUES>
<READONLY> . . . </READONLY>
<REQUIRED> . . . </REQUIRED>
<SERVERDEFAULT> . . . </SERVERDEFAULT>
<SUGGESTEDVALUES> . . . </SUGGESTEDVALUES>
<VALIDUSER> . . . </VALIDUSER>
</WHENNOT>
For more information, see Assign conditional-based values and rules.
WHENCHANGED
Specifies one or more rules to apply to the current field when another field is changed during the revision of the work item. The parent FIELD element defines the current field.
<WHENCHANGED field="fieldReferenceName" >
<ALLOWEDVALUES> . . . </ALLOWEDVALUES>
<ALLOWEXISTINGVALUE> . . . <ALLOWEXISTINGVALUE>
<CANNOTLOSEVALUE> . . . </CANNOTLOSEVALUE>
<COPY> . . . </COPY>
<DEFAULT> . . . </DEFAULT>
<EMPTY> . . . </EMPTY>
<FROZEN> . . . </FROZEN>
<MATCH> . . . </MATCH>
<NOTSAMEAS> . . . </NOTSAMEAS>
<PROHIBITEDVALUES> . . . </PROHIBITEDVALUES>
<READONLY> . . . </READONLY>
<REQUIRED> . . . </REQUIRED>
<SERVERDEFAULT> . . . </SERVERDEFAULT>
<SUGGESTEDVALUES> . . . </SUGGESTEDVALUES>
<VALIDUSER> . . . </VALIDUSER>
</WHENCHANGED>
For more information, see Assign conditional-based values and rules.
WHENNOTCHANGED
Specifies one or more rules to apply to the current field when another field is not changed during the revision of the work item. The parent element defines the current field.
<WHENNOTCHANGED field="fieldReferenceName">
<ALLOWEDVALUES> . . . </ALLOWEDVALUES>
<ALLOWEXISTINGVALUE> . . . <ALLOWEXISTINGVALUE>
<CANNOTLOSEVALUE> . . . </CANNOTLOSEVALUE>
<COPY> . . . </COPY>
<DEFAULT> . . . </DEFAULT>
<EMPTY> . . . </EMPTY>
<FROZEN> . . . </FROZEN>
<MATCH> . . . </MATCH>
<NOTSAMEAS> . . . </NOTSAMEAS>
<PROHIBITEDVALUES> . . . </PROHIBITEDVALUES>
<READONLY> . . . </READONLY>
<REQUIRED> . . . </REQUIRED>
<SERVERDEFAULT> . . . </SERVERDEFAULT>
<SUGGESTEDVALUES> . . . </SUGGESTEDVALUES>
<VALIDUSER> . . . </VALIDUSER>
</WHENNOTCHANGED>
For more information, see Assign conditional-based values and rules.
GLOBALLIST and LISTITEM child elements
You specify the GLOBALLIST and LISTITEM elements as child elements of the ALLOWEDVALUES, SUGGESTEDVALUES, and PROHIBITEDVALUES elements. You can use these elements to enumerate a list of values that appears. Users select values from a pick list or a drop-down menu. For more information, see GLOBALLIST XML element reference.
Element
Description
GLOBALIST
Defines a set of LISTITEM elements that is stored for a project collection and that all projects in a collection can use.
<GLOBALLIST name="globalListName">
<LISTITEM> . . . </LISTITEM>
</GLOBALLIST>
globalListName: A string of text that contains between 1 and 255 characters.
GLOBALLIST is a required child element of the GLOBALLISTS element and an optional child element of the ALLOWEDVALUES, SUGGESTEDVALUES, and PROHIBITEDVALUES elements. You can define a global list within a work item definition, a global list definition, or a global workflow.
LISTITEM
Defines a valid list value.
<LISTITEM value="listName" />
LISTITEM is a required child element of GLOBALLIST and an optional child element of the ALLOWEDVALUES, SUGGESTEDVALUES, and PROHIBITEDVALUES elements.
Attributes specified by FIELD child elements
You can qualify most FIELD rules to apply or not apply to a set of groups or users by including the for or not attributes. For more information, see Rules and rule evaluation.
| Attribute | Syntax | Description |
|---|---|---|
expanditems |
expanditems="true | false" | Optional. Specifies whether a group that the LISTITEM element identifies should be expanded to include subordinate groups in the list. The default value of this attribute is true. |
filteritems |
filteritems="excludegroups" | Optional. Specifies that only the members of groups, and not group names, are included in the list. The only allowed value for this attribute is excludegroups. |
for |
for="userGroupName" | Optional. Specifies the name of a user or group in Team Foundation to whom the rule applies. Valid values consist of a string of text that contains between 1 and 255 characters. |
not |
not="userGroupName" | Optional. Specifies the name of a user or group in Team Foundation to whom the rule does not apply. Valid values consist of a string of text that contains between 1 and 255 characters. |
from |
from="value | field | clock | currentuser" | Required. Specifies the source of the value from which to copy a value or specify a default value. The following values are valid: - clock: Copies the current date and time from the system clock to DateTime fields. No additional attributes are required. For COPY and DEFAULT rules, this value comes from the local computer clock time. For SERVERDEFAULT, the value comes from the server clock when a user saves the work item.- currentuser: Copies the name of the user who is currently logged on. Use the short username of the current user as the value. No additional attributes are required. Used for string fields.- field: Copies the value of the field attribute that you specify. Requires a field="abc" attribute. By default, if the specified "from" field is empty, nothing is performed. The field attribute is used only for <COPY> and <DEFAULT> rules.<br / - value: Copies the value of the value attribute that you specify. Use the value of a string constant that you specify. Requires a value="abc" attribute. value is used only for <COPY> and <DEFAULT> rules.If you specify "value" or "field," you must also include the value or field attribute, respectively. |
field |
field="fieldReferenceName" | Optional. Specifies the name of the field whose value is to be copied into the field when field is specified for the from attribute. |
pattern |
pattern="patternValue" | Required. Enforces basic pattern matching for strings only. patternValue is a string that consists of between 1 and 255 characters, inclusive. That string must not contain a backslash character (\). Each character in the string is interpreted as a literal, unless it is one of the following six metacharacters: - "A" or "a" represent a single alphabetical character. - "N" or "n" represent a single numeric character. - "X" or "x" represent a single alphanumeric character. Pattern value: ^[^\\]*$ For example, pattern="xxxxx.nn.nn" matches any five alphanumeric characters, then a period, then two numeric characters, then a period, then two more numeric characters. |
value |
value="valueToCopy" | Optional. Specifies the value to be copied into the field when value is specified for the from attribute. |