Add a custom field to a work item type (Inheritance process)

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

You add a custom field to support tracking data requirements you have that aren't met with the existing set of fields. For example, you can add a custom field to track a customer ticket number. For a list of all fields defined for your organization—which includes all fields defined for system and inherited processes—see View work item fields and attributes. For a description of each field defined with a system process, see Work item field index.

Important

The Inheritance process model is available for projects configured to support it. If you’re using an older collection, check the process model compatibility. 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. For more information, see Choose the process model for your project collection.

For more information, see About process customization and inherited processes.

Tip

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

Prerequisites

For guidance on tailoring Azure Boards to align with your specific business requirements, see About configuring and customizing Azure Boards.

  • Organization requirement: Ensure you have an organization in Azure DevOps.

  • Permissions:

    • Be a member of the Project Collection Administrators group.
    • Have collection-level permissions such as Create process, Delete process, Edit process, or Delete a field from organization set to Allow.
    • These permissions allow you to modify processes and fields within your organization.
  • Project process model requirement:

  • Permissions:

    • Be a member of the Project Collection Administrators group.
    • Have collection-level permissions such as Create process, Delete process, Edit process, or Delete a field from organization set to Allow.
    • These permissions allow you to modify processes and fields within your organization.

Open organization process settings

  1. Sign in to your organization (https://dev.azure.com/{yourorganization}).

  2. Select Organization settings.

    Screenshot showing Organization settings button for selection.

  3. Select Process.

    Screenshot showing highlighted Process button for selection.

  1. Sign in to your collection (https://dev.azure.com/{Your_Collection}).

  2. Select Collection Settings or Admin settings.

  3. Select Process.

    Screenshot showing highlighted Process button in Collection settings.

Create inherited process

For more information, see Create inherited process.

Add a field

Do the following steps to add a field to an existing work item type. You can't use the Steps control on a custom work item type based on the Test Case work item type.

  1. From the Process page of the selected inherited process, choose the work item type you want to add the custom field to.

    Here we choose the Bug WIT. The breadcrumb links allow you to move back to the All Processes and MyAgile process page.

    All Processes-Process-WIT breadcrumb links

    If the New field and other options are disabled, you don't have the necessary permissions to edit the process. See Set permissions and access for work tracking, Customize an inherited process.

  2. With the WIT selected, choose the New field.

    Process Work Item Types page, Add a field to a WIT

  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.

    Note

    Once created, you can't change the field name or data type.

    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 add the Customer Ticket field to a new group labeled Customer focus.

    Add a field to Use story, specify layout
  6. Choose Add field to complete adding the field. If you haven't specified its 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. You can't add a field to the gray area within the form where the Assigned To, State, and Reason fields are located.

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

    Create a project from the selected process

    Create a project from the selected process

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

    Create new project form

    Create new project 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 Bug.

    Work, Work Items Page, Add New Work Item, Bug

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

    Bug 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. For the process currently used by the project, choose the number of projects.

    Here we open the menu for the Agile default process.

    Agile process, Choose number of team projects

  2. Open the … context menu for the project you want to change, and choose the Change process option.

    Here we open the menu for the MyFirstProject1.

    Project, Change process

  3. From the Change the project process dialog, choose the process from the menu of options. And, then choose Save.

    Change process dialog

  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.

Next steps

Note

Review changes made to an inherited process through the audit log. For more information, see Access, export, and filter audit logs.