About process customization and inherited processes

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

To customize the work tracking system, you customize an inherited process through the administrative user interface for the organization. All projects that use an inherited process get the customizations made to that process. On the other hand, you configure your Agile tools—Backlogs, Sprints, Kanban boards, and Taskboard—for each team.

Important

To customize an on-premises project or update XML definition files to support customization, see On-premises XML process model. This article applies to Azure DevOps Services and Azure DevOps Server 2019 only.

There are a number of customizations you can make. The primary ones are adding custom work item types (WITs) or modifying an existing WIT to add custom fields, modify the layout, or change the workflow.

Note

You can review changes made to an inherited process through the audit log. To learn more, see Access, export, and filter audit logs.

Below you'll find an index to those tasks you can perform to customize an inherited process. Some options of inherited elements are locked and can't be customized.

System versus inherited processes

You'll see two types of processes:

  • locked icon System processes —Agile, Basic, Scrum, and CMMI—which are locked from being changed.
  • inherited icon Inherited processes, which you can customize and that inherit definitions from the system process from which they were created. System processes are owned and updated periodically by Microsoft. Any updates made to a system process automatically cause an update to your inherited processes and their child inherited processes. Updates to processes are documented in the Release Notes for Azure DevOps Server.

Note

The Basic process is available with Azure DevOps Server 2019 Update 1 and later versions.

In addition, all processes are shared. That is, one or more projects can use a single process. Instead of customizing a single project, you customize a process. Changes made to the process automatically update all projects that use that process. Once you've created an inherited process, you can customize it, create projects based on it, make a copy of it, and change existing projects to use it.

For example, as shown in the following image, you see a list of projects defined for the fabrikam organization. The second column shows the process used by each project. To change the customizations of the Fabrikam Fiber project, you need to modify the MyScrum process (which inherits from the Scrum system process). Any changes you make to the MyScrum process also update other projects that use that process. You can't customize the Query test project, on the other hand, until you change it to a process which inherits from Agile.

Screenshot of Admin context, Organization settings, Project list and the process they use.

Process name restrictions

