• Documentation

Resolve configuration duplication in Jira migrations

When migrating Jira data from Data Center to Cloud in phases or while consolidating Jira instances, the same configuration can exist in multiple places. For example, you migrate “Customer ID” custom field as part of one phase of your migration. When you migrate “Customer ID” in another phase, this action can cause duplicate “Customer ID” custom fields in your target Cloud site.

While migrating with Jira Cloud Migration Assistant, it currently creates new copies in your cloud site with suffixes such as “Customer ID(migrated)”, “Customer ID(migrated 1)”, “Customer ID(migrated 2)”, and so on. This can lead to a large number of duplicate configurations and increase the manual cleanup load after migration. Read how Jira Cloud Migration Assistant links your data

The improved Jira Cloud Migration Assistant’s pre-migration checks proactively identify potential duplicates before migration and provide structured ways to resolve duplication conflicts.

The ability to resolve configuration duplication is currently available only to a limited number of customers participating in an early access program. If you wish to participate in the early access program, reach out to your Cloud migration manager for details.

How does it work?

As part of pre-migration checks, configurations that would be duplicated during phased migrations are detected. This includes:

  • Custom field

  • Custom field scheme

  • Custom field option

  • Field layout

  • Field layout scheme

  • Issue type scheme (Work type scheme in Cloud)

  • Issue type (Work type in Cloud)

  • Issue status (Status in Cloud)

  • Screen

  • Issue type screen scheme (Work type screen scheme in Cloud)

  • Project roles (Space roles in Cloud)

  • Screen scheme

  • Workflow

  • Workflow scheme

The feature automatically resolves configuration conflicts when possible. For conflicts it cannot resolve safely, it prompts the customer to choose an option.

You can resolve them with one of four actions:

  • Use the configuration from destination

  • Override with the configuration from source

  • Merge configuration

  • Create a new configuration

Before you begin

Before you run pre-migration checks, you need to:

  1. Understand what the Jira Cloud Migration Assistant is and how your data is migrated.

  2. Install or update the migration assistant.

  3. Complete the mandatory tasks in the pre-migration checklist.

  4. Assess apps and users for migration.

Steps to resolve configuration duplication

Step 1: Find the Update rules for configuration entities card

  1. Follow the steps to create a migration plan. Select the projects, boards, filters, users, and groups you wish to move.

  2. Select Save and run pre‑migration checks.

  3. During pre-migration checks, look for the Update rules for configuration entities card. Select Download CSV file.

The Update rules for configuration entities card.

4. You’ll see the available options for each configuration. Edit the CSV file as required. Select Upload CSV file to upload the edited CSV file back.

Table options

Impact

REUSE

  • Select REUSE to reuse the configuration from your Cloud instance.

OVERRIDE

  • Select OVERRIDE to bring in the configuration from your Data Center.

MERGE_SOURCE

  • Select MERGE_SOURCE to merge compatible configuration elements where supported (For example, merging the issue type list in a Custom Field Scheme).

  • If some attributes can't be merged, the source (Data Center) value is retained.

MERGE_DESTINATION

  • Select MERGE_DESTINATION to merge compatible configuration elements where supported (For example, merging the issue type list in a Custom Field Scheme).

  • If some attributes can't be merged, the DESTINATION (Cloud) value is retained.

DEFAULT

  • Select DEFAULT if you’d like us to use the choice you made for the custom field entity.

  • This choice is available only for child entities to custom field, such as options, default values, and version order.

  • For example, if you chose DEFAULT while uploading your first CSV, the choice made for custom field will be chosen.

DECIDE_LATER

  • Select DECIDE_LATER if you’re unsure.

  • This defers the decision for later. You will have to decide after the validation is complete.

  • Lets you decide per individual entity (for example, per custom field, issue type, etc.).

Step 2: Run a check on the uploaded CSV

  1. Select Run check to validate the changes.

  2. If the check fails, download the CSV file containing errors and try to resolve the errors that you see. Select Run check again. Contact support if the check continues to fail.
    Select Upload CSV file to upload the edited CSV file back.

The Run check button

Step 3: Download the Effective configuration CSV

  1. Once the check is complete, download the Effective configuration CSV to review the configurations that were automatically resolved. Read how the configurations are determined

    1. Refer to the selected_choice column to validate the auto-selected choice for each entity, and the Notes column for additional information about the entity.

    2. This file is for reference. Do not modify or upload it.

The Effective Configuration CSV section

Step 4: Download the Conflicted configuration entities CSV

  1. Download the Conflicted configuration entities CSV to view entities that require you to manually select the required configurations.

    1. Each row of the CSV contains information about an entity type, its source and destination, as well as the available configuration choices.

    2. The Choices column contains information in the format: 

      choiceId|remediationStrategy|name|databaseId|availableWhenconditions

    3. Copy the choice ID of your selection from the Choice column and paste it in the Customer_selected_choice_id column.

    4. We recommend that you use the CSV utility tool to make your selections. Install the tool by selecting Download the JAR above the Effective configuration CSV section. See how to use the CSV tool

  2. Select Upload CSV file to upload the edited CSV file back, and the system will validate your choices.

  3. Once you’ve reviewed and fixed the remaining pre-migration checks, select Review migration.

    Follow the usual steps to complete your migration. Read how to review your migration

The conflicted configuration entities section

Use the CSV utility tool

The CSV utility tool is helpful in making edits in bulk in the CSV.

CSV utility tool homepage

To use the tool:

  1. Upload the Conflicted configuration entities CSV in the Upload CSV file section.

  2. Optionally, you can also upload:

    1. A Conflicted configuration entities CSV from a previous migration or test migration in the Reuse Reference CSV section in order to reuse choices from that CSV instead of manually making choices.

    2. A read-only Effective configuration CSV in the Effective configuration CSV section to see the entities that have been auto-resolved.

  3. Select Upload and continue.

  4. Select the Auto-resolved tab to see entities that will be automatically resolved. Information from the uploaded Effective configuration CSV will be shown here. No action is required here.

The auto-resolved tab

5. The Your Decisions tab will show you entities that require action. Choices from the previous migration/test migration CSV will be auto-filled. Check and select the required entities from the dropdown in the Choices column.

Your decisions tab

6. Select Save all choices to save your selections.

  • Select Download CSV to download the updated CSV file.

You can upload this CSV back into the Pre-migration checks screen and proceed with your migration.

Still need help?

The Atlassian Community is here for you.
Ask the Community
On this pageHow does it work?Before you beginSteps to resolve configuration duplicationStep 1: Find the Update rules for configuration entities cardStep 2: Run a check on the uploaded CSVStep 3: Download the Effective configuration CSVStep 4: Download the Conflicted configuration entities CSVUse the CSV utility tool
CommunityQuestions, discussions, and articles