• Products
  • Documentation
  • Resources
Products
Documentation
Resources
Atlassian Support
/
Migration Resources
/
Jira, Confluence, and Bitbucket pre-migration checklists

Jira pre-migration checklist

Migration can be a complex and challenging process.

To help you out, we’ve created this checklist of everything you need to do to ensure your data is ready to migrate from Jira Server or Data Center to cloud.

Complete these checks before attempting a migration to avoid common failures.

Before you begin

1. Confirm your migration method

What you'll check for varies depending on your migration method. The migration methods covered in this checklist are:

Next, follow the pre-migration checks for the migration method you have chosen.

2. Prepare

To complete the pre-migration checks, you may need access to:

Jira Cloud Migration Assistant checklist

The Jira Cloud Migration Assistant automatically reviews your data for common errors. It will check that:

  • all users have valid email addresses

  • all users have unique email addresses

  • none of the project names or keys conflict with project names or keys in cloud

  • the migration assistant is up to date

However, the migration assistant won’t check for everything, so you’ll also need to run through the following list before starting a migration.

1. Create a user migration plan [MANDATORY]

External Directories

Sync your active external user base to ensure that all users and groups are migrated properly as part of your user migration strategy. This also ensures that data remains linked to the correct users during the migration.

If you're using an external identity provider to manage your users, make sure they are active and synchronized to your internal user base before migrating. 

Sync using the Jira Server UI

  1. Click on the cog icon in the application's right upper corner

  2. Select User Management

  3. Select User Directories

  4. Finally, select Sync

Verify using your Support Zip

You can cross-reference the Epoch timestamps in a site such as https://www.epochconverter.com/.

Make sure directories that are needed are set to Active.


Last External Users Sync Verification

1 2 3 4 5 6 7 grep "com.atlassian.crowd.directory.sync.laststartsynctime" <Support Zip Location>/auth-cfg/directoryConfigurationSummary.txt Example Output: com.atlassian.crowd.directory.sync.laststartsynctime: 1586922783853 com.atlassian.crowd.directory.sync.laststartsynctime: 1586911983804 com.atlassian.crowd.directory.sync.laststartsynctime: 1579025414214


Active External Directory Verification

1 2 3 4 5 6 7 8 9 grep "Active:" <Support Zip Location>/auth-cfg/directoryConfigurationSummary.txt Example Output: Active: true Active: true Active: true Active: false Active: true

Note that the Jira Cloud Migration Assistant migrates:

  • all users and groups

  • users and groups related to the selected projects

2. Check your Jira Server version [MANDATORY]

Make sure Jira is running on a supported version, otherwise, the migration assistant will not work.

Verify using the Jira Server UI

  1. Click on the cog icon in the application's right upper corner

  2. Select System

  3. Select System Information in the left navigation panel

  4. Finally, look for the Jira Version

 

Verify using your Support Zip
Product Version Verification

1 2 3 4 5 grep "<product name" <Support Zip Location>/application-properties/application.xml Example Output: <product name="Jira" version="8.7.1"/>

3. Fix any duplicate email addresses [MANDATORY]

Duplicate email addresses are not supported by Jira Cloud and therefore cannot be migrated with the Jira Cloud Migration Assistant. To avoid errors, you should find and fix any duplicate email addresses before migration. If user information is managed in an LDAP Server, you will need to update emails there and sync with Jira before the migration. If user information is managed locally, you can fix them through the Jira Server or Data Center UI. 

Verify using SQL (tested on Postgres)

Use the query below to find duplicate email addresses (if any), the number of times these addresses repeat, as well as the users assigned to the email address:

1 2 select lower_email_address, count(lower_email_address), array_agg(user_name) as "Users with Dupe E-Mail" from cwd_user group by lower_email_address having count(lower_email_address) > 1;

4. Make sure you have the right permissions [MANDATORY]

Ensure that the user who runs the migration:

5. Check for conflicts with group names [MANDATORY]

Make sure the groups in your cloud site don't have the same name as any groups in your server site, unless you're intentionally trying to merge them. Learn about how the migration assistant manages group name conflicts.

Additionally, there might be some migration scenarios that result in your server site ending up with add-on users. Add-on users are not common in the server world and they might cause a few issues during the migration to cloud. Before migrating, delete or update any of these add-on users.

Verify using SQL (tested on Postgres)

Use the query below to find any of these users and either delete them or update their emails to something other than @connect.atlassian.com:

