Event Specification

Overview

The avi:ecosystem.migration:uploaded:event_file_list 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.

Subscribe to this event in your manifest.yml file.

Typical Workflow for an App

1. Receive Webhook: The app receives the avi:ecosystem.migration:uploaded:event_file_list 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 avi:ecosystem.migration:uploaded:event_file_list 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": "avi:ecosystem.migration:uploaded:event_file_list",
  "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

An app receives exactly one avi:ecosystem.migration:uploaded:event_file_list notification for each enabled exporter in an app data movement. Each notification has a different listing-file key.

File Lists are additive within an app data movement. Each later File List includes all event files listed in earlier File Lists, plus any new files. A File List can also include BINARY or DATABASE files from earlier migrations from the same Data Center instance.

isComplete applies to the entire app data movement, not to an individual exporter. It is set to true only on the final notification for the migration. After a vendor receives a notification with isComplete: true, AMS has sent all EventFiles for that migration. No further File Lists or EventFiles will be sent for that app data movement.

As an example, an app using only the MAPPINGS exporter receives one mapping notification with isComplete: true. When an app enables additional exporters, its single MAPPINGS notification does not by itself indicate that all EventFiles for the migration have been sent; the notification with isComplete: true does.

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.

---