Add a custom work item type (Inheritance process)

Azure Boards | Azure DevOps Server 2019

You use different work item types (WITs) to plan and track different types of work. The main reason you add a custom WIT is to customize the web form and workflow states to meet specific business use cases. Or, you can customize an existing WIT. Your project contains 9 or more WITs that you can customize, based on the process used to create your project.

Important

To customize a project collection that uses the On-premises XML process model, available only for on-premises deployments, see On-premises XML process model. This article applies to Azure DevOps Services and Azure DevOps Server only.

To customize any project defined on a collection for TFS 2018 or earlier, see On-premises XML process model.

Important

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 has been 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.

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

Custom Ticket work item form

To learn more about what you can customize, see About process customization and inherited processes.

Tip

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

Prerequisites

  • You must have an organization created in Azure DevOps Services. If you haven't created one yet, do that now.
  • Users granted Basic or Stakeholder access are automatically granted permission to create, edit, and delete processes, change the process of a project, and administer process permissions. To change these defaults, you can restrict access by setting permissions at the organization level and set permissions explicitly.
  • To create, delete or edit a process, 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 organizaiton set to Allow. See Set permissions and access for work tracking, Customize an inherited process.

Open Settings>Process

You create, manage, and make customizations to processes from Organization settings>Process.

  1. Choose the  Azure DevOps logo to open Projects. Then choose Organization settings.

    Open Organization settings

  2. Then, choose Process.

    Organization Settings, Process page

    Important

    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 Admin settings>Process.

  1. Choose the  Azure DevOps logo to open Projects. Then choose Admin settings.

    Open Organization settings

  2. Then, choose Process.

    Organization Settings, Process page

    Important

    If you don't see Process, then the collection you've created is set to work with the On-premises XML process model. You must use the features supported for the On-premises XML process model.

Create an inherited process

The first step is to create an inherited process that you can customize. The default, system processes are locked from being customized.

  1. From the Process page, open the context menu of the process you'll use to create an inherited process, and then choose Create inherited process. Choose the same system process—Agile, Basic, Scrum, or CMMI—that was used to create the project that you want to customize.

    Here, we create an inherited process from the Agile system process.

    Context menu, Choose Create inherited process

  2. Enter a name for your process and optionally a description. Process names must be unique and no more than 128 characters. For additional restrictions, see Create and manage inheritance processes, Process name restrictions. Optionally, add a description.

    Create inherited process dialog

  1. From the Process page, open the context menu of the process you'll use to create an inherited process, and then choose Create inherited process. Choose the same system process—Agile, Scrum, or CMMI—that was used to create the project that you want to customize.

    Here, we create an inherited process from the Agile system process.

    Context menu, Choose Create inherited process

  2. Enter a name for your process and optionally a description. Process names must be unique and no more than 128 characters. For additional restrictions, see Create and manage inheritance processes, Process name restrictions. Optionally, add a description.

    Create inherited process dialog

Add a work item type

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

    Process, 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 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.

    Create new work item type dialog

    Click Create to save.

    Each new WIT comes predefined with a Details page with the Description field, and Discussion, Development, and Related Work groups. Also added, but not shown nor editable, 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. To learn more, see About work items.

    WIT header details
  3. Name the field and select the field type from one of the supported data types. Field names must be unique and no more than 128 characters. For additional restrictions, see What is a field? How are field names used?. Optionally, add a description.

    Here we add an Integer field labeled Customer Ticket.

    Add a field to Bug, choose field type

    Additional data types you can add include: Picklist, Identity, Rich-text, HTML, and Checkbox.

  4. (Optional) On the Options tab, indicate if the field is required and specify a default value. Or leave these blank.

    Add a field to Use story, specify options

    By making a field Required, users must specify a value for the field in order to save it. The default value you specify is set when you create a work item as well as every time a work item is opened and the field is empty.

  5. (Optional) On the Layout tab, you can enter a different form label than the name of the field. Also, you can choose the page and group where the field appears on the form.

    Here we choose to add a new field. Choose the  (New Field icon).

    New WIT, customize layout

  6. Here, we add the Customer Ticket field to a new group labeled Customer focus.

    Add a field to Use story, specify layout
  7. Choose Add field to complete adding the field. If you haven't specified it's layout location, it is added to the first group of fields on the layout form.

    Tip

    Once you've added a field, you can drag-and-drop it within a page to relocate it on the form. If you have several fields you want to add to a custom page or group, then you may want to add those elements first and then add your fields.

Verify the customization you made

We recommend that you create a test project and apply your customized inherited process to it to verify the changes you've made.

  1. Open the All processes page, and choose the … context menu for the process you want to use, and then select New team project.

    Create a project from the selected process

  2. The Create new project page opens. Fill out the form.

    Create new project form

  3. Open Work Items. (1) Check that you have selected the right project, then (2) choose Work>Work Items.

    Open Work>Work Items

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

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

Apply the customized process to your project

After you've verified your customizations, you can now apply the process to your existing project.

Tip

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

  1. Open the … context menu for the process and choose the Change team projects… option.

    Here we open the menu for the MyAgile inherited process.

    Agile process context menu, Choose Change team projects to use MyAgile

  2. Check the check box of those projects you want to change to use the Agile process. The system lists only those projects that are valid for the current process.

    Here we choose to use the Agile process for the Fabrikam Fiber A and Fabrikam Fiber projects. Only those projects created from the Agile process or one that inherits from Agile appears under the Available projects column.

    Change process to an inherited process dialog

  3. After you've confirmed that the projects you want to change are correct, choose Ok.

Try this next