1 2 --ADD-ON USERS - TESTED ON POSTGRESQL select * from cwd_user where lower_email_address like '%connect.atlassian.com%';

6. Update your firewall allowance rules [MANDATORY]

The migration assistant connects to Atlassian domains in order to run the migration. If any domain gets blocked by either a firewall or a reverse proxy, the migration will fail.

Verify you can connect to Atlassian domains

Ensure that the domains listed on Atlassian cloud IP ranges and domains will not be blocked by any security rules before running a migration. Additionally, allow these endpoints:

7. Determine how you’ll migrate apps [MANDATORY]

The Jira Cloud Migration Assistant will not migrate any app or add-on data. If you have app data to migrate, contact vendors beforehand for advice on how to migrate their data properly. This includes Atlassian-built apps like Portfolio for Jira. If you need to migrate Portfolio for Jira, watch the related feature request to stay up to date.

Also note that in Jira Cloud, Portfolio is not offered as a standalone app, but the features are available as Advanced Roadmaps in Jira Software Cloud Premium. Learn more

8. Check your public access settings [MANDATORY]

You can configure your Jira Server or Jira Cloud site to be publicly available to the internet. Unless you intentionally want your content to be public, you should review your project permissions. If you have projects that are publicly available in Jira Server, remove their anonymous access setup before migrating to cloud. You can always make these projects public again after migrating. Learn more about checking your public access settings. 

Verify using SQL (tested on Postgres)

Projects

This will flag any projects that have the Browse Project permission set to Anyone.

1 2 3 4 5 6 7 8 9 10 11 12 13 // get list of project permission schemes which has share type as "Anyone" (i.e. open) SELECT p.id, p.pname, ps.name FROM project p INNER JOIN nodeassociation na ON p.id = na.source_node_id INNER JOIN schemepermissions sp ON na.sink_node_id = sp.scheme INNER JOIN permissionscheme ps ON na.sink_node_id = ps.id WHERE na.source_node_entity = 'Project' AND na.sink_node_entity = 'PermissionScheme' AND sp.permission_key='BROWSE_PROJECTS' AND sp.perm_type='group' AND sp.perm_parameter is null

 

Filters

This will get a list of filters which has share type as "share with everyone" (i.e. global)

1 2 3 4 5 // get list of filters which has share type as "share with everyone" (i.e. global) SELECT sr.filtername, sp.sharetype AS current_share_state, sr.username AS owner_name, sr.reqcontent AS JQL FROM searchrequest sr INNER JOIN sharepermissions sp ON sp.entityid = sr.id WHERE sp.sharetype='global' and sp.entitytype ='SearchRequest';

 

Agile Boards

This will get a list of Agile boards which has share type as "share with everyone" (i.e. global)

1 2 3 4 5 6 // get list of Agile boards which has share type as "share with everyone" (i.e. global) SELECT DISTINCT "rv"."NAME" as "Board Name", sr.filtername, sp.sharetype AS current_share_state, sr.username AS owner_name FROM "AO_60DB71_RAPIDVIEW" as rv INNER JOIN searchrequest sr ON sr.id = rv."SAVED_FILTER_ID" INNER JOIN sharepermissions sp ON sp.entityid = sr.id WHERE sp.sharetype='global' and sp.entitytype ='SearchRequest';

 

Dashboards

This will get a list of Dashboards which has share type as "share with everyone" (i.e. global)

1 2 3 4 5 6 // get list of Dashboard which has share type as "share with everyone" (i.e. global) SELECT DISTINCT pp.id as Dashboard_Id, pp.pagename AS Dashboard_name, sp.sharetype AS current_share_state, pp.username AS owner_name FROM portalpage pp INNER JOIN sharepermissions sp ON sp.entityid = pp.id WHERE sp.sharetype='global' and sp.entitytype ='PortalPage' ORDER BY pp.id;

9. Review your server setup [MANDATORY]

Depending on the number of issues or projects to be migrated, Jira Server might experience an OutOfMemory error that can crash the entire migration. To prevent this, ensure that your application is running with at least 4GB’s of Heap Allocation by checking the parameters outlined in Increasing Jira's Application Memory.

Also, make sure to review your Open Files limit. Ideally, it should be as close as possible to 32768. Getting the number of Open Files set to your system may vary depending on the Linux distribution. If unsure of how to check that via system commands, generate a Support Zip, open the application-properties/application.xml file and search for <max-file-descriptor>. If this number is close to 32768, adjust it accordingly. More information about it can be seen in the following documentation: Too many open files error. This doesn’t apply to those running Windows.

