Work Item Field Attributes – What You Can and Can’t Change
As a project administrator, you may need to modify a field that’s being used in your team project. This post provides a quick reference as to what you can and can’t change and how you make the change.
Attributes That You Can Change Across a Team Project Collection
Here are the attributes that you can change for a work item field. Changes that you make apply to all team projects within the team project collection:
- Friendly name that displays in the work item query. This name may differ from that displayed on the work item form.
- Synchronization with Active Directory – you can enable/disable synchronization of person name fields. (added in TFS 2010)
- Indexing – you can enable/disable indexing of fields, which enhances performance of queries that filter on these fields.
- Data type – you can only change the data type for PlainText or HTML fields – New in TFS 2012
- Reporting attributes:
- The name of the field as it appears in a report.
- The reference report name.
- The reporting type: Detail, Dimension, or Measure.
You can change these attributes using witadmin changefield or witadmin indexfield commands. See Managing Work Item Fields [witadmin]. When changing reporting attributes, see Adding and Modifying Work Item Fields to Support Reporting.
Attributes That You Can Change for Each Work Item Type
And here’s the set of attributes that you can change for each work item type. You change these attributes by changing the work item type definition for the field:
- Name that displays on the work item form, see the Control XML element.
- Help text, see HELPTEXT XML element.
- Allowed values or Items within a pick list or drop-down menu. See Defining and Using Lists, Pick Lists, and Global Lists.
Fields That Are Indexed Out of the Box
A query index is created based on those fields that have indexing enabled. This index improves the response time when running queries that include indexed fields.
By default, the following fields are indexed: Assigned To, Created Date, Changed By, State, Reason, Area ID, Iteration ID, and Work Item Type. If there are other fields that your team frequently uses in their queries, you can add them to the query index.
Hidden and Non-Changeable Attributes and the Work Item Field Explorer Tool
In addition to the above attributes, there are a number of non-changeable and virtually hidden attributes for each work item field. You can look up the assignments of these fields using the Work Item Field Explorer tool which you access from the Process Editor power tool. You can download the latest version of the Power Tools for Team Foundation Server here.
Here’s a description of each of the attributes that Work Item Field Explorer lists. Each attribute is linked to its corresponding WorkItemTracking SDK reference topic.
Gets the collection of valid values for a Field that uses this field definition. You can change this by specifying a pick list or global list. See Defining and Using Lists, Pick Lists, and Global Lists.
Specifies whether work items within a query can be sorted by this field.
Specifies the data type defined for the field. You cannot change this except for the PlainText and HTML data types.
Specifies the help text defined for the field. You can change this for each work item type using the HELPTEXT XML element.
Specifies the internal ID of the field.
Indicates if the value set by this field is computed (True) or not (False). Examples of computed fields are ones that are set by the system, such as the ID, Revised Date, Changed Date, and External Link Count.
Indicates if users can modify this field (True) or not (False). Examples of non-editable fields are ones that are set by the system, such as the ID, Revision, Created By, and Changed By fields.
Indicates if the field is indexed (True) or not (False). 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.
Indicates if the field shows up within the set of fields you can add to filter a query (True) or not (False).
Specifies the friendly display name of this field definition.
Specifies the reference name of the field definition.
Specifies the reporting attributes of the field definition.
Specifies the type declaration: class types, interface types, array types, value types, enumeration types, type parameters, generic type definitions, and open or closed constructed generic types.
Specifies whether the field is intended for use with work items or work item link objects.
For more information about the Work Item Tracking SDK, see Extending Work Item Tracking by Using the Client Object Model for Team Foundation.