Migration guide
With the future release of Portfolio for Jira 3.0, Portfolio for Jira will no longer support the use of classic plans. When we release this version, you will no longer be able to access or update any of your classic plans. We recommend to start planning your migration to the new experience.
If you have any issues or concerns, let us know via portfoliofeedback@atlassian.com.
In this section, you will learn how to migrate from a Portfolio for Jira classic plan to the new planning experience. Depending on the size of your plan, this can be quite a lengthy, involved process, so this guide is intended to provide simple step-by-step instructions to help migrate your data.
How do you know you're using a classic plan?
The easiest way to determine whether or not you're using a classic plan is based on the positioning of the timeline. Classic plans have the timeline positioned at the bottom of your planning workspace.
Sample classic plan
Portfolio for Jira 2.0 plans, which are also known as live plans, have the timeline positioned at the top.
Sample 2.0 live plan
In the new planning experience, the timeline is now positioned at the right of the scope section. This provides a more intuitive experience, where you can view your roadmap directly beside the data that corresponds to it.
Sample plan in the new experience
Why should I migrate to the new planning experience?
The new planning experience offers a new way to visualize, groom, and communicate your roadmaps. Today, it includes the following features and more:
- A complete refresh of the plan layout, making it easier to see the data that powers your roadmap
- New drag-and-drop scheduling functionality, with enhanced coloring and grouping options
- Improved dependency tracking, to instantly surface conflicting blockers for early and efficient resolution
Plans in the new experience are regularly being updated with more great features, with every version we release. Keep an eye on our release notes, to know what we're releasing with each version in the future.
Before you begin
To migrate to the new planning experience, you'll first need to migrate your classic plan data into a Portfolio for Jira live plan. Once you have your live plan ready, you can then easily enable the new experience in that plan.
This is necessary because the new planning experience is only available as an early access feature, and can only be enabled through an existing live plan.
In the future, when we make the new experience the default interface in all plans, classic plans will no longer be accessible.
Things to consider before you migrate
To migrate to the new experience, you'll need to be using Portfolio for Jira version 2.21 or later. This is needed to enable the early access features of the new experience.
After migrating to the new experience, you'll need to reconfigure the following items for each new plan:
| Initiative relationship | Initiative ↔ epic relationships will not be automatically set when migrating to the new experience. Issue links are created between epics and initiatives in the Jira ticket itself, but you'll need to reset the initiative for all your epics. |
| Team data | Teams, team members, availabilities, and velocities will not be migrated over to the new experience. You'll need to create the teams, add members, and configure other team settings as needed. Also, individual availabilities are no longer supported in the new experience. |
| Plan configurations | Configurations of your plan, such as default estimates, will not carry over during your migration. They will need to be reconfigured once your migration to the new experience is complete. |
| Sprint assignment | Sprint assignment works a bit differently in the new experience. You first need to assign a team to each board issue source in your plan. The selected team will then be assigned to the sprints of each corresponding board. If you have sprints in your classic plans that you want to be available when you migrate to the new experience, then you'll need to create these sprints in Jira. You then need to assign teams to the corresponding board issue sources. The selected teams will then be assigned to the board sprints accordingly. The advantage of sprints in the new experience is that these are the actual sprints in Jira. This way, you can directly plan and groom your actual sprints in Portfolio for Jira. |
The following items will not be migrated and cannot be reconfigured in the new experience:
| Earliest start dates | We're simplifying the experience of scheduling issues by using only one type of date — target dates. This is why earliest start dates are no longer available in the new experience. You can still use other custom date fields that you may have configured before enabling the new experience. However, you'll first need to add these custom fields to your plan. |
Scheduled start and end dates | The calculated dates from classic plans won't be directly accessible in the new experience. The dates will need to be reproduced by either:
Note that the date fields used in the new experience are called target dates, and these can be accessed and updated in both Jira and Portfolio for Jira. |
| Stages and skills | Stages and skills are not supported in the new experience for the following reasons:
|
| Themes | Themes are no longer available in the new planning experience. Instead, we're replicating much of its value by providing flexible coloring options for labels and other custom fields. |
| Future sprints | At this stage, we're not considering implementing the functionality of future sprints in the new experience. |
Why should you migrate?
The new planning experience offers multiple advantages over classic plans. Most importantly, however, is the fact that the new planning experience relies on real-time, dynamic data directly from Jira. Meanwhile, in classic plans, data is stored independently.
Rather than having to import data from Jira to a classic plan, the new experience lets you define projects, boards, or filters as issue sources. With issue sources configured, real-time data is automatically surfaced in the new experience, and you can quickly save any changes you make in your plan back to Jira.
How to migrate from a classic plan to the new planning experience
The following steps are written with the assumption that the data in your classic plans are not linked to Jira. So, if you're already further along the process, jump to the relevant step:
- Create projects or boards to store collections of classic plan issues
- Create linked issues for each project
- Create and link releases to fix versions (optional)
- Apply additional data
- Create a 2.0 live plan
- Enable the new planning experience
- Reconfigure missing data
1. Create projects/boards to store collections of classic plans issues
You first have to choose how you want to group your issues into separate projects. Ideally, you should group your issues by release streams, but you can also group by teams.
a) Create a new project for each of the issue groups, for example, one project per release stream.
b) In the project creation dialog, create a Scrum or Kanban board, depending on how your teams work. Scrum boards are the most recommended issue source because Portfolio for Jira can make use of the velocity of past sprints to determine team velocity.
c) If you’re using initiatives, we recommend you create a Kanban project to store all these initiatives. In the settings for this project, remove all other issue types, and create a new issue type for initiatives.
New planning experience - Infinite hierarchy levels
This is also a good time to create the initiative level of hierarchy. You can create infinite levels of hierarchy in the new planning experience. However, it only goes as high as the epic level by default.
2. Create linked issues for each project
Once you’ve created your projects, it's time to create and link issues in Jira from your classic plan issues. This process will create a Jira version of all your issues, and store them in Jira projects.
Before you complete the following steps, make sure to enable the Issue Link column in your classic plan.
Sample classic plan, with the issue link column enabled
a) Add initiatives
- If you're using initiatives, start off by creating and linking issues for these initiatives. Set the view to Initiatives, and for the first issue, click the Issue Link drop-down > Create and link new issues.
- In the dialog, select the project you created for your initiatives. Clear the Create issues for all related items checkbox (you only need to do this for this initiative step), and then click Create and link issues.
- Do this for each initiative.
b) Add epics and stories
Once you have all your initiatives stored as linked issues in Jira, go ahead and do the same for all your epics and stories.
- In your classic plan, filter by the grouping you decided on earlier — for example, by release stream.
- For each epic in the filtered scope, click the Issue Link drop-down > Create and link new issues. Make sure to select the relevant project you've created for this filtered group.
- Select the Create issues for all related items checkbox, so that the epic and all its stories are linked to Jira tickets. Make sure that none of the initiatives are selected, as they are already stored in a separate project.
- Repeat this process for each project grouping. When completed, review all your issues and make sure they have an issue link.
- This will take some time if you have a lot of initiatives or epics in your plan.
- Make sure you have the correct project selected in the issue link. If you create the issue in the wrong project, you'll need to manually delete these issues from the project to set it right.
3. Create and link releases to fix versions (optional)
This step is recommended if you want to transfer all your releases into the new plan as well.
You can create linked fix versions in each of your projects from your classic plan. In the Releases tab, for each release, hover over the release name until a drop-down appears. Click the drop-down > Create and link new versions. In the dialog, select the relevant project, and click Create and link versions.
You can also link your classic plan releases with existing fix Versions you may already have in your projects. To link a release with an existing fix Version, go to the Releases tab in your classic plan. Expand the streams and use the Version Link drop-down, to associate each release to the corresponding fix versions you created in the Jira projects.
Example: Each stream maps to a project, and each release stream maps to the fix versions in the linked project.
Sample classic plan, with version links
4. Apply additional data
a) Once all your issues and releases have been linked, you'll need to apply some additional data to your Jira issues and versions. Note that only the data that you manually set will be applied, i.e. calculated data will not be applied.
The following data will be applied:
- Issue data:
Assignee, if one team member has been set on the issue
- Fix version, which will be applied to the corresponding Jira ticket
- Due dates
- Release data:
- Fixed start date
- Fixed end date
b) Click plan > Apply updates to project/s.
c) In the Issue fields section, clear the Estimates checkbox.
d) Click Update.
Why disable estimates?
Estimates are already applied when you created and linked the issues. Disabling this will prevent epics with aggregated estimates from having that value applied to the Jira issue. If this were enabled, this would double up the estimates of your epics when you create your plan in the new experience.
If your estimates in the Jira issues are not up to date, we recommend you enable and apply the estimate updates in this step. Then when you get to the last step in this migration process, remove that additional estimate from epics with children.
5. Create a 2.0 live plan
At this stage, you should have all your issues and releases with their associated data stored as issues in Jira. Each of your issue and release groupings would already have their own project and board, which we can now use as the issue sources for your plans in the new experience.
- In Jira, go to Portfolio (in header) > Create. The 'Create' page will be displayed.
- Select Plan > Create.
- In step 1 of the wizard, add a name for your plan.
- In step 2, select all the boards you’ve created for your classic plan issues.
- In step 3, select all the releases you want to bring into your plan.
In step 4, each of your issue sources will automatically create an associated team. Configure these to suit your teams.
This also means that your initiative project will have an associated team, so it’s recommended you delete this one.
- In step 5, confirm the scope of issues in the new plan, and then click Done.
6. Enable the new planning experience
Now that you've created a 2.0 live plan, you can easily switch over to the new planning experience, which is available as an early access feature.
- Go to your plan via Portfolio (in header) > View Portfolio > click your plan.
- Click more (
) > Try the new planning experience. The plan configuration page will display. - Click New experience.
- Click Enable new experience to switch on the new interface for your plan.
See Setting up the new experience for more details.
7. Reconfigure missing data
You might have missed some data along the migration process. Go over the following checklist to reconfigure your previous setup:
- Initiative ↔ epic relationships
- Themes: We suggest you color the issues in your plan by label, to replace the usage of themes. Coloring issues by label provides similar visual value as themes.
- Team data: Teams and team members
- Configurations of your plan
- Sprint assignment: Only sprints that exist in Jira are assignable. Make sure to create sprints in your Scrum backlog, so they're assignable from Portfolio.
Note that team members are no longer available in the new experience. Instead, we're now using assignees, which can be directly set in either Jira or Portfolio for Jira.
Need help?
If you're having problems or need additional help migrating from classic plans, please visit our Support section and create a support request.