Migrating Structures

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:

   Restore Structure Permissions	If selected, Structure will attempt to restore the access permissions for the imported structures. This attempt may fail if the permission rules refer to users or groups not present in Jira. If you don't select this option, or if the attempt to restore permissions fails, the restored structure will have no permission rules. Jira administrators can configure permission rules through the Manage Structures page.
   Restore Synchronizers	If selected, the synchronizers for selected structures are restored. Synchronizers configuration is imported as-is, and might not make sense on a new Jira instance. After you have restored synchronizers, please visit the Synchronization Settings page to check if the synchronizers are configured correctly.
   Restore Structure History	If selected, structures are imported along with their history (if it is present in the backup file). If not selected, structures will have no history.
   Restore User Favorites	If selected, the plugin will try to restore "favorite" marks made by users for the selected structures.
   Restore Views	If selected, all views from the backup files will be restored. If there's a conflict and a view with a given ID already exists, Structure will first verify if the view being restored is different from the one in the system. If it is, Structure will restore the backup view as a new view with a different ID.
   Restore View Settings for Structures	If selected, view settings for the selected structures will be restored.
   Restore Configuration	If selected, the global app permissions will be restored. This includes the list of projects, for which Structure is enabled, permissions to use or create structures, permissions to use Automation, etc.
   Restore Dark Features	If selected, the dark features settings will be restored.

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.