Use Jira Site Import to migrate from server to cloud

Still need help?

The Atlassian Community is here for you.

Ask the community

descriptionStep by step instructions for how to move your data from Jira Server to Jira Cloud using Site Import.

This guide shows you how to use Jira's native site backup and restore functionality (Site Import) to move from Jira Server to Jira Cloud. The process described in this article can be used to migrate Jira Software, Jira Core, and Jira Service Desk from server or Data Center to cloud.


You can now use the Jira Cloud Migration Assistant to migrate individual projects or whole sites from server to cloud. 

Before you start

Before migrating, there are a few prerequisites and best practices to be aware of. We recommend taking the time to consider each of the items below before continuing with your migration.

Have you reviewed our migration planning resources?

Learn more about our planning resources

Start by reviewing our migration planning guide and FAQs. These provide detailed step-by-step guidance from start to finish and will help you plan your migration approach. You can also find information about cloud and server comparisons, case studies, Atlassian Access and more in our Cloud Migration Center.

Have you compared migration methods?

Learn more about different migration methods

Before using Jira Cloud site import, there are some important considerations. Start by comparing migrating methods to make sure this is the best one for your migration strategy.

Do you need to upgrade Jira Server before migrating?

Learn more about supported versions

Depending on your current server version, you may need to upgrade before migrating. Find out which versions are supported.

Have you signed up for a cloud site?

Learn more about signing up for your cloud site

You’ll need a cloud site before you begin your migration. If you don’t already have one, there are a few ways to set one up:

  • Sign up for an extended cloud trial. This lets server and Data Center customers try cloud (Standard and Premium plans) at no cost — giving you time to assess, plan, test, and migrate from server to cloud without having to pay for both products at once.

  • Sign up for a free trial. Cloud trials start at 7 days, and can be extended to 37 days upon request if more time is needed for testing.

  • If you’ve decided on the Free plan, you can set up a site directly and use it to test a migration. Remember not to exceed your user and data limits. If you attempt to migrate more users than the plan allows, your migration will fail. Free plans don’t offer audit logs or the same permissions as Standard and Premium plans, so this isn’t a viable testing option if you ultimately intend to upgrade.

Do you have existing data or users in your cloud site?

Learn about considerations for moving to an existing cloud site

Using Jira site backup and restore to migrate will overwrite all site data (except for users and groups), including projects, issues, and Jira configuration. 

You can choose to also overwrite all users, or to merge users from the import file with existing cloud users.

  • Choosing to overwrite users will delete all existing users in your cloud site, including users with access to Confluence only.

  • Choosing to merge users might escalate the permissions of server users when they are imported, so be sure to check what groups they will be merged into on the cloud site. 

This article is intended to help your migration to a new Jira Cloud site. If you need to merge with an existing Jira Cloud site that has data, you'll need to first merge your cloud and server sites in Jira Server before migrating to Jira Cloud to prevent your cloud data from being overwritten during the migration.

Have you checked your server security setup?

Learn more about security checks

Often, security in Jira Server is partially provided by running Jira inside of your corporate network. Before migrating to cloud, we recommend reviewing and updating your security settings as needed. 

How much storage are you using?

Learn more about storage limits in cloud

Atlassian's cloud plans have different storage limits. Before migrating, take a few minutes to check how much disk space you're currently using and review our cloud storage policy.

Can your site support all the users you plan to import?

Learn more about user import limits

If you have an annual subscription to Jira Cloud, check that you have a user tier that supports all of the users you plan to import.

For example, if you plan to import 125 users, you'll need the annual user tier for 101 - 200 users or above for the import to succeed. If you're paying monthly, this doesn't apply.

To avoid import failures, we recommend keeping monthly subscriptions turned on during your migration, and switching to an annual subscription after completing your migration.

Have you notified support of your migration plan?

Learn more about migration support

If you'll be performing your migration over a weekend or holiday, or are migrating over 1,000 users to cloud, get in touch at least two weeks in advance to let us know. That way, we can ensure we have extra support on hand during your migration.

Learn more about how we support cloud migrations.

Have you learned about next-gen projects?

Learn more about Jira next-gen projects

What are next-gen projects?

