Move work items from one team to another team

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

Introduction

When you add a team or reorganize existing teams, you might need to transfer work items from one team to another by updating their Area Paths. Every work item in Azure DevOps is assigned to an Area Path, which determines team ownership and influences how work items are displayed on backlogs and boards.

Work items categorized under the Requirements category appear on a team's backlog based on their assignment to the team's Area Path. Similarly, assigning other work items to a team's Area Path supports queries and reporting based on team ownership.

Prerequisites

  • Project access: Be a project member.

  • Permissions:

    • To view, follow, and edit work items, have View work items in this node and Edit work items in this node permissions set to Allow. By default, the Contributors group has these permissions. For more information, see Set work tracking permissions.
  • To add tags to work items, have the project-level Create new tag definition permission set to Allow. By default, the Contributors group has this permission.

  • Access levels:

    • To add new tags to work items or to view or follow pull requests, have at least Basic access.
    • To view or follow work items, have at least Stakeholder access. For more information, see About access levels.
    • All project members, including those in the Readers group, can send emails containing work items.

    Note

    • Provide Stakeholder access to members who want to contribute to the discussion and review progress. These are typically members who don't contribute to code, but want to view work items, backlogs, boards, and dashboards.
    • Stakeholders can't add new tags, even if the permission is explicitly set, due to their access level. For more information, see Stakeholder access quick reference.
  • Area Path permissions: Have permissions to view and edit work items under the Area Path nodes. For more information, see Modify work items under an area or iteration path.
  • Configured area paths: Ensure that the target team has its Area Paths correctly configured. If not, set up the required Area Paths before transferring work items.
  • Consistent process model: Teams should be using a compatible process model (Inherited, Hosted XML, or On-premises XML) to ensure seamless movement of work items.
  • Backup work items: We recommend you back up or export work items before performing bulk moves to prevent data loss if there's an error.
  • Tools: To use Azure CLI commands, install Azure CLI as described in Get started with Azure DevOps CLI.
  • Project access: Be a project member.

  • Permissions:

    • To view, follow, and edit work items, have View work items in this node and Edit work items in this node permissions set to Allow. By default, the Contributors group has these permissions. For more information, see Set work tracking permissions.
  • To add tags to work items, have the project-level Create new tag definition permission set to Allow. By default, the Contributors group has this permission.

  • Access levels:

    • To add new tags to work items or to view or follow pull requests, have at least Basic access.
    • To view or follow work items, have at least Stakeholder access. For more information, see About access levels.
    • All project members, including those in the Readers group, can send emails containing work items.

    Note

    • Provide Stakeholder access to members who want to contribute to the discussion and review progress. These are typically members who don't contribute to code, but want to view work items, backlogs, boards, and dashboards.
    • Stakeholders can't add new tags, even if the permission is explicitly set, due to their access level. For more information, see Stakeholder access quick reference.

Move work items under teams

To move work items under a team, do the following steps:

  1. Create a query of all work items you want to reassign.

  2. Multi-select those items, which belong to each team, and bulk edit the area path.

    Screenshot of Web portal, Queries page, Bulk modify select work items.
  3. After you bulk modify, bulk save.

    Screenshot of Bulk save edited work items.

Move a work item using Azure CLI

You can use the az boards work-item update to move a single work item by updating its Area Path.

az boards work-item update --id
                           [--area]
                           [--assigned-to]
                           [--description]
                           [--discussion]
                           [--fields]
                           [--iteration]
                           [--open]
                           [--reason]
                           [--state]
                           [--title]

Parameters

  • id: Required. The ID of the work item to update.
  • area: Optional. Absolute path of an area. Example: --path \ProjectName\Area\AreaName.
  • assigned-to: Optional. Name of the person the work item is assigned to Jamal.
  • description: Optional. Description of the work item.
  • discussion: Optional. Comment to add to a discussion in a work item.
  • fields: Optional. Space separated "field=value" pairs for custom fields you want to set.
  • iteration: Optional. Absolute path of an iteration. Example: \ProjectName\Iteration\IterationName.
  • open: Optional. Open the work item in the default web browser.
  • reason: Optional. Reason for the state of the work item.
  • state: Optional. State of the work item, for example, Active.
  • title: Optional. Title of the work item.

Example

You can only move one work item at a time using Azure DevOps CLI. In this example, we move work item ID=148 under the Fabrikam Fiber\Production Planning area path.

az boards work-item update --id 148 --area "Fabrikam Fiber\Production Planning" --output yaml

The following YAML output provides information on each of the fields defined for the work item.

