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

VSTS (Inheritance)

Each locked icon system 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 icon 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.

For a list of all fields defined for your account—which includes all fields defined for system and inherited processes—see Review fields.

What you can customize

Locked and inherited fields correspond to fields inherited from a system process. You can't customize locked fields. You can customize some options for inherited fields.

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

In addition, you can add an existing inherited or custom field to another WIT within the process. 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 name or 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

Add a custom field

You can add fields and specify the group and page where they should appear. Also, once you've added a field, you can drag-and-drop it within a page to relocated it on the form. If you have several fields you want to add to a custom page or group, then you may want to add those elements first and then add your fields.

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


    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.

  2. With the WIT selected, click the add new field icon (New Field icon).

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

  3. Name the field and select the field type from one of the supported data types. Optionally, add a description.


    You must specify a field name that is unique within the account. A custom field defined for one process cannot be the same as the name defined for another process. For more information on field names, see What is a field? How are field names used?

    Here we add an Integer field labeled Customer Ticket.

    Add a field to Bug, choose field type

  4. (Optional) On the Options tab, indicate if the field is required and specify a default value. Or leave these blank. By making a field Required, users must specify a value for the field in order to save it. The default value you specified is set when you create a work item as well as every time a work item is opened and the field is empty.

    Add a field to Use story, specify options

  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.

    Here, we add the Customer Ticket field to a new group labeled Customer focus.

    Add a field to Use story, specify layout


    While you can change the form label, you must use the field name when adding fields to cards (Kanban, task board) or creating queries based on the field.

  6. Click Add field to complete adding the field. If you haven't specified it's layout location, it will be added to the first group of fields on the layout form.

  7. When you've completed making all your changes, open a work item of the type you've just customized.

    Here, we show the Customer Ticket field has been added to the Status group. You may need to refresh your browser to see the changes.

    Bug form, Customer Ticket field added to Details group

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. You can simply add an item and then press Enter to add another item.

    Add a custom pick list

    To delete an item in the list, highlight the item and then 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

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

Add an Identity field

Use the Identity field to add a field similar to the Assigned To field. Identity fields act in the same way as the 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 and are valid users of the team project.

  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 the add new field icon (New Field icon).

  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

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. Check the box to indicate 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

Existing fields correspond to any inherited field and custom field defined within the collection. 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.

For a list of all work item fields defined for all WITs and processes, see the Work item field index.

Here we add the Customer Ticket field to the User Story WIT.

Add existing field to bug

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

Show, hide, or remove a field

You can choose to show or hide an inherited field or a custom control from appearing on a form. For custom fields, you can remove it from the form. If you want to reinstate it later, you can add it back to the form. These actions differ from the Delete option, which deletes the field from the account.


Data defined for an inherited field, even if you hide it, is maintained in the data store and work item history. You can view a record of it by viewing the history tab for a work item.

Data defined for a custom field is deleted when you remove it from the form. To delete a custom field from a project collection, see Delete a field.

Hide an inherited field or custom control

  1. Open the context menu for the inherited field and choose Hide from layout.

    Bug layout, inherited field, open context menu, choose Hide from layout

  2. To add a hidden field to the form, choose Show on layout.

Remove a custom field from 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

  3. To add a custom field that's been removed, choose New field and select Use an existing field.

Review fields

To review the list of fields defined for all processes and the WITs which reference them, click the Process hub and then the Fields page.

Fields listed correspond to all those defined for the account. For descriptions and usage of each field, see Work item field index.

All Processes, Fields list

Once you've added a custom field, you can create queries or charts to track data related to it.

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. Remember to refresh your web browser to view your latest changes.

Additional topics of interest:

If you are working with test plans or test cases, see these topics:

Delete a field

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

Prior to deleting a field, you must first remove it from the form for each WIT that it's been added to.

  1. You delete the field from a collection from the Fields page for all processes.

    Delete field

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

  2. To complete the delete operation, you must type the name of the field as shown.

    Delete field, confirmation dialog

Can a field be renamed or its field type changed?

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. When selecting the field in a query you need to select the field name and not the field label.

Here, we relabel the Customer Ticket field to Ticket Number.

Layout tab, Relabel a field

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.