Event Specification

Overview

The event-file-list-uploaded event is a specialized notification used for the simplified app migration path. It signals that a collection of data files has been successfully exported from the DC instance and is now available for the cloud application to consume.

This is sent through as avi:ecosystem.migration:uploaded:event_file_list which can be added in your manifest.yml file.

Typical Workflow for an App

1. Receive Webhook: The app receives the event-file-list-uploaded event.
2. Fetch Listing: The app downloads the JSON file at the provided key.
3. Iterate Parts: The app parses the JSON to get the list of individual keys for the data parts.
4. Process Data: The app downloads and processes each part to synchronize the state.
5. Report Status: The app reports the processing outcome (SUCCESS or FAILED) for the parts back to the migration service (see Report Event File Status).

Initial Webhook event

The event is delivered via this structure:

Example event-file-list-uploaded event

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
{
  "eventType": "event-file-list-uploaded",
  "transferId": "ed66d0a8-6009-484c-aced-298e3c0e9bbf",
  "migrationDetails": {
    "migrationId": "6fff0c25-7192-4ce1-9c79-99296b7a0daa",
    "migrationScopeId": "23b5768f-d45b-4291-8d22-fd0fcd341801",
    "createdAt": 1788331184581,
    "cloudUrl": "https://destination-site.atlassian.net",
    "name": "jira-migration"
  },
  "key": "some-file-key",
  "label": "MAPPINGS",
  "messageId": "49395bf3-ca51-42e9-8ee6-e5a0c5fe9404",
  "movementDetails": {
    "appDataMovementId": "ed66d0a8-6009-484c-aced-298e3c0e9bbf",
    "sourceLocation": {
      "cloudUrl": "https://source-site.atlassian.net",
      "type": "cloud"
    },
    "destinationLocation": {
      "cloudUrl": "https://destination-site.atlassian.net",
      "type": "cloud"
    },
    "createdAt": 1788331184581
  },
  "isComplete":true
}

Multiple Notifications

During an incremental migration, an application will receive multiple event-file-list-uploaded notifications at different stages of the process.

Applications using incremental migrations should not assume that a single event-file-list-uploaded event marks the completion of the entire migration; rather, it marks the availability of a specific category of data (such as Mappings or Binary). The final event file for a specific category of data will have isCompleted: True set within the payload.

Listing File Format

The listing file is a JSONL (JSON Lines) file where each line is a valid JSON representing metadata for one Event File.

Example entry (formatted for readability):

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "fileId": "uuid-of-the-file",
  "fullName": "path/to/data-part-1.json",
  "incremental": true,
  "createdAt": "2024-03-26T10:00:00Z",
  "sourceAppARI": "ari:cloud:ecosystem::app/uuid",
  "sourceLocationARI": "ari:cloud:jira::site/uuid",
  "destinationLocationARI": "ari:cloud:jira::site/uuid",
  "exporterARI": "ari:cloud:ecosystem::exporter/uuid",
  "properties": {"migrationId": "uuid"},
  "label": "MAPPINGS"
}

Event File Metadata Fields

API Retrieval

Apps cannot download data parts directly using the fileId. They must first request a presigned download URL from the migration service.

Get Listing File URL

Retrieve a presigned URL to download a File Listing.

Endpoint: POST /app/migration/forge/v1/file-listing/download-url

Request body:

1
2
3
4
{
  "fileKey": "key-from-webhook"
}

Response body:

1
2
3
4
{
  "url": "https://presigned.url/..."
}

The response URL is presigned (contain credentials in the parameters that allow you to download for a short period after it has been generated).

Get Event File URLs

Retrieve a presigned URL to download an Event File.

Endpoint: POST /app/migration/forge/v1/event-file/urls

Request body:

1
2
3
4
{
  "eventFileIds": ["uuid-1", "uuid-2"]
}

Response body:

1
2
3
4
5
6
7
8
9
{
  "eventFiles": [
    {
      "fileId": "uuid-1",
      "presignedUrl": "https://host.domain/..."
    }
  ]
}

Report Event File Status

After processing the downloaded data parts, the app must report the outcome for those files back to the migration service so the platform can track progress and completion.

Endpoint: POST /app/migration/forge/v1/event-files/status

Request body:

1
2
3
4
5
6
{
  "appDataMovementId": "app-data-movement-id-from-webhook",
  "eventFileIds": ["uuid-1", "uuid-2"],
  "status": "SUCCESS"
}

The Forge migration platform treats updates to event files the same as updates to the existing APP_DATA upload process. As a result, any eventFile that is marked as SUCCESS will trigger the sliding window logic and reset the 15-minute timeout window.

---