Work Item Type Categories Element Reference

  • Article

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.

In addition, several features such as the Agile planning tools and My Work Categories use categories to configure process operations. Before you modify a category file, review the information provided in Customize the Backlog and Board Pages Using Process Configuration.

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.

In this topic

  • Syntax structure

  • Categories defined with a default process template

  • Filtering a query 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:CATEGORIES xmlns:cat="https://schemas.microsoft.com/VisualStudio/2008/workitemtracking/categories">
   <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" />
   </CATEGORY>
   . . . 
</cat:CATEGORIES>

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 with a default process template

When you create a team project by using one of the default process templates provided with the latest version of Team Foundation Server, the following categories are defined, all of which are required to support features used by Visual Studio ALM and Test Manager:

  • Bug Category

  • Code Review Request Category and Code Review Response Category

  • Feedback Request Category and Feedback Response Category

  • Requirement Category

  • Shared Step Category

  • Task Category

  • Test Case Category

  • Hidden Types Category

Most of these categories are self-explanatory, and most contain only one work item type within the category. The Hidden Types Category specifies the set of work item types that you do not want users to create manually. These type definitions are used to support the feedback and code review experiences, as well as the definition of test cases.

The following example lists the contents of the default category definition file for the Visual Studio Scrum process template.

<?xml version="1.0" encoding="utf-8"?>
<cat:CATEGORIES xmlns:cat="https://schemas.microsoft.com/VisualStudio/2008/workitemtracking/categories">
<!-- Usage: for resilience in Test system. Even if WITs have different name, they can be referred to by the category -->
   <CATEGORY name="Bug Category" refname="Microsoft.BugCategory" >
      <DEFAULTWORKITEMTYPE name="Bug" />
   </CATEGORY>
   <CATEGORY name="Requirement Category" refname="Microsoft.RequirementCategory">
      <DEFAULTWORKITEMTYPE name="Product Backlog Item" />
      <WORKITEMTYPE name="Bug" />
   </CATEGORY>
   <CATEGORY name="Test Case Category" refname="Microsoft.TestCaseCategory">
      <DEFAULTWORKITEMTYPE name="Test Case" />
   </CATEGORY>
   <CATEGORY name="Shared Step Category" refname="Microsoft.SharedStepCategory">
      <DEFAULTWORKITEMTYPE name="Shared Steps" />
   </CATEGORY>
   <CATEGORY name="Code Review Request Category" refname="Microsoft.CodeReviewRequestCategory">
      <DEFAULTWORKITEMTYPE name="Code Review Request" />
   </CATEGORY>
   <CATEGORY name="Code Review Response Category" refname="Microsoft.CodeReviewResponseCategory">
      <DEFAULTWORKITEMTYPE name="Code Review Response" />
   </CATEGORY>
   <CATEGORY name="Feedback Request Category" refname="Microsoft.FeedbackRequestCategory">
      <DEFAULTWORKITEMTYPE name="Feedback Request" />
   </CATEGORY>
   <CATEGORY name="Feedback Response Category" refname="Microsoft.FeedbackResponseCategory">
      <DEFAULTWORKITEMTYPE name="Feedback Response" />
   </CATEGORY>
   <CATEGORY name="Task Category" refname="Microsoft.TaskCategory">
      <DEFAULTWORKITEMTYPE name="Task" />
   </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>
</cat:CATEGORIES>

Filtering a query 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:

And/Or

Field

Operator

Value

 

Team Project

=

@Project

And

Assigned To

=

@Me

And

Work Item Type

In Group

Bug Category

See Also

Reference

Categories Definition Schema Reference

Customizing Categories for Work Item Types [witadmin]

Concepts

All WITD XML Elements Reference

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

Other Resources

Define Categories to Group Work Item Types