FIELD Element (WORKITEMTYPE Element)
Defines a work item field, and specifies the rules and conditions that apply to it. The attributes that you assign to a field determine how it appears in a work item form and whether you can include that field in reports. You manage the set of field assignments for all team projects on a server that is running Visual Studio Team System Team Foundation Server. Therefore, if you assign an attribute to a field that is defined in more than one type of work item, the attribute must match across all types of work items for all team projects on a server. In addition, all reportable fields from all servers are exported to the data warehouse databases.
Schema Hierarchy
WITD Element (Work Item Type Definition Schema)
WORKITEMTYPE Element (Work Item Type Definition Schema)
FIELDS Element (WORKITEMTYPE Element)
FIELD Element (WORKITEMTYPE Element)
<xs:element name="FIELD" type="FieldDefinition" maxOccurs="unbounded"/>
<FIELD name="field display name" refname="field reference name" type="String | Integer | Double | DateTime | PlainText | HTML | History | TreePath" reportable="Dimension | Detail | Measure" formula="sum" >
<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>
Attributes and Elements
The following sections describe attributes, child elements, and parent elements.
Attributes
Attribute |
Description |
|---|---|
name |
Required FieldDefinition attribute. The friendly name of the field, which appears in the search criteria for work item queries. The friendly name must be unique across all fields that are defined in a team project. Also, the friendly name may differ from the label that appears next to the field on the work item form. For more information, see Control Element (Work Item Type Definition Schema). Attribute type: typelib:FieldName Minimum length: 1 Maximum length: 128 Pattern value: ^[^\.\[\]]+$ Pattern value example: Assigned To |
refname |
Required FieldDefinition attribute. The reference name of the field where the rules and conditions are applied. The reference name must match the reference name in the field definition's FIELD element. For more information, see Field Reference Names and Field Reference Name Naming Conventions. |
type |
Required FieldDefinition attribute. The type of data that the field accepts. For more information, see Field Types. |
reportable |
Optional FieldDefinition attribute. The data from the field will be exported to the data warehouse and can be included in reports. For more information, see Using Fields for Reporting. |
formula |
Optional FieldDefinition attribute. The aggregation type for the measure reportable type. Currently, sum is the only supported aggregation type for measure. For more information, see witfields. |
Child Elements
Element |
Description |
|---|---|
Optional element. Defines the text displayed in the ToolTip for the field. |
|
Optional element. Defines the field as required. |
|
Optional element. Defines the field as read-only. |
|
Optional element. Defines the field as empty. |
|
Optional element. Defines the field as frozen. A frozen field cannot be changed to any non-empty value after changes are committed. However, you can manually clear the field, save the work item, and then specify a different value. |
|
Optional element. Defines the field as cannot lose value. This means that after the current field has acquired a value, it cannot be cleared or made empty. |
|
Optional element. Specifies another field the value of which cannot be identical to the value of the current field. |
|
Optional element. Specifies that the list of allowed values must consist only of valid users of the system. |
|
ALLOWEXISTINGVALUE Element (Work Item Type Definition Schema) |
Optional element. Defines the field as allow existing value. This means that the field values that already exist will be allowed, even if they are not valid. All new field values must be valid. |
Optional element. Defines a pattern for the field that the field value must match. |
|
Optional element. 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. |
|
Optional element. 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 in addition to the ones in the list. |
|
Optional element. Defines a list of prohibited values for the field. |
|
Optional element. Defines a default value for the field. |
|
Optional element. Specifies another field that contains a value to be copied into the current field. |
|
Optional element. Specifies a server component that will provide the value for the field. |
|
Optional element. Specifies one or more rules to apply to the current field when another field has a specific value. |
|
Optional element. Applies one or more rules to the current field when another field does not have a specific value. |
|
Optional element. Applies one or more rules to the current field when a specific field's value is changed. |
|
Optional element. Applies one or more rules to the current field when a specific field's value is not changed. |
Parent Elements
Element |
Description |
|---|---|
Required Element. Contains the work item type field definitions. |
Remarks
FIELD is a required child element of FIELDS.
minOccurs="1"
maxOccurs="unbounded"
You can define no more than 1,024 work item fields for all team projects on a server that is running Team Foundation Server, and you can set no more than 1,024 fields to be reportable.
Note
When you add an existing field to a different type of work item, the current values for the reportable attributes are used.
You cannot define a custom field that starts with the System. prefix. You can define a field by using the Microsoft. prefix. However, this practice is strongly discouraged because it might impede Team Foundation Server functionality.
For more information, see Field Types.
You cannot change the reference name of a field. You can list fields, change the field’s friendly name, and change field attributes by using the witfields command-line tool. For more information, see witfields.
Example
<FIELD name="Activity" refname="Microsoft.VSTS.Common.Activity" type="String" reportable="dimension">
<HELPTEXT>Type of work involved</HELPTEXT>
<SUGGESTEDVALUES>
<LISTITEM value="Development"/>
<LISTITEM value="Testing"/>
<LISTITEM value="Requirements"/>
<LISTITEM value="Design"/>
<LISTITEM value="Deployment"/>
<LISTITEM value="Documentation"/>
</SUGGESTEDVALUES>
</FIELD>
Element Information
Namespace |
https://schemas.microsoft.com/VisualStudio/2005/workitemtracking/typedef |
Schema Name |
Work Item Type Definition |
Validation File |
WorkItemTypeDefinition.xsd |
Element Type |
|
Can Be Empty |
Yes |
See Also
Reference
HELPTEXT Element (Work Item Type Definition Schema)
Other Resources
Work Item Type Definition Schema
Defining Work Item Type Fields
Change History
Date |
History |
Reason |
|---|---|---|
June 2010 |
Added information and moved the syntax of the element earlier in the topic. |
Information enhancement. |