How to move a Jira Integrated, Agile(Scrum) Team to a new Jira Align program
Summary
Moving a Jira Align Team from one Program to another, where the team is integrated to a Jira Board, can affect a number of items and settings, that such a team might directly or indirectly be linked to. Related items include:
The Program (and the relationship to a Jira Project)
The relationship of the Team to a Jira Board
Work Items (Stories, Features / Jira Epics etc)
Sprints
Program Increments (via the Program and Sprints)
Capabilities (via a Feature)
Portfolio Epics (via a Capability or via a Feature)
This article discusses two possible methods to move an integrated team (or the work items / issues for that team) between programs in Jira Align. The provided information is mostly intended for moves under a single Portfolio, however there is also a section covering considerations for moving Teams to Programs under a different Portfolio.
As both Jira and Jira Align permit a lot of variety in configuration, implementation and use, the steps provided cannot cover every possible scenario, so customers that have followed this article should monitor for unexpected behaviours and results as extra corrective steps may be required
Environment
Jira Align
Solution
It is recommended that, a move of a team between programs is performed on the boundary of starting a new Program Increment (PI)
Address any issues with synchronisation between Jira and Jira Align before moving a team between programs - if a Jira Epic or Story is failing to sync to Jira Align before the move this may cause complications that are difficult to resolve during or after the move
There are two potential methods to move the team (or team work items) between programs. 
The recommended method (and Best Practice) is Method 1 - this is because the details of this method came from Atlassian's Advisory Services team and this team has an in-depth understanding of how customers typically use Jira Align with Jira against their business practices
Method 1 - Move the Jira Work Items to New Projects (and Boards), and use new Program(s) and Teams in Jira Align
Key Points about Method 1:
If moving the Team(s) to a Program under a different Portfolio then use Method 1 (but also review the considerations section further down the document)
This method moves the outstanding (not Accepted / not Done) work items associated with the current program/team to a new program and team
As it uses a new team, it is not really a move of the team itself.
Requires additional configuration in Jira to create the new project(s), board(s) and sprint(s) and to move the work items
Configuration in Jira Align is then similar to setting up a new Jira Project for synchronization to Jira Align.
Both the old and new projects and boards remain in Jira after the move between programs is completed
Reporting data in Jira Align is separated between the old and new programs/teams but is otherwise fully available (excepting that any report that crosses the time frame of the move may be confusing)
Individual Jira Align Stories and Features relating to the old program will still be accessible (based on applied filters)
Method 2 - Adjust settings within Jira Align without creating new Projects and Boards in Jira
Key points about method 2:
Method 2 should not be used if the destination program already exists and is active against different PIs than those used in the original program - this is because the method tries to assign the original PI to the destination program in order to maintain existing sprints and would potentially result in parallel PIs for the same timeframe being applied to a single program (which should be avoided)
Method 2 should not be used if moving the Team(s) to a Program under a different Portfolio
Uses the existing Jira Project and Board configuration, so apart from some traffic through the connector has no impact on Jira
Reporting and chart information in Jira Align may be based on data from both programs, so can give an overall view instead of using data that is separated between the old and new programs
Data in Jira Align relating to previously completed work may not be included in some reports.
Any odd results in report and chart data will clear up once a new PI is started - unless the report spans PIs
Individual Jira Align Stories and Features relating to the existing program will still be accessible (depending on applied filters)
This method continues to use the existing Jira Align PIs and existing Sprints after the move
Method 1 - Steps
The steps for Method 1 are discussed in the answer provided in https://community.atlassian.com/t5/Jira-Align-questions/What-are-the-implications-of-moving-a-team-from-1-train-to/qaq-p/1339252 a more detailed version is provided in this article
This method has been split into 3 phases, please expand them to see the individual steps
Accepted/Done stories and epics/features will not be moved. Where possible try and and complete any that are in Dev/Test Complete status so that they also don’t need moving
In Jira, move any Not Started epics/features with their child stories, and any not completed, stand-alone stories to the Unassigned Backlog of the new project(s) - preferably by removing the assigned sprints from the stories before moving them.
If applicable, features should be moved to the Program Project and stories to appropriate Team Projects. After the move members of the teams can then assign the stories to correct sprints in the new board(s).
Don't use sprints created in the original boards! This causes a corrupted/crossed sprint situation.
After synchronisation has taken place:In Jira Align: Update the features' details panel with a suitable PI or decide to keep them in the unassigned backlog
In Jira Align: Verify that stories are assigned to the appropriate team, sprints and still linked to the feature.
For any In Progress epics/features (and their child stories)
In Jira, create a new epic and assign it to the correct/new Program Project
In Jira Align, assign the new feature (once synchronized) to the relevant PI or to the Unassigned Backlog
In Jira, move any not completed child stories of the epic to the Unassigned Backlog of the appropriate new project(s), then assign those stories to the new epic, appropriate sprints and, if applicable, set a new team in the custom field for the teams.
Once all not completed, child stories have been moved from the original epic/feature then mark that original epic/feature as Done/Accepted
Leave all completed child stories under their original epic (as neither the original epic or such stories will be moved)
In Jira Align check that:
no affected features are still assigned to future PIs for the original Program
no affected stories are assigned to future sprints
only accepted features/stories remain linked to the original team(s)
Method 2 - Steps
If using a configuration where Epics are contained in a Jira Program Project and Stories are maintained in one or more separate Jira Team Projects then these steps will need to be taken for all of the individual connected projects
In Settings/Administration > Programs, create or identify the destination program
If Epics are connected to any of the Features (including via a Capability) , then set the Primary Program in the Epic to the destination Program and add the original program as an Additional Program (change both before clicking Save)
If Capabilities are connected to any of the Features, then set the Primary Program in the Capability to the destination Program and add the existing program as an Additional Program (change both before clicking Save).
- If steps 2 and 3 are NOT performed and Capabilities are being used, then it is possible that if a user updates a feature (such as setting a new state) that the link between Feature and Capability will be deleted.
In Items > Program Increments (or in the old Navigation Program > (Manage) +Show All > Program Increments), open the details of any affected, past, current or future Program Increments, click the Programs, Products and... tab to add the new program to the Programs box (don't remove any existing programs and make sure to click on Save when done)
- This step can only be done if the destination program does not already have a different active PI covering the same timeframe as you should not have parallel PIs. If there is an active, existing, different PI for the same timeframe already set against the destination Program then it is recommended you switch to using Method 1
If the PIs in the destination are already linked to both programs then you can continue with this process.
Temporarily disable bidirectional sync: In Settings/Administration > Jira Settings > Jira Setup , change the following settings:
Prior to making these changes, take note of the current settings (you’ll need them later, for configuration restoration)
- Allow feature (jira epic) sync from Jira Align to Jira = Jira to Jira Align sync
- Allow story sync from Jira Align to Jira = Jira to Jira Align sync
- Allow Jira to overwrite Jira Align if two simultaneous syncs conflict = YES
Save settings
- WARNING: During steps 7 through 15, Jira Align users should avoid make any changes to the features or stories while they are still linked to the old program, as any update in Jira Align during the process will probably be reverted to match the content of Jira. Disabling bidirectional sync (above) should reduce the chances of seeing the error: "No changes were pulled in from Jira because there is a Jira Align update waiting to be pushed to Jira.", however this error may also be seen if changes are being made in Jira Align.
In Settings/Administration > Jira Management, identify the entry for the Jira Board linked to the team and make a note of the Jira Board ID and the exact Jira Align Team name, and then delete the entry
In Settings/Administration > Jira Settings, identify the entry linked to the original program, click on the Project key for the entry and change the Program to the New Program
In Settings/Administration > Jira Management, add the board back into the configuration, but specify the new project name, with the original Jira Align Team name ( from Step 7 )
Give time for the yellow triangle against the board to disappear (a screen refresh should eventually show it has gone)
In Team > View All Teams (or in the old Navigation, Team > (Manage) +Show All > Teams), open the details of the affected Agile Team (from step 7) and change the program for that team to the destination program.
In Settings/Administration > Jira Settings > Resync configuration, click on Configuration data pull. Wait at least 10 minutes and refresh the screen until the button re-appears
- In Settings/Administration. > Jira Settings > Jira Integration set the Projects correctly, add a filter for Epics or Stories, and set the Boards to Sync entry and click Run
Allow time for this to run (at least 10 minutes, longer if there are lots of features and stories involved) and then check to see if features and stories have changed their programs.
The locked program for features and stories should automatically change to the new program, if any features or stories remain locked against the old program, then check the audit logs for synchronization issues and troubleshot any specific errors.
- Undo the changes made in Step 5 (Re-enable bidirectional sync)
In Items > Sprints (or in the old Navigation Team > (Manage) +Show All > Sprints), set filters to include both the original and new programs and check for the current and future sprints for the team.
Open the details of any past, current or future sprint that is set to the original program and change the program to the destination program
Considerations for Moving a Team to a destination program in a different Portfolio
As Portfolios may have configuration differences relating to Portfolio Specific Configurations and Work Item Details Panels it may not be appropriate to move a team to a different portfolio and the following items must be considered
Do both portfolios use (or both not use) capabilities or the solution layer
- Are the estimation methods the same or different
- Do both portfolios use Feature Product Field
Are the fields shown on the work items the same between portfolios (as configured in Details Panel Settings)
If you have custom fields, are they the same between portfolios
- Do you want the program to continue to use the same PI in the new Portfolio