Partager via

FIELD (Definition) element reference

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

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 Add and modify area and iteration paths.

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 or 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

  1. FIELD (Definition) is a required child element of FIELDS (Definition).

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

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

  4. 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].

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

  6. For information about how to label fields for reporting purposes, see Add or modify work item fields to support reporting.

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

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

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

<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 work tracking objects to support your team's processes

Define and modify work item fields

Other Resources

Work item tracking: Index to XML element definitions