Customize a field for a process

Last Update: 4/5/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.

Each process—Agile, Scrum, or CMMI—contains 100 or more work item fields. You can add a custom field to support tracking additional data requirements or modify select attributes of an inherited field. For example, you can add a custom field and pick list or change the label that appears in the work item form for an inherited field.

To see a list of all work item fields defined for your process, see Review fields defined for a process.

What you can customize

The field type determines the customization options you can make. Locked and inherited fields correspond to fields inherited from the core system process, such as Agile, Scrum, and CMMI system processes. You can't customize locked fields. You can customize some options for inherited fields.

Field type Customization options
Locked field Locked fields No customization supported
Inherited field Inherited fields
Custom fields

In addition, you can add an existing inherited or custom field to another WIT. For example, you can add Due Date to the user story or bug WITs.

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.

What you can't customize

  • You can't change the field data type once you've defined it
  • With regards to pick lists, you currently can't perform these operations:
    • Change the pick list of an inherited field, such as the Activity or Discipline field
    • Change the pick list order, pick lists display in alphabetic order
  • Import or define a global list

Open Process>Work Item Types in the admin context

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

    Web portal, Account menu, Turn on new navigation selection

  3. Choose the inherited process you want to customize, and then click Work Item Types. If you haven't yet created an inherited process, do that now. See Create an inherited process.

    Here we open Work Item Types for the MyAgile process.

    Process page, WITs

Add a custom field

You can add a field and then specify which page and group it belongs under, or you can open a page and add a field to the group on that page. If you want to add only one or two fields, then follow the steps outlined below.

However, if you have several fields you want to add to a custom page or group, then first customize the web form for a process and then add your fields.

  1. From the Work Item Types tab, choose the Fields options for the WIT to which you want to add a field to, and then click add new field icon (New Field).

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

  2. Name the field and select the field type from one of the supported data types.

    Here we add a Customer ticket field of type Integer.

    Add a field to Bug, choose field type

    (Optional) Add a description for the field.

  3. Click Add field to complete adding the field. It will be added to the first group of fields on the layout form. In this instance, that's the Status group as shown below. Or, click the Options or Layout tab to specify further information about the field.

    Bug form, Customer Ticket field added to Details group

    You may need to refresh your browser to see the changes.

  4. (Optional) On the Options tab, indicate if is required and a default value. Or leave these blank.

    Add a field to Use story, specify options

    By making a field Required you require a user to specify a value for the field. Users cannot save a work item until they have assigned values to all required fields.

  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 will appear on the form.

    Add a field to Use story, specify layout


    While you can change the form label, you must use the field name when creating queries based on the field.

Add a pick list

  1. Start by clicking add new field icon (New Field), then specify the pick list type—integer or string—and then add the items to appear in the pick list.

    Add a custom pick list

    To delete an item in the list, click the Delete icon delete icon.

  2. (Optional) Click the Options tab to define the field as required, specify a default, or allow users to enter their own values.

    Allow values in a custom pick list

    Note: Allowing users to enter their own values is similar to specifying a set of SUGGESTEDVALUES when defining the picklist within the WITD XML definition as described in Apply a rule field.

  3. (Optional) See previous step 5 to specify where you want the field to appear on the form (Layout tab).

Add person-name or Identity field

Use the Identity field to add a field similar to the Assigned To field. Identity fields act in the same way as teh Assigned To field, providing a search and identity picker function. If your account manages users with Azure Active Directory (AAD), then the system synchronizes Identity fields with the names defined in AAD.

  1. Start by clicking add new field icon (New Field), then the field name, Identity type, and optionally a description.

    Add a custom pick list

  2. (Optional) See previous step 5 to specify where you want the field to appear on the form (Layout tab).

Add a rich-text, HTML field

  1. Just as before, choose the WIT you want to add the field to and then click add icon New Field.

  2. Choose Text (multiple lines) as the type. Here we label the field as Customer request to capture customer verbatims.

    Process Work Item Types page, Add a rich-text field to the Bug form

  3. The field is added to the first column under all system-defined rich-text fields, but before the Discussion control.

    Bug form, Customer request field added to first column in form


    The requirement to place the HTML field in the first column has been removed. You can drag and drop these fields within the layout page for a WIT to locate them in any column on the form.

