Manage work item fields

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

The witadmin command-line tool provides powerful capabilities for managing work item fields in your project collection. Whether you need to rename fields, adjust data types, or configure synchronization with identity providers, these commands give you granular control over your work tracking experience.

What you can do with witadmin field commands

Use the following witadmin commands to manage fields across all work item types and projects in your collection:

• changefield: Modify field attributes that apply collection-wide, including:
  • Data type conversion between PlainText and HTML formats

  Important

  When you upgrade Azure DevOps Server, the Description field (System.Description) automatically converts from PlainText to HTML. Use the changefield command to revert this if needed.

  • Friendly names displayed in work item queries (might differ from form labels)
  • Reporting attributes for data warehouse integration
  • Identity synchronization with Microsoft Entra ID or Active Directory
• deletefield: Remove unused fields from your collection
• listfields: View field attributes and usage across projects

Run the witadmin command-line tool

To run the witadmin command-line tool, open a Command Prompt window where Visual Studio is installed. The witadmin command-line tool installs with any version of Visual Studio. You can access this tool by installing the free version of Visual Studio Community or Visual Studio Team Explorer.

For Visual Studio 2022

%programfiles(x86)%\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer

or Professional or Enterprise in place of Community, depending on the version you installed.

For Visual Studio 2019

%programfiles(x86)%\Microsoft Visual Studio\2019\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer

or Professional or Enterprise in place of Community, depending on the version you installed.

For Visual Studio 2017

%programfiles(x86)%\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer

or TeamExplorer or Professional in place of Enterprise, depending on the version you installed.

On a 32-bit edition of Windows, replace %programfiles(x86)% with %programfiles%. You can install Visual Studio Community (which provides access to Team Explorer) or Visual Studio Team Explorer 2017 for free.

For an overview of the fields defined within a default process template, see Work item field index.

Prerequisites

For more information, see Change project collection-level permissions.

Syntax

Use the following command syntax patterns to manage work item fields with the witadmin tool:

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

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

Parameters

Synchronizing person names with Microsoft Entra ID and Active Directory

Configure custom person-name fields to automatically update when user names change in your identity provider.

When to enable synchronization

Custom fields only: You must manually enable synchronization for any custom work item fields used to assign person names.

System fields: All built-in person-name fields automatically have synchronization enabled:

• System.AssignedTo
• System.ChangedBy
• System.CreatedBy

Identity provider support

How synchronization works

Group name restrictions

When you enable the syncnamechanges attribute on a String field, it accepts valid user names but doesn't allow group names if any of these conditions apply:

• VALIDUSER rule specified across all work item types
• VALIDUSER rule specified for a specific work item type
• ALLOWEDVALUES rule specified with filter criteria that excludes groups

Configuration scope

For more information, see:

• Assignments and workflow fields
• All FIELD elements.

Attributes that you can change for each work item type

You change the following attributes or values defined for a field by changing the work item type definition in which the field appears:

• Name that displays on the work item form. See WebLayout and Control elements or Control XML element reference.
• Help text. See Rules and rule evaluation.
• Allowed values or items within a pick list or drop-down menu. See ALLOWEDVALUES, SUGGESTEDVALUES, and PROHIBITEDVALUES XML elements.

Examples

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

• URI for the project collection: http://AdventureWorksServer:8080/tfs/DefaultCollection
• Work item field name: AdventureWorks.Field
• Default encoding: UTF-8

List fields

Use witadmin listfields to see the set of fields in use, to select one to add to a work item type. Also, you can list the attribute assignments defined for a specific field and determine which fields are used by which projects.

View the attributes of a work item field

Enter the following command to list the attributes defined for a specified field, such as Microsoft.VSTS.Common.Issue.

witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:Microsoft.VSTS.Common.Issue  

Field and attribute information appears for the named field, as shown in this example.

Field: Microsoft.VSTS.Common.Issue  
    Name: Issue  
    Type: String  
    Reportable As: dimension  
    Use: Adventure Works (Shared Steps), AW Future (Shared Steps), AW Current (Shared Steps)  
    Indexed: False  

The Use parameter indicates the name of each project and the work item type where the field is used. For more information about field attributes, see Index of work item fields.

List all fields in a project collection

Enter the following command to list all fields defined for a project collection.

witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection  

Field information for all the fields for the named project collection appears. See Index of work item fields.

List fields that aren't being used

Enter the following command to list the fields that are no longer being used in the project collection by any work item type.

witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /unused  

Field and attribute information appears for each field that isn't being used, as shown in this example.

    Field: Microsoft.VSTS.CMMI.TaskType  
    Name: Task Type  
    Type: String  
    Reportable As: dimension  
    Use: Not In Use  
    Indexed: False  

    Field: Microsoft.VSTSUE.Common.Flag  
    Name: Flag  
    Type: String  
    Reportable As: dimension  
    Use: Not In Use  
    Indexed: False  

    Field: Microsoft.VSTSUE.Common.Progress  
    Name: Progress  
    Type: String  
    Reportable As: dimension  
    Use: Not In Use  
    Indexed: False  

