Importing and exporting Advanced Roadmaps data allows you to move planning information, such as teams, plans, programs, scenarios, and custom fields, between Jira instances. This is especially useful when you need to migrate to a new Jira instance or clone and restore environments.

On this page:

• Before you begin
• Exporting Advanced Roadmaps data
• Importing Advanced Roadmaps data
• Data types and dependencies

Before you begin

• You must migrate all Jira-specific data, such as projects, users, issues, and dependencies, to the target instance before importing the Advanced Roadmaps data. If a Jira object can’t be found on the target instance, references to it are removed from the imported data, and an audit log is created.
• We recommend setting your audit log level to ADVANCED to ensure all relevant events are captured. Review your audit logs for errors and transformation issues.
• If you encounter partial imports, manually clean up or recreate data as needed.
• Update the export data if you changed identifying properties during Jira migration, such as project keys.
• Note that global app permissions are also included in the export and import.
• The below global app configuration data isn’t exported or imported. After importing, review and manually set these configurations on the target instance:
  • hierarchy configuration
  • dependencies
  • loading limits

Exporting Advanced Roadmaps data

You can export the Advanced Roadmaps data in Jira or through the REST API. Jira will save the exported JSON file in the home folder: ${JIRA_SHARED_HOME}/export/advanced-roadmaps/${fileName}.

Exporting data in Jira

To export Advanced Roadmaps data in Jira:

1. Go to Settings, then Manage apps.
2. In the Advanced Roadmaps for Jira section, select Export Advanced Roadmaps data.
3. Enter the name for the exported file and select Export.

Exporting data using REST API

To export Advanced Roadmaps data using REST API, use the below endpoint. 

[POST] /rest/jpo/1.0/export

You can set the Content-Type header to application/json. The request body can be empty, or you can use the following naming pattern { "fileName": "file-name.json" }.

Importing Advanced Roadmaps data

You can import the Advanced Roadmaps data using the REST API or the UI. To import data, Jira will read the JSON file from the home folder: ${JIRA_SHARED_HOME}/import/advanced-roadmaps/${fileName}.

Before you import data

• Avoid running multiple imports at the same time.
• Set the logging level for com.atlassian.rm.jp.core.importexport to TRACE.
• Set the app's audit logging level to ADVANCED.
• If the import fails, it'll be left in a partial state and you can’t resume it. There's no rollback. You must manually delete imported data or recreate missing data if needed.
• Running an import multiple times from the same file will create duplicate data.
• You can run multiple imports at the same time, but this might cause unexpected behaviors.
• Some data types depend on other data types. For example, programs require plans to be imported first. How Jira data is mapped

Importing data in Jira

To import Advanced Roadmaps data in Jira:

1. Go to Settings, then Manage apps.
2. In the Advanced Roadmaps for Jira section, select Import Advanced Roadmaps data.
3. From the dropdown menu, select the file you want to import and then select Import.

Importing data using REST API

To import Advanced Roadmaps data using REST API, use the below endpoint.

[POST] /rest/jpo/1.0/import

You can set the Content-Type header to application/json. The request body can be empty, or you can use the following naming pattern { "fileName": "file-name.json" }.

How Jira data is mapped

During import, Advanced Roadmap updates references to Jira object IDs using the following identifying properties:

• Users: Username, then email
• Projects: Project key
• Boards: Board name
• Filters: Filter name
• Custom fields: Name
• Issue types: Name
• Issues: Summary and project
• Releases: Name and project
• Project components: Name and project
• Sprints: Name
• Statuses: Name
• Status categories: Name

Data types and dependencies

Teams

• Exported from: TEAM, RESOURCE, PERSON, ABSENCE, AVAILABILITY, ABILITY, SKILL.
• Both shared and plan teams are included.
• During import, users are matched by username or email. Unmatched users aren’t added to teams.

Plans

• Exported from: PLAN, ISSUE_SOURCE, PLANTEAM, TEAM_EX_SPRINT, EXCLUDED_VERSIONS, EXCLUDED_ISSUE_TYPES, EXCLUDED_STATUSES, EXCLUDED_STATUSCATS, NONWORKINGDAYS
• Permissions from: PERMISSIONS.
• Teams are imported first, then plans, with permissions mapped accordingly.

Programs

• Exported from: PROGRAM, with plan identifiers and program permissions.
• Plans must be imported first.
• Permissions are recreated, and users are matched by username or email.

Scenarios

• Exported from multiple SCENARIO_* tables.
• Plans must be imported first.

Custom fields

• Exported from: PLAN_CUSTOM_FIELD, PROGRAM_CUSTOM_FIELD.
• Plans and programs must be imported first.
• Plan releases
• Exported from: PLANVERSION.
• Plans must be imported first.
• Cross-project releases are imported before plan releases.

Cross-project releases

• Exported from: X_PROJECT_VERSION.
• Plans must be imported first.

Saved views

• Exported from: SAVED_VIEW2.
• Plans must be imported first.

Plugin permissions

• Exported from: AOPERMISSION (system-level permissions for groups only).
• Only imported if they do not already exist.

Issue properties

• Not directly exported or imported by Advanced Roadmaps from Jira.
• The entity_properties table should be migrated with Jira data.
• During import, Advanced Roadmaps updates properties like team_id, parent_id, and jpo-exclude-from-plan with new IDs.