Add and manage fields (Inheritance process)

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

You can customize your work tracking system by adding custom fields or modifying specific attributes of an inherited field. For example, you can add a custom field to capture other data or change the label displayed in the work item form for an inherited field.

To view all fields defined for your organization, including system and inherited fields, see View work item fields and attributes.

After you add a custom field, you can use it to create queries, charts, or Analytics views and Power BI reports to track and analyze related data.

Prerequisites

For guidance on tailoring Azure Boards to align with your specific business requirements, see About configuring and customizing Azure Boards.

Category	Requirements
Permissions	- To create, delete, or edit a process: Member of the Project Collection Administrators group or specific collection-level permissions Create process, Delete process, Edit process, or Delete a field from organization set to Allow. For more information, see Set permissions and access for work tracking, Customize an inherited process. - To update boards: Team Administrator or a member of the Project Administrators group.
Access	- Even if you have Basic or lower access, you can still change a process if someone gives you permissions to do so. - To update and change the type of your existing work items: Member of the project.
Project process model	- Have the Inheritance process model for the project collection containing the project. - If migrating data to Azure DevOps Services, use the Team Foundation Server Database Import Service.
Knowledge	Familiarity with the customization and process models.

Open organization process settings

1. Sign in to your organization (https://dev.azure.com/{yourorganization}).

2. Select Organization settings.

   

3. Select Process.

   

Note

When you customize an inherited process, any projects using that process automatically reflect the customizations. To ensure a smooth transition, we recommend creating a test process and project, which allows you to test your customizations before you implement them organization-wide. For more information, see Create and manage inherited processes.

Custom field names

When you add a custom field to an inherited process, Azure DevOps assigns it a reference name prefixed with Custom and removes any spaces from the field name. For example, a field named "DevOps Triage" is assigned the reference name Custom.DevOpsTriage. Spaces aren't allowed in reference names.

Add a custom field

You can add fields and specify the group and page where they should appear. After you add a field, you can drag and drop it within a page to adjust its placement on the form. If you plan to add multiple fields to a custom page or group, create those pages or groups first before adding the fields.

Each process can define up to 1,024 fields, including system and inherited fields. Fields can only be added within a page on a form. You can't add fields to the gray area of the form where the Assigned To, State, and Reason fields are located.

1. From the Process page of the selected inherited process, select the work item type (WIT) where you want to add the custom field.

   In the following example, we select the Bug WIT. Notice the breadcrumb links that allow you to navigate back to All Processes and the MyAgile process page.

   

   If the New field and other options are disabled, you don't have the necessary permissions to edit the process.

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

   

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

   Field names must be unique within the organization. A custom field in one process can't share the same name as a field in another process. For more information, see What is a field? How are field names used?.

   In the following example, we add an Integer field type labeled Customer Ticket.

   

4. (Optional) On the Options tab, indicate whether the field is required and specify a default value. If left blank, the field remains optional. When you make a field Required, users must specify a value to save the work item. The default value is set when a work item is created or opened, and the field is empty.

   

5. (Optional) On the Layout tab, you can specify a different form label than the field name. You can also choose the page and group where the field appears on the form.

   In the following example, we add the Customer Ticket field to a new group labeled Customer focus.

   

   Note

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

6. Choose Add field to complete the process. If you don't specify a layout location, the system adds the field to the first group of fields on the form.

7. After your changes are complete, open a work item of the customized type to review the updates.

   The following example shows the Customer Ticket field was successfully added to the Status group. If the changes aren't immediately visible, refresh your browser to ensure the updates display correctly. This step ensures the new field is properly integrated into the work item form and ready for use.

   

Add a picklist

Work tracking, process, and project limits

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

Each organization or collection can define up to 2,048 picklists. Each picklist can contain up to 2,048 items. Picklist items must be 256 or fewer characters. To add dependent picklists, see Cascading lists.

1. Select New field, then specify the picklist type—integer or string—and then add the items to appear in the picklist. You can add an item and then select Enter to add another item.

   

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

   

2. (Optional) Specify required or default values and choose where the field appears on the form.

   

Add an Identity field

Use an Identity-based field to add a field similar to the Assigned To field. Identity-based fields act in the same way as the Assigned To field, providing a search and identity picker function. When your organization manages users with Microsoft Entra ID or Active Directory, the system synchronizes Identity-based fields with the names defined in these directories.

Select New field, then the field name, Identity type, and optionally a description.

(Optional) Specify required or default values and choose where the field appears on the form.

Add a rich-text, HTML field

1. Select the WIT you want to add the field to, and then choose the New field.

2. Choose Text (multiple lines) as the type. Here we label the field as Customer request to capture customer comments for product feature requests.

   

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

   

4. (Optional) Specify required or default values and choose where the field appears on the form.

Add a checkbox field

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

   

3. (Optional) Select Options, and then specify whether the field is required.

   

4. By default, the field gets added to the last group defined in the second column. Select Layout, and then drag and drop the field to another group on the form.

   Note

   The field appears as a checkbox in the work item form. Selecting the checkbox indicates a True value. If the field displays on the board or Taskboard, the values True and False show as text instead of a checkbox.

Add an existing field to another WIT

Existing fields correspond to any inherited field and custom field defined within the collection. After you add 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. Open the work item type and choose the existing field.

To look up descriptions of any system-defined work item field, see the Work item field index.

In the following example, we add the Customer Ticket field to the User Story WIT.

(Optional) Specify required or default values and choose where the field appears on the form.

Relabel a field

Renaming a field or changing its type isn't supported. However, you can change the label displayed on the work item form from the Layout tab. When creating queries, use the field name, not the label.

In the following example, we relabel the Customer Ticket field to Ticket Number.

Modify Description help text

Description help text appears when users hover over a field in the work item form. You can customize help text for both custom and inherited fields, but the behavior differs by field type:

• Inherited fields: Help text can be customized for each work item type and process.
• Custom fields: Help text is consistent across all work item types and processes.

To modify the Description help text, choose the work item type you want to modify, choose Edit for the field and choose the Definition tab. The modified value only affects that field in the process and for that work item type.

Here we modify the Story Points field for User Story.

Show, hide, or remove a field

You can choose to show or hide any field or custom control from appearing on a form. If you want to reinstate a field onto the form later, you can unhide 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 gets 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 gets restored. To delete a custom field from a project collection, see Delete a field.

Hide a field or custom control

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

   

2. To add a hidden field or control 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.

   

2. Confirm that you want to remove the field.

   

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

Revert field to preset defaults

You can discard changes you made to an inherited field. From the Layout page of the modified work item type, choose the Revert option for the field.

Delete a custom field

With the Inheritance process model, you can only delete custom fields; you can't delete system default fields.

Deleting a field removes all associated data, including historical values. There might be a short delay before data purge jobs begin. During this time, you can attempt to restore the field and recover its data using the Fields - Update REST API. Recovery might be full, partial, or unsuccessful, depending on the remaining data. Use caution when deleting fields, as recovery isn't always possible or complete.

Note

This action CANNOT be undone. Delete only fields that aren't in use. Use the witadmin listfields command to identify unused fields. For more information, see Manage work item fields (witadmin).
If Analytics is enabled for your organization or collection, you can query Analytics to find where a custom field is in use with the following syntax:

https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/WorkItemTypeFields?$filter=FieldReferenceName eq {CustomFieldReferenceName}&$select=WorkItemType

To delete a custom field, do the following steps:

1. Select Organization settings > Process > Fields > More actions > Delete.

   

   Be a member of the Project Collection Administrators group or granted explicit permissions to Delete fields.

2. Enter the name of the field as shown in the following example, and then confirm by selecting Delete work item field.

   

Related articles

Note

Review changes made to an inherited process through the audit log. For more information, see Access, export, and filter audit logs.

• View work item fields and attributes
• Add or modify a custom work item type
• Customize the web layout
• Work tracking, process, and project limits