Build your migration's gap list before you start, and make the differ refuse to guess

Migration Gap List: Key Factors

Build a comprehensive migration gap list before initiating the process, and resist the temptation to make assumptions. Essential takeaways:

- Construct a list of what your migration will not carry, derived from your own inventory prior to day one, with partials clearly identified.

- Coverage operates in three states: carried, partial, and not carried. Custom fields are copied according to type, while workflows are only copied when linked to a project.

- Identical configuration names in different tenants are distinct entities. Remap based on ID, and avoid mapping ambiguous names at the destination.

- Different tools are required for each path: JCMA for Jira and JSM, CCMA for Confluence, and Data transfer for Cloud-to-Cloud migrations.

- Each Atlassian migration carries most data but leaves a remainder. The remainder is published, varies per path, and is often overlooked in planning.

- Generate two critical artifacts: a list of what the tool won't carry and an ID remap table that refuses to make assumptions.

- Prerequisites include Node 18 or later, verified on v24.15.0, read access to the source instance, and an empty directory. All operations occur offline, exporting an inventory and diffing it locally without writing to the tenant.

- Be aware of your migration path, as tools differ accordingly: Jira/JSM Data Center to Cloud uses the Jira Cloud Migration Assistant, Confluence Data Center to Cloud uses the Confluence Cloud Migration Assistant, and Cloud to Cloud uses Data transfer.

- The process typically takes around forty minutes, primarily focused on reviewing the copied-data page properly.

- The crucial insight is that the set difference method (listing copied items and subtracting from the original) is flawed and exacerbates the issue. Atlassian's page does not provide clear yes or no answers for each item type. Instead, it notes that custom fields are copied (Text, Date, Number, Time, Labels, URL, Select list), while project pickers, affected services, and responders are not. Workflows and permission schemes not linked to a project are also excluded.

- The coverage model adopts three states: carried, partial, and not carried. Partial items are highlighted in the output with associated caveats.

- The copied-data page should be encoded as a three-state coverage map for your specific path. Export an inventory of your source instance by kind in JSON format. Compute the gap list, separating partials from outright gaps. Verify that the differ exits non-zero when encountering ambiguous names. Assign an owner to each item, transforming the list into a scoped plan.

- Step 1: Encode the page as three states. Open the current copied-data page for your path, save it as gaps.mjs, and define the CARRIED, PARTIAL, and NOT_CARRIED constants. This map is specific to Cloud-to-Cloud migrations. Confirm that none of the states are empty by running a Node.js command.

- Step 2: Export a source inventory. Create a JSON file named inv.json containing the counts of various items (projects, workflows, custom fields, automation rules, global permissions, app data, and dashboards) in your source instance. Ensure the kind names match your coverage map. Validate the inventory by checking for unknown kinds using a Node.js command. Any discrepancies should be addressed, as unknown kinds are treated as work and may inflate your plan.

- Step 3: Compute the gap list. Implement a function that counts items by kind, handling arrays and individual numbers appropriately. Compare the count against the coverage map to identify gaps. Use a Node.js command to run this function and verify that all three states have non-zero values. Any zero in the partial state indicates a mistake in reading the page—revisit it for yes/no tables and exclusions.