fields:
  Microsoft.VSTS.Common.Priority: 2
  Microsoft.VSTS.Common.StackRank: 1500000001.0
  Microsoft.VSTS.Common.StateChangeDate: '2021-11-23T22:26:28.27Z'
  Microsoft.VSTS.Common.ValueArea: Business
  System.AreaPath: Fabrikam Fiber\Production Planning
  System.AssignedTo:
    _links:
      avatar:
        href: https://fabrikamprime.visualstudio.com/_apis/GraphProfile/MemberAvatars/aad.NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
    descriptor: aad.NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
    displayName: Jamal Hartnett
    id: d291b0c4-a05c-4ea6-8df1-4b41d5f39eff
    imageUrl: https://fabrikamprime.visualstudio.com/_apis/GraphProfile/MemberAvatars/aad.NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
    uniqueName: fabrikamfiber4@hotmail.com
    url: https://spsprodeus27.vssps.visualstudio.com/A5d5b8da6-3db7-4829-baf9-1e500c21cc12/_apis/Identities/d291b0c4-a05c-4ea6-8df1-4b41d5f39eff
  System.BoardColumn: Backlog
  System.ChangedBy:
   _links:
      avatar:
        href: https://fabrikamprime.visualstudio.com/_apis/GraphProfile/MemberAvatars/aad.NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
    descriptor: aad.NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
    displayName: Jamal Hartnett
    id: d291b0c4-a05c-4ea6-8df1-4b41d5f39eff
    imageUrl: https://fabrikamprime.visualstudio.com/_apis/GraphProfile/MemberAvatars/aad.NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
    uniqueName: fabrikamfiber4@hotmail.com
    url: https://spsprodeus27.vssps.visualstudio.com/A5d5b8da6-3db7-4829-baf9-1e500c21cc12/_apis/Identities/d291b0c4-a05c-4ea6-8df1-4b41d5f39eff
  System.ChangedDate: '2022-05-19T22:58:52.93Z'
  System.CommentCount: 0
  System.CreatedBy:
   _links:
      avatar:
        href: https://fabrikamprime.visualstudio.com/_apis/GraphProfile/MemberAvatars/aad.NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
    descriptor: aad.NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
    displayName: Jamal Hartnett
    id: d291b0c4-a05c-4ea6-8df1-4b41d5f39eff
    imageUrl: https://fabrikamprime.visualstudio.com/_apis/GraphProfile/MemberAvatars/aad.NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
    uniqueName: fabrikamfiber4@hotmail.com
    url: https://spsprodeus27.vssps.visualstudio.com/A5d5b8da6-3db7-4829-baf9-1e500c21cc12/_apis/Identities/d291b0c4-a05c-4ea6-8df1-4b41d5f39eff
  System.CreatedDate: '2021-11-23T22:26:28.27Z'
  System.Description: <div>This user story is for documentation purposes.&nbsp; </div>
  System.IterationPath: Fabrikam Fiber\Release 2\Sprint 1
  System.Reason: New
  System.State: New
  System.TeamProject: Fabrikam Fiber
  System.Title: Test the Request feedback functionality
  System.WorkItemType: User Story
  WEF_10182DA5BCCD4CE2A43629FFBD290EF2_Kanban.Column: Backlog
id: 148
relations:
- attributes:
    isLocked: false
    name: Child
  rel: System.LinkTypes.Hierarchy-Forward
  url: https://fabrikamprime.visualstudio.com/854a3f67-9962-43d1-a968-2e5f2eb66c99/_apis/wit/workItems/152
- attributes:
    isLocked: false
    name: Child
  rel: System.LinkTypes.Hierarchy-Forward
  url: https://fabrikamprime.visualstudio.com/854a3f67-9962-43d1-a968-2e5f2eb66c99/_apis/wit/workItems/153
- attributes:
    isLocked: false
    name: Child
  rel: System.LinkTypes.Hierarchy-Forward
  url: https://fabrikamprime.visualstudio.com/854a3f67-9962-43d1-a968-2e5f2eb66c99/_apis/wit/workItems/151
- attributes:
    isLocked: false
    name: Child
  rel: System.LinkTypes.Hierarchy-Forward
  url: https://fabrikamprime.visualstudio.com/854a3f67-9962-43d1-a968-2e5f2eb66c99/_apis/wit/workItems/149
rev: 5
url: https://fabrikamprime.visualstudio.com/854a3f67-9962-43d1-a968-2e5f2eb66c99/_apis/wit/workItems/148

Verify your team backlog

After you move work items from one team to another team, check your team backlog to ensure the items appear. For more information, see Create your backlog.

If you encounter any problems, review Set up your project's backlogs and boards.