witAdmin: Customize and manage objects for tracking work
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018 - TFS 2013
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 change how you track your team's progress by creating and customizing objects that track work items. By using the witadmin command-line tool, you can create, delete, import, and export objects such as categories, global lists, global workflow, types of links, and types of work items. You can also delete, list, or change the attributes of work item fields.
In addition, for on-premises Azure DevOps Servers, you can manage the resolution types, bug, and failure types used with test case management with the tcm fieldmapping command.
As the following illustration shows, you manage categories and types of and work items for each project. You manage global lists, types of links, and fields in work item for each project collection. You can customize global workflow for a project or a collection.
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 TFS Process Template editor from the Visual Studio Marketplace. You can use this version of the Process Editor to modify the old-style work item forms. You can't use it to edit forms associated with the new web forms.
Or, you can use the TFS Team Project Manager, an open-source client available from GitHub.
For most commands, you must be a member of the Project Administrators or Project Collection Administrators groups. For more information, see Change project collection-level permissions.
How to 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
If you are connecting to an on-premises server, you must use the same or later version of Visual Studio or Team Explorer as Azure DevOps Server. For example, if you connect to a TFS 2017 instance, you must connect from Visual Studio 2017 or Team Explorer 2017. There is no Team Explorer 2015 version.
Visual Studio 2017 or Team Explorer 2017 client:
%programfiles(x86)%\Microsoft Visual Studio\2017\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer
or, TeamExplorer, Professional or Enterprise in place of Community, depending on the version you've 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.
Global parameters
You can use the following parameters to display help text for witadmin.
| Parameter | Description |
|---|---|
| /help or /? |
Displays the syntax and parameters for the witadmin command-line tool. |
| command /help or command /? |
Displays the syntax and parameters for the witadmin command that you specify. |
XML definition files
You customize all work tracking objects—such as, work item types, process configuration, global lists—by updating their XML definitions. If you're new to work tracking customization, see Customize your work tracking experience.
You run witadmin commands against Azure DevOps Services or an on-premises Azure DevOps Server. As shown in the command lists below, only witadmin commands that list or export files are supported for the Azure DevOps Services.
Work item types
Work items are used to track anything you need to track. Each work item is based on a work item type. Each work item types defines the fields available in which to store information. The available work item types depend on the process you used when your project was created (Agile, Scrum, Basic, or CMMI). To learn more, see Track your work items in Azure Boards user stories, issues, bugs, features, and epics.
For the Inherited process model, you can add and delete work item types from the web portal. To learn how, see Add and manage work item types(Inheritance process).
Command
Azure DevOps Services
Azure DevOps Server
destroywitd: Delete a work item type
✔️
exportwitd: Export a work item type file
✔️
✔️
importwitd: Import a work item type file
✔️
listwitd: List work item types
✔️
✔️
renamewitd: Change the display name for a work item type
✔️
Fields
Fields are used to track the status and information associated with work items. Fields are defined for an organization or collection. To learn more about fields, see Work item fields and attributes. To look up the description of a specific field, see Field descriptions for default and work item fields used in process templates.
For the Inherited process model, you can view and delete fields from the web portal. To learn how, see Add and manage fields (Inheritance process).
Command
Azure DevOps Services
Azure DevOps Server
deletefield: Delete a field
✔️
listfields: List field attributes
✔️
✔️
indexfield: Turn field indexing on/off
✔️
changefield: Change a field attribute
✔️
renamewitd: Change a WIT display name
✔️
Categories
Categories associate one or more work item types as belonging to the same category. Azure Boards relies on default category definitions, many of which specify a single work item type per category. To learn about categories and how they are used, see Use categories to group work item types.
Command
Azure DevOps Services
Azure DevOps Server
exportcategories: Export the Categories file
✔️
✔️
importcategories: Import the Categories file
✔️
Link types
You use different link types to manage the various relationships between work items. For On-premises XML and Hosted XML process models, you can define custom link types. To learn more about default link types, see Manage dependencies, link work items and Reference guide for link types.
Command
Azure DevOps Services
Azure DevOps Server
deletelinktype: Delete a link type
✔️
exportlinktype: Export a link type file
✔️
✔️
importlinktype: Import a link type file
✔️
listlinktypes: List the defined link types
✔️
✔️
reactivatelinktype: Reactivate or rename a link type
✔️
Global lists
Global lists are pick lists that you can include within one or more fields and work item type definitions. You can share list items among several work item types for a collection of projects by including the list items in one or more GLOBALLIST elements. To learn more, see GLOBALLIST XML element reference.
Command
Azure DevOps Services
Azure DevOps Server
destroygloballist: Delete a global list
✔️
exportgloballist: Export the global list
✔️
✔️
importgloballist: Import the global list
✔️
listgloballist: List all global list names
✔️
✔️
Global workflow
With global workflow, you can define and update fields and global lists that apply to all work item types in a project or collection. To learn more, see Global workflow XML element reference.
Command
Azure DevOps Services
Azure DevOps Server
exportglobalworkflow: Export the global workflow file
✔️
importglobalworkflow: Import the global workflow file
✔️
Process configuration
Process configuration defines the default configuration and functional capabilities that your teams can access using Azure Boards. The configuration determines the work item types that appear on the product backlog, sprint backlogs, Kanban board, and task board. To learn about process configuration and what you can customize, see ProcessConfiguration.
For the Inherited process model, you can customize backlogs from the web portal. To learn how, see Customize your backlogs or boards (Inheritance process).
Command
Azure DevOps Services
Azure DevOps Server
exportprocessconfig: Export the ProcessConfiguration file
✔️
✔️
importprocessconfig: Import the ProcessConfiguration file
✔️
Work items
The following witadmin command is only available for TFS 2018.1 and earlier versions. It has been deprecated for TFS 2018.2 and later versions. To learn more about how to permanently delete work items for later versions, see Remove, delete, or restore work items.
- destroywi: Permanently delete work items
Client cache
After certain maintenance operations, client computers require a cache refresh. After you move, restore, rename, or fail over a data-tier or application-tier server, you must refresh the cache for tracking work items and users must refresh the version control cache on client computers.
The following witadmin command is only available for Azure DevOps Server on-premises.
- rebuildcache: Rebuild the client cache
Test case management field mapping
To customize the resolution types, bug work item type, and failure types used when working with Azure Test Plans, you can use the following tcm command. This command is only available for Azure DevOps Server on-premises versions.
- tcm fieldmapping: Import or export a file that defines the resolution types, bug, or failure types to use with test case management.