Documents to help you prepare to migrate your Atlassian Server products.
A collection of topics that help prepare you to migrate your apps to the Cloud.
Ensure you’re ready to migrate with these pre-migration checklists for Jira, Confluence, and Bitbucket Server or Data Center.
Documents that walk you through using the Confluence Cloud Migration Assistant to migrate to Cloud.
Documents that walk you through using the Bitbucket Cloud Migration Assistant to migrate to Cloud.
Documents to help you use Jira Site Import to migrate to Cloud.
Resources to help get started and testing after you migrate.
Everything you need to know about moving your data from one cloud site to another.
When you're planning a migration from Server or Data Center to Cloud, we strongly recommend performing a trial run before migrating. Testing your migration will help you:
Establish a clearer timeline for your live migration, including any expected downtime.
Validate the data and run User Acceptance Testing (UAT).
Prepare for your launch and develop onboarding communications.
Identify possible bugs and the steps needed to resolve them before the actual migration.
In this guide, we'll outline how to conduct a test migration for Jira or Confluence, including best practices and what to test for.
Before you begin
Review the planning guide: A well-planned migration is a successful migration. Before starting your testing, take the time to review our Cloud migration guide. They'll walk you through the key phases and consideration for each step, including what you need to know before you begin testing.
Choose your migration method: There are a number of Cloud migration methods. Before testing, you'll need to compare these and choose the one that's best for you.
Complete any prerequisite steps: Once you've chosen a method, review the documentation to ensure there aren't any prerequisite steps you need to complete before testing.
Check your Cloud organization
We’ve been rolling out changes that may affect your migration experience. From your organization at admin.atlassian.com, if the Users list and Groups list are under the Directory tab, you have the improved user management experience. This means that the users and groups across sites will be merged under the organization. Read more about how groups and permissions are migrated. If you have any concerns, contact support.
For a test migration or UAT, we recommend that your test Cloud site is not part of the organization that also hosts your prod site. The prod site should be hosted in a different organization. This is to ensure smooth migration of the relevant users and groups.
How testing works
If you've completed your pre-migration checks, you're ready to go.
Here's an overview of the basic steps we recommend to test your migration and prepare for your production migration:
Clean up your data
Sign up for your Cloud site
(Optional) Set up Atlassian Access
Perform the test migration
Review your data and conduct User Acceptance Testing (UAT)
(Optional) Reset your test site
Create your migration runbook
Develop your change-boarding and launch plan
Step 1: Clean up your data
The more data you migrate, the longer and more complex your migration is likely to be. Because of this, we recommend taking the time to clean house, so to speak, before running your test migration. This can result in a smoother migration, fewer performance issues, and even productivity gains once in Cloud.
Find out more information about cleaning up your Server instance before migration.
Step 2: Sign up for your Cloud site
If you haven’t already, now’s the time to sign up for a Cloud site. You'll need to decide if you want to perform your test to a trial site or to your production site.
If you decide to use a trial site you can:
activate your free Cloud migration trial
set up a standard 7 day trial (this will revert to a Free plan after the trial)
If you are using a Cloud migration trial, we recommend choosing or upgrading to an Atlassian Cloud Premium plan or an Enterprise plan so you can test your migration in a sandbox environment. Keep in mind that you may see additional features in this testing environment as both Premium and Enterprise plans have more features than a Standard plan.
Learn more about how to set up a sandbox testing and staging environment.
The format for your site name (URL) will be https://example.atlassian.net/, where example is a unique character string that you specify.
Site names are chosen for an entire Atlassian Cloud site at the time you sign up for your first product – for example, when you first sign up for Jira Software Cloud or Confluence Cloud.
There are a few things to be aware of when choosing your site name:
Step 3 (optional): Set up Atlassian Access
Atlassian Access offers Cloud security and user management features including SAML SSO, user provisioning (SCIM), enforced two-factor authentication and audit logs. It works across all your Atlassian Cloud products and domains so you can manage users and security policies in one simple place.
If you're planning to use Atlassian Access in Cloud, you can sign up for a 30-day free trial before beginning your test migration to get SSO set up for all users and test out user provisioning and audit logging. If you need more than 30 days, contact our support team.
Step 4: Complete the pre-migration checklist
Step 5: Perform the test migration
Now you're ready to test your migration.
For Jira and Confluence Cloud Migration Assistants
After migrating your data, migrate or install any apps you're planning to use in Cloud.
If you need to test your migration multiple times, you'll need to manually delete any data you're planning to re-import. This is because the migration assistant does not currently overwrite data that already exists in your Cloud site. There are two ways to delete your data:
After deleting the data, you can re-run your test migration.
For Jira Site Import
Follow the instructions outlined in Use Jira Site Import to migrate from Server to Cloud to import your data.
After migrating your data, migrate or install any apps you're planning to use in Cloud.
If you need to re-test your migration, a Jira site import will wipe all existing content, including any previously imported Jira data or data that exists on your Cloud site. This means that data from any prior test migrations will be wiped automatically, so if you're testing multiple times, you won't need to delete data first.
Step 6: Review your data and conduct User Acceptance Testing (UAT)
After migrating, review your Cloud site to validate that everything is working as expected.
General data review
check your links to other content are working, for example, Confluence pages linked to Jira issues
check if application links to other Server products may need to be reconfigured. If they do, after re-configuring them, re-test the functionality to ensure the integration works as expected
check that any apps or app data you've migrated is working as expected
test integrations with other products, like Jira, Confluence, or Bitbucket
take screenshots and document changes between your Server and Cloud sites for any training or communications you plan to deliver during the migration and post-launch
Data review for Jira
When reviewing Jira data:
check your workflows are working as expected. You may, for example, have post functions that rely on third-party apps that aren't migrated. You may find they aren't working in Cloud but continue to work on your Server site.
use the product and create test data - test things like creating a new project, creating and editing issues, and uploading attachments
run the Jira macro repair and verify whether it fixed any broken macros
Data review for Confluence
When reviewing Confluence data:
check your attachments have imported correctly
check that any apps or app data you've migrated is working as expected. Any macros that rely on third-party apps may be broken, for example, Gliffy Diagrams. If this is the case, check with the app vendor if it's possible to fix them.
UAT and change management best practices
We also advise conducting UAT, or having some end users replicate common day to day tasks using the test site. This will not only help you catch any unexpected issues but can help your organization prepare for change.
Who needs to be involved
This varies for every organization, but a few options to consider include testing with:
members of a specific team
a combination of power-users and less frequent users
an appointed member of each team that will be moving to your Cloud site
Consider as well who has the bandwidth and ability to provide clear and constructive feedback. Generally speaking, you want to ensure that every major user type or role that will be using your Cloud site is invited to provide input.
What to test for
Take note of any issues users have as they get used to the things that may change as a result of your migration, including:
a new user interface
new URLs and changing bookmarks
differences in user administration
For Jira Software and Jira Work Management:
test things like creating sprints, adding issues to backlogs, and viewing boards
For Jira Service Management (formerly Jira Service Desk):
ask agents to view queues, check their portal view, and any other common activities
have users try creating a new space, creating and editing pages, and uploading attachments
Record any areas of confusion or changes to functionality, since you may want to include these in any pre-launch or onboarding communications and training you provide.
Step 7 (optional): Reset your test site
In some cases, you may need to delete the data from your Cloud site and start again – for example, if you used your production instance to test, or need to re-run your tests. Follow these instructions to reset and delete all of the data from your Cloud site.
Step 8: Create your migration runbook
Migration runbooks are a step-by-step procedural guide for what you need to do to complete your migration. Creating one can help your production migration run smoothly and according to plan.
Your runbook should include things like each step in the process, any instructions needed for those steps, who will complete them, and how long they’re expected to take.
Step 9: Develop your change-boarding and launch plan
After testing, you should have a good idea of what major changes your users can expect as a result of your move. Now's the time to prepare any training, documentation or communications your users will need to get back to work quickly.
Keep in mind as you put this together you'll want to highlight not only what's changing, but why – as well as how your users will benefit from the move.
Some common benefits for users include:
access to free Cloud mobile apps
the ability to take work anywhere, and access it quickly and securely - no more VPN required
better integrations with other SaaS tools and cloud apps
More information and support
We have a number of channels available to help you with your migration.
for more migration planning information, visit the Atlassian Migration Program website
for technical issues or support with strategy and best practices, contact our support team
for peer advice, ask the Atlassian Community
for expert guidance, work with an Atlassian Partner
Was this helpful?