Verify using your support zip

Ensure the value of the Xmx and Xms is at least 4096m or 4g:

1 2 3 4 5 grep -i "xmx"" <Support Zip Location>/application-properties/application.xml Example Output: <JVM-Input-Arguments>-Djava.awt.headless=true -Datlassian.standalone=JIRA -Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true -Xms4g -Xmx4g

Ensure the value of <max-file-descriptor> is close to 32768

1 2 3 4 5 grep -i "<max-file-descriptor>"" <Support Zip Location>/application-properties/application.xml Example Output: <max-file-descriptor>32,000</max-file-descriptor>

Alternative ways to verify heap sizing

If on Linux

Go to /jira-installation-directory/bin/setenv.sh file and confirm both parameters below are greater than 4096m or 4g (if it was set in gigabytes instead of megabytes):

1 2 JVM_MINIMUM_MEMORY="4096m" JVM_MAXIMUM_MEMORY="4096m"


If on Windows, not running as a service 

Go to /jira-installation-directory/bin/setenv.bat file and confirm both parameters below are greater than 4096m or 4g (if it was set in gigabytes instead of megabytes):

1 2 JVM_MINIMUM_MEMORY="4096m" JVM_MAXIMUM_MEMORY="4096m"


If on Windows, running as a service

Follow the instructions in this article.

10. Check your server timezone (if merging cloud sites) [MANDATORY]

If you're using the migration assistant in order to merge Jira Cloud sites, there might be a slight shift in timezones for timestamps in issues. Jira Cloud uses UTC. If the Jira Server instance uses any other timezone, it shifts in hours based on the difference from UTC.

The workaround is to add a system flag to the Jira Server instance -Duser.timezone=UTC as outlined here. 

Verify using your Jira Server UI

To confirm your server timezone:

  1. Click on the cog icon in the application's right upper corner

  2. Select System

  3. Select System Information in the left navigation panel

  4. Finally, look for jvm.system.timezone

 

Verify using your Support Zip

You can also use the following query to verify your server timezone:

1 2 3 4 5 grep "<jvm.system.timezone>" <Support Zip Location>/application-properties/application.xml Example Output: <jvm.system.timezone>America/New_York</jvm.system.timezone>

11. Fix any duplicate shared configuration names [RECOMMENDED]

To avoid migration conflicts, rename shared configuration (workflows or permission schemes) in your server instance that have the same name as shared configuration in your cloud site. If we find a conflict we may alter the name of the configuration during migration.

12. Check you won't exceed storage limits [RECOMMENDED]

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 documentation. 

13. Prepare your server instance [RECOMMENDED]

To ensure that your server data migrates successfully, check the status of your data using the Database Integrity Checker (native to Jira Server) and the Integrity Check for Jira app from the Atlassian Marketplace.

Other checks and actions to perform:

  • all required fields must have a value, and should not be null

  • reactivate any archived projects that you want to migrate

  • reactivate any inactive user directories that you intend to migrate

For more information about cleaning up your data, see Clean up your server instance before migration.

14. Prepare your cloud site [RECOMMENDED]

Things to consider when setting up your cloud site:

  • Your cloud site must have the same Jira products enabled as your server site, excluding Jira Service Management (formerly Jira Service Desk). For example, if you have Jira Core and Jira Software on your server site, you need both on your cloud site, even if you’re not migrating Jira Core projects. This is so that all your users and groups migrate successfully. If you don’t want to use all those products after migrating, you can set up free trials for the relevant product(s) and then deactivate them after migrating.

  • Ensure that the language of your cloud site is the same as the language on your server site. Some fields may not migrate properly if the languages are different.

  • If you’re using Atlassian Access, you should set that up before migrating.

15. Back up your data [RECOMMENDED]

Before you run a migration, we recommend that you back up your current Jira Server site. If your destination cloud site has existing data, back up your Jira Cloud site as well.

16. Run a test migration [RECOMMENDED]

We strongly recommend you run a test migration before running your production migration. Check out our guidance on testing your migration.

17. Notify support of your migration plan [RECOMMENDED]

If you’re performing your migration over a weekend or holiday, or will have over 1,000 users in cloud, we recommend getting in touch with our migration support team at least one to two months in advance. That way, we can ensure we have extra support on hand during your migration. 

