Working with Work Item Type Categories

You can define categories of work item types to help run queries and track information that may be similar but is assigned a different name. By using categories, an association is made between a work item type and the category. The work item type is tagged as belonging to a specific category.

Each category has a friendly name and a reference name that must be unique within the team project. For more information, see Naming Conventions for Work Item Tracking Objects.

Only team project administrators and Team Foundation administrators are authorized to modify categories.

Topic Contents

  • Syntax Structure

  • Categories Defined for MSF Process Templates

  • Filtering a Work Item List Based on a Category

Syntax Structure

A category is defined within the CATEGORIES set of CATEGORY elements that is stored and used by a team project. A category cannot be empty. Each CATEGORY element must define exactly one DEFAULTWORKITEMTYPE and zero or more WORKITEMTYPE elements.

To add a category to a project collection, you import the following syntax using the witadmin importcategories command-line tool:

<?xml version="1.0" encoding="utf-8" ?> 
<cat:WITCATEGORY version="1.0" xmlns:cat="">
   <CATEGORY name="Category Name" refname="Category Reference Name" >
      <DEFAULTWORKITEMTYPE name="MyCorp.Defect"/>
      <WORKITEMTYPE name="work item type name 1" />
      <WORKITEMTYPE name=" work item type name 2" />
      <WORKITEMTYPE name=" work item type name n" />

The names of each work item type that are specified for each DEFAULTWORKITEMTYPE and WORKITEMTYPE elements must correspond to work item types that are defined for the team project. When you import a categories file, you overwrite the contents that were previously imported.

Categories Defined for the MSF Process Templates

When you create a team project by using one of the Microsoft Solutions Framework (MSF) process templates, the following categories file is used to define four categories: Bug Category, Requirement Category, Shared Steps Category, and Test Case Category. You can use these specially designed categories to support interaction with Team Foundation work item tracking and Test Manager.

The contents of this file, as listed below, define the default work item types for each category:

<?xml version="1.0" encoding="utf-8"?>
<cat:CATEGORIES xmlns:cat="">
   <CATEGORY name="Bug Category" refname="Microsoft.BugCategory" >
      <DEFAULTWORKITEMTYPE name="Bug" />
   <CATEGORY refname="Microsoft.RequirementCategory" name="Requirement Category">
      <DEFAULTWORKITEMTYPE name="User Story" />
   <CATEGORY refname="Microsoft.SharedStepCategory" name="Shared Step Category">
      <DEFAULTWORKITEMTYPE name="Shared Steps" />
   <CATEGORY refname="Microsoft.TestCaseCategory" name="Test Case Category">
      <DEFAULTWORKITEMTYPE name="Test Case" />

Filtering a Work Item List Based on a Category

You can define a work item query that will filter the list based on all work items whose Work Item Type belongs to a selected category. You can use this query by using the In Group operator. For example, the following filter criteria will return all work items that are in the current team project, assigned to the team member, and defined as belonging to the Bug Category:






Team Project




Assigned To




Work Item Type

In Group

Bug Category

See Also


Create a Category for Types of Work Items


Categories Definition Schema Reference

Customizing Categories for Work Item Types [witadmin]


All WITD XML Elements Reference

Customizing Project Tracking Data, Forms, Workflow, and Other Objects

Other Resources

Grouping Work Item Types into Categories