Unlike self-hosted Jira, in cloud we also offer next-gen projects for Jira Software and Jira Service desk. As the name implies, next-gen projects are the newest project type, and are designed to empower autonomous teams who want to get up and running quickly. They're perfect for teams who want to easily jump in and design their own unique workflow, without the need for a Jira admin or added complexity.

Next-gen appeals to some teams because it helps reduce the complexity of Jira and the strict standardization of agile methodology. Next-gen allows teams to be fully autonomous, customize their project components (sprints, reports, etc), and adapt Jira to their workflows, not the other way around.

We're building next-gen Jira Software from the ground up, so it doesn't yet have all the features that our classic Jira Software does. You can keep track of what's been recently released and we're working on next at our Jira Software Cloud public roadmap.

Next-gen and migrations

By default, when you migrate from self-hosted to cloud your projects will be imported as classic projects – the project type you know and love today in self-hosted Jira.

We recommend continuing to work with classic projects initially, as they more closely match your server experience (although there are still navigational and UI differences). Over time, you can let your teams decide which is right as they adapt to working in cloud and learn more about next-gen capabilities and how it's evolving.

Next-gen and Portfolio for Jira Cloud

Portfolio for Jira doesn't currently support next-gen projects. if you're planning to use Portfolio in cloud, you should stick with classic projects.

There's an open feature request to extend Portfolio for Jira to next-gen projects. You can vote on it to help this feature move forward.

How to migrate

If you've answered the questions above and completed your pre-migration checks, you're ready to go.

Here's an overview of the basic steps you'll take to migrate from Jira Server to Jira Cloud:

  1. Determine your user migration strategy
  2. Back up your Jira Server database
  3. Back up your Jira Server attachments, project avatars, and logos
  4. Import your server database backup into Jira Cloud
  5. Import your Jira Server attachments, project avatars, and logos into Jira Cloud
  6. Review and grant access to groups imported from server
  7. Re-add yourself to groups imported from server
  8. Complete post-migration checks

Before starting, check that you have the right permissions on both the server and the cloud side:

  1. In Jira Server: Check that you're a user in a group with the Jira System Administrators permission.
  2. In Jira Cloud: Check that you're in the site-admins group. If you've just created your new cloud site, you're the site administrator and will have the permissions you need.

If you don't have the required permissions, work with your Jira administrator to grant them before you begin your migration. Not having the right permissions will mean you won't be able to complete the migration and may see different information than what's indicated in the steps below.


Step 1: Determine your user migration strategy

The best way to import your users and groups will depend on a few variables: what products you’re migrating, how your users and groups are currently managed in server, and if you plan to use Atlassian Access for SCIM (user provisioning). Before beginning your migration, take time to review the Jira user migration strategies and determine which you'll need to use. 

Step 2: Back up your Jira Server database

This step will back up your Jira Server database in a portable XML format. If you have multiple Jira applications on the same site, for example Jira Software, Jira Core and Jira Service Desk, this backup will contain all project types (Software, Business and Service Desk) by default. 

  1. Log in as a user with the Jira System Administrators permission.
  2. Choose  > System.
  3. Select Import & Export > Backup System to open the Jira backup page. 
  4. In the File name field, type a name for your backup file.
  5. Click the Backup button and wait while your Jira data is backed up. Jira will save your backup as a zipped XML archive file within the export subdirectory of the Jira application home directory (jira-home for short). Check that Jira has the necessary file system permissions to write to this location.
  6. When the backup is complete, you'll see a confirmation message. You can now retrieve the file from your server.

Step 3: Back up your Jira Server attachments, project avatars, and logos

If you want to migrate attachments, project avatars, or logos, you'll need to back them up as well. These are stored in your Jira application’s data directory, which is a sub-directory of the Jira application home directory

To complete this step, you'll need to create a ZIP archive of the /data/attachments, /data/avatars/, and /logos/ directories. Make sure it uses the following structure:

attachments-1.zip
└─── data
		├── attachments
		│ 		├── ProjectKey1
		│ 				│ └── 10000
		│					│ ├── IssueKey-1
		│ 					│ ├── IssueKey-2
		│ 					│ └── IssueKey-3
		│ 		├── ProjectKey2
		│		└── ProjectKey3
		└── avatars
└── logos
Show me how