Learn more about how we support cloud migrations.

Jira Site Import checklist

1. Check your Jira Server version [MANDATORY]

For the import to work, your backup XML file needs to be from a supported version of Jira Server or Data Center.

 

Verify using the Jira Server UI

  1. Click on the cog icon in the application's right upper corner

  2. Select System

  3. Select System Information in the left navigation panel

  4. Finally, look for the Jira Version

Verify using your Support Zip

Product version verification

1 2 3 4 5 grep "<product name" <Support Zip Location>/application-properties/application.xml Example Output: <product name="Jira" version="8.7.1"/>

 

Verify using your XML backup file

You can cross-reference the build number to the Jira version using Jira Server Build and Versions.

Product version verification

1 2 3 4 5 grep 'Build #' <Backup File Location>/entities.xml Example Output: Build # : 100118

2. Check your XML file is valid [MANDATORY]

Ensure that both entities.xml and the activeobjects.xml are valid XML files. Sometimes exports from large customers with complex environments result in invalid XML structures.

Verify using your XML backup file

Use the query below to find out if your file is valid:

1 2 xmllint --noout <Backup File Location>/entities.xml xmllint --noout <Backup File Location>/activeobjects.xml : 100118

If the command does not produce an output, the file is valid. Any exceptions point to the spot with the formatting error.

3. Check your XML file structure [MANDATORY]

Ensure that the backup file is correctly structured for import. If you have a large instance, we recommend splitting your cloud backup file into a database file containing your activeobjects.xml and entities.xml, and a separate one for your attachments and other media.

This can help avoid timeout errors and reduce the risk of issues on import.

The total size of the .xml files should be less than or equal to 10GB before zipping and importing the file. To import larger files, contact support.

Verify using your XML backup file

Depending on if you separate data from your media and other attachments or not, make sure the resulting hierarchy matches the relevant format below:

Attachments and data

1 2 3 4 5 6 7 JIRA-backup-XXXXXX ├── activeobjects.xml ├── entities.xml ├── data │ ├── attachments │ └── avatars └── logos

Attachments and other media only

1 2 3 4 5 6 7 8 9 10 media-only-X.zip └─── data ├── attachments │ ├── ProjectKey │ │ └── 10000 │ │ ├── IssueKey-1 │ │ ├── IssueKey-2 │ │ └── IssueKey-3 │ └─── ProjectKey2 └── avatars


4. Check for failed upgrade tasks [MANDATORY]

Failed or pending upgrade tasks from Jira Server may cause an import to cloud to fail. 

Verify using your XML backup file

Run the following to identify any failed upgrade tasks before attempting an import into cloud:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 grep '<UpgradeHistory' <Backup File Location>/entities.xml | awk 'BEGIN{ORS="\n"};{print $2}{print $5"\n"}' Example Output: id="10000" status="complete" id="10100" status="complete" id="10101" status="complete" id="10104" status="complete" id="10105" status="failed"

 

1 2 3 4 5 6 7 8 9 10 11 12 grep '<UpgradeTaskHistory' <Backup File Location>/entities.xml | awk 'BEGIN{ORS="\n"};{print $2}{print $5"\n"}' Example Output: id="10000" status="complete" id="10100" status="complete" id="10101" status="complete" id="10104" status="complete" id="10105" status="failed"

If any upgrade tasks return with "failed", the workaround is to update them to "complete" or remove the failed upgrade tasks altogether. Make sure that the resulting XML structure is valid when removing the elements.

Once the change is made, save the file and re-zip, making sure to keep the same file structure as the original backup file.

5. Check for duplicate and invalid user emails [MANDATORY]

One of the most common reasons for a failed import is duplicate or invalid emails. Although import checks can capture duplicate or invalid emails, it can result in failed imports or uploads that can take time and extend a maintenance window for large customers. It's a best practice to try and capture these beforehand.

Verify using your XML backup file

Duplicate users
Run the following to identify any duplicate emails (denoted by more than 1 to the left of the email):

1 2 3 4 5 6 7 grep 'lowerEmailAddress="' <Backup File Location>/entities.xml | awk -F\lowerEmailAddress=\" '{print $2}' | cut -d\" -f1 | sort | uniq –с Example Output: 1 felix.test@test.com 2 fixed.test@test.com 1 florian.test@test.com

Below is additional query for db (with same function as above).

