Work item fields and attributes in Azure Boards

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

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

Prerequisites

• To view the fields defined for an organization or collection, you must 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, you can use one of the following tools, depending on the process model—Inheritance, Hosted XML, or On-premises XML—you use. For an index of fields defined within the default processes, see Work item field index.

Field data types and names

Each work item type specifies the fields defined for the work items that reference that type. Each field is associated with a number of attributes, many of which are set by the system and cannot be changed.

Each field is defined by the following three attributes.

• Data type: Specifies the type of data that can be entered into the field, such as Boolean, Double, Integer, HTML, and String. For descriptions of each data type, see Query fields, operators, and macros.
• Friendly name: Specifies the name assigned to the field and that you select for a Field in a query clause. This name may differ from the name displayed on the work item form.
• Reference name: Specifies the name that you use when creating WIQL query or an improvised work item template, using REST API commands, or defining XML work item type definitions. Once defined, the reference name cannot be changed.

For a description of each field attribute and how you can list them, see Field attributes and List field attributes later in this article. For an overview of WITs and work items, see Track work with user stories, issues, bugs, features, and epics.

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, Agile, Basic, Scrum, and CMMI 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 an organization or collection, you can't add a custom field to a process with the same field name that you add to another process.

For more information, see Naming restrictions and conventions.

System and predefined fields

All system defined fields have reference names that begin with System, for example, System.AreaPath, System.AssignedTo, and continue in that pattern.

Predefined fields defined by the default process begin with Microsoft.VSTS and then further differ based on their usage. Examples of predefined fields that are used in common, for scheduling purposes and integration with Office Project, for integration with Team Foundation Build, and integration with test case management (TCM) are as follows:

• Microsoft.VSTS.Common.Priority
• Microsoft.VSTS.Scheduling.DueDate
• Microsoft.VSTS.Build.FoundIn
• Microsoft.VSTS.TCM.Steps

For an overview of all system and predefined fields that are defined for the default processes/process templates, see Work item field index. For more information about specifying field names, see Naming restrictions.

Custom fields

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

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

The field data type determines the kind and size of data that you can store in the field. A field can have only one type defined within a project collection. This restriction encourages organizations to use common fields across projects and work item types.

How can I determine the field data type?

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, you must install the Process Editor Tool. Based on the version of Visual Studio you have installed, get the Process Editor Tool from one of the following extensions.

• Visual Studio 2019: Process Template Editor.
• 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 non-changeable and hidden attributes for each work item field. The following table describes each attribute. Attributes have different names based on if you get them through the Fields - Get REST API or view through the Work Item Field Explorer (WIFE) tool.

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

List field attributes

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

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

{
"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"
}

https://{ServerName:Port}/tfs/{Collection}/_apis/wit/fields/FieldReferenceName?api-version={version}

https://fabrikam:8080/tfs/DefaultCollection/_apis/wit/fields/System.IterationPath?api-version=4.1

{
"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://fabrikam:8080/tfs/DefaultCollection/_apis/wit/fields/System.IterationPath?api-version=4.1"
}

witadmin listfields /collection:http://fabrikam:8080/tfs/DefaultCollection /n:Microsoft.VSTS.Common.Issue  

Field: Microsoft.VSTS.Common.Issue  
Name: Issue  
Type: String  
Reportable As: dimension  
Use: Adventure Works (Shared Steps), AW Future (Shared Steps), AW Current (Shared Steps)  
Indexed: False  

Add and modify fields

Related articles