There’s no one specific way to back up the data directory, but Backing up data outlines a few methods to consider.

An example command that can be run from a *nix server:

cd <Jira Home Dir> 
zip -r data.zip logos/ data/avatars/ data/attachments/

Once the ZIP file is created, you’ll need to transfer the file from your server to the local workstation you’re using. Some common methods of doing this include using SFTP, rsync, wget, and curl.

Step 4: Import your server database backup into Jira Cloud

  1. Log in to your new Jira Cloud site with site-admin permissions.

  2. Click Jira Settings > System.

  3. In the Import and Export section, click Restore system.

  4. Select Import data and select the ZIP file you downloaded in Step 2: Back up your Jira Server database. 
  5. We'll check your file for errors, and ask you to choose settings for how you want your data imported.
    1. First, select your outgoing mail setting. Whichever option you choose, you can manually change after you migrate in the outgoing mail settings.
      1. You can choose to Enable outgoing mail, which allows Jira to send automated emails for interactions – for example, new comments on issues or issue transitions.

      2. If you choose to Disable outgoing mail, Jira won't send automated emails for interactions.

    2. Next, select whether you want to overwrite or merge users from your server site with the users on your cloud site.

      1. Choosing to overwrite will completely replace all users from Confluence and Jira with the users in your backup file.

      2. Choosing to merge users will also merge groups. This means that if we find a group on your server instance with the same name as a group on your cloud site (in either Jira or Confluence), we will merge the users from the server group into the cloud group. The server group users will receive the permissions of the cloud group. Make sure you check for possible permission escalation before choosing this option.

  6. Click Run import. This will take you to a page where you can track your import progress. It may take a while for your import to finish, depending on the size of your backup.
  7. When the import is complete, you'll be taken to a confirmation screen.
  8. From here, if you still need to import your media (attachments, logos, and project avatars) choose Import media. You'll need to return to the Import and Export page before managing application access. If you've already completed this step, or aren't planning to import your media, you can skip to step 6 by clicking the link to Grant application access.

Troubleshooting this step

Formatting your backup file

Before you import, unzip the backup file and make sure it has a file structure similar to:

JIRA-backup-20161021
├── activeobjects.xml
├── entities.xml

If you see this error:

Import error

There was an error importing file JIRA-backup-20161021.zip: Validation failed. The following issues were reported:

The import archive doesn't contain entities.xml file.

Then you may have zipped a folder containing the .xml files, instead of zipping the XML files directly.

If there are invalid characters in your XML

You may have to clean up invalid characters in your backup before importing into Jira Cloud. Take a moment to look over the documentation and integrate it into your migration plan.

If your import is stalled

During the import process, you may see it stall on the following percentages/steps: 

  1. 50% - Upgrading database
  2. 90% - Importing users and groups

This is going to be normal and you just need to wait for them to complete.

If there are errors with usernames or emails

You may find you need to audit usernames or email addresses to check for errors before you can complete the import to cloud. The primary things to review are:

  1. All emails must end in a top-level domain. For example: john_doe@company isn't valid because it's missing the .com, and would block the import.

  2. All emails must use a valid domain. For example: john_doe@example.com is not allowed because example.com is not recognized as a valid domain. 

  3. All users must have unique email addresses. You can identify users with duplicate addresses using: 

    select email_address, count(*) from cwd_user group by email_address having count(*) > 1
  4. Usernames starting with with addon_ will need to be renamed or deleted. This prefix is reserved for Atlassian Marketplace apps. If you haven't moved from Atlassian's cloud products in the past, you're not likely to hit this issue.

If there are links that need to be mapped in cloud

At this step, you may see a list of URLs for Atlassian server sites. To make sure links point to the new Jira Cloud site instead of the old server site after you migrate:

  1. Select the URL of the Jira server instance you're importing to cloud from the list.
  2. Then click Run import to continue with your migration.

Step 5: Import your Jira Server media into Jira Cloud

  1. (If not already) log in to your new Jira Cloud site with site-admin permissions.

  2. Click Jira Settings > System.

  3. In the Import and Export section, click Restore system.

  4. Choose Import media and then find and select the media ZIP you created and downloaded in Step 3: Back up your Jira Server attachments, project avatars, and logos.
  5. This will take you to a page where you can track your import progress. It may take a while for your import to finish, depending on the size of your file.
  6. When the import is complete, you'll be taken to a confirmation screen.
  7. From here, if you still need to import more media, repeat this step until all media files are imported. Note that you may want to test that all media was imported successfully in a new tab before importing the next batch of media.