1 2 3 4 5 SELECT lower_email_address, count(lower_email_address), array_agg(user_name) AS "Users with Dupe E-Mail" FROM cwd_user GROUP BY lower_email_address HAVING count(lower_email_address) > 1;

If you find duplicates, correct them on the source instance or edit the entities.xml to make them unique.

Additionally, add-on users may cause issues on migration. You can prevent these by cleaning up add-on users before importing to cloud.

Verify using SQL (tested on Postgres)

Add-on users

Use the query below to find any users that meet such criteria and either delete them or update their emails on the source to reflect something other than @connect.atlassian.com:

1 2 --ADD-ON USERS - TESTED ON POSTGRESQL select * from cwd_user where lower_email_address like 'connect.atlassian.com';

6. Turn off the incoming mail handlers in cloud during testing [MANDATORY]

By default, the incoming mail handlers are turned on after an import. This can cause mail handlers in cloud to process emails instead of mail handlers in server. We strongly recommend turning these off during testing to prevent mails from incorrect processing.

You can do the following:

  1. Click Jira Settings > System.

  2. Select Global Mail Settings, and then turn off Email puller and Email processor.

  3. Select Incoming Mail, and then delete all mail servers and handlers.

  4. If you have Jira Service Management, go to Settings > Products > Email requests, and make sure the Email addresses section is empty.

7. Check for invalid or unhandled characters [MANDATORY]

In older versions of Jira, it was possible to cut and paste text containing control characters into Jira issue fields. This causes problems, because Jira's backup format is XML, and XML does not allow for the storage of most control characters. When XML containing control characters is imported into Jira, the import fails with an irreversible error.

To prevent this, follow our guide to removing invalid characters from an XML backup for both entities.xml file and activeobjects.xml files.

8. Fix any duplicate workflows [MANDATORY]

An import may fail if there are workflows with the same name in the backup file. By design, workflows may not have the same name creating them through the user interface. However, if the workflow names have the same name but with different casing (e.g. "workflow1" vs "WORKFLOW1"), then it can lead to a failed import.

Verify using your XML backup file

Duplicate workflows

Use the following query to make sure all of your workflow names are unique:

1 2 3 4 5 6 7 8 9 10 11 12 13 cat <Backup File Location>/entities.xml | grep '<Workflow id="' | cut -d " " -f7- | sort | uniq -c Example Output: 1 name="Software Simplified Workflow for Project SER"> 1 name="Software Simplified Workflow for Project SKP"> 1 name="Software Simplified Workflow for Project TES"> 1 name="TEST: Change Management workflow for Jira Service Desk"> 1 name="TEST: Incident Management workflow for Jira Service Desk"> 1 name="TEST: Jira Service Desk default workflow"> 1 name="TEST: Problem Management workflow for Jira Service Desk"> 1 name="TEST: Service Request Fulfilment with Approvals workflow for Jira Service Desk"> 1 name="TEST: Service Request Fulfilment workflow for Jira Service Desk"> 1 name="company-managed default workflow">

Make sure each workflow name from the output is unique (has a 1 to the left of the name). If you find duplicates, correct them on the source instance or edit the entities.xml to make them unique.

9. Fix any duplicate clustered jobs [MANDATORY]

An import may fail if there are duplicate clustered jobs with the same ID in the backup file. You’ll need to ensure that there are no duplicated clustered jobs' IDs prior to import, as outlined here.

Verify using SQL (tested on Postgres)

Find duplicate clustered jobs

Use the query below to find any duplicate clustered jobs

1 2 3 SELECT * FROM clusteredjob WHERE job_id in (SELECT job_id FROM clusteredjob GROUP BY job_id HAVING COUNT(*)>1)

Mitigate on the source instance

  1. Shut down JIRA and back up the database properly

  2. Delete either of the duplicate entries: 

    1 delete from clusteredjob where id =XXXXX;

  3. Restart Jira

Verify using your XML backup file

First, run the following query:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 grep 'ClusteredJob id="' <Backup File Location>/entities.xml | cut -d "=" -f2 | sort | uniq -c Example Output: 1 "10001" jobId 1 "10107" jobId 1 "10201" jobId 1 "10202" jobId 1 "10204" jobId 1 "10205" jobId 1 "10300" jobId 1 "10301" jobId 1 "10302" jobId 1 "10303" jobId 1 "10304" jobId 1 "10307" jobId 1 "10308" jobId 1 "10309" jobId 1 "10311" jobId

