/
Migrating Structures

This article is for Data Center. Visit Cloud

Migrating Structures

May 16, 2024

Migrating structure data lets you import one or more structures from a different Jira instances after you have imported projects with Jira's Project Import operation. In addition, you can add structures from a backup file to those that are already present in Jira.

Migrating structure will not affect issues in any way. The issues that make up the hierarchy should already exist in Jira. You may need to run Jira Project Import or the standard Jira data restore first - see Structure Backup, Restore and Migration. 

During migration, the issues in the structures are located in Jira by their issue keys. A structure cannot be migrated if it refers to issues from a project that is missing in Jira.

To migrate structures from a backup:

  1. Navigate to Administration | Structure | Migrate Structure.

  2. Enter the full path to the structure backup file (either .xml or .zip).

  3. Click Select Structures to Restore.

  4. Select the structures that should be restored. 

    • If there's an existing structure with the same ID or name, select Overwrite Existing to replace the existing structure with the one from backup; otherwise, the structure will be restored as a new structure, leaving the existing one unaltered.

    • The "Projects" column will be blank for structures created using generators. Projects are only listed for manually built structures.

    • If you see the 'Structure permissions cannot be fully migrated' message below a structure name, this is typically caused by one of two things: 1) some users or user groups with permissions to the original structure have not been configured in the target Jira instance, or 2) some permissions configured for projects/project roles have not been migrated.

  5. Under the list of structures, you will see a list of additional restore options:

  6. Click Restore Selected Structures.

  7. You will see the Process Status page. Once the restore process is completed, the Show Result button will take you to the result page, where you'll be able to see the result and any warning messages.

After structures have been migrated, open the Structure | Manage Structure page to verify that your structures were restored successfully.

As of version 3.3, Migrate Structure does not support Structure.Testy or Structure.Pages data.

Owners and Permissions

When migrating structures, the following ownerships and permissions are included in the migration:

  • Structure owners

  • View owners

  • Structure permissions

  • "Apply Permissions" rules, if the structures they refer to are migrated

  • When a permission rule cannot be migrated, Structure logs a warning and skips this specific rule

Backups created in a version of Structure prior to 6.2 do not contain usernames and project role names. When trying to migrate from an older backup file, ownerships and permissions that require this information will not be included.