Best approach for preserving issue links during phased Jira Data Center to Cloud migration?

Jiahao Song

We're migrating Jira Data Center projects to Jira Cloud in phases rather than performing a full-instance migration.

We're running into a challenge with issue links between projects that are migrated at different times.

Example

• Project A has been migrated to Jira Cloud.
• Project B remains in Jira Data Center and will be migrated in a later wave.
• Issues in Project A and Project B have existing issue links (Blocks, Relates To, Depends On, etc.).
• After Project A is migrated, issue links from Project A to issues in Project B are no longer visible on the migrated Cloud issues.
• Atlassian documentation indicates that when projects are migrated in smaller batches, links to issues or projects that have not yet been migrated may be missing until the linked items are migrated later. [support.at...assian.com]

Based on the Atlassian documentation, these issue links should reappear once the linked project is migrated to Cloud in a later wave. However, some of our projects may remain in different environments for an extended period of time. During that transition period, we're looking for ways to preserve visibility of cross-project dependencies and relationships.

Questions

• Has anyone encountered this issue during a phased Jira Data Center → Cloud migration?
• Did you implement a temporary solution to surface issue relationships while linked projects existed in different environments? If so, what approach did you use?
• Once the second project migrated to Cloud, were you able to automatically restore the original Jira issue links?

We're interested in any best practices, Marketplace apps, scripting approaches, or Atlassian-supported solutions for handling this transition period.

Viswanathan Ramachandran

Hi there,

Yes, this is one of the most common challenge.

To answer your questions:

1. Has anyone encountered this issue during a phased Jira Data Center → Cloud migration?

Yes, absolutely. I had this issues in server to DC migration.

2. Did you implement a temporary solution to surface issue relationships while linked projects existed in different environments? If so, what approach did you use?

Typically use one of three approaches depending on the needs. For me, I used the (remote issue links)

• Scripted Remote Issue Links (Most Common): Using a Python script or ScriptRunner to create Web/Remote Links on Cloud issues pointing directly to the DC issue URL.
• Application Link (AppLink) + Rich Remote Links: Configuring an AppLink between DC and Cloud so DC users can see live Cloud issue status/summary badges.
• Two-Way Sync Apps (For Active Coexistence): Using apps like Exalate or Backbone Issue Sync when teams in both environments need real-time status and comment synchronisation across instances.

3. Once the second project migrated to Cloud, were you able to automatically restore the original Jira issue links?

Yes, JCMA handles this automatically.

• When Project 1 migrates, JCMA stores the link mapping in its local database on DC.
• When Project 2 migrates in a subsequent wave to the same Cloud site, JCMA executes an automated reference resolution (link-fixer) step that recreates the native internal issue links between Project 1 and Project 2 in Cloud.
• ⚠️ Key Requirement: You must not clear or reset the JCMA migration history/database on your DC instance between waves.

Approaches & Solutions for the Transition Period

A. The Atlassian-Supported Native Behavior (JCMA + AppLinks)

• How JCMA resolves links: JCMA maintains an ID mapping table (Source DC Issue ID > Cloud Issue ID). When subsequent waves land on the same Cloud tenant, JCMA retroactively links them.
• Configuring AppLinks: Setting up an Application Link between Jira DC and Jira Cloud allows DC users working on unmigrated projects to see rich, live status previews of already-migrated Cloud issues. (Note: AppLinks are not required for JCMA to migrate data, but they improve interim user visibility).

B. Scripting Approaches (Remote Issue Links via REST API)

If you need Cloud users to see clickable links to DC issues immediately without purchasing third-party tools:

• Query DC for cross-project dependencies: Extract links between the migrated project and unmigrated project using SQL or the Jira DC REST API.
• Batch-create Remote Links in Cloud: Use Python or ScriptRunner to call the Jira Cloud REST API:

Endpoint: POST /rest/api/3/issue/{issueKey}/remotelink

• Post-migration cleanup: Once Project 2 migrates and JCMA restores native links, delete the temporary remote links using DELETE /rest/api/3/issue/{issueKey}/remotelink/{linkId}.

C. Marketplace Apps (For Heavy Dual-Run / Long Coexistence)

If the gap between waves is several months and teams require active bidirectional sync:

• Exalate: Highly customisable Groovy-based sync engine that keeps fields, comments, attachments, and links synchronised across Cloud and DC in real-time.
• Backbone Issue Sync: Robust, point-and-click configuration for synchronising issue data and links across instances.

Summary Checklist

Scope	Phase	Action Item	Method / Tool	Purpose & Notes
Current Project (Already Migrated)	Immediate	Lock Data Center project	Jira DC Permission Scheme (Read-Only)	Prevents users from making updates or adding new links in DC that won't sync to Cloud.
	Interim	Add temporary Remote Links	Cloud REST API (POST /remotelink)	Provides Cloud users clickable links straight to DC issues during the waiting period.
	Preservation	Keep JCMA history intact	Jira Cloud Migration Assistant (DC)	Critical: Do not clear or reset the JCMA database on DC so mapping tables remain available for future waves.
Upcoming Project (Next Migration Wave)	Pre-Migration	Configure AppLink (Optional)	Jira DC > Application Links	Allows DC users to view rich status previews of Cloud issues. (Helpful for user visibility).
	Pre-Migration	Audit dependencies	JQL / DC Database query	Maps all outgoing links from the upcoming project to migrated and unmigrated projects.
	Pre-Migration	Update JCMA	DC Manage Apps	Ensures the latest version and bug fixes for reference resolution / link-fixing.
	Migration	Run JCMA wave	JCMA > Select same Cloud site	JCMA's automated link-fixer reconnects native Cloud-to-Cloud issue links between the projects.
	Post-Migration	Lock source DC project	Jira DC Permission Scheme (Read-Only)	Prevents further modifications on Data Center.
	Post-Migration	Validate Cloud links	Cloud JQL / REST API	Confirms native links between the migrated projects are restored correctly.
	Post-Migration	Purge temporary Remote Links	Cloud REST API (DELETE /remotelink)	Removes interim web links to prevent duplicate link entries in Cloud.

Best Practices

1. Lock DC Projects Post-Migration: Immediately apply a read-only permission scheme to migrated DC projects so users cannot create orphan links or out-of-sync edits.
2. Wave Clustering: Use JQL (issueFunction in linkedIssuesOf("project = PROJA") AND project != PROJA) to identify tightly coupled projects and group them into the same wave whenever feasible.
3. Retain JCMA Data: Keep the JCMA app data and migration plans untouched on DC until all migration phases are complete.