Migrating Scale Between Azure DevOps Projects
Summary:
Scale keeps two kinds of data separate. Your work item data (work items, hierarchy and relations, dependencies, WSJF values, history) will show up in the new project automatically, as long as the underlying Azure DevOps structure (area paths, iterations, teams, and parent-child links) is recreated first. Your Scale configuration (setup, board styling, team assignments, and each user's personal preferences) is stored per project and will need to be reconfigured in the new project. Plan for some setup time per workspace after the move.
Applies to: Scale for Azure DevOps, current release. This guide covers migrating within the same Azure DevOps organization (one project to another). Cross-organization migrations are not covered here.
Today, moving Scale between ADO projects is a manual process: there is no migration tool. This guide walks through what moves automatically, what you'll need to set up again, and a recommended order of operations.
- Re-creating area paths, iterations, and team structures and hierarchies in the new project for everything that is intended to be migrated.
- Migrating all work items to new project. The work items of particular importance to Scale: Agile Release Train, Program Increment, PI Objective, Risk and Dependency Request.
- Make sure the new project uses the same or equivalent process template and work item types as the source project. Scale specifically looks for the work item types mentioned in the previous point.
Scale reads from two separate layers of data:
| Layer | What it includes | Where it's stored | Moves with your work items? |
|---|---|---|---|
| Work item data | Work items, parent-child and other relations, area and iteration paths, team definitions, history | Read directly from Azure DevOps; Scale doesn't keep its own copy | ✅ Yes, if structure and links are preserved |
| Scale configuration | Initial configuration of project, team assignments to workspaces, all project scoped settings within the extension, personal preferences | Azure DevOps extension storage, scoped to each project | ❌ No, set up again in the new project |
Scale always reads your work item data live from Azure DevOps rather than storing its own copy. Keeping this in mind will make the rest of this guide easier to follow.
- If a PI doesn't appear under its Workspace/ART after migrating: this usually means the parent-child link between the PI and ART work item wasn't preserved during the move. Scale builds the ART to PI to Feature hierarchy entirely from these links, so double-check them if something looks out of place.
- If Scale shows a setup screen instead of your planning board: this is expected the first time you open Scale in a new project. It means the initial process configuration step (below) hasn't been completed yet.
Step 1: Set up initial Scale configuration in the new project
Scale's configuration is stored separately for each project, so this part needs to be done manually.The first time you open Scale in the new project, it'll prompt you to map your work item types to Scale's hierarchy (what counts as an ART, a PI, etc.). Nothing else will appear until this is done.
Step 2: What Shows Up Automatically
Once the structure above is in place and your work items have moved, the following happen without any extra setup:
| This... | ...will appear automatically | As long as |
|---|---|---|
| Workspaces (ARTs) | ✅ | Scale has been set up for the new project (Step 1) and the Agile Release Train work items are on the root area and iteration path of the new project |
| PIs under their ART | ✅ | The parent-child link to the ART was preserved for all Program Increment work items |
| Work items in the right sprint | ✅ | Iterations were migrated and items assigned correctly in the iteration hierarchy. Please note this requires that the teams have been reassigned to the workspaces. See step 3 |
| Dependencies | ✅ | The original ADO links were preserved. Also requires teams to be reassigned |
| Field values on work items | ✅ | These live on the work item itself and move with it |
Step 3: Additional manual configuration
None of Scale's configuration carries over automatically when you move to a new project. Configuration lives in three places: Azure DevOps extension storage shared across the project, extension storage scoped to each individual user, and custom fields on the ART work item itself. All three need to be set up again after migration.
Not in Extension Storage
This setting lives on the work item itself rather than in extension storage, so it follows a different path during migration.
| Setting | Where it lives |
|---|---|
| Team assignments per ART workspace | Custom fields on the ART work item (Custom.{artTeams}, Custom.{artDependentTeams}), including team order |
Team IDs in Azure DevOps are unique to each project, so they don't carry over to the new project. This means Custom.{artTeams} and Custom.{artDependentTeams} will still be pointing at team IDs that no longer exist in the new project. Even if the custom fields themselves are preserved on the ART work item, the team assignments will need to be reconfigured for each workspace using the new project's team IDs. The new project's teams are assigned in Scale in the planning view to each workspace. As with area and iteration paths, each team still needs to be assigned its own area and iteration paths for work items to connect to it correctly in the product.
Project Scope (Shared Across All Users)
These settings apply to the whole project and are typically configured once per workspace, not per person.
| Setting | Description |
|---|---|
| Process configuration | Work item type mappings (what is an ART, PI, Feature, Story). See step 1 |
| Board settings | Card styling rules, tag colors, field display, event markers, dependency visualization, working with cards mode. Per ART |
| Planning settings | Sprint length and number of sprints shown. Per ART |
| WSJF settings | Field mappings for the WSJF calculation |
| Objectives settings | Column configuration and sort settings. Per ART |
| Risks settings | Default area path and team area path configuration. Per ART |
| Dependencies settings | Dependency work item type, internal/PI dependency visibility, email notification preferences |
| ART ordering | Display order of ART workspaces on the planning page, stored as an array of ART work item IDs |
| Capacity indicators | Capacity values per sprint per team |
| Flow efficiency configuration | Shared analytics configuration for flow efficiency |
| ROAM board | Risk items placed on the ROAM board |
| Risk assessments board | Risk assessment board state |
User Scope (Per User, Per Project)
These settings are personal to each user and stored separately for every project. They can't be transferred in bulk, so each person on your team will need to reset their own after migration:
| Setting | Description |
|---|---|
| Board options | Compact cards, dependency visibility, child dependency visibility |
| Board filter bar | Active filter state on the planning board |
| Objectives filter bar | Active filter state on the objectives tab |
| Risks filter bar | Active filter state on the risks tab |
| Favorite workspaces | Which ART workspaces the user has marked as favorites, stored as ART work item IDs |
| Selected PI | Which PI the user last had selected |
| Analytics dashboards | Saved analytics dashboards |
| Selected dashboard | Which analytics dashboard the user last had open |
| Flow distribution configuration | Per-user analytics configuration for flow distribution |
It's worth letting your team know ahead of time that these will need to be reconfigured, so it isn't a surprise after the move.