Share via

FIELD (Definition) Element

  • Article

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 determine how it appears in a work item form and whether it is available for inclusion in reports. You manage the set of field assignments for a team project collection. Therefore, attributes that you assign to fields that are defined in one type of work item must match across all types of work items for all team projects in a collection. In addition, all reportable fields from all collections are exported to the data warehouse databases.

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.

You can change the attribute assignments that you make to existing fields for a collection by using the witadmin command tool. For more information, see Manage Work Item Fields [witadmin].

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.

Note

Fields in different project collections that have the same reportingrefname must be assigned the same value for type. If the values differ, data conflicts can occur when the data warehouse is processed. For more information, see Resolve Schema Conflicts That Are Occurring in the Data Warehouse.

The following table lists valid values for this attribute:

Value

Usage

DateTime

Specifies a date according to Coordinated Universal Time (UTC) moment in time.

Double

Specifies a floating-point value.

GUID

Specifies a field that will contain a unique identifier.

History

Supports discussion threads and keeps track of other historical information.

Note

The System.History field is the only field that uses this data type. You cannot define a custom field using this data type.

HTML

Supports capture of rich-text data and is used for longer text descriptions such as a work item description.

Integer

Specifies a 32-bit signed integer value.

PlainText

Supports entry of a text string that can contain more than 255 Unicode characters.

String

Supports entry of a text string that can contain up to 255 Unicode characters. Use a String field for a label or other short text string up to one line long.

TreePath

Specifies a field that displays entries in a hierarchical or tree structure, such as what is required to display the area and iteration paths for a product. To define child nodes, see Create and Modify Areas and Iterations.

Note

The System.AreaPath and System.IterationPath fields are the only fields that use this data type. You cannot define a custom field using this data type.

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 and Modify Work Item Fields to Support Reporting.

Note

Fields in different project collections that have the same value for the reportingrefname must be assigned the same value for reportable. If the values differ, data conflicts can occur when the data warehouse is processed. For more information, see Resolve Schema Conflicts That Are Occurring in the Data Warehouse.

The following table lists valid values for this attribute:

Value

Usage

Detail

Can be specified for fields of type DateTime, Double, Integer, or String.

The data in this field is moved into the relational warehouse database in the Work Item and Current Work Item tables but not into the Analysis Services cube. This type is a good choice for unrestricted text fields because you can use them in reports without making the cube significantly larger.

Dimension

Can be specified for fields of type DateTime, Integer, String, or TreePath.

The data in this field enters the relational warehouse database and the Analysis Services cube as an attribute of the Work Item dimension so that the data can be used to filter reports. Use this type for fields that have lists of valid values. Work Item Type and State are good examples of a dimension.

Measure

Use the measure type only for Integer and Double fields. Measures are the numeric values in your reports.

When the Analysis Services cube is processed, data is precalculated on fields whose reportable attributes are set to measure. For example, the Work Item and Current Work Item measure groups contain cumulative data for the following fields: Original Estimate, Remaining Hours, and Completed Hours.

When you specify measure, you must specify the formula attribute.

None

Specify None when you do not want to use the field for inclusion in reports. This is the default assignment.

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.

Note

Fields in different project collections that have the same reportingrefname must be assigned the same value for the reportingname. If the values differ, data conflicts can occur when the data warehouse is processed. For more information, see Resolve Schema Conflicts That Are Occurring in the Data Warehouse.

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).

minOccurs="1"

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. For more information, see Add and Modify Work Item Fields to Support Reporting.

Note

When you add an existing field to a different type of work item, the current values for the reportable attributes are used.

For additional requirements and restrictions on field-friendly names and reference names, see Naming Conventions for Work Item Tracking Objects. For information about how to label fields for reporting purposes, see Add and Modify Work Item Fields to Support Reporting.

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 an overview of the field work item tracking object, see Working with Work Item Fields.

For an overview of all system and predefined fields that are defined for the Microsoft Solutions Framework (MSF) for Agile Software Development v5.0 process template, see Work Item Field Reference for Visual Studio ALM.

Field reference names cannot be renamed. You can list fields, rename the field friendly name, and change field attributes using the witadmin command-line tool. For more information, see Manage Work Item Fields [witadmin].

For information about how fields are used across team project collections, see Resolve Schema Conflicts That Are Occurring in the Data Warehouse and Add and Modify Work Item Fields to Support Reporting.

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>

See Also

Reference

Manage Work Item Fields [witadmin]

Concepts

Naming Conventions for Work Item Tracking Objects

Work Item Field Reference for Visual Studio ALM

Customize Project Tracking Data, Forms, Workflow, and Other Objects

Working with Work Item Fields

Other Resources

Index to XML Element Definitions for Work Item Types