How to migrate Dependency Maps from Data Center to Cloud

As teams transition to Jira Cloud, we’re rolling out tools to simplify migrating Dependency Maps. This article describes how to migrate using the export and import UI.

Note: Migration is supported from Dependency Map for Jira version 2.1.3 and later.

Overview

The migration is performed with the following steps:

1. Prepare for migration of your maps.
   1. Upgrade Dependency Map for Jira to a migration compatible version (version 2.1.3 or later).
   2. Migrate legacy maps to the 2.0 map format. Read how to do this here.
   3. Migrate Jira Data Center to Cloud (e.g. using the Jira Cloud Migration Assistant).
2. Export maps to file.
3. Import the exported maps into Cloud.

Step by step

Here we discuss each of the steps in the outline in detail.

Prepare for migration

To be able to migrate a map, it must use the new map format introduced by Dependency Map 2.0. To convert a single legacy map to the new format, open it and click “Save As”. This will create a version of the map which then can be migrated to Jira Cloud.

For conversion of multiple legacy maps, use the process described here.

Before you migrate any Dependency Map, your Jira Data Center instance needs to be migrated to Cloud. This can be done in a phased way, e.g. only migrating some projects etc. Consult the Atlassian documentation about migrating to Cloud for how to do this.

Exporting maps from Jira Data Center

To be able to export maps, you need to run as a user who has access to the maps that shall be exported.

1. Open the “Available maps” page.
2. Edit the URL in the address bar of your browser, make it end with /migration:

   From: https://jira.company.com/plugins/servlet/dependency-map/start
   To:   https://jira.company.com/plugins/servlet/dependency-map/migration

3. Go to the section “Export maps to file, for migration to Jira Cloud“.
4. Select which maps to export by one of the following alternatives:
   1. Click “Load maps” to load all maps.
   2. Use a filter to narrow the list.
   3. Search maps by name.
   4. Use the checkboxes to narrow the selection.
5. Review the list.
6. Click “Export maps to file” to start.
7. A JSON file is downloaded.
8. A summary of what has been exported is displayed.

Import the exported maps into Cloud

On your Jira Cloud instance, you can now import the exported Dependency Maps.

1. Open the “Available maps” page.
2. Edit the URL in the address bar of your browser, make it end with /migration:

   From: https://<jiracloud>/jira/apps/1234...-5678/12345678-...-8901/
   To:   https://<jiracloud>/jira/apps/1234...-5678/12345678-...-8901/migration

3. Click “Import maps from Data Center…” and select a file with the Dependency Maps you exported from Jira Data Center.
4. Review any validation errors and decide whether to proceed with the import or not.
   • Errors such as a missing filter can be resolved by e.g. creating the filter in the Cloud instance, making sure it has the same name as the missing filter.
5. Before proceeding with the import you can select the “Overwrite” option to re-import already imported maps.
6. Click “Import N maps” to start the import (where N is the number of maps in the file).
   • Note that this may take some time to complete – do not close the browser window.
7. When the import has completed, a summary is displayed.

Screenshots of the import steps:

The /migration page:

After selecting a file in step 3, the “Preparing to import” dialog is displayed:

If there are any validation errors, they are displayed as follows:

Before the import is started, a confirmation dialog is displayed:

When the import has completed, a dialog is displayed with a summary of the results and information for each map:

Final words

We’ll post updates as our Cloud migration support evolves.  If you have any questions – Contact us—we’re happy to assist!