All WITD XML elements reference

Last Update: 2/9/2017

Team Services (Hosted XML) | TFS 2017 | TFS 2015


This topic applies to team project customization for Hosted XML and On-premises XML process models. For the Inheritance process model, see Customize a process.

For an overview of process models, see Customize your work tracking experience.

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.

WITD syntax structure

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>  
        <GLOBALLISTS> . . . </GLOBALLISTS>  
        <FIELDS> . . . </FIELDS>  
        <WORKFLOW> . . . </WORKFLOW>  
        <FORM> . . . </FORM>  

WITD child elements

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"
   . . .


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 (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 (refname): 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.


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.

Note: 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. Define global lists supports cross-group collaboration and ease of maintenance.

<GLOBALLIST name="globalListName">


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>


Specifies the design of the work item form by defining the fields and controls that appear on the form and in what order.

For TFS 2015 and earlier versions, the FORM element contains Layout, Control, Group, TAB, TabGroup, Splitter, and other elements.

   <Layout> . . . </Layout>

For the Hosted XML and On-premises XML (TFS 2017 and later versions) process models, the FORM element contains WebLayout, Control, SystemControls, Section, Page, and other elements.

               <Control> . . . </Control>
               <Control> . . . </Control>
. . .
For the Hosted XML and On-premises XML process models (TFS 2017 and later versions), see WebLayout and Control elements.

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>

Process template work item types

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

For TFS 2017:

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

For TFS 2015:

%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 Modify or add a custom work item type.