List work item fields and attributes

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

Work item fields are used to track information within Azure DevOps. These fields are defined at the organization level and are shared across all projects in the organization. To review the fields defined for your organization, you can use one of the following two tools, available for both Inherited and Hosted XML process models:

• Process > Fields web page
• Work Item Field Explorer

For a description of each field defined with a system process, see Work item field index.

Prerequisites

Permissions: To view the fields defined for an organization or collection, be a member of the Project Collection Valid Users application group or have the View instance-level information permission set to Allow for the organization or collection.

List or review fields

To list or review fields, use one of the following tools based on your process model—Inherited, Hosted XML, or On-premises XML. For an index of fields defined within the default processes, see Work item field index.

Tool	Inheritance	Hosted XML	On-premises XML
Web portal: List inherited and custom-defined fields	✔️	✔️1
Work item field explorer	✔️	✔️	✔️
witadmin listfields command line tool	✔️	✔️	✔️

Note

1. Only supported for default processes (Agile, CMMI, Scrum).

Field data types and names

Each work item type specifies the fields included in work items of that type. Each field has multiple attributes, many of which are system-defined and immutable.

Fields get defined by the following three attributes:

• Data type: Indicates the kind of data that can be entered into the field, such as Boolean, Double, Integer, HTML, or String. For detailed descriptions of each data type, see Query fields, operators, and macros.
• Friendly name: The user-friendly name assigned to the field, used when selecting a Field in a query clause. This name might differ from the name displayed on the work item form.
• Reference name: The identifier used when creating WIQL queries, improvised work item templates, executing REST API commands, or defining XML work item type definitions. The reference name is permanent and can't be changed once set.

For a detailed description of each field attribute and instructions on how to list them, see Field attributes and List field attributes later in this article. For an overview of work item types (WITs) and work items, refer to Track work with user stories, issues, bugs, features, and epics.

What is a field? How are field names used?

Each work item type includes 31 system fields and several type-specific fields. Work items are used to plan and track your project.

Each field captures specific information about the work to be performed. The values you assign to these fields are stored in the work tracking data store, enabling you to create queries that determine status and trends.

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

Field names

A work item field name uniquely identifies each work item field. Ensure your field names adhere to the following guidelines:

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

Since custom fields are defined at the organization or collection level, you can't add a custom field with the same name to multiple processes.

For more information, see Naming restrictions and conventions.

System and predefined fields

A work item field name uniquely identifies each field within Azure DevOps. Ensure your field names comply with the following guidelines:

