Quick Start: Minimal SAM Integration (Mapping)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// Express.js endpoint handler
app.post('/api/forge/events', async (req, res) => {
  const event = req.body;
  const { eventType } = event;

  console.log(`Received migration event: ${eventType}`);

  try {
    if (eventType === 'event-file-list-uploaded') {
      await handleFileListUploaded(event);
    }
    // Handle other events (listener-triggered, transfer-settled, etc.)

    res.status(200).send({ success: true });
  } catch (error) {
    console.error('Event handling failed:', error);
    res.status(500).send({ error: error.message });
  }
});

async function handleFileListUploaded(event) {
  const { key, label, isComplete, transferId, movementDetails } = event;

  console.log(`File list uploaded - Label: ${label}, IsComplete: ${isComplete}`);

  if (label === 'MAPPINGS') {
    // TODO: Process mappings in next step
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
async function handleFileListUploaded(event) {
  const { key, label, movementDetails } = event;

  if (label !== 'MAPPINGS') {
    throw new Error(`Expected label 'MAPPINGS', got '${label}'`);
  }

  // 1. Request presigned URL for the file list
  const listingUrl = await getFileListingUrl(key);

  // 2. Download the file list
  const fileListing = await downloadFileListing(listingUrl);

  // 3. Batch fetch download URLs for all event files (up to 100 at a time)
  const fileIds = fileListing.map(ef => ef.fileId);
  const urlsMap = await getEventFileUrls(fileIds);

  // 4. Process files in parallel (10 at a time for performance)
  const CONCURRENCY = 10;
  for (let i = 0; i < fileListing.length; i += CONCURRENCY) {
    const batch = fileListing.slice(i, i + CONCURRENCY);
    await Promise.all(
      batch.map(eventFile =>
        processEventFile(eventFile, urlsMap.get(eventFile.fileId), movementDetails)
      )
    );
  }
}

async function getFileListingUrl(fileKey) {
  const response = await fetch(
    'https://api.atlassian.com/app/migration/forge/v1/file-listing/download-url',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${accessToken}` // Get from Forge context
      },
      body: JSON.stringify({ fileKey })
    }
  );

  const { url } = await response.json();
  return url;
}

async function downloadFileListing(presignedUrl) {
  // This file can be up to 5GB, make sure your production code can handle this
  const response = await fetch(presignedUrl);

  // Stream the JSONL file line-by-line to handle large listings efficiently
  const eventFiles = [];
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';

  while (true) {
    const { done, value } = await reader.read();

    if (value) {
      buffer += decoder.decode(value, { stream: true });

      // Process complete lines
      const lines = buffer.split('\n');
      buffer = lines.pop(); // Keep incomplete line in buffer

      for (const line of lines) {
        if (line.trim()) {
          eventFiles.push(JSON.parse(line));
        }
      }
    }

    if (done) {
      // Process any remaining data
      if (buffer.trim()) {
        eventFiles.push(JSON.parse(buffer));
      }
      break;
    }
  }

  return eventFiles;
}

async function getEventFileUrls(fileIds) {
  // Batch fetch up to 100 URLs at once (API limit)
  const BATCH_SIZE = 100;
  const urlsMap = new Map();

  for (let i = 0; i < fileIds.length; i += BATCH_SIZE) {
    const batch = fileIds.slice(i, i + BATCH_SIZE);

    const response = await fetch(
      'https://api.atlassian.com/app/migration/forge/v1/event-file/urls',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${accessToken}`
        },
        body: JSON.stringify({ eventFileIds: batch })
      }
    );

    const { eventFiles } = await response.json();
    eventFiles.forEach(({fileId, presignedUrl}) => {
      urlsMap.set(fileId, presignedUrl);
    });
  }

  return urlsMap;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
async function processEventFile(eventFile, presignedUrl, movementDetails) {
  const { fileId } = eventFile;

  console.log(`Processing event file: ${fileId}`);

  try {
    // 1. Download the event file (URL already fetched in batch)
    const mappingRecords = await downloadEventFile(presignedUrl);

    // 2. Process the mappings
    await importMappings(mappingRecords, movementDetails);

    // 3. Acknowledge successful processing
    await acknowledgeEventFile(fileId, movementDetails.appDataMovementId, 'SUCCESS');

  } catch (error) {
    console.error(`Failed to process ${fileId}:`, error);
    await acknowledgeEventFile(fileId, movementDetails.appDataMovementId, 'FAILED');
    throw error;
  }
}

async function downloadEventFile(presignedUrl) {
  const response = await fetch(presignedUrl);
  const text = await response.text();

  // Parse JSONL format
  const lines = text.trim().split('\n');

  // First line is metadata header
  const metadata = JSON.parse(lines[0]);
  console.log(`Event file metadata:`, metadata);

  // Remaining lines are mapping records
  return lines.slice(1).map(line => JSON.parse(line));
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
async function importMappings(records, movementDetails) {
  const { cloudUrl } = movementDetails.migrationDetails;

  for (const record of records) {
    const { sourceId, targetId, entityType } = record;

    // Store the mapping in your app's database
    await storeMappingInYourDatabase({
      cloudUrl,
      dcId: sourceId,
      cloudId: targetId,
      entityType: entityType
    });

    console.log(`Mapped ${entityType}: ${sourceId} → ${targetId}`);
  }

  console.log(`Imported ${records.length} mappings`);
}

// Example mapping record structure:
// {
//   "sourceId": "10001",           // DC issue ID
//   "targetId": "10234",           // Cloud issue ID
//   "entityType": "jira:issue",
//   "namespace": "ari:cloud:jira::site/abc123"
// }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
async function acknowledgeEventFile(eventFileId, appDataMovementId, status) {
  await fetch(
    'https://api.atlassian.com/app/migration/forge/v1/event-files/status',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${accessToken}`
      },
      body: JSON.stringify({
        appDataMovementId,
        eventFileIds: [eventFileId],
        status // 'SUCCESS' or 'FAILED'
      })
    }
  );

  console.log(`Acknowledged event file ${eventFileId} with status: ${status}`);
}