How to Migrate Structure App Data to Jira Cloud: Common Pitfalls to Avoid

[#1]

A comprehensive roadmap of the frequent snags on the journey from on-prem to cloud.

So you want to migrate to Jira Cloud, and you want to take your apps — and their data — along for the ride. If you're a Structure for Jira user (or admin) and you're worried about being a trailblazer on the Structure-to-cloud pathway, don't worry: The path is now well-traveled.

If you're ready to take the plunge, our wiki page, along with instructions in the Jira Cloud Migration Assistant guide, should give you all you need. But now that we've gained experience in these migrations, we know the kinds of common problems that show up. This article will walk through the process. At each step, we will also document potential problems so you know how to avoid them. 

A map of potential snags

We'll walk through the transition using the Jira Cloud Migration Assistant (JCMA), migrating the Jira project data at the same time — a requirement for the Structure migration to work.

We'll illustrate with a migration that was completed mid-January 2022 with Jira 8.8.1. (This should work for all versions up to 8.20) and the JCMA v1.6.6 and Structure v7.3. You’ll want the latest version of the JCMA and Structure because you’ll get the most support, but also because the JCMA will constantly throw errors if it detects an update is available but not installed in the UPM. 

We’ll also need a clean cloud environment to migrate to (you can migrate to an in-use environment, but the details how to handle that are outside the scope of this guide — please reach out if you need help). You’ll need admin access to both. 

Note: While you could migrate Jira projects incrementally or piecemeal, this is not recommended for Structure. Because Structure isn’t project-based, but works across your instance, it is best to migrate all the data over at once.

 

In the admin section, system subsection, find the “Migrate to Cloud” option. This will take you to the JCMA interface. Unless otherwise stated, this is the place we’ll keep coming back to. It should look like this:

Obviously your numbers for Groups, Users, etc will be different. 

We will perform the three steps outlined above, in that order. But there is one special step needed in part 2 that isn’t mentioned in the JCMA walkthrough proper. You can find the details in our wiki page. 

1. Assess your apps

This is a check to make sure you indeed have the latest version (or at least, a version compatible with the current JCMA version). It will list all your apps and give you the option to indicate whether each is needed in your new cloud environment.

Our example shows a few different options. We will set the status “needed in cloud” for just Structure, and not for the others. In your particular migration you may want to include all the apps you intend to migrate. Please note, there isn’t currently a migration pathway for Structure.Gantt — please track our release notes for updates on that.

Some notes:

• The red x symbols indicate there isn’t an equivalent cloud version for that app in the marketplace. 
• "View differences" allows you to go to a vendor-indicated page, which outlines the differences in their cloud vs on-prem products. 
• If it says "View Listing," it just means the vendor hasn’t supplied such a reference and it will take you to the marketplace listing itself. 
• "Can be migrated" is another column — if the app needs an upgrade to even be considered for migration, it will demand that. 
• The link to “automated path” will send you to our documentation. 

Notes are purely for your own reference later in your migration configuration. This table of options can be converted to a CSV file and downloaded if you choose. When we select "Done," we are brought back to the JCMA main page. 

2. Prepare your apps

This menu allows you to connect to a cloud instance if you have one ready, or create one if you still need to create one. You can select “choose cloud site” to go to an interactive menu where you fill in your on-prem Jira instance and can select from all cloud sites your Atlassian ID has access to. Remember to indicate that you allow Atlassian to access your data, since without it, nothing will get migrated. Once you click "approve," you’ll be redirected back to your on-prem JCMA menu for preparing your apps. When you click "continue," you'll be prompted to install the apps in the new cloud environment.

This list is populated from the ones we indicated were needed in cloud in our previous menu choice. We can again click "continue," and it will take us to the agreement step where we now allow the app vendors access to the on-prem data so it can be migrated. You may need to update or sign a migration agreement or EULA. 

Once we hit "done," we have completed step 2.

If you've completed the first two steps, you'll see this message pop up:

Not so fast! There is one more step covered below.

3. Migrate your data.

We are now going to create a migration.

Your migrations will be listed here. We are going to select “create new migration."

In the next menu, we will give our migration a name and point it to a cloud instance where we want to move all our data. 

Extremely important! Remember the name of your migration. It is important for later. Copy it to a note, verbatim. 

Our next menu will ask us to select what data we are going to migrate. 

Select all your projects. If you select the empty box in the top left of the screen, it will select all your projects in this screen, not all the projects. You need to do that for each page here. 

Migrating users and groups over will be important because those links will also need to be preserved for ownership of structures, views, and permissions. 

After that we will select the apps to migrate. 

It is important to note that selecting Structure here is not enough to migrate structures over. We still need to create a structure migration configuration. 

If you proceed to migrate from within the JCMA, no Structure data will be migrated. 

Proceeding to the "check for errors" phase next, you will almost certainly run into errors. You’ll have warnings about user tiers not lining up, groups and project permissions, etc. You will also see an automated message, as below:

Yellow warnings are not critical and will not prevent your data migration. But red warnings must be dealt with before going to the next step. The explanation of the problem and possible ways to resolve it will show up under the warning.

At this point we are saving our Migration Set (do not run it yet!) and going to create Structure migration configuration. Go to Administration | Structure | Migrate to Cloud and create a new configuration there. Give it the exact same name you used for the Jira migration set created earlier. If the names do not match exactly, Structure data will not migrate.

Here we also have the option to choose which structures we want to migrate or just take it all. Just make sure that Jira projects behind chosen structures are also included in the migration package. 

Now, we are all set to start our migration 

Return to Administration | System | Migrate to Cloud and run the JCMA migration we’ve created. You’ll see the progress bar showing the status of operations.  

With a bit of luck we will see in a couple of minutes that all data has been migrated successfully and we can move to the next step.

If we click on “view details” in the current migration action menu we can check individual statuses of each migrated item, as well as download logs and error reports.

But you might also have a case where app migration progress stays in “spinning wheel” mode for a long time. That doesn’t always mean something is wrong, so don't panic — first we need to check what app data we now have on the cloud site.

Go to Jira Cloud site Settings | Apps. In the left panel, locate the Structure Cloud section, and click "Migration." This will bring up a list of migrations with the status of each. If your current migration status is marked with a green “Done” or orange “Review required” sign, that means our data has been successfully migrated and one or several structures need to be reviewed. We can now go into the Structure app itself and inspect those one by one.

If your migration doesn't work…

If for some reason we have failed an app migration attempt, we still need to check which Jira projects and structures have been moved (if any) to prepare for the second attempt.

Make sure you clean everything up before trying again. Having Jira projects with the same names on the cloud instance will prevent JCMA from running, and migrating the same structures over existing ones will create duplicates, which can be confusing during the following review process. 

You can needless Jira projects and Structures manually, by going into Jira settings | Projects menu and Structure | Manage Structures menu. It is also possible to wipe out the whole cloud instance at once, for example if it’s been used for test migration runs and now is ready to take up the main data set. Atlassian also has a useful how-to article on the subject. 

We hope this has been useful. Cloud migrations can be tricky, but remember that we're here to help – reach out if you're having any trouble!