This documentation is archived and is not being maintained.

Customizing Categories for Work Item Types [witadmin]

You can manage the categories for work item types defined for a team project by using the following witadmin commands:

  • exportcategories:  Exports the XML definition of categories defined on a server that runs Team Foundation Server.

  • importcategories:  Imports a work item type XML definition file into a team project on a server that runs Team Foundation Server. 

    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.

The witadmin command-line utility is located in Drive:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE on the client computer that runs Team Explorer.

NoteNote

You can create and modify categories by using Process Editor, a power tool for Visual Studio. This power tool is not supported. For more information, see the following page on the Microsoft Web site: Team Foundation Server Power Tools April 2010.

Required Permissions

For the team project where the work item types are defined, you must have the following permissions set:

  • To export categories of work item types, you must be a member of the Readers group or have your View work items in this node permission set to Allow

  • To import categories of work item types, you must be a member of the Team Foundation Administrators security group or the Project Administrators security group.

For more information, see Team Foundation Server Permissions and Team Foundation Server Default Groups, Permissions, and Roles.

NoteNote

Even if you log on 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, click Start, right-click Command Prompt, and click Run as Administrator. For more information, see the Microsoft Web site: User Account Control.

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

Parameter

Description

/collection:CollectionURL

Specifies the URI of the team project collection. The format for the URI is the following: 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 team 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.

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.

For information about the categories XML file structure, see Categories Definition Schema Reference.

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

  • URI for the team project collection: http://AdventureWorksServer:8080/AWTeam/Collection1

  • Project name: AdventureWorks

  • Input or output file name: myCategories.xml

  • Default encoding: UTF-8

List Work Item Type Categories

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

witadmin exportcategories /collection:http://AdventureWorksServer:8080/AWTeam/Collection1 /p:AdventureWorks 

Export Work Item Type Categories

The following command exports the work item type categories defined for the AdventureWorks project to the myCategories XML file.

witadmin exportcategories /collection:http://AdventureWorksServer:8080/AWTeam/Collection1 /p:AdventureWorks /f:myCategories.xml 

Import Work Item Type Categories

The following example imports categories from the myCategories XML file to the AdventureWorks project.

witadmin importcategories /collection:http://AdventureWorksServer:8080/AWTeam/Collection1 /p:AdventureWorks /f:myCategories.xml 
Show: