You use the FIELD (Definition) element to define a work item field and specify the rules and conditions that apply to it. The attributes that you assign to a field determines its data type and whether it is available for inclusion in reports.
 Note |
|---|
For information about the FIELD (Workflow) element, which you use to specify rules and conditions to fields during a state change or workflow transition, see FIELD (Workflow) element. |
Schema Hierarchy
WITD
WORKITEMTYPE
FIELDS
FIELD
<FIELD name="fieldDisplayName" refname="fieldReferenceName" type="String | Integer | Double | DateTime | PlainText | HTML | History | TreePath | GUID" syncnamechanges ="true | false" reportable="Dimension | Detail | Measure" formula="sum" reportingname="ReportingDisplayName" reportingrefname="ReportingReferenceName" > <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. The friendly name of the field that appears in the drop-down menus of work item queries. The friendly name must be unique across all fields that are defined within 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 XML element reference. The attribute type is typelib:FieldName. Minimum length: 1; maximum length: 128. Pattern value: ^[^\.\[\]]+$ Pattern value example: Assigned To | ||||||||||||||||||||||||||
refname | Required. The unique label that distinguishes a field from all other fields that are defined in the team project collection. For additional requirements and restrictions on friendly names and reference names, see Naming conventions for work item tracking objects. The attribute type is typelib:ReferenceFieldName. Minimum length: 1; maximum length: 70. Pattern value: ^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z0-9_]+)+$ Pattern value example: Company.IssueType | ||||||||||||||||||||||||||
type | Required. Specifies the type of data that the field accepts.
The following table lists valid values for this attribute:
| ||||||||||||||||||||||||||
syncnamechanges | Optional. Specifies whether the work item field is used to store names that you want to be updated as changes are made in Active Directory or a Workgroup. This option is only valid when type="String". The attribute type is xs:boolean. Specify true to enable synchronization for the data field, specify false to disable synchronization for the data field. | ||||||||||||||||||||||||||
reportable | Optional. Specifies whether data from the field is available for inclusion in reports. Fields with the default value of None are neither exported to the relational data warehouse nor processed for the SQL Server Analysis Services cube. For more information about reportable fields, see Add or modify work item fields to support reporting.
The following table lists valid values for this attribute:
| ||||||||||||||||||||||||||
formula | Optional. The aggregation type for the measure reportable type. The only valid value is sum, which returns the sum of all values over the set. | ||||||||||||||||||||||||||
reportingname | Optional. Specifies the name that appears in reports. If you do not specify a value, the value that is assigned to the name attribute is used.
The attribute type is typelib:FieldName. Minimum length: 1; maximum length: 128. Pattern value: ^[^\.\[\]]+$ Pattern value example: Assigned To | ||||||||||||||||||||||||||
reportingrefname | Optional. Specifies the reference name that is used when a reportable field is processed. If you do not specify a value, the value that is assigned to the refname attribute is used. You can use this attribute to either merge or diverge fields that are processed to the data warehouse. To merge two fields that have distinct reference names and that are defined in different project collections, you assign the same reportingrefname to both of them. To diverge two fields that have the same reference name but that are defined in different project collections, you assign a different reportingrefname to each field. You should merge fields whenever possible to minimize the number of fields in the warehouse and to keep under the maximum limit of 1024 reportable fields. You can generate cross-group reports with merged fields. The attribute type is typelib:ReferenceFieldName. Minimum length: 1; maximum length: 70. Pattern value: ^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z0-9_]+)+$ Pattern value example: Company.IssueType |
Child Elements
Element | Description |
|---|---|
ALLOWEDVALUES | Optional. 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. |
ALLOWEXISTINGVALUE | Optional. Defines the field to allow existing values. This element allows the field values that already exist to be used, even if they are not valid. All new field values must be valid. |
CANNOTLOSEVALUE | Optional. Defines the field as cannot lose value. This element keeps the current field value and it cannot be cleared or made empty. |
COPY | Optional. Specifies another field that contains a value to be copied into the current field. |
DEFAULT | Optional. Defines a default value for the field. |
EMPTY | Optional. Defines the field as empty. |
FROZEN | Optional. 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. |
HELPTEXT | Optional. Defines the text displayed in the ToolTip for the field. |
MATCH | Optional. Defines a pattern for the field that the field value must match. |
NOTSAMEAS | Optional. Specifies another field, the value of which cannot be identical to the value of the current field. |
PROHIBITEDVALUES | Optional. Defines a list of prohibited values for the field. |
READONLY | Optional. Defines the field as read-only. |
REQUIRED | Optional. Defines the field as required. |
SERVERDEFAULT | Optional. Specifies a server component that will provide the value for the field. |
SUGGESTEDVALUES | Optional. 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 additionally to the ones in the list. |
VALIDUSER | Optional. Specifies that the list of allowed values must consist only of valid users of the system. |
WHEN | Optional. Specifies one or more rules to apply to the current field when another field has a specific value. |
WHENCHANGED | Optional. Applies one or more rules to the current field when a specific field's value is changed. |
WHENNOT | Optional. Applies one or more rules to the current field when another field does not have a specific value. |
WHENNOTCHANGED | Optional. Applies one or more rules to the current field when a specific field's value is not changed. |
Parent Elements
Element | Description |
|---|---|
FIELDS | Required. Contains the work item type field definitions. |
Remarks
FIELD (Definition) is a required child element of FIELDS (Definition).
For an overview of all system and predefined fields that are defined for the TFS process templates, see Work item field reference for Visual Studio ALM.
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 additional requirements and restrictions on field-friendly names and reference names, see Naming conventions for work item tracking objects.
Although you can rename a field's friendly name, you can't rename the field's reference names. You can list fields and change several field attributes using the witadmin command-line toolSee Manage work item fields [witadmin].
You can define no more than 1,024 work item fields in the same team project collection, and you can set no more than 1,024 fields to reportable in all team project collections.
All fields defined within all work item types (WITs) for all team projects defined for a project collection are for a team project collection. Therefore, attributes that you assign to fields that are defined in one WIT must match across all WITs for all team projects in a collection. In addition, all reportable fields from all collections are exported to the data warehouse databases.
For information about how to label fields for reporting purposes, see Add or modify work item fields to support reporting.
When you add an existing field to a different WIT, either explicitly set the reporting attributes to be the same as the current field definition, or let them default to these values.
Schema conflicts can occur if different reporting attributes are assigned to the same field in different WITs or the same WITs in different team projects. To fix these conflicts, see Resolve schema conflicts that are occurring in the data warehouse.
To understand how fields are used to support queries, reports, and work item tracking, see Modify or add a field to support queries, reports, and workflow.
For an overview of how to apply constraints or conditions on a FIELD by using child elements, see Apply a rule to a work item field.
Example
 Copy Code | |
|---|---|
<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> | |
See Also
Reference
Concepts
Other Resources