• Uniqueness: Field names must be unique within an account or project collection.
• Length: Field names must be 128 Unicode characters or fewer.
• Spacing: Field names can't have leading or trailing spaces or contain multiple consecutive spaces.
• Composition: Field names must include at least one alphabetic character.
• Prohibited Characters: Field names can't include the following characters: .,;':~/*|?"&%$!+=()[]{}<>`.

Since custom fields are defined at the organization or collection level, you can't add a custom field with the same name to multiple processes.

For more information, see Naming restrictions and conventions.

Custom fields

Because custom fields are defined at the organization or project collection level, you can't add a custom field with the same name to multiple processes.

When adding custom fields, note the following limits:

• Maximum fields per work item type (WIT): 64
• Maximum fields per process: 512

The field data type determines the kind and size of data that can be stored in the field. Each field can have only one type defined within a project collection, encouraging the use of common fields across different projects and work item types.

When you add a custom field to an inherited process, Azure DevOps assigns a reference name prefixed with Custom followed by the field name without spaces. For example, adding a field named DevOps Triage results in the reference name Custom.DevOpsTriage. Spaces aren't allowed in reference names.

For more information, see Naming restrictions and conventions.

How can I determine the field data type?

You can view the data type of fields defined for your organization by opening the Process>Fields page.

Review fields list

To review the list of fields defined for an organization or collection, do the following steps:

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

   

2. Select Process.

   

3. Select Fields.

   Fields listed correspond to all fields defined for the organization or collection, which includes all custom fields and the fields defined for system processes.

   

   Note

   If you don't see Fields, then your collection uses the On-premises XML process. The Fields page isn't supported for that process.

   For descriptions, usage, and reference names of each field, refer to the Work item field index. Additionally, you can retrieve field reference names using the Work Item Types Field - List REST API.

Work Item Field Explorer

You can look up the assignments of field attributes using the Work Item Field Explorer tool.

To access the Work Item Field Explorer, install the Process Editor Tool. Based on your installed version of Visual Studio, get the Process Editor Tool from one of the following extensions.

• Visual Studio 2019 & 2022: As of now, there's no specific Process Template Editor extension available. But, you can still customize process templates using other tools such as any text editor or XML editor. You can also use the Azure DevOps web portal for certain customizations, especially for inherited processes.
• Visual Studio 2017: TFS Process Template Editor. You can also use this version of the Process Editor to modify the old-style work item forms. You can't use it to edit forms associated with the new web forms.
• Visual Studio 2015: TFS Power Tools.

Field attributes

There are many nonchangeable and hidden attributes for each work item field. The following table describes each attribute. Attributes have different names depending on whether you retrieve them through the Fields - Get REST API or view them through the Work Item Field Explorer (WIFE) tool.

Attributes assigned to a field depend on the platform and version you're using. For example, some attributes aren't supported with the Inheritance process. To look up the reference name for a field, see the Work item field index.

Attribute

Attribute type

Description

---

REST:
WIFE: AllowedValues

collection

Gets the collection of valid values for a field that contains picklist values. You can change this by specifying a picklist or global list (on-premises).
Can change?=Yes

REST: canSortBy
WIFE: CanSortBy

boolean

Indicates whether you can sort query results with this field.
Can change?=No

REST: description
WIFE: HelpText

string

Specifies a description for the field, which also defines the help text that appears when you hover over the field within the work item form.
Can change?=Yes

REST:
WIFE: ID

Integer

Specifies the internal ID of the field.
Can change?=No

REST:
WIFE: IsCloneable

boolean

Indicates whether the value defined for the field is copied when a user chooses to copy a work item. For example, Title, Tags, and Description fields are copied, but the ID and History fields aren't copied.
Can change?=No

REST:
WIFE: IsComputed

boolean

Indicates if the value set by this field is computed by the system (True) or not (False). Examples of computed fields are ones that are set by the system, such as the ID, Revised Date, Changed Date, and External Link Count.
Can change?=No

REST:
WIFE: IsCoreField

boolean

Indicates whether this field is specified for all work item types.
Can change?=No

REST:
WIFE: IsEditable

boolean

Indicates if users can modify this field (True) or not (False). Examples of noneditable fields are ones that are set by the system, such as the ID, Revision, Created By, and Changed By fields
Can change?=No

REST: isIdentity
WIFE: IsIdentity

boolean

Indicates whether this field is an Identity field. Identity fields are string fields used to store user identities.
Can change?=No

REST:
WIFE: IsIndexed¹

boolean

Indicates whether this field is indexed to support search.
Can change?=No

REST:
WIFE: IsLongText

boolean

Indicates that the field can contain more than 255 characters, such as fields assigned a data type of PlainText, HTML, or History.
Can change?=No

REST: isPicklist² WIFE:

Boolean

Indicates whether the field is associated with a picklist. The value is set to True when a custom field is defined for Azure DevOps and Picklist (String) or Picklist (Integer) type is selected. The value is set to False for inherited fields that define picklists.
Can change?=No

REST: isPicklistSuggested² WIFE:

Boolean

Indicates whether the field allows users to enter their own values for a picklist. The value is set to True when a custom field is defined for Azure DevOps, Picklist (String), or Picklist (Integer) type is selected, and the checkbox for Allow users to set their own values is checked.
Can change?=Yes

REST: isQueryable
WIFE: IsQueryable

boolean

Indicates if the field shows up within the set of fields you can add to filter a work item query (True), or not (False). Most fields are queryable.
Can change?=No

REST:
WIFE: IsReportable ³

boolean

Indicates if the reportable attribute is defined or set to anything other than None. This attribute can be changed for on-premises environments.
Can change?=Yes

REST:
WIFE: IsUsedInGlobalWorkflow

boolean

Indicates if the field is defined within a global workflow.
Can change?=No

REST:
WIFE: IsUserNameField

boolean

Indicates if the field is used to display an Identity field.
Can change?=No

REST: name
WIFE: Name

string

Friendly name assigned to the field. The friendly name can't be changed for Azure DevOps, but can be changed for on-premises using the witadmin changefield command.
Can change?=On-premises only

REST: picklistId
WIFE: HelpText

GUID

If the field is a picklist, the identifier of the associated picklist, otherwise null. A unique GUID value is assigned when a custom field is defined for Azure DevOps and Picklist (String) or Picklist (Integer) type is selected.
Can change?=No

REST:
WIFE: ProhibitedValues

collection

Gets the collection of prohibited values for a field that specifies such values. You can only define prohibited values for on-premises deployments.
Can change?=On-premises only

REST: readOnly
WIFE:

Boolean

Indicates whether the field is set to read only. For Azure DevOps Services, only custom fields can be changed to be read-only. System fields can't be modified.
Can change?=Yes

REST: referenceName
WIFE: ReferenceName

string

Specifies the reference name of a field.
Can change?=No

REST:
WIFE: ReportingAttributes³

Specifies Detail, Dimension, or Measure, depending on whether and how you want the field to be included in reports. Data from fields that have a value other than None for this attribute are exported to the data warehouse and can be included in SQL reports.
Can change?=On-premises only

REST:
WIFE: ReportingName³

string

Specifies the label for a field when data appears in SQL reports. If you don't specify a value, the field's friendly name is used.
Can change?=On-premises only

REST:
WIFE: ReportingReferenceName³

string

Specifies a different reference name to a field that is used when data is exported to the relational data warehouse. If you don't specify a value, the fields reference name is used.
Can change?=On-premises only

REST: supportedOperations
WIFE:

set

The set of query operators that are valid for use when referencing this field. For a quick reference of supported operations based on data type, see Query quick reference, Operators, and macros supported for each data type.
Can change?=No

REST:
WIFE: SupportsTextQuery

boolean

Indicates whether the field supports text queries such as Contains Words, Does Not Contains Words.
Can change?=No

REST:
WIFE: SystemType

string

Specifies the data type of the field, referencing the system name such as System.DateTime or System.String.
Can change?=No

REST: type
WIFE: FieldType

string

Specifies the data type of the field, such as Boolean, DateTime, Integer, String, and so on. For a complete list and descriptions, see Query fields, operators, and macros.
Can change?=No

REST: usage
WIFE: Usage

string

Specifies whether the field is intended for use with work items (WorkItem) or work item link (WorkItemLink) objects. The usage for most fields is WorkItem. For a complete list of usage values, see Get Fields, FieldUsage.
Can change?=No

Note

1. For on-premises deployments, you can enable indexing for a field to improve query response times when filtering on the field. For more information, see Indexed fields later in this article.
2. The isPicklist and isPicklistSuggested attributes are only assigned to custom fields defined for an inherited process. The Inherited process model is supported for Azure DevOps Server 2019 and later versions. For more information, see Inherited process model.
3. All reporting attributes are valid only for on-premises deployments whose projects have been configured to support SQL Server Reporting and SQL Server Analysis Services.

List field attributes

You can list the attributes assigned to a field by using the Fields - Get REST API. Replace OrganizationName with your actual organization name.

https://dev.azure.com/OrganizationName/_apis/wit/fields/FieldReferenceName

For example, to list the attributes for the Iteration Path, use the reference name System.IterationPath for the fabrikam organization:

https://dev.azure.com/fabrikam/_apis/wit/fields/System.IterationPath

**Returned data:**

> [!div class="tabbedCodeSnippets"]
> ```JSON
> {
> "name": "Iteration Path",
> "referenceName": "System.IterationPath",
> "description": "The iteration within which this bug will be fixed",
> "type": "treePath",
> "usage": "workItem",
> "readOnly": false,
> "canSortBy": true,
> "isQueryable": true,
> "supportedOperations": [
> {
> "referenceName": "SupportedOperations.Under",
> "name": "Under"
> },
> {
> "referenceName": "SupportedOperations.NotUnder",
> "name": "Not Under"
> },
> {
> "referenceName": "SupportedOperations.Equals",
> "name": "="
> },
> {
> "referenceName": "SupportedOperations.NotEquals",
> "name": "<>"
> },
> {
> "referenceName": "SupportedOperations.In",
> "name": "In"
> },
> {
> "name": "Not In"
> }
> ],
> "isIdentity": false,
> "isPicklist": false,
> "isPicklistSuggested": false,
> "url": "https://dev.azure.com/mseng/_apis/wit/fields/System.IterationPath"
> }
> ```

Add and modify fields

To add fields to a process, you add them to one or more work item types. For more information, see Customize an inheritance process.

Related articles

• Refer to the Query quick reference to quickly understand query syntax and usage.
• Explore the Work item field index to view all available work item fields.
• Add and manage fields for an inherited process to customize fields according to your inherited process requirements.
• Access the metadata reference for Azure Boards Analytics to understand analytics metadata and reporting capabilities.