Add and manage work item types
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
You can add custom work item types (WITs) or modify existing WITs to add fields, remove or hide fields, add custom rules, and more. For example, you may want to capture customer issues in a custom Ticket WIT.
This article applies to Azure DevOps Services and Azure DevOps Server 2019 and later versions. To customize any project defined on a collection for TFS 2018 or earlier, see On-premises XML process model.
You can only use the Inheritance process model for projects defined on a project collection configured to support the Inheritance process model. If your on-premises collection is configured to use the On-premises XML process model, you can only use that process model to customize the work tracking experience. To learn more, see Customize work tracking, Choose the process model for your project collection.
To customize any project defined on a collection for TFS 2018 or earlier, see On-premises XML process model.
Prior to customizing a process, we recommend that you review Configure and customize Azure Boards, which provides guidance on how to customize Azure Boards to meet your business needs. For a description of the different backlogs and boards, see Tasks supported by Backlogs, Boards, Taskboards, and Plans.
- You must have an organization created in Azure DevOps Services. If you haven't created one yet, do that now.
- To create, edit, and manage processes, you must be a member of the Project Collection Administrators group, or have the corresponding collection-level permissions Create process, Delete process, Edit process, or Delete a field from organization set to Allow. See Set permissions and access for work tracking, Customize an inherited process.
- You must have selected the Inheritance process model for the project collection where the project is created. To learn more, see Choose the process model for your project collection.
- To create, edit, and manage processes, you must be a member of the Project Collection Administrators group, or have the corresponding permissions Create process, Delete process, Edit process, or Delete a field from organization set to Allow. See Set permissions and access for work tracking, Customize an inherited process.
You create, manage, and make customizations to processes from Organization settings>Process.
Choose the Azure DevOps logo to open Projects. Then choose Organization settings.
Then, choose Process.
If you don't see Process, then you're working from TFS-2018 or earlier version. The Process page isn't supported. You must use the features supported for the On-premises XML process model.
You create, manage, and make customizations to processes from Collection Settings>Process.
Choose the Azure DevOps logo to open Projects. Choose the project collection whose processes you want to customize, and then choose Collection Settings.
Then, choose Process.
You create, manage, and make customizations to processes from Admin settings>Process.
Choose the Azure DevOps logo to open Projects. Then choose Admin settings.
Then, choose Process.
As you customize an inherited process, all projects that use that process are updated automatically to reflect the customizations. For this reason, we recommend that you create a test process and test project when you have a number of customizations to make in order to test the customizations prior to rolling them out to your organization. To learn more, see Create and manage inherited processes.
Add a work item type
From the Work Item Types page, choose New work item type.
Name the WIT and optionally specify a description, icon and color. The icon and color you specify appear throughout the web portal, including on the work item form and when associated work items appear on a backlog, boards, query results, and more. Choose Create to save.
From the Layout page, you can add fields, groups, or pages to specify the form and fields you want to track. Each new WIT comes predefined with a Details page with the Description field, and Discussion, Development, and Related Work groups. For details, see Add and manage fields or Customize the web layout for a process.
Also added, but not shown nor editable from the Layout page, are the standard elements included with the header of the form as shown in the following image, as well as the history, links, and attachment pages.
Open the States page to view the default workflow states. Optionally, customize the workflow states.
Optional. To add the WIT to a backlog, see Customize your backlogs or boards for a process. By default, custom WITs aren't added to any backlog. To learn more about different backlog levels, see Backlogs, boards, and plans.
Verify the custom work item type appears as expected. Open the Work>Work Items page (user context) and choose New Work Item and select the WIT you customized. Here we choose Ticket.
If you don't see the custom WIT, refresh your browser to make sure it registers all the custom changes you've made.
Verify that the field you added appears on the form. Note that the (exclamation mark) icon indicates the field is required.
Change description, icon or color
To change the description, icon or color of a custom WIT, choose Edit from the WIT context menu.
Here we change the description, icon and color for the Ticket custom WIT.
Enable or disable a WIT
You can disable a custom WIT, which prevents users from being able to add work items using it. However, all existing work items defined using the custom WIT remain available. You can query for them and edit them.
You may want to disable a custom WIT until you have defined all the fields, workflow, and layout that you have planned.
To disable a custom WIT, choose Disable from the WIT context menu.
To re-enable the WIT, choose Enable from the WIT context menu.
Disabling a WIT removes the WIT from the New drop down and add experiences. Creating a work item of that WIT is also blocked via REST APIs.
No changes are made to existing work items of that type. You can update or delete them and they continue to appear on backlogs and boards. Also, you can change the work item type of disabled WITs to an enabled type, but you can't change the type to a disabled WIT.
Delete or destroy a custom WIT
Destroying a WIT deletes all work items and data associated with that WIT, including historical values. Once destroyed, you can't recover the data.
To completely remove a custom WIT and all work items based on that WIT, choose Destroy from the WIT context menu.
To destroy a WIT, you must be a member of the Project Collection Administrators group or be granted explicit permissions to edit a specific process.
To complete the delete operation, you must type the name of the WIT as shown.
To work with WITs programmatically, see Work Item Types REST API.
Q & A
Q: How do I get my custom work item type to show up on my backlog?
A: Modify your requirement backlog to include the custom work item type. For details, see Customize your backlogs or boards, Edit or rename the requirement backlog.
The backlog level to which you add a custom work item type determines the parent work item type(s) for the work item type.
You can review changes made to an inherited process through the audit log. To learn more, see Access, export, and filter audit logs.