Managing Work Item Fields

  • Article

You can manage the work item type fields that are defined for a team project collection by using the following witadmin commands:

  • deletefield: Deletes the specified field.

  • listfields: Lists the attributes for all fields or a specified field.

  • indexfield: Turns indexing on or off for the specified field. 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.

  • changefield: Changes one or more attributes of a field, such as the friendly field name, attributes for data warehouse reporting, or the ability to synchronize a field that contains person names. When synchronization is enabled, the field is updated as updates are made to Active Directory or a workgroup. For information about how to use fields for reporting, see Working with Work Item Fields.

    Important

    When you upgrade from an earlier version to the current version, all built-in fields the syncnamechanges attribute is set to true for all String fields that contain person names. However, you must manually assign the attribute to any custom fields that you use to store person names and that you want to have synchronized. For more information, see Updating Custom Person-Name Fields to Synchronize with Active Directory or Workgroups.

The witadmin command-line tool is located in Drive:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE on the client computer that runs Team Explorer. 

For more information about fields, see Defining Work Item Fields.

Note

You can create and modify work item fields by using Process Editor, a power tool for Visual Studio. This tool is not supported. For more information, see the following page on the Microsoft Web site: Team Foundation Server Power Tools April 2010.

Required Permissions

For the team project collection where the work item type fields are defined, you must have the following permissions set:

  • To list fields, you must be a member of the Readers group or have your View work items in this node permission set to Allow

  • To delete or rename fields or change the reporting characteristics of a field, you must be a member of the Team Foundation Administrators security group or the Project Administrators security group.

For more information, see Team Foundation Server Permissions and Team Foundation Server Default Groups, Permissions, and Roles.

Note

Even if you log on with administrative permissions, you must open an elevated Command Prompt window to perform this function on a server that is running Windows Server 2008. To open an elevated Command Prompt window, click Start, right-click Command Prompt, and then click Run as Administrator. For more information, see the Microsoft Web site: User Access Control.

witadmin deletefield /collection:CollectionURL /n:RefName [/noprompt]

witadmin listfields /collection:CollectionURL /n:RefName [/unused]

witadmin indexfield /collection:CollectionURL /n:Name /index:on|off 

witadmin changefield /collection:CollectionURL /n:RefName [/name:NewName] [/syncnamechanges:true | false] [/reportingname:ReportingName] [/reportingrefname:ReportingRefName] [/reportingtype:Type] [/reportingformula:Formula] [/noprompt]

Parameters

Parameter

Description

/collection:CollectionURL

Specifies the URI of the team project collection. The format for the URI is the following: http://ServerName:Port/VirtualDirectoryName/CollectionName

If no virtual directory is used, then the format for the URI is the following:

http://ServerName:Port/CollectionName

/n:RefName

/n:Name

The reference name of a work item type field.

/index

Specifies to enable or disable indexing for the specified field. Specify on to enable indexing and off to disable indexing.

/name:NewName

Specifies the new name for the field.

/syncnamechanges

Specifies to use the work item field to store names and to update as changes are made in Active Directory or a workgroup. This option is valid only when a field with the data type of String is specified for the typename.

Specify true to enable synchronization for the data field, specify false to disable synchronization for the data field.

/reportingname:ReportingName

Specifies the name of the field in the data warehouse to be used for reporting.

/reportingrefname:ReportingRefName

Specifies the reference name of the field in the data warehouse to be used for reporting.

/reportingtype:Type

Specifies how the field is used in the warehouse for reporting. The following values are valid:

  • dimension: Used for the Integer, String, or DateTime fields.

  • detail: Used for the Integer, Double, String, or DateTime fields.

  • measure: Used for the Integer and Double fields. The default aggregation type is sum. You can specify another aggregation type by using the formula parameter.

  • disable: Used to disable reportability on the field.

For more information, see Working with Work Item Fields.

/reportingformula:Formula

Specifies the aggregation formula to be used when the field is reported as a measure. The only supported formula is sum.

/unused

Lists all fields that are not used by any team project defined in the team project collection.

/noprompt

Disables prompt for confirmation.

/? or help

Displays help about the command in the Command Prompt window.

Remarks

When you assign the syncnamechanges attribute to a String field, the field always accepts valid user names. However, the field does not allow group names that are stored in Team Foundation Server or in Active Directory if any one of the following conditions is true:

  • The VALIDUSER rule is specified across all work item types

  • The VALIDUSER rule is specified for a work item type

  • The ALLOWEDVALUES rule is specified for a work item type, and that rule has a filter criteria that excludes groups

For more information, see All FIELD XML Elements Reference.

For a summary of the system fields that are indexed, see Using System Fields and Fields Defined by the MSF Process Templates.

Examples

Unless otherwise specified, the following values apply in each example:

  • URI for the team project collection: http://AdventureWorksServer:8080/AWTeam/Collection1

  • Work item field name: AdventureWorks.Field

  • Default encoding: UTF-8

List Fields

The following command displays information about each field defined for Collection1 on the AdventureWorksServer server:

witadmin listfields /collection:http://AdventureWorksServer:8080/AWTeam/Collection1

The following command displays the field information for the specified field AdventureWorks.Field used by Collection1:

witadmin listfields /collection:http://AdventureWorksServer:8080/AWTeam/Collection1 /n:AdventureWorks.Field

The following command displays all fields that Collection1 is not using:

witadmin listfields /collection:http://AdventureWorksServer:8080/AWTeam/Collection1 /unused

Rename a Field

The following command changes the friendly name of the referenced field AdventureWorks.Field to NewFieldName for Collection1:

witadmin changefield /collection:http://AdventureWorksServer:8080/AWTeam/Collection1 /n:AdventureWorks.Field /name:NewFieldName

Change the Report As Value for a Field

The following command specifies the ability to report the type of the DateTime field AdventureWorks.CreatedOn to dimension. This field's data enters the warehouse and Analysis Services databases so that it can be used to filter reports.

witadmin changefield /collection:http://AdventureWorksServer:8080/AWTeam/Collection1 /n:AdventureWorks.CreatedOn /reportingtype:dimension

The following command specifies the ability to report the type of the Double field AdventureWorks.Field to measure. All measures are aggregated by sum.

witadmin reportfield /collection:http://AdventureWorksServer:8080/AWTeam/Collection1 /n:AdventureWorks.Field /reportingtype:measure

Enable Synchronization of a Custom Name Field

The following command enables synchronization for the work item field AW.CustomerName defined for Collection1 on the AdventureWorksServer.

witadmin changefield /collection:http://AdventureWorksServer:8080/AWTeam/Collection1 /n:AW.CustomerName /syncnamechanges:true

Delete a Field

The following command deletes the field AdventureWorks.Field from Collection1:

witadmin deletefield /collection:http://AdventureWorksServer:8080/AWTeam/Collection1 /n:AdventureWorks.Field

See Also

Tasks

List Work Item Fields and View Attributes Assigned to Fields

Concepts

Resolving Schema Conflicts That Are Occurring in the Data Warehouse

Adding and Modifying Work Item Fields to Support Reporting

Using System Fields and Fields Defined by the MSF Process Templates

Other Resources

Defining Work Item Fields

Defining Work Item Fields

witAdmin: Administering Objects for Tracking Work Items