Change a project process from Basic to Agile

Azure DevOps Services | Azure DevOps Server 2020

You can change a project based on the Basic process to use to use an inherited Agile process. This article provides the steps needed to make this change.

Prior to making this change, we recommend you familiarize yourself with the process you are changing to. The Task and Epic work item types are the same for both Basic and Agile processes. Most State and Reason field values, however, are different.

  Process Work item types Workflow
Basic Basic work item types basic workflow
Agile Agile work item types Agile workflow

For an overview of all processes, see Choose a process.

Reasons you might want to change your process from Basic to Agile:

  • You want to track code defects using bugs separate from issues and user stories
  • You want to use the Agile workflow states in place of those defined for the Basic process
  • You want access to both Feature and Epic portfolio backlogs to organize your work items
  • Your organization is requiring everyone to standardize their tracking with a customized inherited process based on the Agile process.


If you have existing work items, this process requires manual updates to work items and board configuration. Make sure you follow the steps provided in this article to ensure you address the manual steps required after you change the process used by a project.


Open Settings>Process

You create, manage, and make customizations to processes from Organization settings>Process.

  1. Choose the Azure DevOps logo to open Projects. Then choose Organization settings.

    Choose Organization settings.

  2. Then, choose Process.

    Choose Process.


    If you don't see Process, then you're working from TFS-2018 or earlier version. The Process page isn't supported. You must use the features supported for the On-premises XML process model.

You create, manage, and make customizations to processes from Collection Settings>Process.

  1. Choose the Azure DevOps logo to open Projects. Choose the project collection whose processes you want to customize, and then choose Collection Settings.

    Choose Organization settings.

  2. Then, choose Process.

    Choose Process.

Change the process

  1. Choose the process that contains the project you want to change. To change from Basic to Agile, choose Basic.

    Choose the Basic process

  2. Choose Projects.

    Choose Projects tab

  3. For the project you want to change, choose the actions icon and select Change process and follow the steps in the wizard.

    Choose Change process

  4. Choose the Agile process that you want to change to and then choose Save. You can select the system Agile process or an inherited Agile process.

    Step 1 of 3 of change process dialog, Choose the process

  5. Upon completion, the wizard displays the following information. Make a note of the steps to follow and then choose Close.

    Step 3 of 3 of change process dialog

Steps to manually update your work items and board settings:

  • Update the column to state mapping for each team Kanban board
  • Update existing work items using the work item types set by the target process
  • Update existing work items using the correct state model of the target process.

Update Kanban board column-to-state settings

You can customize Kanban boards to display intermediate columns. For each column added, you must choose a valid workflow state for the work item types displayed on the board. To learn more, see Workflow states & state categories.

  1. For each team, open your Kanban board.

    Open team Kanban board

  2. Choose the Correct this now link or the gear icon to configure the board settings.

    The Settings dialog opens. Those tabs that display a required icon need correction.

    Columns dialog

    Rename each column and choose the correct state for each column so that the column-to-state mapping is correct. As needed, add one or more columns. When done, choose Save and close.

    Columns dialog, corrected

Update work items

Your next step is to bulk update work items. The recommended sequence is:

  • Create a work item query that displays all work items
  • Perform a bulk update to change the work item type of Issue work items to User Story
  • Perform a bulk update on all States to change from Basic states—To Do, Doing, and Done—to Agile process states—New, Active, and Closed.
  1. Create a query to get a list of all Issues, Tasks, and Epics.

    Query all items

  2. Choose the actions icon and then select Column options. Choose to show the State and Reason fields. Choose the Sort tab, and set it to sort the list by work item type and state value.

    Column options dialog, sort tab

  3. Choose Results to just show the list of work items.

  4. Highlight all Issues, choose the actions icon, select Change type, and change the type to User Story.

    Change type dialog

    For more details, see Move, change, or delete work items, Change the work item type.

    Choose the actions icon and select Save items.

    It's possible that you will receive errors where the work item type and the state are mismatched. In that case, you can't save your changes until you update the state as described in the next step.

    Error state of changed work item type

  5. Sort the work items by the State column, highlight all work items of the same State, such as Doing, choose the actions icon, and then select Edit. Add the State field and select Active for the value. For details, see Bulk edit work items.

    Edit work item dialog

  6. Choose the actions icon and select Save items.

  7. Repeat these steps for the Done state, changing to Closed; and the To Do state, changing to New.

  8. When done, make sure you save all your changes. Choose the actions icon and select Save items.

Verify your changes

  1. Go to your team backlog and review the user stories.

    View team backlog

    If you want to change any user stories to bugs, do that now using bulk update and Change type. If you want to show bugs at the same level as user stories, then make that change now. For details, see Show bugs on backlogs and boards.

  2. Go to your team board and verify that the column settings are valid.

    View team board

    To add columns or change column names, see Add columns to your Kanban board.

Optional updates

After changing the process, you may want to make additional updates as follows: