Working with Work Item Fields

  • Article

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

  • You 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. For more information, see Work Item Fields (Agile) or Work Item Fields (CMMI). 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 Using System Fields and Fields Defined by the MSF Process Templates.

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

  • You 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 Customizing Global Workflow.

  • You map a project collection to an instance of Project Web App (PWA). After you install the Visual Studio Team Foundation Server 2010 and Project Server Integration feature pack, you 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 Customizing Project Tracking Data, Forms, Workflow, and Other Objects.

To add or customize a field for a collection, you modify the XML content for the definition of a type of work item or global workflow. You 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 Customizing 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.

You 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="avg" >
   <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 per Team Foundation Server. 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.

You can add a DateTime field to a work item form by using either the FieldControl or DateTimeControl type attributes.

Double

Specifies a floating-point value. Double fields are frequently used in query filters and results lists.

You can add a Double field to a work item form by using the FieldControl type 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.

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

You can add the System.History field to a work item form by using the WorkItemLogControl type 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.

You can add an HTML field to a work item form by using the HTMLControl type 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.

You can add an Integer field to a work item form by using the FieldControl type attribute.

PlainText

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

You can add a PlainText field to a work item form by using either the FieldControl type attribute and limited to plain text, or the HTMLControl type 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.

You can add a String field to a work item form by using the FieldControl type 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.

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

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

    You can 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 Adding and Modifying 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, Double, 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 Managing 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 Microsoft Solutions Framework (MSF) process templates 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 Office 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 MSF for Agile Software Development v5.0 process template, see Using System Fields and Fields Defined by the MSF Process Templates. For more information about specifying field names, see Naming Conventions for Work Item Tracking Objects.

Back to top

See Also

Tasks

Add a Field to or Remove a Field from a Work Item Type

Reference

Managing Work Item Fields [witadmin]

FIELD (Definition) Element

Concepts

Resolving Schema Conflicts That Are Occurring in the Data Warehouse

Adding and Modifying Work Item Fields to Support Reporting

All WITD XML Elements Reference

All FIELD XML Elements Reference

Other Resources

Defining Work Item Fields