Troubleshooting this step

If your large file import fails

Large attachment files may not import properly and can take a long time to complete.

If your file is larger than 10 GB, you may need to split up the backup into 2-5 GB chunks instead and then import each one separately. The file structure should be:

attachments-1.zip 
└─── data 
		├── attachments 
		│ 		├── ProjectKey1 
		│ 				│ └── 10000 
		│ 					│ ├── IssueKey-1 
		│ 					│ ├── IssueKey-2 
		│					│ └── IssueKey-3 
		│ 		├── ProjectKey2 
		│ 		└── ProjectKey3 
		└── avatars 
└── logos
attachments-2.zip 
└─── data 
		└── attachments 
				├── ProjectKey4 
				├── ProjectKey5 
				└── ProjectKey6 
attachments-3.zip 
└─── data 
		└── attachments 
				└── ProjectKey#

See How to import only part of a Jira export into Jira Cloud for more instructions.

If the attachment import stalls out

During the attachment import step, there are a few distinct phases, including uploading, processing, and the actual import. Large attachment files may be interrupted during the processing phase. You can identify this if the page reloads suddenly and there's no further progress or message shown.

If everything is okay, after the processing step you should see a message like:

Attention

This will import non-database content (such as attachments and avatars) into your Jira instance. You should only do this after a full database import because the full import will remove any existing data that you import using this page.

This operation could take anywhere from several minutes to several hours depending on the size and number of attachments.

Note that this operation cannot be undone.

This indicates the processing is completed. From here, click the Proceed button to finish importing your attachments.

If you notice that the import failed during the processing step, the solution is to divide the attachments into smaller ZIP files and import each file separately.

Step 6: Review and grant access to groups imported from server

Once you've imported everything into your cloud site, you'll need to review the groups imported from server and decide which to grant access to. 

As a security measure, the import process won't automatically apply the default application access settings or grant access to new users. You'll need to grant the application access to these users before they can log in.

  1. Log in to your new Jira Cloud site and click  Jira Settings > User management.
  2. In the Site settings section, choose Product access.
  3. Choose Review imported groups to review and confirm the default groups' access.

Note that during the import, the name of the default Jira Server group Jira-administrators changes to administrators in Jira Cloud.

Step 7: Re-add yourself to groups imported from server

As a security measure, the group settings for the person performing the migration are not imported. This means the user who executed the migration will need to be added back to their previous groups. You can do this two ways, either from the Groups section or the Users section at https://admin.atlassian.com.

From the Users section

  1. Go to https://admin.atlassian.com
  2. If you have multiple cloud sites, you'll need to select the cloud site you've just migrated to.
  3. In the User management section, first choose Users.
  4. Find your profile.
  5. Click the ... icon
  6. Choose Add user to group.
  7. Select the group(s) you need to be added to.
  8. Click Add to Groups.

From the Groups section

  1. Go to https://admin.atlassian.com.
  2. If you have multiple cloud sites, you'll need to select the cloud site you've just migrated to.
  3. In the User management section, first choose Groups.
  4. Then, select the group you need to be added to.
  5. Choose Add members, and add yourself to the group. 
  6. Repeat as needed for the rest of your groups.

Step 8: Compete post-migration checks

Depending on the type of migration, there may be some things you need to do once your migration is finished. For a full list of post-migration recommendations, refer to the Jira migration planning guide.

Troubleshooting this step

If your content is linked to "Admin" after importing to cloud

There's a known bug affecting admins on the cloud site. After importing your data to cloud, the content associated with your account in server may be associated to "Admin". If you run into this bug, just contact our support team for help resolving the issue.

Additional troubleshooting

If you've run into a problem during your migration, we're here to help. You can start by searching for known issues in our public issue tracker. There, you can find information about common issues we see with Jira migrations, including their status and suggested workarounds.

Some known issues include the following:

More information and support

We have a number of channels available to help you with your migration.


Last modified on Mar 25, 2020

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.