Edit

Share via

Process customization and inheritance

Azure DevOps Services

To tailor the Azure DevOps work tracking system to your organization's needs, you can customize an inherited process through organization settings. All projects in an organization that use the inherited process get the customizations you make to that process. You can then configure project backlogs, sprints, and boards for each project team.

Important

This article applies only to the inheritance process model in Azure DevOps Services. To customize on-premises projects or update XML definition files, see Hosted XML process model and Customize a Hosted XML process.

You can make several customizations to inherited processes. The most important ones are creating custom work item types (WITs) or modifying existing WITs to add custom fields, modify layouts, or change workflows. Some options of inherited elements are locked and can't be customized.

This article provides an overview of ways to customize inherited processes. For information about limits on the numbers of fields, WITs, backlog levels, and other objects you can customize, see Work tracking, process, and project limits.

Note

You can review changes made to an inherited process by using the audit log and auditing features. For more information, see Access, export, and filter audit logs.

System and inherited processes

The system processes Agile, Basic, Scrum, and Capability Maturity Model Integration (CMMI) are locked, and users can't change them. Microsoft owns these system processes and updates them periodically.

Inherited processes are customized from system processes and inherit definitions from the system process they're based on. Any updates Microsoft makes to system processes automatically update in inherited processes and their child inherited processes.

All projects in an organization can share all of its processes. You customize the process instead of customizing the single projects.

Once you create an inherited process, you can customize it, copy it, create projects based on it, and change existing projects to use it. Changes you make to the inherited process automatically update all projects in the organization that use that process.

The following example shows a list of projects in the fabrikamprime organization and the process each project uses. To change customizations for the Fabrikam Fiber project, you modify the My Agile process, which inherits from the Agile system process. Changes you make to the My Agile process also update the Agile by design project that uses that process. To customize the other projects, you would need to change them to use inherited processes.

Screenshot of projects and the processes they use.

Change the process of an existing project

You can switch the process a project uses from one process to another. For more information and instructions, see the following articles:

By following the general guidance in the listed articles, you can make other changes such as from CMMI to Agile or Agile to CMMI. Before you change a project process, familiarize yourself with the process you're changing to. For more information, see About processes and process templates.

When you transition a project to a different process, some existing tools or work items might become invalid. For example, work items that lack a field required in the new process might display errors. To proceed with changes and save the work items, you must resolve these errors. If the process change adds, removes, or hides workflow states for a WIT that appears on a board, make sure to update the board column configurations for all teams defined in the project.

Change or rename an inherited process

Changing an inherited process is straightforward, but it's best to test the changes before applying them to an active project. You can copy a process and make your changes to the copied process first to avoid affecting existing projects and help you surface any negative effects of the process changes.

You can rename an inherited process in Organization Settings by selecting the More actions icon next to the process name and selecting Edit.

Process names

Process names have the following requirements:

  • Must be unique in the organization
  • Must have 128 Unicode characters or less
  • Can't contain any of the following characters: . , ; ' : ~ \ / * | ? " & % $ ! + = ( ) [ ] { } < >

Inherited and custom objects

Each inherited process inherits the WITs defined in the underlying Basic, Agile, Scrum, or CMMI system process. For example, processes that inherit from Agile provide Bug, Task, User Story, Feature, Epic, Issue, and test-related WITs.

You can add fields and modify the workflow and work item form for all WITs that display on the Work Item Types page of an inherited process. You can also add custom WITs.

If you don't want users to create new work items based on an inherited process WIT, you can disable it by selecting the More actions icon next to the WIT name in Organization Settings and selecting Disable from the context menu.

Work item fields

This section describes work item fields.

Fields and field references

You use work items to plan and track your project. Each work item type is associated with 31 system fields and several more type-specific fields that provide tracking information about the work items. Values you assign to a field are stored in the work tracking data store, which you can query to determine status and trends.

For descriptions and usage of each field defined for the core system processes Scrum, Agile, and Capability Maturity Model Integration (CMMI), see Work item field index.

Field names

A work item field name uniquely identifies each work item field. Make sure your field names meet these requirements:

  • Must be unique within the organization or project collection
  • Must be 128 or fewer Unicode characters
  • Must contain at least one alphabetic character
  • Can't contain any leading or trailing spaces, or two or more consecutive spaces
  • Can't contain any of the following characters: . , ; ' : ~ \ / * | ? " & % $ ! + = ( ) [ ] { } < >

Field names and definitions apply to the entire organization. You can't add a field with a field name that already exists in the organization or that another inherited process added to a WIT.

Field customizations

Fields are defined for all projects and processes in an organization. Inherited processes inherit the fields defined in system processes, and you can make limited modifications to them. You can create and modify custom fields in inherited processes.

You can add any custom field you define for a WIT in one process to any WIT defined for another process. You can also add an existing field to another WIT within the same process. For example, you can add Due Date to the User story or Bug WITs.

Customize fields and controls

The following resources describe how to implement various customizations for inherited fields, custom fields, or custom controls.

Inherited fields

Custom fields

Custom control

Delete or restore deleted fields

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 can hide or remove the field from a work item form. For details, see Show, hide, or remove a field.

