Add or modify a custom control for a process and WIT

Last Update: 3/8/2017

Team Services (Inheritance)


This topic applies to team project and process customization for the Inheritance process model. For the Hosted XML process model, you customize your team project by importing a custom process template; and for the On-premises XML process model, you customize 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. Each custom control corresponds to an extension, a simple add-on that supports functionality that extends your Team Services or TFS experience.

You can browse the Marketplace to find available controls. Or, you can create your own custom control.

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

Work item form, group extension example, Who viewed this

Types of custom control extensions

Custom control extensions come in three flavors: field, group, and page. When you add group and page extensions, they are automatically added to all WITs defined for all processes, both inherited and custom. You can choose to hide a control for a specific WIT, or move it within the form from it's default location.

To add a custom control group or page to a work item type, you simply Add the custom control extension. If you don't want the control to appear on each WIT, then you can hide it from appearing on the form.

To add a custom control for a field, you Add the custom control extension for the field, add a custom field to associate with the field, and then add the control to the specific WIT(s) where you want it to appear. See Add a field custom control for details.

To perform any of these actions, you must be a member of the Project Collection Administrators group or be granted explicit permissions to edit a specific process.

Add a custom control extension

To add a custom control, you begin by adding it first through the Extensions page.

  1. To open the admin context from the user context, click the gear Settings icon and choose Account settings.


    If you don't see the Account settings option, then you are working from an on-premises TFS. The Process page isn't supported. You must use the features supported for the On-premises XMl process model as described in Customize your work tracking experience.

    Default Collection Overview, Projects reference processes

  2. Click Extensions.

    Web portal, Account menu, Turn on new navigation selection

  3. You'll see any extensions that have already been installed. Click Browse Marketplace to install an extension from the Marketplace.

    Account settings, Extensions page, Team Services

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

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

    If you've installed a field extension, refresh your browser, complete the additional steps provided under Add a field control.

Add a custom control field

The steps to add a custom control field are:

  1. Install the custom control field extension as discussed earlier in this topic.

  2. Add a custom field to associate with the custom control field.

  3. From the Layout tab of the WIT you want to add the custom control field to, click the New custom control link.

    For example, here we add a new custom control for the Bug WIT for the MyAgile process:

    Process, WIT, Bug, Layout, New custom control


    If you don't see the New custom control link, then you haven't installed a custom control field extension. Or, you may need to click the Refresh refresh icon to cause the browser to register any new extensions that have been installed.

  4. Fill out the dialog box. At a minimum, enter the field name to use with the custom control.


    The dialog box will differ depending on the extension you installed.

    For example, here we associate the custom field, Customer Severity, with the custom control.

    Custom control dialog

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

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

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:

Marketplace extensions

Visit the Visual Studio Team Services Marketplace and search on "custom controls" to find extensions you can start using.

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: