This article was written by Kamil Beer, an Atlassian Engineer at Idalko.
We’re happy to see you join us for Part III of our Migrating Apps series. Today’s topic is the popular Jira “Structure – Project Management at Scale” add-on by ALM works and how to migrate it.
You can see it on many Jiras, where it displays huge projects as multi-leveled task hierarchies. As with other crucial plugins, you may need to migrate it to Cloud – and Idalko is here to help you out!
Migrating Structure for Jira
Let’s review the difference between the two deployments first. From the documentation, it’s apparent that the Cloud add-on unfortunately lacks many key on-prem features.
To start, Automations have been affected, one of which are the relatively new Effectors (that copy information from Structure fields to Jira fields). The scope of the overall change to automations is hard to assess, as the link in the official documentation doesn’t work.
Transformations aren’t included, as is sorting by columns. S-JQL, a type of Structure JQL syntax, is also unavailable. You can’t export and import structures anymore. The Memos feature (that allows you to insert custom objects like notes or requirements) was likewise removed. Lastly, you no longer see the “Structure” panel in Jira issues.
ALM Works display their efforts towards a better Cloud version on a public roadmap. Sadly, we see that even basic functions like column sorting or JQL searching are yet to be shipped – with the estimated time of one to two years. The option to migrate structures via JCMA, (that we will cover next) was added recently.
Structure has many extensions, like Structure.Testy or Structure.Gannt. On Cloud, only .Gannt is available.
The documentation doesn’t mention if and when these apps will be adapted. After searching on other channels, only one community thread mentions .Testy. Pages are mentioned in a thread from April 2021, where one of the add-on developers states there are no near-term plans to adapt this app for Cloud. The newest extension “Structure.Deliver”, used for Agile planning, is also available only on-prem.
ALM Works propose two migration paths: One using the Migration Assistant, another a manual migration.
The second one, despite being named in a way that may remind you of the “Site Import” Jira migration type, is simply about creating a backup, recording every setting (including those of Structure.Gantt), and then recreating everything on Cloud manually. No easy-to-import archives, as with Jira’s Site Import, are used in this case.
The JCMA option branches into two more paths; one uses the Atlassian App migrator, the other Structure’s native capabilities. At the time of writing (Q4/21), the official Jira add-on migrator went from its Early Access stage to the Beta version, and so we’d like to focus on the second method by ALM works.
First, the limitations: You can only migrate structures with manually added issues & folders, that have perhaps been sorted through Automations. Only custom structure views can be migrated.
The migration interface is in Administration -> Structure -> Migrate to Cloud. It contains two important parts: the Configuration name and Structures. In the first field, you record the name of the configuration that you prepared (but haven’t started) in JCMA.
This is important: you need to set this up before doing the mentioned Jira migration.
ALM works describe that to do this, you must enable the app-migration Dark feature:
- Go to the page: <jiraurl>/secure/SiteDarkFeatures!default.jspa
- Into the “Enable dark feature” box, add com.atlassian.jira.migration.app-migration.feature.
- Choose “Add”.
When we tried to perform the migration, it worked even without turning on this setting, but as a best practice proposed by the vendor, we recommend that you turn it on.
Under Structures, select what to migrate. Clean your instance by moving only those Structures that you actively use. Your stakeholders will tell you which those are, or you can search for the most popular structures:
Another option is the Performance Audit Log, that shows recently opened or edited structures.
Note that you should only migrate those structures whose issues you will be moving concurrently or that are already on Cloud. When you selected and joined them with the plan in JCMA, you can begin!
When the migration is done, review that all issues and users have moved to the Cloud successfully – and then check the Cloud app’s status (Apps -> Migration -> Review).
There are two levels here: Migrations and the structures themselves. They both have several stages:
- Review Required (this means there have been some changes you should know about)
- In Progress
When you choose „Audit“, you see several notices about what changed. If something went wrong, you can always re-run the migration in five days from the original run.
In every migrated structure, you will see an error message recommending that you review it first:
After you migrate each of the structures, we recommend double-checking the above, along with the changes in automations, permissions, memos, and other objects unavailable in Cloud. Then, you mark it as reviewed and you’re good to go.
Structure for Jira is an example of something we haven’t seen on the previous add-ons: a native migration utility. It helps you transfer your app data until the Atlassian app migrator is more mature.
That said, Structure itself is another plug-in that suffers from a lack of feature parity (most apparent in the case of . Testy and .Pages not being ported to Cloud), as many of its Server/DC functionalities simply don’t (or can’t) exist on the new environment. We’re looking forward to ALM works improving the Cloud version so that it provides mostly a similar experience as the on-prem add-on.
- The 2021 Guide to Migrating Jira: Preparation, Planning, Testing, and Execution
- Migrating Atlassian Apps from Server to Cloud – Part I: Migrate Scriptrunner
- Migrating Atlassian Apps from Server to Cloud – Part II: Gliffy and Draw.io
- What’s on the Atlassian Roadmap for Q1 2022?
- How to Prepare and Validate your Jira Test Instance after Changes or Migration
- GDPR: The Complete Guide to Compliance Regulations in Jira