Customize the workflow (Inheritance process)

  • Article

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

Each work item type (WIT) has an associated workflow that tracks the status of work from creation to completion. To align with your business and team processes, you can add custom states to most WITs. For example, you might add a Triaged state for bugs or a Design state for features or user stories.

In the following example, we customized the Bug WIT to include a Triaged state. The state and reason fields are displayed in the header area of the work item form.

Screenshot of Bug work item form, header area, added state.

For documentation on the workflow for build and release DevOps tasks, see Use Azure Pipelines.

Important

The Inheritance process model is available for projects configured to support it. If you’re using an older collection, check the process model compatibility. If your on-premises collection is configured to use the on-premises XML process model, you can only use that process model to customize the work tracking experience. For more information, see Choose the process model for your project collection.

Supported 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—Agile, Basic, Scrum, or CMMI—you selected 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. 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 icon Inherited states

Custom states

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 Workflow states and state categories 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 will remove or hide 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.
  • 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; the system disallows adding any custom state to this category.
  • Keep the name of custom states as is; you can't change them.
  • Accept the natural sequence of states in the drop-down list on the work item form; you can't change their order.
  • 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.
  • Allow transitions from any state to another; you can't restrict transitions.

State drop-down menu sequence

The State drop-down menu lists states in the order you define within each state category. For newly added work items, the first state in the Proposed category is assigned as the default state.

The following image illustrates the state sequence defined for a User Story and its corresponding drop-down menu.

Screenshot of User story state sequence.      Screenshot of User story State drop-down menu.

Within each category, you can move custom states up or down.

Affect to teams with workflow changes

Update board configuration

Teams should update their board configuration when making the following customizations:

Taskboard configuration

  • Add states to the task WIT, which adds columns to the Taskboard.
  • Track bugs along with tasks, adding states to the bug WIT, which also adds columns to the Taskboard.
  • Add the same states to both task and bug WITs, which updates the status consistently and minimize the number of columns added.

Prerequisites

Check out Configure and customize Azure Boards, which offers guidance on tailoring Azure Boards to align with your specific business requirements.

  • Organization requirement: Ensure you have an organization in Azure DevOps.

  • Permissions:

    • Be a member of the Project Collection Administrators group.
    • Have collection-level permissions such as Create process, Delete process, Edit process, or Delete a field from organization set to Allow.
    • These permissions allow you to modify processes and fields within your organization.

  • Project process model requirement:

  • Permissions:

    • Be a member of the Project Collection Administrators group.
    • Have collection-level permissions such as Create process, Delete process, Edit process, or Delete a field from organization set to Allow.
    • These permissions allow you to modify processes and fields within your organization.

Open organization process settings

  1. Sign in to your organization (https://dev.azure.com/{yourorganization}).

  2. Select gear icon Organization settings.

    Screenshot showing Organization settings button highlights.

  3. Select Process.

    Screenshot showing highlighted Process button for selection.

  1. Sign in to your collection (https://dev.azure.com/{Your_Collection}).

  2. Select Collection Settings or Admin settings.

  3. Select Process.

    Screenshot showing highlighted Process button in Collection settings.

Note

When you customize an inherited process, any projects using that process automatically reflect the customizations. To ensure a smooth transition, we recommend creating a test process and project, which allows you to test your customizations before you implement them organization-wide. For more information, see Create and manage inherited processes.

Add a workflow state

States you add appear in the drop-down menu for the States field shown in work item forms and the query editor. A transition to and from the State you add is created to every other State. Also, default reasons are defined, such as Moved to state Triaged, Moved out of state Triaged.

  1. From the Work Item Types page, choose the work item type you want to modify, choose States, and then choose New State.

    Screenshot of Process page, Bug WIT, States tab, Add state.

    If the New state option is disabled, you don't have the necessary permissions to edit the process. See Set permissions and access for work tracking, Customize an inherited process.

  2. Enter the name of the State, choose its category and color, and then select Save. The color you specify appears throughout the product including on the work item form and when the State field appears on a backlog, boards, query results, and more.

    Screenshot of State menu in work item form.

    Note

    Any workflow state you add to the In Progress or Resolved state categories will cause the Activated By/Activated Date and Resolved By/Resolved Date fields to update with workflow state changes in and out of these categories. For more information, see Query by assignment or workflow changes, Activated By/Date and Resolved By/Date fields.

  3. (Optional) To change the sequence of the State within the drop-down menu, choose the context menu icon and choose Move up or Move down.

    Screenshot of Move up State.

  4. When you're done adding states for the WIT, verify your changes by refreshing your browser and open a work item of the type you customized.

    Here we show the State drop-down menu with Triaged selected.

    Screenshot of Bug form, Triaged state added.

  5. Remember, when you add a State to a WIT, which is associated with a backlog level, each team that uses the board needs to update their column settings.

Edit a state

You can edit the category or the color of a custom state. However, you can't change the name of the custom state.

  1. Select Edit from the … context menu for the state you want to modify.

    Screenshot of Bug WIT, Edit custom state.

  2. Modify the category or color, and then choose Save.

  3. If you change the category, teams that use the board need to update their column settings.

Hide or remove a custom state

When you hide or remove a state:

  • The state no longer appears in the State drop-down menu for the WIT
  • No changes occur to the work item history
  • Existing work items maintain their state value, but are in an invalid state. If you want to make a change to the work item, you must first update the state values. You might want to create a query and do a bulk update to move the affected work items into a valid state. If you add the state back to the work item type, the work items revert to a valid state.

Hide or unhide an inherited state

You can hide an inherited state that your team doesn't use in its workflow process. However, you must have at least one state defined for each category.

  1. Open the … context menu for the state you want to hide and choose the Hide option.

    Here we hide the Resolved state for the Bug WIT.

    Screenshot of Hide an inherited state.

    Note

    If you hide the state of a WIT tracked on a board, each team that uses the board needs to update their column settings.

  2. To unhide, open the … context menu and choose the Unhide option.

Remove a custom state

  1. Open the … context menu for the state you want to remove, and choose Remove. You can only remove a custom state.

  2. From the Remove State dialog, select Remove.

    Screenshot of Remove state warning dialog box.

View the State workflow model

You can view the State workflow model by installing the State Model Visualization Marketplace extension. This extension adds a new hub under Boards labeled State Visualizer. On that page you can choose a work item type and view the workflow state model.

Note

The State Model Visualization extension is not supported by Azure Boards or the product team. For questions, suggestions, or issues, please visit the extension page.

For example, you can customize the Bug workflow to have a Triaged state and all states can transition from one state to another.

You can zoom in and zoom out of the view. Also, you can move the state nodes around to gain a better view of the state model.

Next steps

Review changes made to an inherited process through the audit log