Add type definitions for work items to a process template

Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018 - TFS 2013

Work item types (WITs) provide the foundation for all tracking, monitoring, and reporting on the development of a product and its features. A WIT defines the data fields, the workflow, and the work item form for an item of work that you will track. Types of work items include bugs, user stories, and tasks.

When you customize a process template, you can make the following WIT customizations:

• Add fields
• Customize the workflow
• Modify the work item form
• Add or remove WITs

You specify the type definitions for a process template for several work items as a task within the WorkItemTracking plug-in. This task is required because work item types support tracking and reporting work. You specify each type definition file to upload within the taskXml element. The plug-ins for test management, reports, and the portal depend on the successful upload of the definitions for WITs.

The default process templates define several WITs. The types and the fields that are defined within them are referenced in the definitions of categories, work item queries, and reports. Therefore, the task to upload the WIT definitions must successfully complete before the tasks to upload categories, work item queries, and reports.

Also, the task to upload the definition files for link types must precede the task to upload the type definitions for WITs. For more information, see Define dependencies for task groups and tasks.

After a project is created using the process template, you can add, remove, rename, and change the definitions of WITs by using the witadmin command-line tool. For more information, see Import, export, and manage work item types.

Define a WIT

Each WIT definition must be specified in its own file in the WITD container element. Each definition must also conform to the schema definition for work item types.

The following example shows the high-level syntax structure that defines a work item type.

<WITD application="work item type editor" version="1.0">  
    <WORKITEMTYPE name="Bug">  
        <DESCRIPTION>Bug work items are used to track defects in the code.</DESCRIPTION>  
        <GLOBALLISTS> . . . </GLOBALLISTS>  
        <FIELDS> . . . </FIELDS>  
        <WORKFLOW> . . . </WORKFLOW>  
        <FORM> . . . </FORM>  
    </WORKITEMTYPE>  
</WITD>  

You can customize or create type definition files in the TypeDefinitions folder. For more information about how to define a type of work item, see All WITD elements.

Specify WIT definition files to upload

To upload a WIT definition, you specify the WORKITEMTYPE element. The filename attribute is a relative path of the type definition file. For example, the following syntax specifies that the Bug.xml file will be uploaded.

<WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\filename.xml"/>  

The following example shows how to specify a task that creates the following WITS: bug, issue, shared steps, task, test case, and user story. Because the definitions for several WITs contain filters for the TestedBy link type, the LinkTypes task must be completed before the WITs task can be completed.

<task id="WITs" name="WorkItemType definitions" plugin="Microsoft.ProjectCreationWizard.WorkItemTracking" completionMessage="Work item types created">  
      <dependencies>  
      <dependency taskId="LinkTypes" />  
      </dependencies>  
      <taskXml>  
      <WORKITEMTYPES>  
       <WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\Bug.xml" />  
       <WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\Issue.xml" />  
       <WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\CodeReviewRequest.xml" />  
        <WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\CodeReviewResponse.xml" />  
        <WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\Feature.xml" />  
        <WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\FeedbackRequest.xml" />  
        <WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\FeedbackResponse.xml" />   
        <WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\SharedStep.xml" />  
       <WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\Task.xml" />  
       <WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\TestCase.xml" />  
       <WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\UserStory.xml" />  
      </WORKITEMTYPES>  
      </taskXml>  
</task>  

WORKITEMTYPES element reference

The following table describes the elements that you use to upload the type definitions for work items. You specify these elements within a taskXml container element in the WorkItemTracking plug-in file.

Related articles

• All WITD elements
• Modify a field or add a custom field
• Add or modify a work item type
• Import, export, and manage work item types
• Define objects for tracking work items