Add extensions and custom controls to a work item type (Inheritance process)

Azure Boards | Azure DevOps Server 2020 | Azure DevOps Server 2019

With extensions, you can add rich functionality to your work item forms. An extension comes in four flavors, or contribution types. The following controls appear on the web form layout for all inherited and customizable work item types (WITs):

  • Field-level contribution (custom controls)
  • Group-level contribution
  • Page-level contribution

The fourth type, action-level contributions, on the other hand, appear in the context menu of the web form.

Important

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.

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

You add all contributions by installing its extension from the Visual Studio Marketplace, Azure DevOps tab. Or, you can create your own custom control.

For example, you can add the Who recently viewed a work item? extension. This group-level contribution appears in your work item form as shown.

Work item form, group extension example, Who viewed this

Prerequisites

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.

To add extensions or edit a process, you must be a member of the Project Collection Administrators group or be granted explicit permissions to edit a specific 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 Projects>Organization settings.

  2. Then, choose Process.

    Then, choose Process.

    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 Collection Settings>Process.

  1. Choose the Azure DevOps logo to open Projects. Choose the project collection whose processes you want to customize, and then choose Collection Settings.

    Open Projects>Organization settings

  2. Then, choose Process.

    Then, choose Process.

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 Project>Organization settings.

  2. Then, choose Process.

    Then, choose Process.

Note

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.

Review installed Marketplace extensions

From the Settings context, Extensions, you can view the extensions that are already installed. You may need to choose Refresh to refresh the page to show newly installed extensions.

Organization settings, Extensions page

To learn more about extensions, see Install free extensions.

Add a Marketplace extension

You can browse the Marketplace to determine what extension(s) you want to add.

  1. To add an extension to a work item type, choose your inherited process, the WIT, and then choose Get extensions.

    Process, WIT, Bug, Layout, Get extensions

  2. Select the extension you want to add. Here we choose the Work item checklist.

  3. Select the organization you want to add it to and choose Install.

    Visual Studio Marketplace, install extension

    Important

    Extensions you install are added to all WITs across all processes.

  4. Return to the process and WIT and verify the location of the extension is where you want it. Look for it at the bottom of the middle column and drag it to where you want it on the form.

    Group extension on Bug work item form

Add a field-level contribution or custom control

  1. Install the custom control as discussed in the previous section.

  2. Open Settings>Work>Process from a work item form. For details, see Open Settings>Process.

  3. (Optional) Add a field to associate with the custom control. Alternatively, you can specify an existing field, inherited or custom.

  4. With the WIT selected, choose Add custom control.

    Process, WIT, Bug, Layout, New custom control

    Note

    If you don't see the Add custom control option, then you haven't installed a field-level extension. Or, you may need to refresh your browser to cause your browser to register any new extensions that have been recently installed.

  5. Choose the custom control you want from the menu of options.

    For example, here we choose the Toggle control that you can associate with a Boolean field.

    Add a  custom control dialog, Definition tab

  6. Choose the Options tab and fill out the dialog box. The options you need to specify depend on the custom control you've selected.

    For example, here we specify the custom field, Triaged, and indicate the toggle labels to appear on the form.

    Custom control dialog
  7. (Optional) Open the Layout tab and specify the label for the field.

    Fill in any additional required fields. Review the extension description for guidance.

  8. Verify the working of the custom control by opening a work item of the type you modified. You may need to refresh your browser to see your changes.

    Here, we show how the control appears by default with the checkbox and then with the toggle control.

    Boolean field with checkbox Boolean field with toggle control
    Boolean field with checkbox Boolean field with toggle control

Group-level and page-level contributions

When you add group-level and page-level contributions, they are automatically added to all WITs defined for all processes, both inherited and custom. You can choose to hide these contributions from appearing on the form for a specific WIT, or move it within the form from it's default location.

If you've installed a group or page contribution, refresh your browser, and then open a work item to view the placement of the contribution on the form. To move or hide the contribution, follow the guidance provided for the Layout tab.

Action-level contributions

Action-level contributions are added to the context menu of inherited and customizable WITs for both system and inherited processes. All action-level contributions are added to all work item types and cannot be hidden or removed without uninstalling or disabling the extension.

For example, the following image shows nine action-level contributions have been added and appear in the context menu for the user story.

User story web form, context menu, Action-level options

Programmatically add custom controls

You can use these REST APIs to work with extensions:

Note

You can review changes made to an inherited process through the audit log. To learn more, see Access, export, and filter audit logs.