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, boards, and Taskboards—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

Review changes made to an inherited process through the audit log. For more information, 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.

Note

For more information, see the following articles:

• Use backlogs to manage projects
• Configure and customize Azure Boards
• Create a project using the process of your choice
• Customize your work tracking experience
• Create and manage inherited processes

System versus inherited processes

You'll see two types of processes:

• System processes —Agile, Basic, Scrum, and CMMI—which are locked from being changed.
• 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.

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.

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:

• From Basic to Agile
• From Scrum to Agile
• From Agile to Scrum

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.

Agile process

Basic process

Note

The Basic process is available when you create a new project from Azure DevOps Services or Azure DevOps Server 2019.1. For earlier on-premises deployments, choose Agile, Scrum, or CMMI process.

Scrum process

CMMI process

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

• Change the field label
• Show/Hide field on form

• Modify picklist (drop-down menu)

• Modify Description help text

---

Custom fields

• Add a custom field
• Add picklist (drop-down menu)
• Add person-name/Identity
• Add a rich-text (HTML) field
• Add a checkbox (Boolean) field
• Add a custom control
• Add custom rules to a field
• Change the field label
• Set Required/Default options
• Move the field within the layout

• Modify Description help text
• Show/Hide field on form

• Remove field from form
• Delete field

---

Custom control

• Add a field-level contribution or custom control
• Add a group-level or page-level contribution
• Move the control within the layout
• Show/Hide control on form

---

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. For more information, see Define global lists.

Configurable picklists

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

• Area paths
• Iteration paths

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 transition a project to an inherited process, you might encounter Agile tools or work items in an invalid state per the following examples:

• If you designate a field as required, work items lacking that field display an error message. To proceed with further changes and save the work item, resolve these errors.
• If you add, remove, or hide workflow states for a WIT that appears on the board, ensure you update the board column configurations for all teams defined in the project. Also, consider maintaining single ownership of work items by team area path or formalizing columns with custom states share across teams.

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. For more information, 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

• Add custom rules to a WIT
• Add/remove custom fields
• Add/remove custom groups
• Add/remove custom pages
• Add/remove a custom control
• Enable/disable

---

Custom work item types

• Add custom WIT
• Change color or description
• Add/remove custom fields
• Add/remove custom groups
• Add/remove custom pages
• Add/remove a custom control
• Add custom rules to a wit
• Add, edit, or remove a workflow state
• Enable/disable
• Delete

---

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

• Relabel
• Add/remove custom fields
• Show/hide fields

---

Custom groups

• Add, modify, re-sequence, delete
• Add/remove custom fields
• Add/Hide a group extension

---

Inherited pages

• Relabel
• Add/remove custom fields
• Add/remove a custom group

---

Custom pages

• Add, modify, re-sequence, delete
• Add/delete custom fields
• Add/hide a page extension

---

Layout and resizing

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

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 vary based on the system process that you selected to create your custom process. The options are Agile, Basic, Scrum, or Capability Maturity Model Integration (CMMI). For more information, see Workflow states, transitions, and reasons.

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. For example, the Basic process Issue WIT includes three states—To Do, Doing, and Done.
• Default reasons for each state transition

---

State types

Supported customizations

---

Inherited states

• Hide or unhide a state
• Add rules when changing a workflow state

Custom states

• Add a workflow state
• Edit a workflow state (change color or category)
• Remove a workflow state
• Add rules when changing a workflow state

---

Workflow states must conform to the following rules

• Define at least one state for either the Proposed or In Progress State categories.

  Note

  Before you add a workflow state, see About workflow states in backlogs and boards to learn how workflow states map to state categories.

• Define at least two workflow States.
• Define a maximum of 32 workflow States per work item type.

Unsupported workflow customizations

• Hide inherited states if you don't want them visible (you can't change their name, color, or category).
• Ensure only one state exists in the Completed state category. Adding a custom state to this category removes or hides any other state.
• Keep the name of custom states as is; you can't change them.
• Use default reasons for state transitions, such as Moved to state Triaged and Moved out of state Triaged; you can't specify custom reasons.
• Accept the default location of the State and Reason fields on the form; you can't change their placement.
• Use the default state category names; you can't customize them.

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

• Add a custom work item type (WIT)

• Add an inherited work item type

• Change the default work item type
• Rename a backlog

---

Custom portfolio backlogs

• Add a portfolio backlog that displays custom work item types (WITs)
• Edit or rename a portfolio backlog
• Delete the top-level custom portfolio backlog

---

Unsupported customizations:

• Removing an inherited portfolio level:
  • While you can’t directly remove an inherited portfolio level from a product, you have a couple of options:
    • Rename the portfolio level: You can rename the inherited portfolio level to better suit your needs.
    • Disable an inherited WIT: If the inherited portfolio level includes WITs that you don’t want to use, you can disable them. This action prevents teams from creating new work items of those types.
• Inserting a backlog level:
  • You can't insert a new backlog level within the existing set of defined backlogs. The predefined backlog levels are typically fixed (for example, Epics, Features, User Stories, Tasks), and you can’t add custom ones in between.
• Reordering backlog levels:
  • Unfortunately, you can't reorder the backlog levels. They usually follow a predefined hierarchy, and changing their order isn’t supported.
• Adding a WIT to multiple backlog levels:
  • Each WIT can only belong to one backlog level. You can't add a WIT to two different backlog levels simultaneously.
• Creating a custom task backlog level:
  • Although you can't create a custom task-specific backlog level, you can still add custom WITs to the iteration backlog. For example, you could create a custom WIT called "Enhancement" or "Maintenance" and associate it with the iteration backlog.
• Managing bugs:
  • The Bug WIT doesn’t belong to any specific backlog level by default. Instead, each team can decide how they want to manage bugs. You can choose to show bugs on backlogs and boards or handle them separately.

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.

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.