All WITD XML elements reference


Updated: July 15, 2016

You can customize an existing work item type (WIT) or create a WIT to meet your project tracking requirements. A WIT defines the fields, rules, and workflow states and transitions for an item of work that will be tracked for a team project, such as a bug, requirement, or risk. You create a team project either in Visual Studio Team Services or on an on-premises Team Foundation Server (TFS).

The root element in each definition of a WIT is the WITD element, which must have only one WORKITEMTYPE element defined. The name of each WIT must be unique in a team project, and each type name must be no more than 128 Unicode characters long.

To customize or create a WIT definition, you modify the type definition XML file. WITs are scoped to a team project within a project collection.

The following example shows the high-level structure of a WIT definition.

<witd:WITD application="Work item type editor" version="1.0" xmlns:witd="">
    <WORKITEMTYPE name="bug" refname="Microsoft.VSTS.WorkItemTypes.Bug">
        <DESCRIPTION> Describes a divergence between required and actual behavior, and tracks the work done to correct the defect and verify the correction.</DESCRIPTION>
        <FIELDS> . . . </FIELDS>
        <WORKFLOW> . . . </WORKFLOW>
        <FORM> . . . </FORM>

The structural elements used in the previous example are described in the following table:




The complete WIT definition is wrapped by the tag WITD. You can use any name for the application name. The version identifies the WIT schema that may change from one release to the next. Use "1.0".

<witd:WITD application="Work item type editor" version="1.0" xmlns:witd="">


Names of WITs must be unique in a specific team project. At run time, you use the name specified by this element. For example, the name can appear as a menu option. In this case, a user could choose Bug on the New Work Item menu.

<WORKITEMTYPE name="WorkItemTypeName" refname="WITReferenceName" >
    <FIELDS> . . . </FIELDS>
    <WORKFLOW> . . . </WORKFLOW>
    <FORM> . . .</</FORM>

Friendly name: This name appears in the drop-down menus of work item queries. The friendly name must be unique across all WIT names that are defined within a team project. Specify a name no longer than 128 Unicode characters that uses alphanumeric, underscore, and hyphen characters.

Reference name: Specify a name no longer than 70 Unicode characters that uses alphanumeric, underscore, and hyphen characters. The reference name must contain at least one period (.), but no period can appear at the start or end of a name. Also, the reference name cannot start with a number or an underscore, and it cannot have multiple consecutive hyphens, such as (--).

Do not specify a name that overlaps with the reserved System. XXX and Microsoft. XXX namespaces. See Naming conventions for work item tracking objects.


Specifies a string that describes the type of work item that you are defining. The description should help any user who is customizing the WIT.


You can view the description only in the XML definition. You cannot view the description anywhere in the user interface, and it has no relationship to the field System.Definition.


You specify a string of text that describes the type of work item that you are defining.


Contains the global list definitions that are used by the WIT. You use global lists to share pick lists among multiple WITs defined for a team project collection. Using global lists supports cross-group collaboration and ease of maintenance.

<GLOBALLIST name="globalListName">
    <LISTITEM> . . . </LISTITEM>


Defines the fields used to track data for the WITWithin the FIELDS element, you define all the fields that you want to use to track data. This includes fields that you will use to run queries and generate reports.

   <FIELD> . . . </FIELD>


Defines the workflow elements that help track the work item status as it moves from a new state to closed or done. This element contains the set of STATE and TRANSITION elements that define the workflow. The workflow is a set of valid transitions from one state to another and the specific conditions associated with each transition.

   <STATES> . . . </STATES>


Specifies the design of the work item form by defining the fields and controls that appear on the form and in what order. It contains LAYOUT, CONTROL, GROUP, TAB, TABGROUP, SPLITTER, and other elements.

   <Layout> . . . </Layout>

Upon installing or upgrading an instance of TFS, the default process templates are downloaded to the following directory:

%programfiles%/Microsoft Team Foundation Server 14.0/Tools/Deploy/ProcessTemplateManagerFiles/1033

WIT definition files are stored in the WorkItem Tracking\TypeDefinitions folder.

To learn how to create or customize a WIT, see Customize work tracking objects to support your team's processes. To add a new WIT to your process template. see Add type definitions for work items to a process template.