Change a project process from Basic to Agile

Article
03/01/2022
5 minutes to read

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020

You can change a project based on the Basic process 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
Agile

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.

Important

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.

Prerequisites

To change a process:
- To create, delete or edit a process, you must be a member of the Project Collection Administrators group, or have the corresponding collection-level permissions Create process, Delete process, Edit process, or Delete a field from organization set to Allow. See Set permissions and access for work tracking, Customize an inherited process.
- Users granted Basic or Stakeholder access can be granted permissions to create, edit, and delete processes, and administer process permissions.
To update Kanban boards, you must be the team administrator for the boards or a member of the Project Administrators group
To update and change the work item type of existing work items, you must be a member of the project.

Open Settings>Process

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

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

Important

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.

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

Change the process

Choose the process that contains the project you want to change. To change from Basic to Agile, choose Basic.
Choose Projects.
For the project you want to change, choose the actions icon and select Change process and follow the steps in the wizard.
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.
Upon completion, the wizard displays the following information. Make a note of the steps to follow and then choose Close.

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.

For each team, open your Kanban board.
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.

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.

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.

Create a query to get a list of all Issues, Tasks, and Epics.
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.
Choose Results to just show the list of work items.
Highlight all Issues, choose the actions icon, select Change type, and change the type to User Story.

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.
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.
Choose the actions icon and select Save items.
Repeat these steps for the Done state, changing to Closed; and the To Do state, changing to New.
When done, make sure you save all your changes. Choose the actions icon and select Save items.

Verify your changes

Go to your team backlog and review the user stories.

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.
Go to your team board and verify that the column settings are valid.

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: