Define and modify work item fields

You use work item fields to track data for a work item type and to define the filter criteria for queries as well as to generate reports. Any data element, except for core system data fields in Team Foundation Server (TFS), that you want to track, use to define the workflow, or appear on the form for a work item type must be defined as a work item field. You can define work item fields within the definition of a work item type or global workflow.

Work item fields are maintained for a team project collection. You add fields when you perform one of the following tasks:

• Create a team project. All fields that are defined within the definitions for work item types or global workflow and that are defined for the selected process template are created. The core system fields are automatically defined for every work item type that is defined for a team project. For a list of these fields, see Work item field reference for Visual Studio ALM.

• Import a definition for a type of work item. All new fields that are defined within the definition for a type of work item are added to the collection. For more information, see All WITD XML elements reference.

• Import a global workflow definition. All new fields that are defined within the global workflow are added to the collection. You define a global workflow when you want to maintain a set of work item fields that several types of work items share. For more information, see Customize global workflow.

• Map a project collection to an instance of Project Web App (PWA). After you install the Team Foundation Server Extensions for Project Server, configure the integration by mapping various components of Team Foundation. When you map a collection, a global workflow definition that supports several fields in Project Server fields is imported. For more information, see Project Server fields added to TFS to support data synchronization.

All fields that are defined in all work item types and all global workflows for all team projects make up the complete set of fields that are defined for the collection. You can change the attribute of, rename, and delete existing fields. However, you incur certain costs when you make these kinds of changes. For more information, see Customize work tracking objects to support your team's processes.

To add or customize a field for a collection, modify the XML content for the definition of a type of work item or global workflow. Define each field through a FIELD element within the FIELDS section of the definition for either a type of work item or global workflow. For information about the structure and location of these files, see All WITD XML elements reference and Customize global workflow.

FIELD (Definition) syntax structure

Each FIELD (Definition) element has an friendly name, which is optional, and a reference name, which is required. The reference name must be unique within the collection. For more information, see Naming conventions for work item tracking objects.

Define a field by the following XML syntax in the definition file for the type of work item.

<FIELD name="fieldDisplayName"
   refname="fieldReferenceName" type="String | Integer | Double | DateTime | PlainText | HTML | History | TreePath | GUID"
   syncnamechanges="true | false"
   reportingname="reportingDisplayName"
   reportingrefname="reportingReferenceName"
   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>

For more information, see FIELD (Definition) element reference.

Data types

The type of a field defines the kind and size of data that you can store in the field. A field can have only one type defined within a team project collection. This restriction encourages organizations to use common fields across projects and work item types.

The following list shows the supported field types:

Reportable attributes

Some field values are especially useful for reporting. By using the work item type definition language, you can specify the following optional attributes:

• reportable. Set the reportable attribute to None, Detail, Dimension, or Measure, depending on whether and how you want the field to be included in reports. Data from fields that have a value other than None for this attribute are exported to the data warehouse and can be included in reports.

  When you add an existing field to a work item type, the current value for the reportable attribute is used. When you add a field to a work item type, reporting is disabled unless you explicitly specify it by using the reportable attribute.

• reportingname. Assign a different label to a field that is used when data appears in reports. If you do not specify a value, the friendly name that is assigned for the name attribute is used.

• reportingrefname. Assign a different reference name to a field that is used when data is exported to the relational data warehouse. If you do not specify a value, the value that is assigned to the refname attribute is used.

  Use this attribute to either merge or diverge fields that are included in reports. To merge two fields that have distinct reference names and that are defined in different project collections, you assign the same reportingrefname to both fields. To diverge two fields that have the same reference name and that are defined in different project collections, you assign a different reportingrefname to each field.

After you define a field, you can use the witadmin changefield command at a command prompt to change the value of all attributes except for the refname attribute.

For information about best practices in labeling fields for reporting purposes, see Add or modify work item fields to support reporting.

Reportable attribute values

As the following table describes, you can assign one of the following values to the reportable attribute: none, dimension, detail, and measure.

Examples Showing How to Specify Reporting

Detail Example

<FIELD refname="MyCorp.Summary" name="Summary" type="String" reportable="detail">

Dimension Example

<FIELD refname="MyCorp.Category" name="Category" type="String" reportable="dimension">

Measure Example

<FIELD refname="MyCorp.Cost" name="Cost" type="Integer" reportable="measure" formula="sum">

Indexed Fields

You can enable or disable indexing for a work item field by using the witadmin indexfield command. When you enable indexing for a field, you may increase the performance of finding work items whose queries specify that field. If you add a custom field that you use in many of your work item queries, you may want to enable indexing for that field. For more information, see Manage work item fields [witadmin].

FIELD (Definition) child elements

There are a number of optional child elements that you can specify for a work item field, for example:

• Help text. Defines the tool tip or help information that displays for a field on the work item form (HELPTEXT).

• Field restrictions. Specifies a field as required, read-only, empty, frozen, or matching a specific pattern (REQUIRED, READONLY, EMPTY, FROZEN, MATCH).

• Field value auto-population. Specifies a value for the field (DEFAULT, COPY, SERVERDEFAULT).

• Field lists. Specifies allowed, suggested, or prohibited values. (ALLOWEDVALUES, SUGGESTEDVALUES, PROHIBITEDVALUES)

• Field conditions. Applies one or more rules to a field when another field is changed or not changed, or another field has or does not have a specific value, or other condition (WHEN, WHENNOT, WHENCHANGED, WHENNOTCHANGED, CANNOTLOSEVALUE, NOTSAMEAS).

For more information, see All FIELD XML elements reference.

System and predefined fields

All system defined fields have reference names that begin with System, for example, System.AreaPath, System.AssignedTo, and continue in that pattern.

Predefined fields defined by the default process templates that TFS provides begin with Microsoft.VSTS and then further differ based on their usage. Examples of predefined fields that are used in common, for scheduling purposes and integration with Microsoft Project, for integration with Team Foundation Build, and integration with Team Foundation are as follows:

• Microsoft.VSTS.Common.Priority

• Microsoft.VSTS.Scheduling.DueDate

• Microsoft.VSTS.Build.FoundIn

• Microsoft.VSTS.TCM.Steps

For an overview of all system and predefined fields that are defined for the default process templates that TFS provides, see Work item field reference for Visual Studio ALM. For more information about specifying field names, see Naming conventions for work item tracking objects.

Hidden and non-changeable attributes and the Work Item Field Explorer

In addition to the attributes that you can change for a work item field, there are a number of non-changeable and virtually hidden attributes for each field. You can look up the assignments of these fields using the Work Item Field Explorer tool. Access the Work Item Field Explorer tool from the Process Editor power tool.

Work Item Field Explorer

See Also

Reference

Manage work item fields [witadmin]

Concepts

Add or modify work item fields to support reporting

All FIELD XML elements reference

Other Resources

Modify or add a field to support queries, reports, and workflow