Rename a field

You can change the friendly name of a work item field to meet the naming conventions that your team uses. The new name is applied to all work item types that reference the changed field in all projects in the project collection. The friendly name displays when you define filter criteria in a work item query. The name that appears on a work item form might be different than the friendly name defined for the field.

To rename a work item field

1. Enter the following command to rename the friendly name assigned to Microsoft.VSTS.Common.Rank to Important Rank.

   witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:Microsoft.VSTS.Common.Rank /name:"Important Rank"  
   

2. At the confirmation prompt, enter y and then select ENTER. Wait until you receive the following message:

   Field renamed.

To verify changes imported to a single project

1. In Team Explorer, choose Refresh.

   The latest updates are downloaded from the server, which include the changes that you just made to the field name. Wait several seconds for the refresh to finish.

2. Choose New Query to create a query.

3. In the Query Editor, choose the Click here to add a clause link to add a row, select the blank Field cell, and in the cell, enter Rank. The following message that appears above the results list. This message indicates that the Rank can't be found.

   Run the query to see the query results. TF51005: The query references a field that doesn't exist. The error is caused by <\<Rank>>.

4. Delete the value Rank from the Field cell, and enter Important Rank into the cell.

5. Select <> in the Operator cell, and enter 1 into the Value cell.

6. On the Query toolbar, choose Run.

7. Open the shortcut menu for any row in the results and select Column Options. Scroll down in the Available columns list. Notice that the Rank field is no longer present but the Important Rank field is present.

8. Select Important Rank in the Available columns box, and then choose the > button (add selected columns). Choose OK.

   Notice that the friendly name for Microsoft.VSTS.Common. Rank is renamed from Rank to Important Rank throughout the query builder and results list.

9. Close the query. Choose No when you're prompted to save the query.

10. Create a new Task work item. Choose the New Work Items link, and then choose Task.

    This work item is created from the work item type that you changed and imported.

11. Notice, in the Status box, that the label for the renamed field Rank didn't change. The field labels on the work item forms are scoped to the parent project and are independent of the server-wide field name specified.

    Note

    For more information about how to change field labels on work item forms, see Control XML element reference.

12. Close the new Task and choose No when you're prompted to save the work item.

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/tfs/DefaultCollection /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 aggregate by sum.

witadmin reportfield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:AdventureWorks.Field /reportingtype:measure  

Enable synchronization of a custom person-name field

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

Verify the data type of the field that you want to convert

Verify the data type assigned to the field, such as MyCompany.CustomerName, that you want to synchronize by entering the following command:

witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:MyCompany.CustomerName  

Enable synchronization

1. To enable synchronization for a person-named field, type the following command, substituting your data for the arguments that are shown here:

   witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:MyCompany.CustomerName /syncnamechanges:true  
   

2. The following confirmation prompt appears:

   This will change properties for field {0} on the Azure DevOps Server. Do you want to continue?

3. Enter 0 to confirm that you want to change the field, or 1 to cancel the request.

   If the change request succeeds, the following confirmation message appears:

   The field was updated.

   If the change request fails, an error message appears. The most common mistakes that can be made are trying to change a system reference field, or trying to change a field of a data type other than String. These operations aren't supported.

Delete a field

Before you delete a field, verify that the field isn't in use. If the field is in use, you must first remove the field from the work item types that use it before deleting it from the project collection. The following command deletes the field AdventureWorks.Field from Collection1:

witadmin deletefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:AdventureWorks.Field  

Verify a field isn't in use

1. Enter the following command, specifying the reference name for the work item field, such as MyCompany.MyProcess.MyField.

   witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:MyCompany.MyProcess.MyField  
   

   In the information displayed for the field, verify that the value for Use is "Not In Use" as follows in this example.

   Field: MyCompany.MyProcess.MyField  
   Name: MyField  
   Type: String  
   Reportable As: dimension  
   Use: Not In Use  
   Indexed: False  
   

2. If the Use field indicates that the field is in use, then you must delete it from each work item type for each project that is listed. For example, the Microsoft.VSTS.TCM.SystemInfo field indicates that it's being used by the Bug and Code Defect work item types for four projects: Arroyo, Desert, Palm, and Springs.

   Field: Microsoft.VSTS.TCM.SystemInfo  
   Name: System Info  
   Type: Html  
   Reportable As: None  
   Use: Arroyo (Bug), Desert (Bug), Palm (Bug), Springs (Bug, Code Defect)  
   Indexed: False  
   

   Before you can delete this field, you must remove it from each of the work item types listed for each project for which it's defined. To remove the field, you modify the definition for the work item type by deleting the FIELD and Control elements that contain the field reference name. See Import, export, and manage work item types, FIELD (Definition) element reference, and Control.

Delete a field from a project collection

Enter the following command to delete the MyCompany.MyProcess.MyField field, and then choose Enter.

witadmin deletefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:RefName  

Enter y at the confirmation prompt to complete this step.

Related articles

• Customizing your work tracking experience
• Work item field index
• witAdmin: Customize and manage objects for tracking work