Add and manage work item types


You use different work item types (WITs) to plan and track different types of work. Your project contains several WITs that you can customize, based on the process—Agile, Scrum, or CMMI—used to create your project. Also, you can add a custom WIT to support additional tracking requirements.

For example, you may want to capture customer issues in a custom Ticket WIT.

Custom Ticket work item form


  • You must have an organization created in VSTS. If you haven't created one yet, do that now.
  • You must be a member of the Project Collection Administrators group, the organization owner, or be granted explicit permissions to edit, create, or manage a specific process and to create a project.

    If you aren't a project administrator, get added as one. Or, have someone provide you with explicit permissions to Edit or Create a specific process and Create new projects.

Open Settings>Process hub


Choose Previous navigation when you see a top-level, blue-bar. Choose New navigation if you see a vertical sidebar or if you enabled the New Navigation preview feature. The vertical sidebar along with other navigational features are enabled when the New Navigation preview feature has been enabled for the signed-in user or the VSTS organization. To learn how to use the web portal effectively, see Navigation Basics.

You create, manage, and make customizations to processes from the Organization Settings>Process hub.

  1. Choose the VSTS icon to open Projects. Then choose Admin settings.

    Open Organization settings

  2. Then, expand Work as needed and choose Process.

    Organization Settings, Process page


    If you don't see Process, then you're working from an on-premises TFS. The Process page isn't supported. You must use the features supported for the On-premises XML process model as described in Customize your work tracking experience.

::: moniker-end


As you customize an inherited process, all projects that use that process will update 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

  1. From the Work Item Types page, choose  New work item type.

    Process hub, Inherited process, Work Item Types, Add new work item type

  2. Name the WIT and optionally specify a description, icon and color. The icon and color you specify will 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. Click Create to save.

    Create new work item type dialog

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

    New WIT, customize layout

    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.

    WIT header details

  4. Open the States page to view the default workflow states. Optionally, customize the workflow states.

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

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

    Work>Work Items page, add new work item, Ticket

    If you don't see the custom WIT, refresh your browser to make sure it registers all the custom changes you've made.

  7. Verify that the field you added appears on the form. Note that the (exclamation mark) icon indicates the field is required.

    Ticket form, Customer Ticket field added to Customer Focus group

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.

Overview page, edit custom ticket description, icon and color

Enable or disable a WIT

You can disable a custom WIT which will prevent 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 will remove the WIT from the New drop down and add experiences. Creating a work item of that WIT will also be blocked via REST APIs.

No changes are made to existing work items of that type. You can update or delete them and they will 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 will delete all work items and data associated with that WIT, including historical values. Once destroyed, you can't recover the data.

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

  2. To complete the delete operation, you must type the name of the WIT as shown.

    Delete field, confirmation dialog

WIT extensibility

To work with WITs programmatically, see Work Item Types REST API.