Process names must be unique and 128 Unicode characters or less. Also, names can't contain the following characters: .,;'`:~\/\*|?"&%$!+=()[]{}<>.

To rename a process, open the … context menu for the process and choose Edit.

Change the reference process of a project

If you want to switch the process a project uses from one system process to another, you can do that. To make these changes, you must create an inherited process based on the process you want to switch to. For example, instructions are provided to support the following changes:

Following the guidance provided in the above listed articles, you can also make additional changes, for example, from CMMI to Agile or Agile to CMMI.

Prior to making this change, we recommend you familiarize yourself with the process you are changing to. The system processes are summarized in About processes and process templates.

Best practices when making changes

Making changes to an inherited process is straight forward and safe. However, it is always a best practice to test those changes before applying them to an active project. Following these steps will help you surface any negative affects your process changes may have.

Inherited objects versus custom objects

Each inherited process you create inherits the WITs defined in the system process—Basic, Agile, Scrum, or CMMI. For example, the Agile process provides bug, task, user story, feature, epic, issue and test-related WITs.

Conceptual image of Agile process work item hierarchy.

You can add fields and modify the workflow and work item form for all inherited WITs that display on the Work Item Types page. If you don't want users to create a WIT, you can disable it. In addition, you can add custom WITs.

Field customizations

Fields defined in the system process appear with an inherited icon, indicating that you can make limited modifications to it in your inherited process.

Fields are defined for all projects and processes in the organization. That means that any custom field you defined for a WIT in one process can be added to any other WIT defined for another process.


Field type

Customization support


Inherited fields


Custom fields


Custom control


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 field to another WIT within the process. For example, you can add Due Date to the user story or bug WITs.

What you can't customize

  • You can't change the field name or data type once you've defined it
  • You can't modify the gray area on the form where the State, Reason, Area Path, and iteration path fields are located
  • You can't import or define a global list as supported by the Hosted XML and On-premises XML process models. To learn more, see Define global lists.
  • You can't change the field name or data type once you've defined it
  • You can't modify the gray area on the form where the State, Reason, Area Path, and iteration path fields are located
  • With regards to picklists, you currently can't perform these operations:
    • Change the picklist of an inherited field, such as the Activity or Discipline field
    • Change the picklist order, picklists display in alphabetic order
  • You can't modify the Description help text of inherited fields
  • Import or define a global list as supported by the Hosted XML and On-premises XML process models. To learn more, see Define global lists.

Note

With the inherited process, you can't modify the picklists of predefined fields—such as Activity, Automation Status, Discipline, Priority, plus others.

Configurable picklists

The following picklists are configured for each project and not customizable through an inherited process.

Picklists associated with person-name fields, such as Assigned To and Changed By, are managed based on the users you add to a project or team.

Can I rename a field or change its data type?

Renaming a field or changing the data 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.

Can I delete or restore a deleted field?

You can delete a field, and later restore it. Deleting a field deletes all data associated with that field, including historical values. Once deleted, you can only restore the field and recover the data using the Fields - Update REST API.

Instead of deleting a field, you may want to instead hide or remove the field from a work item form. For details, see Add and manage fields, Show, hide, or remove 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 organization or 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 all fields are defined for the organization, you can't add a custom field with the same field name that already exists in the organization or was added to a WIT in another inherited process.

Note

When you change a project to use an inherited process, you may find one or more Agile tools or work items appear in an invalid state. For example:

  • If you make a field required, work items with that field undefined show an error message. You'll need to resolve the errors to make additional changes and save the work item.
  • If you add or remove/hide workflow states of a WIT that appears on the Kanban board, you'll need to update the Kanban board column configurations for all teams defined in the project.

Custom rules and system rules

Each WIT—bug, task, user story, etc.—has several system rules already defined. Some are simple, like making the Title field required or setting a default for the Value Area field. In addition, a number of system rules define actions to take when a workflow state changes.

For example, several rules exist to copy the current user identity under the following conditions:

  • When a work item is modified, copy the user identity to the Changed By field
  • When the workflow state changes to Closed or Done, copy the user identity to the Closed By field.

Important

Predefined system rules take precedent over any custom rule that you define which would overwrite it.

Custom rules provide support for a number of business use cases, allowing you to go beyond setting a default value for a field or make it required. Rules allow you to clear the value of a field, copy a value into a field, and apply values based on dependencies between different fields' values.

With a custom rule, you can define a number of actions based on specific conditions. For example, you can apply a rule to support these types of scenarios:

  • When a value is defined for Priority, then make Risk a required field
  • When a change is made to the value of Release, then clear the value of "Milestone"
  • When a change was made to the value of Remaining Work, then make Completed Work a required field
  • When the value of Approved is True, then make Approved By a required field
  • When a user story is created, make the following fields required: Priority, Risk, and Effort

Tip

You can't define a formula using a rule. However, you may find a solution that fits your needs with Power Automate or TFS Aggregator (Web Service) Marketplace extension. See also Rollup of work and other fields.

For details on defining custom rules, see Rules and rule evaluation.

Restrict modification of select fields for select user groups

Using one of the following two conditions, you can make select fields required for a user of a security group or who are not a member of a security group.

  • current user is a member of a group...
  • current user is not a member of a group...

For example, you can make the Title or the State field Read-only for select users or groups.

Restrict modification of work items based on Area Path

You can disallow users from modifying select work items by setting permissions on an Area path. This is not a rule setting, but a permission setting. To learn more, see Create child nodes, modify work items under an area path.

Work item type (WIT) customizations

Here are your customization options for inherited and custom WITs.


Work item type

Customization support


Inherited work item types


Custom work item types


What you can't customize

  • You can't add or remove an inherited WIT to or from a backlog
  • You can't change the position of an inherited field within the form layout (however, you can hide the field in one area of the form and add it elsewhere in the form)
  • You can't remove the inherited portfolio level from the product (but you can rename them)
  • You can't change the name of a custom WIT.

Work item form customizations

You can make the following customizations to a WIT form.


Group or page type

Customization support


Inherited groups


Custom groups


Inherited pages


Custom pages


Layout and resizing

The web form layout is organized into three columns as shown in the image below.

Illustration of 3-column page layout for work item form.

If you only add groups and fields to the first two columns, then the layout reflects a two-column layout. Likewise, if you only add groups and fields to the first column, then the layout reflects a one-column layout.

The web form resizes depending on the width available and the number of columns in the layout. At maximum width, in most web browsers, each column within a page displays within its own column. As the display width decreases, each column resizes proportionally as follows:

  • For three columns: 50%, 25%, and 25%
  • For two columns: 66% and 33%
  • For one column: 100%.

When the display width won't accommodate all columns, columns appear stacked within the column to the left.

Workflow customizations

You can customize the workflow of any work item type (WIT) by hiding inherited states or adding custom states. Inherited states differ based on the system process —Agile, Basic, Scrum, or CMMI, —you chose from which to create your custom process.

Each default workflow for each WIT defines between two and four States and specifies the following workflow operations:

  • Forward and backward transitions between each state
  • Default reasons for each state transition

For example, the Basic process, Issue WIT is characterized by the three States—To Do, Doing, and Done—and transitions shown in the following image.

Basic Process, Issue work item type, workflow state model


State types

Supported customizations


Inherited icon Inherited states

Custom states


Workflow states must conform to the following rules

  • You must define at least one state for either the Proposed or In Progress State categories

    Note

    Before adding a workflow state, review Workflow states and state categories to learn how workflow states map to state categories.

  • You must define at least two workflow States
  • You can define a maximum of 32 workflow States per work item type

Unsupported workflow customizations

  • You can't modify an inherited state (you can't change its name, color, or category), but you can hide it
  • You can only have one state in the Completed state category. If you add a custom state to the Completed category, any other state is removed or hidden
  • You can't change the name of a custom state
  • You can't specify a Reason for a state, instead, default reasons are defined such as Moved to state Triaged, Moved out of state Triaged
  • You can't change the location of the State and Reason fields on the form
  • You can't customize state category names
  • You can't modify an inherited state (you can't change its name, color, or category), but you can hide it
  • You can only have one state in the Completed state category. The system disallows adding any custom state to this category
  • You can't change the name of a custom state
  • You can't change the order of states, states are listed in their natural sequence based on their state category within the drop-down list of a work item form
  • You can't specify a Reason for a state, instead, default reasons are defined such as Moved to state Triaged, Moved out of state Triaged
  • You can't change the location of the State and Reason fields on the form
  • You can't restrict transitions, all transitions are defined from any state to another state.

Backlog and board customizations

Backlogs and boards are essential Agile tools for creating and managing work for a team. The standard backlogs—product, iteration, and portfolio—inherited from the system process are fully customizable. In addition, you can add custom portfolio backlogs for a total of five portfolio backlogs.


Backlog types

Customization support


Inherited backlogs


Custom portfolio backlogs


What you can't customize

  • You can't remove an inherited portfolio level from the product (but you can rename the portfolio level and you can disable an inherited work item type)
  • You can't insert a backlog level within the existing set of defined backlogs
  • You can't reorder the backlog levels
  • You can't add a work item type to two different backlog levels
  • You can't create a custom task backlog level, although you can add custom WITs to the iteration backlog
  • You can't add the Bug WIT to any backlog level. Instead, the system allows each team to decide how they want to manage bugs. To learn more, see Show bugs on backlogs and boards.
  • You can't add or remove an inherited WIT to or from a backlog, for example, you can't add the Issue WIT to the product backlog
  • You can't remove an inherited portfolio level from the product (but you can rename the portfolio level and you can disable an inherited work item type)
  • You can't insert a backlog level within the existing set of defined backlogs
  • You can't reorder the backlog levels
  • You can't add a work item type to two different backlog levels
  • You can't create a custom task level, although you can add custom work item types to the iteration backlog
  • You can't add the Bug WIT to any backlog level. Instead, the system allows each team to decide how they want to manage bugs. To learn more, see Show bugs on backlogs and boards.

Note

Certain features require installation of Azure DevOps Server 2020.1 update. For more information, see Azure DevOps Server 2020 Update 1 RC1 Release Notes, Boards.

When you change the default WIT for a backlog level, it causes that WIT to appear by default in the quick add panel. For example, Customer Ticket appears by default in the following quick add panel for the product backlog.

Screenshot of Product backlog, Quick Add Panel, Displays Default WIT for a backlog level

Object limits

For a list of limits placed on the number of fields, WITs, backlog levels, and other objects you can customize, see Work tracking object limits.