Define Work Item Fields

  • Article

You use work item fields to track data for a work item type, to define the criteria for queries, and to design reports. You can customize how you use a predefined work item field for a work item type, or you can create fields that will support additional requirements for tracking data. For an index of fields defined within the default process templates for Team Foundation Server, see Work Item Field Reference for Visual Studio ALM.

You may want to customize a work item field for the following reasons:

  • Change the field label to match your team's naming conventions.

  • Add or modify attributes of a field.

  • Specify a default value, or control the values to which users can set a field.

  • Restrict who can modify a field.

  • Add a field to capture data that is specific to your team's process or tracking requirements.

  • Define or customize a pick list.

  • Replace a pick list with a global list to support cross-group consistency and ease of maintenance.

Work item forms use fields to display data, or to enable users to input data or select options. You can control the appearance and behavior of fields on work item forms by defining those fields in the work item type definition.

In the work item type definition, you define a field by specifying a name, a reference name, and a type. Fields can also be defined to include Help text, to follow rules, and to exhibit specific reporting behavior. By using global workflow, you can define fields that apply to all types of work items that are defined for a team project or collection. You can use global workflow to define and update field rules that affect all types of work items in a team project or collection.

Work item fields are maintained for a team project collection. You can change an attribute of, rename, and delete existing fields.

FIELD Element Syntax

The following syntax structure and attributes define fields:

<FIELD name="field display name" refname="field reference name" type="String | Integer | 
Double | DateTime | PlainText | HTML | History | TreePath | GUID " 
syncnamechanges="true | false" reportable="Dimension | Detail | Measure" formula="sum" 
indexable="true | false" >
</FIELD>

Note the following information about the specification of attributes:

  • You can specify a field name that you want and have it be different in different work item definitions. All field data is tracked based on the reference name.

  • The type attribute specifies the data type for the field. For a description of each data type, see Working with Work Item Fields. For information about the controls that display specific field types, see Specify Work Item Form Controls.

  • String fields that are used to store person names should have the syncnamechanges attribute set to true. This setting indicates that the contents of the field should be updated as changes are made to person names in Active Directory or a workgroup.

  • Fields that have their Reportable attribute assigned a value of Detail, Dimension, or Measure are tracked in the data warehouse. For more information, see Working with Work Item Fields.

  • The Indexable attribute is set to True to increase the performance of running queries that specify that field in the filter criteria. If you add a custom field that you use in many of your work item queries, you might want to enable indexing for that field.

You can change the field name and the Reportable and Indexable attribute assignments for any field, except system fields, by using the witadmin command-line tool. For more information, see Managing Work Item Fields [witadmin].

Back to top

Common Tasks

Tasks

Related topics

Learn about the field types and field attributes that you can specify. You can define fields to store specific types of data, such as text, numbers, or HTML content. Depending on how you want to use the data field for reporting or query purposes, you can set additional attributes.

Look up the syntax of a FIELD (Definition) element. You define work item fields by using the FIELD (Definition) element. You specify the behavior of a field, define default values, or define a pick list of values by using one or more child elements. You can combine field rule elements. You can apply most rules to a specific user or group or ignore them for a specific user or group.

Specify fields to perform specific actions for tracking process. Team Foundation manages system fields, which you can use to track all types of work items. All other fields are added to a team project collection through the work item type definitions. Work item types are specified in the process template from a team project that was created, or you can import work item types to a team project later.

For best results, you should specify fields that are already in use if they meet your needs for tracking projects.

Specify the behavior, default value, or conditions of field values. You can set field rules to define the behavior of and constraints on field values. Field rules are additional elements that are listed inside a FIELD element container. You can define field rules for a field, state, transition, reason, or global workflow.

Define the list items, and optionally set conditions on them. You use field lists to enumerate a set of allowed, suggested, or prohibited values. You can also define global lists for all types of work items.

Back to top

Task

Related topics

Understand the restrictions placed on naming fields and other work item tracking objects. You can specify a friendly name for all work item tracking objects, and for some you must also specify a reference name. Both types of names must meet the requirements defined based on the object type.

Add fields, or modify reporting attributes of existing fields. You can add fields or change the attributes of existing fields to support reporting. When you add or change fields, you should name them systematically so that you can find the field in the Analysis Services cube because the fields are logically grouped into folders.

Define fields or lists to be used by all types of work items for a project or collection. You can define and update fields and enumerated lists by defining them as part of the global workflow.

Add, remove, or modify the states or transitions that control workflow. You control the workflow by defining its initial state, its valid states, the valid transitions between those states, and the users or groups that have permission to perform those transitions. The WORKFLOW section of the work item type controls how a work item is tracked.

Modify and customize the work item form for a work item type. You can control the way a work item type displays user-interface elements through the FORM section of the work item type definition. Each work item type must have one and only one form. You describe the whole form, which includes all its tabs, fields, and groups.

Back to top

See Also

Concepts

Reportable Fields Reference for Visual Studio ALM

Work Item Field Reference for Visual Studio ALM

All WITD XML Elements Reference

Customize Work Item Tracking and Your Team Project

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