Add a checkbox field

  1. Just as before, choose the WIT you want to add the field to and then click add icon New Field.

  2. Choose Boolean as the type, and give it a label. Here we label the field as Triaged to track the triage state of the bug.

    Add a boolean field

  3. (Optional) Open the Options tab and specify if the field should be required.

    Set options for boolean field

  4. By default, the field is added to the last group defined in the second column. Open the Layout tab to drag and drop the field to another group on the form.


    The field will appear as a checkbox in the work item form. A check in the box indicates a True value. If you display the field on the Kanban or Task board, then the field values of True and False display (not a checkbox).

Add an existing field to another WIT

Once you've added a custom field to one WIT, you can add it to others from the form menu. Simply open the work item and choose the existing field.

Here we add the Customer Ticket field to the Bug WIT.

Add existing field to bug


Existing fields correspond to all fields defined for all processes within a team project collection. If you've created team projects using two or more of the default processes --Agile, Scrum, and CMMI-- you'll have access to all the fields defined for each of these processes. For a list of all work item fields defined for all WITs and processes, see the Work item field index.

Optionally, specify the Required/Default values and placement within the form for the field.

Show or hide a field

You can choose to show or hide fields on a form.

  1. Choose Remove from the context menu of the field you want to remove.

    Remove field from bug work item type

  2. Confirm that you want to remove the field.

    Confirm to remove field from the bug work item form

    This is the same as choosing Remove from layout on the Layout tab for the WIT.


Once data has been defined for a field, it's maintained in the data store and work item history, even if you remove it from the form. You can view a record of it by viewing the history tab for a work item.

To delete a field from a project collection, see Delete/destroy a field.

Rename a field or change the field type

Renaming a field or changing the field type aren't supported actions.

However, you can change the label that appears for a field on the work item form from the Layout tab.

Layout tab, Relabel a field

Note that when selecting the field in a query you need to select the field name and not the field label.

Review fields defined for a process

To review the list of fields defined for a process and the WITs which reference them, open the Fields page.

Fields listed correspond to only those used by the currently selected process, such as MyAgile in the following example. For descriptions and usage of each field, see Work item field index.

Fields list

Once you've added a custom field, you can create queries or charts to track data related to it. Note, however, that you can't access custom field data from Power BI reports.

As you add custom fields, 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.

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

Additional topics of interest:

Revert field to preset defaults

If you've made changes to an inherited field, and now want to discard those changes, you can do that by choosing the revert option for the field from the WIT layout tab.

Delete/destroy a field

Destroying a field will delete all data associated with that field, including historical values. Once destroyed, you can't recover the data.

Prior to destroying a field, you must first remove it from each work item type that it's been added to.

You destroy the field from a collection from the Fields page.

Delete field

Click Destroy in the confirmation dialog box to continue.

To destroy fields, you must be a member of the Project Collection Administrators group or be granted explicit permissions to edit a specific process.

What is a field? How are field names used?

Each work item type is associated with 31 system fields and several more type-specific fields. You use work items to plan and track your project.

Each field supports tracking a piece of information about the work to perform. Values you assign to a field are stored in the work tracking data store which you can create queries to determine status and trends.

For descriptions and usage of each field defined for the core system processes—Scrum, Agile, and CMMI system processes—see Work item field index.

Field names

A work item field name uniquely identifies each work item field. Make sure your field names fall within these guidelines:

  • Field names must be unique within the account/project collection
  • Field names must be 128 or fewer Unicode characters
  • Field names can't contain any leading or trailing spaces, nor two or more consecutive spaces
  • Field names must contain at least one alphabetic character
  • Field names can't contain the following characters: .,;'`:~\/\*|?"&%$!+=()[]{}<>.

Because custom fields are defined for the account collection, you can't add a custom field to a process with the same field name that you add to another inherited process.

Customization limits

When adding custom fields, note the following limits:

  • A maximum of 64 fields can be defined for each WIT
  • A maximum of 512 fields can be defined per process

Return to the process overview

From the Process tab, you can choose another process to customize or return to the Process overview page.

Return to process overview page

Feedback and support

We welcome your feedback.

Send suggestions on UserVoice, and follow us on Twitter @VSTeam. Or, tell us what you think with Send-a-Smile on the title bar ... Send-a-Smile.

Or, see our comprehensive feedback and support page.

Need additional help?

Email VS Team Services Customization Help and we'll be happy to help you out!