Manage work item fields
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
Important
For the On-premises XML process model, you can use witadmin to list, import, export, and modify a process for a project. For the Inherited and Hosted XML process models, you can only use witadmin to list and export process information. For an overview of process models and what is supported, see Customize your work tracking experience.
You can manage the fields defined for work item types that are defined for a project collection (On-premises XML) by using the following witadmin commands. If you want to add a global field (valid for On-premises XML) you can do so by modifying the global workflow file and importing it to the collection.
changefield
: Changes one or more attributes of a field. When you change one of the following attributes, you change it for all work item types and projects within the project collection:Data type for
PlainText
orHTML
fields.Important
When you upgrade Team Foundation Server from an earlier version to the current version, the type assignment for the Description (System.Description) field is automatically converted from
PlainText
toHTML
. With thechangefield
command, you can restore the content of this field to display plain text.Friendly name that displays in the work item query. This name may differ from that displayed on the work item form.
Reporting attributes which includes the name of the field as it appears in a report, the reference report name, and the reporting type.
Synchronization with Active Directory - you can enable/disable synchronization of person name fields.
deletefield
: Deletes the specified field.listfields
: Lists the attributes for all fields or a specified field.
Note
The witadmin indexfield
command has been deprecated with Azure DevOps Server 2019 and later versions. Indexing fields is no longer required.
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.
Note
To connect to Azure DevOps Services, we recommend that you use the latest version of Visual Studio or Visual Studio Community.
Note
To connect to an on-premises server, we recommend that you use the same or later version of Visual Studio as your Azure DevOps Server. For example, if you connect to Azure DevOps Server 2019, then connect to your project from a version of Visual Studio 2019.
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.
Tip
With witadmin, you can import and export definition files. Other tools you can use include the Process Editor (requires that you have installed a version of Visual Studio). Install the Process Template editor from the Visual Studio Marketplace.
Prerequisites
- To list fields, you must have your View project-level information permission for the project in the collection set to Allow.
- To delete or rename fields or change an attribute of a field, you must be a member of the Team Foundation Administrators security group or the Project Collection Administrators security group.
For more information, see Change project collection-level permissions.
Note
Even if you sign in 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, choose Start, open the Command Prompt shortcut menu, and then choose Run as Administrator. For more information, see the Microsoft Web site: User Access Control.
Syntax
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
Parameter | Description |
---|---|
/collection :CollectionURL |
Specifies the URI of the project collection. For example: On-premises format: http://ServerName:Port/VirtualDirectoryName/CollectionName If no virtual directory is used, then use the following format: 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.- none: Used to disable reportability on the field.For more information, see About work item fields and attributes. |
/reportingformula:Formula |
Specifies the aggregation formula to be used when the field is reported as a measure . The only supported formula is sum . |
/type:HTML | PlainText |
Specifies to convert the contents of the field from PlainText to HTML or from HTML to PlainText . You can specify this option only for fields whose type assignment is PlainText or HTML . See FIELD (Definition) element reference. |
/unused |
Lists all fields that are not used by any project defined in the project collection. |
/noprompt |
Disables prompt for confirmation. |
/? or help |
Displays help about the command in the Command Prompt window. |
Synchronizing person names with Active Directory
You must manually enable synchronization of any custom work item fields that are used to assign person names that reference Active Directory. You must enable synchronization for each field for each project collection that contains the custom fields.
All system reference fields that show person-names have the attribute syncnamechanges
set to true
. Such fields include System.AuthorizedAs, System.AssignedTo, System.ChangedBy and System.CreatedBy. Synchronization in enabled for each person name field that is defined in one of the default process templates. For more information, see Assignments and workflow fields.
After synchronization is enabled, the field no longer shows a static string. Instead, the field shows the name associated with a user account. When you change the user name in Active Directory or in Workgroup, a field with syncnamechanges
set to true
automatically shows the new name.
When you assign the syncnamechanges
attribute to a String field, the field always accepts valid user names. However, the field doesn't 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 typesThe
VALIDUSER
rule is specified for a work item typeThe
ALLOWEDVALUES
rule is specified for a work item type, and that rule has a filter criteria that excludes groupsFor more information, see 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 are not 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 is not 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. Note that 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 may be different than the friendly name defined for the field.
To rename a work item field
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"
At the confirmation prompt type y and then press ENTER. Wait until you receive the following message:
Field renamed.
To verify changes imported to a single project
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.
Choose New Query to create a query.
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, type Rank. The following message that appears above the results list. This message indicates that the Rank cannot 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>>.
Delete the value Rank from the Field cell, and type Important Rank into the cell.
Select <> in the Operator cell, and type 1 into the Value cell.
On the Query toolbar, choose
Run.
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.
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 has been renamed from Rank to Important Rank throughout the query builder and results list.
Close the query. Choose No when you are prompted to save the query.
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.
Notice, in the Status box, that the label for the renamed field, Rank, has not changed. This is because the field labels on the work item forms are scoped to the parent project and are independent of the server-wide field name just specified.
Note
For more information about how to change field labels on work item forms, see Control XML element reference.
Close the new Task and choose No when you are 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 are aggregated 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
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
The following confirmation prompt appears:
This will change properties for field {0} on the Team Foundation Server. Do you want to continue?
Type 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 are not supported.
Delete a field
Before you delete a field, verify that the field is not in use. If the field is in use, you must first remove the field from the work item types that use it prior to 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 is not in use
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
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 is 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 is defined. To remove the field, you modify the definition for the work item type by deleting the
FIELD
andControl
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.