Add or modify a custom work item type for a process

Last Update: 4/5/2017

Team Services (Inheritance)


This topic applies to team project and process customization for the Inheritance process model. For the Hosted XML process model, you customize your team project by importing a custom process template; and for the On-premises XML process model, you customize by importing modified XML definition files.

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

Your team project contains 14 or more work item types (WITs), based on the process—Agile, Scrum, or CMMI—used to create the team project. You use different WITs to plan and track different types of work.

With custom WITs, you can add WITs to support your custom tracking needs. For example, you may want to capture customer issues in a custom Ticket WIT.

Custom Ticket work item form

What you can customize

Each process you create inherits the WITs associated with the core system process —Agile, Scrum, or CMMI. For example, the Agile process provides bug, task, user story, feature, epic, issue and other test-related WITs.

You can add fields and modify the workflow and form for all inherited WITs that display on the Work Item Types page. If you don't want users to use a WIT, you can disable it.

In addition, you can add custom WITs.

WITs Customization options
Inherited WITs Add custom field | Modify form layout | Enable/disable a WIT | Modify workflow states | Add or remove custom controls
Custom WITs Add a work item type | Change color, description | Define the form layout | Define the workflow states | Add to or remove from a backlog | Enable/disable | Delete/destroy | Add or remove custom controls

To perform any of these actions, you must be a member of the Project Collection Administrators group or be granted explicit permissions to edit a specific process.

What you can't customize

  • You can't modify an inherited WIT (you can't change its name, color, backlog assignment, nor can you delete an inherited WIT)
  • You can't change the name of a custom WIT.

Open Process>Work Item Types in the admin context

  1. To open the admin context from the user context, click the gear Settings icon and choose Account settings.


    If you don't see the Account settings option, then you are 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.

    Default Collection Overview, Projects reference processes

  2. Click Process.

    Web portal, Account menu, Turn on new navigation selection

  3. Choose the inherited process you want to customize, and then click Work Item Types. If you haven't yet created an inherited process, do that now. See Create an inherited process.

    Here we open Work Item Types for the MyAgile process.

    Process page, WITs

Add a work item type

  1. From the Work Item Types tab, click green plus icon New work item type.

    Process page, WITs, Add new work item type

  2. Name the WIT and optionally specify a description and color. The color you specify will appear throughout the product 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. In the layout page, add fields, groups, or pages to specify the form and fields you want to track.

    Define layout for custom ticket WIT

    For details, see Customize a web form for a process

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

  5. Optional. Specify the backlog where the custom WIT should appear. By default, custom WITs aren't added to any backlog. (To learn more about different backlog levels, see Show bugs on backlogs or boards.

    Here we add Ticket to the Stories backlog.

    Set backlogs for custom ticket WIT

  6. Verify the custom work item type appears as expected. Either navigate to the backlog or board to which you added the custom WIT, or open the Queries page, and open a new work item of the type you added.

    stories Kanban board, add new custom ticket work item

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

Change description or color of a custom WIT

  1. To change the description or color of a custom WIT, open the Overview page for the WIT.

    Here we change the description and color for the Ticket custom WIT.

    Overview page, edit custom ticket description and color

  2. Click Save icon Save when done.

Enable or disable a custom WIT

You can disable a custom WIT which will prevent users from being able to add new work items using it. However, all existing work items defined using the custom WIT remain in the data store.

You may want to disable a custom WIT until you have defined all the fields, workflow, and form layout that you have planned.

  1. Open the Overview page for the WIT and select the Disable this work item type checkbox.

    Here we change the description and color.

    Overview page, disable custom WIT

  2. Click Save icon Save when done.

  3. To re-enable the WIT, uncheck the checkbox and click Save icon Save.

Note: Disabling a WIT will remove the work item type 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.

As you customize a WIT, all team projects that reference the inherited process that you're customizing will automatically update to reflect the custom WITs you've added. To view your customizations, refresh your web browser.

To customize a single team project, always start by creating an inherited process and migrating the team project to that process. Then, all the customizations that you make to the inherited process automatically appear for the team project you migrated.

Additional topics of interest:

Delete or destroy a custom WIT

Important: 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.

To completely remove a custom WIT and all work items based on that WIT, you select the Destroy option from the WIT's Overview page.

Overview page, disable custom WIT

Click OK to confirm.