| title | titleSuffix | description | ms.service | ms.custom | ms.assetid | ms.topic | ms.author | author | monikerRange | ms.date |
|---|---|---|---|---|---|---|---|---|---|---|
witAdmin Customize and manage objects for tracking work |
Azure DevOps |
Tracks your team's progress by creating and customizing objects that track work items. |
azure-devops-boards |
witadmin, engagement-fy23 |
7853f6db-98c9-4012-b6a5-51618c41d58c |
reference |
chcomley |
chcomley |
<= azure-devops |
11/13/2023 |
[!INCLUDE version-lt-eq-azure-devops-plus-witadmin]
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.
::: moniker range="< azure-devops"
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.
::: moniker-end
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.
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.
[!INCLUDE temp]
You can use the following parameters to display help text for witadmin.
| Parameter | Description |
|---|---|
/? or help |
Displays the syntax and parameters for the witadmin command-line tool. |
command /helpor command /? |
Displays the syntax and parameters for the witadmin command that you specify. |
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 following command lists, only witadmin commands that list or export files are supported for the Azure DevOps Services.
Work items are used to track anything you need to track. Each work item is based on a work item type. Each work item type 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). For more information, 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. For more information, see Add and manage work item types (Inheritance process).
:::row::: :::column span="2"::: Command :::column-end::: :::column span="1"::: Azure DevOps Services :::column-end::: :::column span="1"::: Azure DevOps Server :::column-end::: :::row-end:::
:::row:::
:::column span="2":::
destroywitd: Delete a work item type
:::column-end:::
:::column span="1":::
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::row-end:::
:::row:::
:::column span="2":::
exportwitd: Export a work item type file
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::row-end:::
:::row:::
:::column span="2":::
importwitd: Import a work item type file
:::column-end:::
:::column span="1":::
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::row-end:::
:::row:::
:::column span="2":::
listwitd: List work item types
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::row-end:::
:::row:::
:::column span="2":::
renamewitd: Change the display name for a work item type
:::column-end:::
:::column span="1":::
Fields are used to track the status and information associated with work items. Fields are defined for an organization or collection. For more information, 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. For more information, see Add and manage fields (Inheritance process).
:::row::: :::column span="2"::: Command :::column-end::: :::column span="1"::: Azure DevOps Services :::column-end::: :::column span="1"::: Azure DevOps Server :::column-end::: :::row-end:::
:::row:::
:::column span="2":::
deletefield: Delete a field
:::column-end:::
:::column span="1":::
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::row-end:::
:::row:::
:::column span="2":::
listfields: List field attributes
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::row-end:::
:::row:::
:::column span="2":::
changefield: Change a field attribute
:::column-end:::
:::column span="1":::
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::row-end:::
:::row:::
:::column span="2":::
renamewitd: Change a WIT display name
:::column-end:::
:::column span="1":::
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. For more information, see Use categories to group work item types.
:::row::: :::column span="2"::: Command :::column-end::: :::column span="1"::: Azure DevOps Services :::column-end::: :::column span="1"::: Azure DevOps Server :::column-end::: :::row-end:::
:::row:::
:::column span="2":::
exportcategories: Export the Categories file
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::row-end:::
:::row:::
:::column span="2":::
importcategories: Import the Categories file
:::column-end:::
:::column span="1":::
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. For more information, see Link work items to other objects and Reference guide for link types.
:::row::: :::column span="2"::: Command :::column-end::: :::column span="1"::: Azure DevOps Services :::column-end::: :::column span="1"::: Azure DevOps Server :::column-end::: :::row-end:::
:::row:::
:::column span="2":::
deletelinktype: Delete a link type
:::column-end:::
:::column span="1":::
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::row-end:::
:::row:::
:::column span="2":::
exportlinktype: Export a link type file
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::row-end:::
:::row:::
:::column span="2":::
listlinktypes: List the defined link types
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::row-end:::
:::row:::
:::column span="2":::
reactivatelinktype: Reactivate or rename a link type
:::column-end:::
:::column span="1":::
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. For more information, see GLOBALLIST XML element reference.
:::row::: :::column span="2"::: Command :::column-end::: :::column span="1"::: Azure DevOps Services :::column-end::: :::column span="1"::: Azure DevOps Server :::column-end::: :::row-end:::
:::row:::
:::column span="2":::
destroygloballist: Delete a global list
:::column-end:::
:::column span="1":::
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::row-end:::
:::row:::
:::column span="2":::
exportgloballist: Export the global list
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::row-end:::
:::row:::
:::column span="2":::
importgloballist: Import the global list
:::column-end:::
:::column span="1":::
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::row-end:::
:::row:::
:::column span="2":::
listgloballist: List all global list names
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::row-end:::
::: moniker range="< azure-devops"
With global workflow, you can define and update fields and global lists that apply to all work item types in a project or collection. For more information, see Global workflow XML element reference.
:::row::: :::column span="2"::: Command :::column-end::: :::column span="1"::: Azure DevOps Services :::column-end::: :::column span="1"::: Azure DevOps Server :::column-end::: :::row-end:::
:::row:::
:::column span="2":::
exportglobalworkflow: Export the global workflow file
:::column-end:::
:::column span="1":::
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::row-end:::
:::row:::
:::column span="2":::
importglobalworkflow: Import the global workflow file
:::column-end:::
:::column span="1":::
::: moniker-end
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, boards, and Taskboards. For more information about process configuration and what you can customize, see Process Configuration.
For the Inherited process model, you can customize backlogs from the web portal. For more information, see Customize your backlogs or boards (Inheritance process).
:::row::: :::column span="2"::: Command :::column-end::: :::column span="1"::: Azure DevOps Services :::column-end::: :::column span="1"::: Azure DevOps Server :::column-end::: :::row-end:::
:::row:::
:::column span="2":::
exportprocessconfig: Export the ProcessConfiguration file
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::column span="1":::
✔️
:::column-end:::
:::row-end:::
:::row:::
:::column span="2":::
importprocessconfig: Import the ProcessConfiguration file
:::column-end:::
:::column span="1":::
::: moniker range="< azure-devops"
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
::: moniker-end
::: moniker range="< azure-devops"
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.
::: moniker-end
::: moniker range="azure-devops"
::: moniker-end
::: moniker range=">= azure-devops-2019 < azure-devops"
::: moniker-end