Add and manage fields for an inherited process

Azure Boards | Azure DevOps Server 2019

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 or change the label that appears in the work item form for an inherited field.

Important

To customize a project collection that uses the On-premises XML process model, available only for on-premises deployments, see On-premises XML process model. This article applies to Azure DevOps Services and Azure DevOps Server only.

To customize any project defined on a collection for TFS 2018 or earlier, see On-premises XML process model.

Important

You can only use the Inheritance process model for projects defined on a project collection configured to support the Inheritance process model. If your on-premises collection has been configured to use the On-premises XML process model, you can only use that process model to customize the work tracking experience. To learn more, see Customize work tracking, Choose the process model for your project collection.

To customize any project defined on a collection for TFS 2018 or earlier, see On-premises XML process model.

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

Once you've added a custom field, you can create queries, charts, or Analytics views and Power BI reports to track data related to it.

Prerequisites

Open Settings>Process

You create, manage, and make customizations to processes from Organization settings>Process.

  1. Choose the  Azure DevOps logo to open Projects. Then choose Organization settings.

    Open Organization settings

  2. Then, choose Process.

    Organization Settings, Process page

    Important

    If you don't see Process, then you're working from TFS-2018 or earlier version. The Process page isn't supported. You must use the features supported for the On-premises XML process model.

You create, manage, and make customizations to processes from Admin settings>Process.

  1. Choose the  Azure DevOps logo to open Projects. Then choose Admin settings.

    Open Organization settings

  2. Then, choose Process.

    Organization Settings, Process page

    Important

    If you don't see Process, then the collection you've created is set to work with the On-premises XML process model. You must use the features supported for the On-premises XML process model.

Note

As you customize an inherited process, all projects that use that process are updated automatically to reflect the customizations. For this reason, we recommend that you create a test process and test project when you have a number of customizations to make in order to test the customizations prior to rolling them out to your organization. To learn more, see Create and manage inherited processes.

Review fields

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

Fields listed correspond to all those defined for the organization. For descriptions and usage of each field, as well as the Reference name for each field, look it up from the Work item field index. You can also get the Reference name of fields from the Work Item Types Field - List REST API.

Make a copy of a selected inherited process

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.

Note

You can only add fields within a page on a form. You can't add a field to the gray area within the form where the Assigned To, State, and Reason fields are located.

  1. From the Process page of the selected inherited process, choose the work item type you want to add the custom field to.

    Here we choose the Bug WIT. Note the breadcrumb links that allow you to move back to All Processes and MyAgile process page.

    All Processes-Process-WIT breadcrumb links

    If the New field and other options are disabled, you don't have the necessary permissions to edit the process. See Set permissions and access for work tracking, Customize an inherited process.

  2. With the WIT selected, choose the  New field.

    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.

    Note

    You must specify a field name that is unique within the organization. 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 appears 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

    Note

    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. Choose Add field to complete adding the field. If you haven't specified its layout location, it is 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 Customer focus group

Add a picklist

You can add a new field and define a pick list or customize the pick list of an inherited field.

  1. Start by choosing add new field icon New field, then specify the picklist type—integer or string—and then add the items to appear in the picklist. You can simply add an item and then press Enter to add another item.

    Add a custom picklist

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

    To modify the pick list of an inherited field, choose **Edit** to edit the field. On the **Definition** tab, you can choose to **Add value**.

    Priority field, Definition tab dialog

  2. (Optional) Choose 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 picklist
  3. (Optional) See previous step 5 to specify where you want the field to appear on the form (Layout tab).

Add an Identity field

Azure Active Directory (Azure AD) 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 organization manages users with Azure Active Directory (Azure AD), then the system synchronizes Identity fields with the names defined in Azure AD and are valid users of the project.

  1. Start by choosing add new field icon New field, then the field name, Identity type, and optionally a description.

    Add a custom picklist

  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 choose the add new field 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

Add a checkbox field

  1. Just as before, choose the WIT you want to add the field to and then choose 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.

    Note

    The field appears 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. Or, you can add a field defined for one process to a work item type in another process. 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 a User Story

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

Relabel a field

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

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

Note

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.

When you remove a custom field from the layout, it is maintained in the data store but stripped from the history. You can view it from the query results. If you add the field back to the form, then the history for it is restored.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.

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 Layout page of the modified WIT.

Layout page, Field context menu, choose Revert option

Delete a field

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

  1. You delete the field from the All processes>Fields page.

    Delete field

    To delete fields, you must be a member of the Project Collection Administrators group or be granted explicit permissions to Delete field from account.

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

    Delete field, confirmation dialog

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