Make sure each name from the output is unique (has a 1 to the left of the name). If you find duplicates, correct them on the source instance or edit the entities.xml to make them unique.

10. Check the length of your attachment filenames [MANDATORY]

An import may fail if there are attachments in the backup with a filename greater than 250 characters.

Verify using SQL (tested on Postgres)

The query below will identify attachments with more than 250 characters:

1 2 3 SELECT id,issueid, char_length(filename) FROM fileattachment WHERE char_length(filename) > 250

Verify using your XML backup file

Make sure that the command below does not identify any filenames greater than 250. It should show 0.

1 2 3 4 5 grep <Backup File Location>/entities.xml | cut -d\ -f9 | awk 'length > 250 {print ;}' | wc -l Example Output: 0

If you find any files greater than 250, identify them in the entities.xml and rename them in the field filename="XXXXX.txt"

11. Check your public access settings [MANDATORY]

You can configure your Jira Server or Jira Cloud site to be publicly available to the internet. Unless content is meant to be public, we highly recommend reviewing project permissions that you have made publicly available in Jira Server, and remove their anonymous access setup before migrating to cloud.

Verify using SQL (tested on Postgres)

Projects

This will flag any projects that have the Browse Project permission set to Anyone.

1 2 3 4 5 6 7 8 9 10 11 12 13 // get list of project permission schemes which has share type as "Anyone" (i.e. open) SELECT p.id, p.pname, ps.name FROM project p INNER JOIN nodeassociation na ON p.id = na.source_node_id INNER JOIN schemepermissions sp ON na.sink_node_id = sp.scheme INNER JOIN permissionscheme ps ON na.sink_node_id = ps.id WHERE na.source_node_entity = 'Project' AND na.sink_node_entity = 'PermissionScheme' AND sp.permission_key='BROWSE_PROJECTS' AND sp.perm_type='group' AND sp.perm_parameter is null

 

Filters

This will get a list of filters which has share type as "share with everyone" (i.e. global)

1 2 3 4 5 // get list of filters which has share type as "share with everyone" (i.e. global) SELECT sr.filtername, sp.sharetype AS current_share_state, sr.username AS owner_name, sr.reqcontent AS JQL FROM searchrequest sr INNER JOIN sharepermissions sp ON sp.entityid = sr.id WHERE sp.sharetype='global' and sp.entitytype ='SearchRequest';

 

Agile Boards

This will get a list of Agile boards which has share type as "share with everyone" (i.e. global)

1 2 3 4 5 6 // get list of Agile boards which has share type as "share with everyone" (i.e. global) SELECT DISTINCT "rv"."NAME" as "Board Name", sr.filtername, sp.sharetype AS current_share_state, sr.username AS owner_name FROM "AO_60DB71_RAPIDVIEW" as rv INNER JOIN searchrequest sr ON sr.id = rv."SAVED_FILTER_ID" INNER JOIN sharepermissions sp ON sp.entityid = sr.id WHERE sp.sharetype='global' and sp.entitytype ='SearchRequest';



Dashboards

This will get a list of Dashboards which has share type as "share with everyone" (i.e. global)

1 2 3 4 5 6 // get list of Dashboard which has share type as "share with everyone" (i.e. global) SELECT DISTINCT pp.id as Dashboard_Id, pp.pagename AS Dashboard_name, sp.sharetype AS current_share_state, pp.username AS owner_name FROM portalpage pp INNER JOIN sharepermissions sp ON sp.entityid = pp.id WHERE sp.sharetype='global' and sp.entitytype ='PortalPage' ORDER BY pp.id;

12. Ensure you won’t exceed your cloud user limit [MANDATORY]

Make sure the sum of users to be migrated from server, plus any users that already exist in cloud, doesn’t exceed your subscription user tier. For example, if you have a 51-100 user subscription and try to import 110 active users, the migration will fail. 

To resolve this, do one of the following:

Verify using SQL (tested on Postgres)

Use the queries referenced in our Get list of licensed users in Jira server guide to get the number of licensed users.

Verify using Support Zip

Use the query below before running a migration to verify the number of users to be migrated with your cloud plan user limit. If needed, reduce the number of users, upgrade your cloud plan, or add more users to your subscription.

1 2 3 4 grep "<Users>" <Support Zip Location>/application-properties/application.xml Example Output: <Users>2205</Users>

13. Check the size of your attachments [RECOMMENDED]

