Working with 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 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 Project Tracking Data, Forms, Workflow, and Other Objects.

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.

In this topic

• FIELD (Definition) Syntax Structure

• Field Data Types

• Reportable Attributes Assigned to Fields

• Indexed Fields

• FIELD (Definition) Child Elements

• System Fields and Predefined Fields

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.

Important

You can change the friendly name for a field by using the witadmin changefield command-line tool. However, if you rename a field, it affects all work item types in all team projects within the collection.

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.

Back to top

Field 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:

Data type	Description
DateTime	Specifies a date according to Coordinated Universal Time (UTC) moment in time. Add a DateTime field to a work item form by using either the FieldControl or DateTimeControltype attributes.
Double	Specifies a floating-point value. Double fields are frequently used in query filters and results lists. Add a Double field to a work item form by using the FieldControltype attribute.
GUID	Specifies a field that will contain a unique identifier. You cannot add a GUID field to a work item form.
History	Supports viewing discussion threads and tracking 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. Add the System.History field to a work item form by using the WorkItemLogControltype attribute which supports rich text format controls.
HTML	Supports the ability to capture rich-text data and to use longer text descriptions such as a work item description. An HTML field differs from a PlainText field in that an HTML field is strongly typed to HTML for richer displays of information. Add an HTML field to a work item form by using the HTMLControltype attribute, which supports rich text format controls.
Integer	Specifies a 32-bit signed integer value. Integer fields are frequently used in query filters and results lists. Add an Integer field to a work item form by using the FieldControltype attribute.
PlainText	Supports entry of a text string that can contain more than 255 Unicode characters. Add a PlainText field to a work item form by using either the FieldControl type attribute and limited to plain text, or the HTMLControltype attribute which supports rich text format controls.
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. String fields are frequently used in query filters and results lists. Add a String field to a work item form by using the FieldControltype attribute.
TreePath	Specifies a field that displays entries in a hierarchical or tree structure, such as the requirements to display area and iteration paths for a product. 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. Add the System.AreaPath and System.IterationPath fields to a work item form by using the WorkItemClassificationControl type attribute.

Back to top

Reportable Attributes That Are Assigned to Fields

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

Back to top

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.

Note

You can make a field reportable after it has been used for a work item. After you set the reportable value, new revisions of the work item that are copied to the warehouse will contain the field value. However, the revisions that are already in the warehouse will not be backfilled with the existing values.

Attribute value	Description
Detail	Use the Detail type only for Integer, Double, String, or DateTime fields. 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 SQL Server Analysis Services cube. By using this type for unrestricted text fields, you can use them in reports without making the cube significantly larger.
Dimension	Use the Dimension type only for Integer, String, or DateTime fields. 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. During processing of the Analysis Services cube, data is precalculated on fields that 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. For more information about measure groups, see Perspectives and Measure Groups Provided in the Analysis Services Cube for Team System. When you specify Measure, you must specify sum for the formula attribute, which returns the sum of each measure referenced in the query.
None	Specify None when you do not want to include the field in reports. This value is the default assignment.

Back to top

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

Back to top

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.

Back to top

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.

Back to top

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

Note

The Process Editor power tool provides a graphical user interface for customizing Team Foundation Server process templates. You can use this tool to import and export work item types, modify the contents of the process template, and explore the set of fields defined for a team project collection. For more information, see the following page on the Microsoft website: Team Foundation Server Power Tools.

See Also

Reference

Manage Work Item Fields [witadmin]

Concepts

Customize Work Item Tracking and Your Team Project

Add and Modify Work Item Fields to Support Reporting

All FIELD XML Elements Reference

Other Resources

Define Work Item Fields