This is a resumed guide of how to migrate a Linux Server – Jira Servicedesk Instance to Atlassian cloud. This guidance is meant for people trying yo migrate to the cloud . Certain Jira Administration & Linux knowledge is required to follow the guide successfully
Migrating attachments will be done in the next post 🙂
Requirements and recommendations
- Basic knowledge and experience managing JIRA . Some terms used or guidance may bypass information assuming you know the system.
- Create an Atlassian account , Standard plan ( Trial is available ) ->https://www.atlassian.com/
- Install: Cloud Migration Assistant app ( Jira ) In server & User management app ( Jira)
- Create a Snapshot or a backup of your enviorment and a plan to roll back if possible , clone the server in a test enviorment
- Root credentials ( Linux )
- Port SSH will have to be opened to your machine or network
- Read official guidance’s ( Atlassian )
- Disable Mail handlers before test or going live ( or either block internet traffic on the Jira server)
- If you use AD SYNC . and for any reason you need to get in the server for any reason after the migration , beware this guidance migrates all users from AD to Jira Directory. Doing so you will need a Jira Admin account not synced to ad . if any AD user has to get in the old enviorment. You must reset the password as is lost in the process.
- Remember to do a testing phase and all the Atlassian Official documentation checks
- You should not need to pay for any of the 2 tools used in this guidance , as for now the user management tool is free if you request trial , and cloud migration assistant is free.
- If you migrate confluence after this guidance , remember to create the project links
- The method for this guidance is called Site Import/Export. No other method works for formerly service desk Jira . Other project types are supported with the cloud migration assistant
- Strategy Recommended : We will use Cloud migration assistant to check for possible errors in our Jira directory – AD Sync. Migrate the users once all errors are cleared. Further in the guidance you’ll notice we will migrate with the site export. but we will “merge” the users after that . If you do not resolve invalid emails or duplicates… with the assistant you will have to do so during the site import/export. If not done the migration wont continue. So as recommendation and good practice we do this before the process of “Site / import export”
- Make sure you have in hand your Legacy Jira SEN license. Just in case asked for support or any license discounts .
Useful Links Section
Jira User management tool ( Used for this guidance )
Jira Cloud Migration assistant app
Compare Cloud migration methods
About licensing limitations and issues , very important!
Before going live , we faced issues with email handler outbound ( Basically we had to instruct Atlassian to finish the trial mode , with trial you cant send more than 100 notifications outbound per day! . So make sure you resolve this with Support beforehand , pay in advance for the year or just migrate when you finished the trial ( so its paid ).
If you do not action on licensing and you go live before the Trial ends ( before your first bill ) you will get this error:
You’ve sent the maximum number of notifications in 12 hours for your plan. This limitation will be removed when you move to Standard/Premium (paid) plan after your evaluation period.
Also make sure your users are not in a group that makes them “Jira servicedesk users or similar” inherited from the Legacy Server wich actually migrates them as agents. If that happens so you will be charged with a numerous amount of money. Make sure you check how many agents you have or you need . If migrating the users causes you to have loads of agents , prepare to remove them manually from Jira Service Management.
About the user migration
Read all the official guidance’s , I recommend you to read them all and also use the “User migration assistant to migrate the users and amend your Jira . If you do use AD sync for example , you may have invalid emails or other settings that Jira cloud wont accept .
Step 1 . Disabling Handlers ( optional ) and email inbound/outbound
Disable the handlers if required so both enviorment don’t run at the same time prior migration . If you do not do this in a test enviorment you will have to inform your team during this period – No tickets will be received. ( I really recommend you do this in a cloned server if possible ).
Step 2 Migrating the users with Cloud Migration Assistant & Resolving possible issues
- In Jira Server or Data Center go to Settings > Manage apps.
- Choose Find new apps and search for Jira Cloud Migration Assistant.
- Choose Install and you’re all set.
Run the Migration process and resolve any issues that may be displayed ( example attached )
In this case , Email addresses in AD had to be sorted… ( assigning a fictional email address or either deleting the user ) . note: Sometimes deleting the user does not work so I recommend to just assign fictional addresses and later on clean-up the cloud user section
We choose to do this so site import/ export method does not give any problems towards the users as your Jira users will be amended with this assistant.
After resolving all your issues you should be able to migrate the users with the assistant as displayed.
Step 3 ( Only required if you using AD SYNC ) . Migrating AD users directory to Jira Service desk directory & Disabling SYNC
Important: Here you have to use an admin account that is not ADSYNC, because we will disable ADSYNC after this step. This step is mandatory to site import/export!
Only perform this actions if you are using AD SYNC . AD SYNC its not supported to be migrated with site import/ export. So what we will do is migrate all the AD users into Jira users.
You must install the plugin . Otherwise you will have to amend this directly via Database . The Atlassian guides recommend you to use a plugin if possible as the Database method its not supported. If you skip this part all tickets raised or assigned to AD accounts will get “former user” status. Meaning you will not know who raised the ticket or who has it assigned in the past .
Link for the plugin – https://marketplace.atlassian.com/apps/1215285/user-management-for-jira?utm_source=jira-server-app&tab=overview&utm_content=select_users&utm_campaign=usermanagement-server&hosting=server&utm_medium=footer&utm_term=bulk
Link for the Database Method:
After installing the plugin you would see this screen in user management ( bulk user actions )
Select the Filter: Active Directory , Confirm selection
Select the option , change directory
Confirm and wait for the process to finish
Migrated users will look like this in the list ( notice they are members of both directories )
Non migrated users ( during the process or if failed will look like this )
Logs section can be found here :
Disable Active Directory SYNC * Clean-up . Beware If this step is not done , Importing Servicedesk into the cloud will fail
You will find the migrated users with the following in the bulk list ( where you can find they belong to 2 directories).To ensure all is migrated . You should see all users in both directories in all the pages.
Disable AD integration/ Remove( once all users copied)
Disable and remove the Active directory Server Sync
Step 4 . Export the XML database for Jira cloud
Must do : Prepare SSH connection to Jira server ( port 22 ). Use Putty if using windows client.
Using the backup system section, we will back up the XML into the Server. Give it a friendly name
Getting the XML
- Connect Via SSH to the server and head to the folder: /home/jira/jira-home/export
- Run sudo su ( root privileges)
- Move the file in the apache folder so we download it
- Change permission to public so we can download it.
- Delete the file when downloaded.
$ sudo su $ cd /home/jira/jira-home/export $ mv Migration02062021b.zip /var/www/html $ cd /var/www/html $ chmod 777 Migration02062021b.zip $ (only when downloaded the file -> rm Migration02062021b.zip
After this procedure you can download the files directly using the main Jira web+ the name of the zip
Step 5. Migrating using site import/export to the cloud
Now we are going to upload the file that we got out of our Jira server (ZIP)
This file should contain 2 files Compressed . Activeobjects.xml and Entities.XML
In restore system we will select the file we exported ( it should be on our computer ) . Also select the option “Merge with existing cloud users “. This is located in the System options in Jira cloud
We will select “Import data” , and Merge users ( that’s why we used before Jira cloud assistant! ). And then select the ZIP .
Process will start once selected
Once all is review we will run the import and our project will be migrated to the cloud .
Problems that you may encounter during site import
So . You got here . Im sorry and you seeing this error ( We all been there ). Here I leave you some tips.
** Import again with a different backup file or get in touch with our support team …. Include the steps you followed , along with any unique characteristics of your jira Setup **
Corrupted /Invalid addresses
Error IMCAEX . Users with this prefix needs fixing .
Remove this users ( either from ad or Jira directory)
The users and groups failed:
FIX: Make sure you used cloud migration assistant and amended all duplicated, invalid users.
The following tickets needs amending from the entities.xml backup as are missing reference , if we don’t amend the file the migration fails
Issues with following IDs are missing project Reference
This all can be found on the XML and removed; they are missing ticket reference ( correct entities.xml)
This ones failed for me:
51838, 51839, 51843, 51845, 51846,
51847, 51849, 51850, 51853, 51854, 51855, 51866, 51870, 51871, 51873, 51878, 51880, 51881, 51883,
51884, 51885, 51888, 51889, 51895, 51897, 51898, 51899, 51900, 51901, 51906, 51909, 51910, 51911,
51913, 51916, 51917, 51919, 51922, 51923, 51924, 51925, 51927, 51928, 51929, 51933, 51934, 51935,
51936, 51938, 51939, 51940, 51942, 51943, 51944, 51945, 51947, 51950,
51957, 51958, 51959, 51961, 51962, 51964, 51967, 51968, 51970, 51972,
51976, 51979, 51982, 51983, 51984, 51985, 51988, 51992, 51999, 52002, 52006
I removed them all from the XML using Notepad++. it is clear are missing references. No idea why this happened.