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:

• The Jira Cloud Migration Assistant

• Jira Cloud site import

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:

• The Jira Server or Cloud user interface

• An unzipped Jira Support Zip

• An unzipped Jira XML Backup

• SQL queries on the source instance

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. 

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

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. Contact Atlassian Support for the flexibility to chose specific users or groups to migrate.

2. Check your Jira Server version MANDATORY

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

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. 

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:

• has System Administrator global permissions on the Server instance

• exists in the target cloud site

• has Site Administrator permission in cloud

• has Create issues permission for all projects you're migrating

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.

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

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. 

// 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

// 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';

// get list of Agile broads 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';

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

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 

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

JVM_MINIMUM_MEMORY="4096m"
JVM_MAXIMUM_MEMORY="4096m"

JVM_MINIMUM_MEMORY="4096m"
JVM_MAXIMUM_MEMORY="4096m"

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. 

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.

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

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.

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

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.

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

3. Check your XML file structure MANDATORY

JIRA-backup-XXXXXX
├── activeobjects.xml
├── entities.xml
├── data
│   ├── attachments
│   └── avatars
└── logos

media-only-X.zip
└─── data
      ├── attachments
      │         ├── ProjectKey
      │         │         └── 10000
      │         │		    ├── IssueKey-1
      │         │		    ├── IssueKey-2
      │         │       	└── IssueKey-3
      │         └─── ProjectKey2
      └── avatars

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"

grep 'lowerEmailAddress="'<Backup File Location>/entities.xml | awk -F\lowerEmailAddress=\" '{print $2}' | cut -d\" -f1 | sort | uniq -c

Example Output:
   1 felix.test@test.com
   2 fixed.test@test.com
   1 florian.test@test.com

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

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="classic default workflow">

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

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

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

grep <Backup File Location>/entities.xml | cut -d\  -f9 | awk 'length > 250  {print ;}' | wc -l


Example Output:
   0 

// 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

// 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';

// get list of Agile broads 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';

// 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;

grep "<Users>" <Support Zip Location>/application-properties/application.xml

Example Output:
<Users>2205</Users>

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;

xmlstarlet sel -t -v "/entity-engine-xml/Project/@key"  -n <Backup File Location>/entities.xml 


Example Output:
SER

SKP
TEST