Add a custom control to a work item type (Inheritance process model)

Last Update: 5/12/2017

Team Services (Inheritance)

IMPORTANT

This topic applies to process customization for the Inheritance process model, which supports customization of team project(s) through a shared process model.

For the Hosted XML process model, you customize your team projects by importing a custom process template; and for the On-premises XML process model, you customize a team project by importing modified XML definition files. For an overview of process models, see Customize your work tracking experience.

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

  • Field-level contribution
  • Group-level contribution
  • Page-level contribution
  • Action-level contribution (appears in the context menu of the web form)

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

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

Work item form, group extension example, Who viewed this

Add a Marketplace extension

Browse the Marketplace to determine what extension(s) you want to add. To install an extension, see these topics:

From the admin context, Extensions hub, you can view the extensions that are already installed.

Account settings, Extensions page, Team Services

You may need to click Refresh to refresh the page to show newly installed extensions.

Add a field-level contribution

  1. Install the field-level extension as discussed in the previous section.

  2. Open the admin context Process hub from a work item form or by choosing the Account Settings option from the gear option. For details, see Customize a process, Start customizing.

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

  4. With the WIT selected, click 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 installed.

  5. Choose the field-level 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. Click the Options tab and fill out the dialog box. The options you need to specify will depend on the extension 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 extensions, 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 extension, refresh your browser, and then open a work item to view the placement of the control on the form. To move or hide the control, follow the guidance provided for the Layout tab.

Action-level contributions

Action-level extensions are added to the context menu of inherited and customizable WITs for both system and inherited processes. All action-level extensions 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

As you add custom controls, keep in mind that all team projects that reference the inherited process that you're customizing will automatically update to contain the new fields. To view your customizations, refresh your web browser.

Additional topics of interest:

Required permissions

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.

Programmatically add custom controls

You can use these REST APIs to work with custom controls: