Import and export categories

  • Article

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 import and export categories defined for a project by using the following witadmin commands:

  • exportcategories: Exports the XML definition of categories defined for a project.
  • importcategories: Imports a work item type XML definition file into a project. If a category with the same name already exists, this command overwrites the existing definition. If the work item type does not already exist, this command creates a new category.

To learn about the default categories and how they are used, see Use categories to group work item types.

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.

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.

Prerequisites

For the project for which the categories are defined, you must have the following permissions set:

  • To export categories of work item types, you must have your View project-level information permission set to Allow.
  • To import categories of work item types, you must be a member of the Project Administrators security group or have the Edit project-level information permission set to Allow.

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

Syntax

witadmin exportcategories /collection:CollectionURL /p:Project [/f:FileName] [/e:Encoding]   
  
witadmin importcategories /collection:CollectionURL /p:Project /f:FileName [/e:Encoding]

Parameters

Parameter Description
/collection:CollectionURL Specifies the URI of the project collection. For example:

On-premises TFS format: http://ServerName:Port/VirtualDirectoryName/CollectionName

If no virtual directory is used, then the format for the URI is the following: http://ServerName:Port/CollectionName.
/p:Project The name of the project from which the categories are exported or to which the categories are imported.
/f:FileName The path and file name of the XML definition file that contains the categories to be exported or imported. If you omit this parameter when you use the exportcategories command, the command lists the categories in the Command Prompt window.
/e:Encoding The name of a .NET Framework 2.0 encoding format. The specified encoding will be used to export or import the XML data. For example, /e:utf-7 specifies Unicode (UTF-7) encoding. If you omit this parameter, witadmin attempts to detect the encoding, and if detection fails, witadmin uses UTF-8.
/? or help Displays help about the command in the Command Prompt window.

Remarks

Importing a categories file creates the categories if they do not already exist. If categories already exist, the witadmin importcategories command will warn you that the current list will be overwritten. You can write your own program to update an existing set of categories, or you can update the categories yourself with new data.

Important

Changes you make to categories can impact process configuration. See ProcessConfiguration XML elements.

For information about the categories XML file structure, see Categories XML element reference.

Examples

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

  • URI for the project collection: http://AdventureWorksServer:8080/tfs/DefaultCollection
  • Project name: AdventureWorks
  • Input or output file name: myCategories.xml
  • Default encoding: UTF-8

List categories

The following command lists the work item type categories defined for the AdventureWorks project.

witadmin exportcategories /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /p:AdventureWorks

Add a category to the Hidden Types categories

You add a category to the Hidden Types categories to remove support for users to create work item types in that category.

  1. Export the definition file for categories for your project.

    witadmin exportcategories /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /p:AdventureWorks /f:myCategories.xml

  2. Open the Categories file in your preferred text editor, and locate the CATEGORY element for the "Hidden Types Category".

    <CATEGORY name="Hidden Types Category" refname="Microsoft.HiddenCategory">  
   <DEFAULTWORKITEMTYPE name="Code Review Request" />  
   <WORKITEMTYPE name="Code Review Response" />  
   <WORKITEMTYPE name="Feedback Request" />  
   <WORKITEMTYPE name="Feedback Response" />  
   <WORKITEMTYPE name="Shared Steps" />  
</CATEGORY>

  3. Add a WORKITEMTYPE element that specifies the friendly name of the work item type that you want to add.

    For example, the following syntax adds the custom work item type of "Integration Build" to the Hidden Types Category.

    <CATEGORY name="Hidden Types Category" refname="Microsoft.HiddenCategory">  
   <DEFAULTWORKITEMTYPE name="Code Review Request" />  
   <WORKITEMTYPE name="Code Review Response" />  
   <WORKITEMTYPE name="Feedback Request" />  
   <WORKITEMTYPE name="Feedback Response" />  
   <WORKITEMTYPE name="Shared Steps" />  
   <WORKITEMTYPE name="Integration Build" />  
</CATEGORY>

  4. Import the definition file for categories to your project.

    witadmin importcategories /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /p:AdventureWorks /f:myCategories.xml