Jira DC to Cloud Migration: How to Preserve App Data When JCMA Changes IDs

A practical guide to migrating Jira app data when Active Objects don’t transfer and all entity IDs change

The ID Problem

In Jira Data Center, every comment has a numeric ID (e.g., 10501, 10502). Our app stores thread structure in Active Objects:

Comment 10501: "We found a bug"
├── Comment 10502: "Which endpoint?" (parent: 10501)
│   └── Comment 10503: "POST /users" (parent: 10502)
└── Comment 10504: "I'll fix it" (parent: 10501)

After JCMA migration, these same comments get completely new Cloud IDs (e.g., 5001, 5002, 5003, 5004). The old 10501 → 10502 parent-child link becomes meaningless because comment 10501 no longer exists in Cloud.

Our Solution: Marker-Based Migration

Since we couldn’t rely on JCMA to preserve our data, we developed a marker system that “rides along” with the comments themselves.

Marker Format

We chose a visible text-based marker format:

:::VOTAZZ_MIG:10501:::

Yes, visible. We couldn’t make them invisible, and here’s why.

What Markers Look Like

In Data Center:

In Cloud (after JCMA migration, before cleanup):

The Migration Flow

Before: "This is a reply"
After:  "This is a reply :::VOTAZZ_MIG:10502:::"

[
  {"issueId": 10001, "commentId": 10501, "parentCommentId": null},
  {"issueId": 10001, "commentId": 10502, "parentCommentId": 10501},
  {"issueId": 10001, "commentId": 10503, "parentCommentId": 10502},
  {"issueId": 10001, "commentId": 10504, "parentCommentId": 10501}
]

dcToCloudMap = {
  "10501": "5001",
  "10502": "5002",
  "10503": "5003",
  "10504": "5004"
}

// Export says: 10502 → parent 10501
// dcToCloudMap: 10502 = 5002, 10501 = 5001
// Result: 5002 → parent 5001

Technical Implementation

DC Side (Java Plugin)

We added migration endpoints to the DC plugin:

• POST /migration/add-markers — inject markers into all threaded comments
• GET /migration/export-data — export hierarchy JSON
• POST /migration/remove-markers — cleanup after verification

Cloud Side (Forge App)

A dedicated migration module handles:

• Chunked upload of large migration data
• Building DC→Cloud mapping by scanning markers
• Batch processing with progress tracking
• Marker cleanup after successful import

Challenges Encountered

Building a migration tool on Atlassian Forge presented unique platform constraints that significantly shaped our architecture.

// Process ~100 comments per resolver call
// Save progress to storage
// Frontend polls and triggers next chunk
while (hasMoreComments) {
  const batch = await fetchComments(startAt, 100);
  processAndSaveProgress(batch);
  if (approachingTimeout()) break; // Leave 5s buffer
}

// Upload: Split into 2000-record chunks (~170KB each)
const CHUNK_SIZE = 2000;
for (let i = 0; i < records.length; i += CHUNK_SIZE) {
  const chunk = records.slice(i, i + CHUNK_SIZE);
  await storage.set(`migration-chunk-${chunkIndex}`, { records: chunk });
}

// Store metadata separately
await storage.set('migration-meta', {
  totalChunks: chunkCount,
  totalRecords: records.length
});

if (response.status === 429) {
  await saveProgress(currentState);
  return {
    rateLimited: true,
    waitUntil: Date.now() + 60000,
    message: 'Rate limited, will retry automatically'
  };
}

The Compound Effect

These constraints don't exist in isolation — they multiply:

A migration that would take 10 minutes on a traditional server can take hours on Forge — not because the code is slow, but because we're constantly working around platform constraints.

Key Takeaways

Threaded Comments for Jira by Votazz