Extend the work item form

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Use extensions to customize the work item form by adding groups, pages, menu actions, observers, or custom controls.

• Add a group
• Add a page (tab)
• Add a menu action
• Add a custom control
• Listen for events
• Configure contributions

For the full source code, see the UI example in the Azure DevOps extension samples on GitHub.

Add a group

To add a group to the main page, add a contribution to your extension manifest with type ms.vss-work-web.work-item-form-group targeting ms.vss-work-web.work-item-form:

"contributions": [
   {  
       "id": "sample-work-item-form-group",
       "type": "ms.vss-work-web.work-item-form-group",
       "description": "Custom work item form group",
       "targets": [
           "ms.vss-work-web.work-item-form"
       ],
       "properties": {
           "name": "My Group",
           "uri": "workItemGroup.html",
           "height": 600
       }
   }
]

Properties

JavaScript sample

This example registers a provider that responds to work item form events. It uses the WorkItemFormService to read field values when the work item loads.

import { IWorkItemFormService, WorkItemTrackingServiceIds } from "azure-devops-extension-api/WorkItemTracking";
import * as SDK from "azure-devops-extension-sdk";

async function getWorkItemFormService(): Promise<IWorkItemFormService> {
    return await SDK.getService<IWorkItemFormService>(WorkItemTrackingServiceIds.WorkItemFormService);
}

SDK.init();

SDK.ready().then(() => {
    SDK.register(SDK.getContributionId(), () => {
        return {
            // Called when the active work item is modified
            onFieldChanged: (args) => {
                console.log("onFieldChanged", JSON.stringify(args));
            },

            // Called when a new work item is being loaded in the UI
            onLoaded: async (args) => {
                const service = await getWorkItemFormService();
                const values = await service.getFieldValues([
                    "System.Id", "System.Title", "System.State", "System.CreatedDate"
                ]);
                console.log("onLoaded", JSON.stringify(values));
            },

            // Called when the active work item is being unloaded in the UI
            onUnloaded: (args) => {
                console.log("onUnloaded", JSON.stringify(args));
            },

            // Called after the work item has been saved
            onSaved: (args) => {
                console.log("onSaved", JSON.stringify(args));
            },

            // Called when the work item is reset to its unmodified state (undo)
            onReset: (args) => {
                console.log("onReset", JSON.stringify(args));
            },

            // Called when the work item has been refreshed from the server
            onRefreshed: (args) => {
                console.log("onRefreshed", JSON.stringify(args));
            }
        };
    });
});

Events

Add a page

A new page is rendered as a tab on the work item form. New pages appear next to the Details tab.

To add a page to the work item form, add a contribution to your extension manifest with type ms.vss-work-web.work-item-form-page targeting ms.vss-work-web.work-item-form:

"contributions": [
    {  
        "id": "sample-work-item-form-page",
        "type": "ms.vss-work-web.work-item-form-page",
        "description": "Custom work item form page",
        "targets": [
            "ms.vss-work-web.work-item-form"
        ],
        "properties": {
            "name": "My Page",
            "uri": "workItemPage.html"
        } 
    }
]

Properties

JavaScript sample

See the JavaScript sample in the form group section. The name of the registered object should match the id of the contribution.

Events

Configure contributions

In Azure DevOps Services, group extensions appear at the end of the second column by default, and page contributions appear as the last tab. Control contributions aren't shown by default - users must manually add them to the form. In Azure DevOps Server, see Configure work item form extensions to show, hide, or move contributions.

Add menu action

To add an item to the work item toolbar, add this contribution to your extension manifest. The item appears in the vertical ellipsis (...) dropdown menu.

"contributions": [
   {  
      "id": "sample-work-item-menu",  
      "type": "ms.vss-web.action",  
      "description": "Sample toolbar item which updates the title of a work item",  
      "targets": [  
          "ms.vss-work-web.work-item-context-menu"  
      ],  
      "properties": {  
          "text": "Try me!",  
          "title": "Updates the title of the work item from the extension",  
          "toolbarText": "Try me!",  
          "icon": "images/show-properties.png",  
          "uri": "menu-workItemToolbarButton.html"  
      }  
   }
]

Properties

Listen for events

Observers listen to work item events without any UI on the form. Use observers to listen for the onSaved event, since observers live outside the form and aren't destroyed when the form dialog closes.

"contributions": [
   {  
       "id": "sample-work-item-form-observer",
       "type": "ms.vss-work-web.work-item-notifications",
       "description": "Gets events about the current work item form for the 'Try Me!' toolbar button",
       "targets": [
           "ms.vss-work-web.work-item-form"
       ],
       "properties": {
           "uri": "myformobserver.html"
       }
   }
]

Properties

Events

JavaScript sample

The following example registers an observer by using the modern SDK:

import * as SDK from "azure-devops-extension-sdk";

SDK.init();

SDK.ready().then(() => {
    SDK.register(SDK.getContributionId(), () => {
        return {
            onFieldChanged: (args) => {
                // Handle field changes
            },
            onLoaded: (args) => {
                // Handle work item loaded
            },
            onUnloaded: (args) => {
                // Handle work item unloaded
            },
            onSaved: (args) => {
                // Handle work item saved
            },
            onReset: (args) => {
                // Handle work item reset (undo)
            },
            onRefreshed: (args) => {
                // Handle work item refreshed
            }
        };
    });
});

Compatibility notes

Action vs. action-provider

Use ms.vss-web.action-provider when dynamically loading menu items by using getMenuItems on the menu handler. Use ms.vss-web.action when your menu items are static and defined in the manifest.

Deprecated patterns

The following patterns are no longer supported:

• require("VSS/Events/Document") - not supported with New Boards Hub
• SDK.js script tag with usePlatformScripts: true - use the npm package azure-devops-extension-sdk instead

Related content

• Add a custom control to the work item form
• Configure work item form extensions (on-premises)
• Extension manifest reference
• Contribution model