All FIELD XML elements reference

  • Artikel

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.