Limitations

  • You can't change a field name or data type once you define it. However, you can change the label that appears for a field on the work item form from the Layout tab. When you select the field in a query, you must use the field name and not the field label.
  • You can't modify the gray area on the form that contains the State, Reason, Area path, and Iteration path fields.
  • The area paths and iteration paths picklists are configured for each project and aren't customizable through an inherited process.
  • Picklists associated with user identity fields, such as Assigned To and Changed By, are populated based on the users added to the project or team.
  • A maximum of 64 fields can be defined for each WIT and a maximum of 512 fields can be defined per process.
  • You can't import or define a global list as supported by the Hosted XML and On-premises XML process models.

Custom rules and system rules

Each WIT has several system rules defined, like requiring the Title field or setting a default for the Value Area field. System rules also define actions to take when a workflow state changes.

For example, several rules copy the current user identity to the Changed By field when a work item is modified or to the Closed By field when the workflow state changes to Closed or Done. Predefined system rules take precedence over any custom rules that would overwrite them.

Custom rules provide support for several business use cases, letting you go beyond setting a default value for a field or making it required. Custom rules allow you to clear the value of a field, copy a value into a field, or apply values based on dependencies between different field values.

With custom rules, you can define various actions based on specific conditions. For example, you can apply rules to support the following scenarios:

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

For more information about defining custom rules, see Add a rule to a work item type (Inheritance process).

Tip

You can't define a formula by using a rule. However, you might find a solution that fits your needs with Power Automate. For more information, see Rollup of work and other fields.

Restrict modification of select fields for select user groups

By using the conditions current user is a member of a group... or current user is not a member of a group..., you can require or configure selected fields for users who are members or nonmembers of a group or security group. For example, you can make the Title or the State field read-only for selected users or groups.

Restrict modification of work items based on area path

Consider maintaining single ownership of work items by team area path, or formalizing columns with custom states that are shared across teams.

You can disallow users from modifying selected work items by setting permissions on an area path. This setting isn't a rule, but a permission setting. For more information, see Create child nodes, modify work items under an area or iteration path.

Work item type customizations

The following resources describe customization options for inherited and custom WITs.

Inherited work item types

Custom work item types

Changing the default WIT for a backlog causes the WIT to appear by default in the quick add panel. For example, Custom Story appears by default in the following quick add panel for a product backlog.

Screenshot of the quick add panel with a default custom work item type.

Limitations

  • 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 change the name of a custom WIT once you define it.

Work item form customizations

You can make the following customizations to a WIT form:

Inherited groups

Custom groups

Inherited pages

Custom pages

Layout and resizing

The web form layout for a work item is organized into three columns, as shown in the following image.

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

If you only add groups and fields to the first two columns, the layout shows two columns. If you only add groups and fields to the first column, the layout shows one column.

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 in its own column. When the display width doesn't accommodate all columns, columns appear stacked within the column to the left.

As the display width decreases, the columns resize proportionally as follows:

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

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 used to create the custom process: Agile, Basic, Scrum, or Capability Maturity Model Integration (CMMI). For more information, see Workflow states, transitions, and reasons.

The 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.

Inherited and custom workflows must conform to the following rules:

  • Define at least two workflow states.
  • Define at least one state for either the Proposed or In Progress state categories.
  • Define a maximum of 32 workflow states per work item type.

Note

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

For customizations to inherited and custom workflow states, see the following resources:

Inherited states

Custom states

Limitations

  • You can't change the name, color, or category of inherited states, but you can hide them if you don't want them visible.
  • You can't change the names of custom states once defined.
  • You can't change or customize the default state category names.
  • Only one state can exist in the Completed state category. Adding a custom state to this category removes or hides any other state in that category.
  • You can't specify custom Reasons for state transitions. Use default reasons, such as Moved to state Triaged and Moved out of state Triaged.
  • You can't change the placement of the State and Reason fields on the work item form.

Backlog and board customizations

Backlogs and boards are essential Agile tools for creating and managing work for a team. The standard product, iteration, and portfolio backlogs inherited from system processes are fully customizable. You can also add custom portfolio backlogs up to a total of five portfolio backlogs.

For more information about customizing inherited and custom portfolio backlogs, see the following resources:

Inherited backlogs

Custom portfolio backlogs

Limitations

  • You can't remove an inherited portfolio level from a product. You can rename the level, or disable WITs to prevent teams from creating new work items of those types.
  • You can't insert a new custom backlog level within the existing set of defined backlogs. The predefined backlog levels are typically fixed, for example Epics, Features, User stories, and Tasks.
  • You can't reorder the backlog levels. They usually follow a predefined hierarchy, and changing the order isn't supported.
  • You can't add a WIT to two different backlog levels. Each WIT can belong to only one backlog level.
  • You can't create a custom task-specific backlog level, but 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.
  • The Bug WIT doesn't belong to any specific backlog level by default. Each team can decide how they want to manage bugs. You can choose to show bugs on backlogs and boards or handle them separately. For more information, see Show bugs on backlogs.

Related content

  • Last updated on