Before you migrate from a Data Center instance to a Cloud instance, you must make sure your structures are set up properly. This includes updating the app on your instance, if necessary, to the latest version, and checking the content of your structures.
Updating Structure
If you’re using an outdated version of structure, you will see the following error message during the pre-migration check in the Jira Cloud Migration Assistant (JCMA).
The apps listed below need to register their cloud app to receive notifications for a successful migration
Make sure you upgrade Structure to the latest version before continuing with the migration.
The same applies to the Gantt Charts app. If you’re migrating Gantt data, you must use the latest version of the app.
Inspecting your structures
The difference in architecture between Cloud and Data Center means there are limits on the content you can migrate. Despite Structure Cloud’s similar functionality to Structure Data Center, migration does not include some features, while others may use a different method to migrate.
The following are common examples of problems you may encounter during a migration.
Unsupported features
Features available on Data Center, but unsupported on Cloud, are not included during a migration. If you use these in a structure you plan on migrating, either replace them with a supported alternative or remove them from those structures, if possible.
Large structures
Structures on Structure Cloud have a set limit of 30,000 items. You can still migrate structures from Data Center that are over the limit, but some content will not display post-migration.
Make sure you optimize your structure as much as possible before migrating. One strategy is to adjust the scope of generators to lessen the amount of work items they add. For example, excluding closed work items, or excluding work items from specific projects. You can also split one large structure into multiple smaller structures, keeping each one under the 30,000 item limit.
Custom views
Migration only includes views saved and associated to a structure. Make sure columns you want to keep are saved in a custom view, and make sure your custom views are associated with at least one of the migrated structures.
Unsupported Formula column functions
Formulas that use any of the functions that are incompatible with Structure Cloud are included during a migration, but the functions will not work or return the results you expect. Make sure you adjust your formulas before migration, or recreate them after migration using Structure Cloud’s functions.
Structure permissions
Any set permissions must meet the following criteria to migrate:
-
No permissions are copied from another structure.
-
Users, groups, and roles must be mapped to a new user, group, and role on your Cloud instance.
-
Each group of permissions is greater than, or equal to, any previous permission groups—also known as a non-decreasing monotonic sequence.
Make sure you adjust your permissions before migrating. If you prefer, you can recreate a structure’s permissions after migration.
Structure owners
Generators in a structure only display work items that the owner can see in their Jira instance. If the owner of a structure doesn’t have access to, or doesn’t exist in, the Cloud instance, their structure will appear empty after migrating.
Make sure the users that own a structure exist on your Cloud instance, and have the same access level before migrating.
Unused structures
It can be beneficial to exclude unused structures from the scope of your migration. Go to the Manage Structures page on your instance and check the Last opened column. Using your own criteria, we recommend archiving or deleting structures you haven’t used over a period of time.
Tools to help you inspect structures
The Performance Audit log
Go to Administration > Structure > Support to find the audit log, which contains the configurations of all existing structures. You can search this page to find:
-
The current owners of structures on your instance.
-
Generator types, S-JQL functions used in generators and filters, and any manual adjustments made to your structures.
-
References to custom fields and saved Jira filters in generator configurations. For example, viewing a configuration to account for a filter that doesn’t exist on your Cloud instance.
The following example shows the configuration of a structure named “Team’s tasks”. You can see the different types of generators, the JQL queries of both the Insert generator and the Filter generator, the name of the owner, and the enabled manual adjustments.
Groovy scripts
The following scripts—which all require Scriptrunner to be installed on your instance—can help you find specific types of content and structures on your instance.
-
Use the Show All Structure Boards and Corresponding Item Counts script to generate your structures, count items across them, and output an item count for each structure. This can help identify any structures that exceed the 30,000 item limit.
Running this script may use a lot of resources and time based on the number and complexity of structures in your instance. We recommend running it outside of business hours to avoid disruptions.
-
Find unused structures with the List Structures That Haven’t Been Accessed script. You can adjust the time frame to cover more time if needed.
-
To make sure all existing views migrate to your Cloud instance, use the Associate Unassociated Views With a Structure script.
-
Run the Find Unsupported Formulas Before Migrating to Cloud script to analyze formulas in views and columns that contain unsupported functions. You can then adjust the formulas to prepare them for migration.
-
Find references to a specific field in generators, transformations, and saved formulas with the Find Field Usage Across Structures script. If any fields don’t exist, or use a different name or ID, on Cloud, this script will help you make adjustments to your structure.
-
The Find Saved Views Containing Notes Columns identifies any saved view which contains a Notes column. While this column is supported during migration, it will appear empty when the migration finishes. These columns need adjustments after migration, and the results of this script can help you determine if you need to take an action to restore the notes data.
Next steps
After you make any adjustments to your DC structures, you should view:
-
Our step-by-step guide to migration with the JCMA.
-
Additional migration notes to find information about how more specific features migrate.
-
The migration frequently asked questions page.
If your migration target is an Atlassian Government Cloud instance, make sure to review the guide on migrating to an AGC instance.