Migrate a Backbone synchronization to a new Backbone synchronization
This guide explains how to migrate a Backbone synchronization to another so that the synchronization works for the project(s) just as it did before migration.
Possible scenarios
You are synchronizing two projects on two different Jira instances. Let's call them Project A on Jira Instance A, and Project B on Jira Instance B. In case you only use one Jira instance, ignore the reference to two Jira instances.
Migrate a synchronized project to another Jira instance
The synchronization is configured in the Jira instance A. You want to migrate Project A to another instance, but after moving, you want Project A to synchronize with Project B just like before the migration.
You should first migrate the project A as described in the Atlassian docs, then follow the steps below.Migrate a synchronization from a workaround solution to a real one
The synchronization is configured in another Jira instance, e.g. because you started to synchronize two cloud instances before Backbone officially supported it. Please follow the steps below.
Requirements
You can use the instructions on both deployment types of Backbone, i.e. Jira Server and Jira Cloud. However, at the moment we do not support to migrate a synchronization over email or file exchange, because step 2 (Exporting the synchronization config) is not supported. If you are affected by this, please reach out to our support team and describe us your use case.
In case you are synchronizing comments with enriched mapping, you need Python 3 installed on your computer.
Instructions
Step-1: Prepare the synchronization migration
Stop the original running synchronization
Export the synchronization config for this synchronization
Download the synced issue data for this synchronization (open the synchronization config and click ••• > Download synchronized issues)
Step-2: Migrate the synchronization
Go to (the new Jira instance for) Project A and create a new synchronization with Project B
Import synchronization config that you exported in step 1.2
In the synchronization config, check every tab ('Issue types', 'Fields - mappings' etc.) for validation errors – these will appear in yellow warning boxes. These warnings can appear due to custom IDs (issue type IDs, field IDs, etc) being different in the new Jira instance. Find any errors and correct them.
Step-3: Pair the issues
There are different ways depending on how you synced comments before:
If you haven’t synced comments
Upload the synced issue data for the issues in this project that you exported in step 1.3 (click ••• > Pair existing issues > Pair existing issues synced with Backbone before)
If you synced comments with anonymous mapping
Do an automatic pairing of your issues: More about automatic pairing
If you synced comments with enriched mapping
The migration works only, if the enrichment format is on the first line. For example:
_commented by ${comment.author} - ${comment.addTime}_
${comment.content}
If you are synchronizing comments with a different enrichment format, then please contact our support.
Download the script translateMappingsMigrateBackbone.py.zip
Run
python3 -m pip install requests
in the directory of the script to install the requests module for pythonExecute the script:
python3 translate-comment-mappings.py -f <PATH_TO_YOUR_FILE_FROM_STEP_1> --bu1 <URL_OF_OLD_JIRA_A> --u1 <USER_FOR_OLD_JIRA_A> --p1 <PASSWORD_OF_OLD_JIRA_A> --bu2 <URL_OF_NEW_JIRA_A> --u2 <USER_FOR_NEW_JIRA_A> --p2 <PASSWORD_OF_NEW_JIRA_A>
In case you are migrating Jira Instance B, you can add the ‘-r’ flag:python3 translate-comment-mappings.py -f <PATH_TO_YOUR_FILE_FROM_STEP_1> --bu1 <URL_OF_OLD_JIRA_B> --u1 <USER_FOR_OLD_JIRA_B> --p1 <PASSWORD_OF_OLD_JIRA_B> --bu2 <URL_OF_NEW_JIRA_B> --u2 <USER_FOR_NEW_JIRA_B> --p2 <PASSWORD_OF_NEW_JIRA_B> -r
This will produce a new file<PATH_TO_YOUR_FILE_FROM_STEP_1>-converted.json
Upload the new file from step 2.3 (click ••• > Pair existing issues > Pair existing issues synced with Backbone before) to pair the issues
Step-4: Start the new synchronization
Start the new synchronization
In the new synchronization, trigger a resync from Project A to Project B and afterwards from Project B to Project A. Select only the summary field to resync, so the resync doesn't take long. This is done in order to recreate the information in the Sync info panel
Once you have verified everything is working correctly, delete the original synchronization. This will also delete the old information in the sync info panel