witAdmin: Customize and manage objects for tracking work

TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013

Important

With witadmin, you can modify XML definition files to support the On-premises XML process model. For Hosted XML and Inheritance process models, you can only use witadmin commands to list 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 permanently delete types of work item types, and you can delete, list, or change the attributes of fields in work item.

As the following illustration shows, you manage categories and types of and work items for each team project. You manage global lists, types of links, and fields in work item for each team project collection. You can customize global workflow for a team project or a collection.

Work Item Tracking Objects

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):

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 Add an administrator.

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 TFS, you must use the same version of Visual Studio or Team Explorer as TFS. 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.

TFS 2018 and TFS 2017

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.

TFS 2015

Visual Studio 2015 client:

cd %programfiles(x86)%\Microsoft Visual Studio 14.0\Common7\IDE

TFS 2013

Visual Studio 2013 client:

cd %programfiles(x86)%\Microsoft Visual Studio 12.0\Common7\IDE

Team Explorer 2013 client:

cd %programfiles%\Microsoft Visual Studio 12.0\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer

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.

witadmin commands

All work tracking objects—such as, work item types (WITs), process configuration, global lists— are customized by their XML definitions.

All witadmin commands can be run against an on-premises TFS. You can run list and export witadmin commands against a VSTS account. If you are new to work tracking customization and for definitions of the work tracking objects your can customize, see Customize your work tracking experience.

Work item types

  • destroywitd: Delete a WIT
  • exportwitd: Export a WIT file
  • importwitd: Import a WIT file
  • listwitd: List WIT names
  • renamewitd: Change a WIT display name

Fields

  • deletefield: Delete a field
  • listfields: List field attributes
  • indexfield: Turn field indexing on/off
  • changefield: Change a field attribute

Process configuration

  • exportprocessconfig: Export the ProcessConfiguration file
  • importprocessconfig: Import the ProcessConfiguration file
  • 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

  • destroygloballist: Delete a global list
  • exportgloballist: Export the global list
  • importgloballist: Import the global list
  • listgloballist: List all global list names

Global workflow

  • exportglobalworkflow: Export the global workflow file
  • importglobalworkflow: Import the global workflow file

Work items

  • witadmin destroywi: Permanently delete work items

Client cache

  • rebuildcache: Rebuild the client cache

Categories

  • exportcategories: Export the Categories file
  • importcategories: Import the Categories file