All WITD XML elements reference
Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018 - TFS 2013
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 project, such as a bug, requirement, or risk. You create a project either in Azure DevOps Services or 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 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 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="http://schemas.microsoft.com/VisualStudio/2008/workitemtracking/typedef">
<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>
</WORKITEMTYPE>
</witd:WITD>
WITD child elements
The structural elements used in the previous example are described in the following table:
Element
Description
WITD
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" >
<WORKITEMTYPE>
. . .
</WORKITEMTYPE>
</witd:WITD>
WORKITEMTYPE
Names of WITs must be unique in a specific 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" >
<DESCRIPTION>Text</DESCRIPTION>
<GLOBALLISTS> . . .</GLOBALLISTS>
<FIELDS> . . . </FIELDS>
<WORKFLOW> . . . </WORKFLOW>
<FORM> . . .</FORM>
</WORKITEMTYPE>
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 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.
DESCRIPTION
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.
<DESCRIPTION> DescriptionOfWorkItemType</DESCRIPTION>
You specify a string of text that describes the type of work item that you are defining.
GLOBALLISTS
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 project collection. Define global lists to support cross-group collaboration and ease of maintenance.
<GLOBALLIST name="globalListName">
<LISTITEM> . . . </LISTITEM>
</GLOBALLIST>
FIELDS
Defines the fields used to track data for the WIT. Within 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.
<FIELDS>
<FIELD> . . . </FIELD>
</FIELDS>
FORM
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.
<FORM>
<Layout> . . . </Layout>
</FORM>
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.
<WebLayout>
<Page>
<Section>
<Group>
<Control> . . . </Control>
<Control> . . . </Control>
</Group>
</Section>
</Page>
. . .
</WebLayout>
Important
For the Hosted XML and On-premises XML process models (TFS 2017 and later versions), see WebLayout and Control elements.
WORKFLOW
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.
<WORKFLOW>
<STATES> . . . </STATES>
<TRANSITIONS> . . . </TRANSITIONS>
</WORKFLOW>
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%/TFS 15.0/Tools/Deploy/ProcessTemplateManagerFiles/1033
For TFS 2015:
%programfiles%/TFS 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.