Imports into Jira Cloud that contain a large number of attachments (20+ GB uncompressed) may cause long delays or timeouts. We recommend importing your media (attachments, project avatars, and logos) separately after importing your database backup (entities.xml and activeobjects.xml files).

Verify using SQL (tested on Postgres)

The first query below will identify the overall attachment size from the database. The second query will break it down by project if it needs to be assessed further.

1 2 3 4 5 6 7 8 9 10 11 select round(sum(filesize)/1024/1024,2) as "Total Attachment Size(MB)" from fileattachment join jiraissue on jiraissue.id = fileattachment.issueid; select round(sum(filesize)/1024/1024,2) as "Size(MB) by Project", project.pname as "Project Name" from fileattachment join jiraissue on jiraissue.id = fileattachment.issueid join project on project.id = jiraissue.project group by project.pname order by "Size(MB) by Project" desc;

14. Check for orphan data [RECOMMENDED]

An import may fail if there is orphan data in the backup that is not handled properly in cloud. A common scenario is null project keys.

Verify using your XML backup file

Use the following to try to identify some of the orphan data:

If you notice a blank line in the output, you more than likely have a project key that is null and needs to be corrected by making sure the key value is not empty. Correct it in the entities.xml before importing into cloud.

XML Validity Verification

1 2 3 4 5 6 7 8 xmlstarlet sel -t -v "/entity-engine-xml/Project/@key" -n <Backup File Location>/entities.xml Example Output: SER SKP TEST

15. Check you won't exceed storage limits [RECOMMENDED]

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 documentation. 

16. Back up your data  [RECOMMENDED]

Before you run a migration or any of the updates recommended on this guide, we recommend that you back up your current Jira Server site so that you have a restore point. Similarly, if your destination cloud site has existing data, back up your Jira Cloud site as well in case you need to revert back post-migration for any reason. This is a best practice and adds a restore point in case the maintenance needs to be reverted.

17. Run a test migration [RECOMMENDED]

We strongly recommend you run a test migration before running your production migration. Check out our guidance on testing your migration.

18. Notify support of your migration plan [RECOMMENDED]

If you’re performing your migration over a weekend or holiday, or will have over 1,000 users in cloud, we recommend getting in touch with our migration support team at least two weeks in advance. That way, we can ensure we have extra support on hand during your migration. 

Learn more about how we support cloud migrations.

More information and support

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

 

Last modified on Oct 5, 2021
Cached at 8:59 AM on Oct 20, 2021 |

Additional Help

On this pageBefore you begin1. Confirm your migration method2. PrepareJira Cloud Migration Assistant checklist1. Create a user migration plan [MANDATORY]2. Check your Jira Server version [MANDATORY]3. Fix any duplicate email addresses [MANDATORY]4. Make sure you have the right permissions [MANDATORY]5. Check for conflicts with group names [MANDATORY]6. Update your firewall allowance rules [MANDATORY]7. Determine how you’ll migrate apps [MANDATORY]8. Check your public access settings [MANDATORY]9. Review your server setup [MANDATORY]10. Check your server timezone (if merging cloud sites) [MANDATORY]11. Fix any duplicate shared configuration names [RECOMMENDED]12. Check you won't exceed storage limits [RECOMMENDED]13. Prepare your server instance [RECOMMENDED]14. Prepare your cloud site [RECOMMENDED]15. Back up your data [RECOMMENDED]16. Run a test migration [RECOMMENDED]17. Notify support of your migration plan [RECOMMENDED]Jira Site Import checklist1. Check your Jira Server version [MANDATORY]2. Check your XML file is valid [MANDATORY]3. Check your XML file structure [MANDATORY]5. Check for duplicate and invalid user emails [MANDATORY]6. Turn off the incoming mail handlers in cloud during testing [MANDATORY]7. Check for invalid or unhandled characters [MANDATORY]8. Fix any duplicate workflows [MANDATORY]9. Fix any duplicate clustered jobs [MANDATORY]10. Check the length of your attachment filenames [MANDATORY]11. Check your public access settings [MANDATORY]12. Ensure you won’t exceed your cloud user limit [MANDATORY]13. Check the size of your attachments [RECOMMENDED]14. Check for orphan data [RECOMMENDED]15. Check you won't exceed storage limits [RECOMMENDED]16. Back up your data  [RECOMMENDED]17. Run a test migration [RECOMMENDED]18. Notify support of your migration plan [RECOMMENDED]More information and support
CommunityQuestions, discussions, and articles