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.

Typical Workflow for an App

Receive Webhook: The app receives the event-file-list-uploaded event.
Fetch Listing: The app downloads the JSON file at the provided key.
Iterate Parts: The app parses the JSON to get the list of individual keys for the data parts.
Process Data: The app downloads and processes each part to synchronize the state.

Payload Fields

The event is delivered via this structure:

Field	Value / Description
`eventType`	`event-file-list-uploaded`
`key`	The path to the listing file (e.g., `listing/uuid-metadata.json`).
`label`	The type of data being notified (e.g., `MAPPINGS`, `DATABASE`, `BINARY`).
`transferId`	The unique ID of the application's transfer.
`migrationDetails`	Contextual info about the overall migration.

Multiple Notifications

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

Applications 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.

Listing File Format

The listing file is a JSONL (JSON Lines) file where each line is a valid JSON object representing one data part.

Example entry (formatted for readability):

1
2
{
  "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",
  "exporterARI": "ari:cloud:ecosystem::exporter/uuid",
  "properties": "{\"migrationId\": \"uuid\"}",
  "label": "MAPPINGS"
}

Event File Metadata Fields

Field	Type	Description
`fileId`	string (UUID)	Unique identifier for the specific data part.
`fullName`	string	Original filename or identifier from the DC instance.
`label`	string	The type of data being notified (e.g., `MAPPINGS`, `DATABASE`, `BINARY`).
`incremental`	boolean	Whether this is part of an incremental migration.
`createdAt`	string (ISO 8601)	When the part was generated on the DC instance.
`sourceAppARI`	string (ARI)	The ARI of the source application.
`sourceLocationARI`	string (ARI)	The ARI of the source location (e.g. Jira site).
`exporterARI`	string (ARI)	The ARI of the component that performed the export.
`properties`	string (JSON)	Optional metadata properties (e.g., migration scope).

API Retrieval

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

Get Event File URLs

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

Request body:

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

Response body:

1
2
{
  "eventFiles": [
    {
      "fileId": "uuid-1",
      "presignedUrl": "https://host.domain/..."
    }
  ]
}

Get Listing File URL

For the listing file itself, apps can use:

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

Request body:

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

Response body:

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