A Building Blocks Importer moves data into your app. Examples of use cases for importers are for optimised Data Center to Cloud migrations, for bringing data in to the new cloud site in a cloud-to-cloud migration, and for loading an export file for future Apps Backup/Restore Import/Export functionality.

The future vision is that, as long as you can create a compatible format (export contract), you will only need to write one Importer. However, we acknowledge that many app partners have invested heavily in building their classic Data Center to Forge migration pathways, and so we support 'hybrid' importers that run alongside the classic Data Center to Forge migration, and only import part of the total available data (for example, they might only use the Building Blocks approach for mapping files).

Register your Importer

In the future, you will be able to declare that your importer exists, and provide its details in your Forge manifest. However, until such a feature is developed, the registration of Building Blocks importers and exporters is managed manually by Atlassian staff. If we have not already given you a contact in relation to your implementation of Building Blocks, please reach out via ecosystem partner support, who will be able to arrange for the App Migrations Platform team to support you.

The following information will be required:

What Forge app ID(s) do you need to register your importer for?
What cloud sites will you be performing migrations on? In the future, importer registrations will apply for all cloud sites, but during this early phase we are rolling out to individual cloud sites.
Is your Importer a hybrid importer (that only works in tandem with a normal Data Center to Cloud, and so is inappropriate for Cloud-to-Cloud migrations or Backup Restoration Import)?

Please be aware that in the future, you will be required to move the above information into your Forge Manifest.

Forge Event sent to your Importer

When your app is registered as having a Forge Importer, you will start receiving a new event, avi:ecosystem.migration:uploaded:event_file_list. This event is sent multiple times per App Data Movement - one for each 'File Group Label'.

You will need to register to receive the event in your Forge Manifest using the trigger module.

When you receive the event, it will have a 'key' field which provides a file key for the File List. It also provides a 'label' field identifying the File Group Label that the File List will be filtered to.

Use the 'key' field to request the File Listing from https://api.atlassian.com/migration/forge/v1/file-listing/download-url, with the fileKey in the request:

1
2
{"fileKey": "key from event here"}

You will receive a JSON response with a URL: {"url": "https://some-url-including-signature-parameters"}. This URL is a pre-signed URL (i.e. it includes credentials that grant access to download for a short period of time). Download it to obtain the File List.

Interpreting the File List

The File List, it is a JSONL with one record per line and no header:

1
2
{"fileId": "someid", "fullName": "a name describing the file", "incremental": "false", "createdAt": "2026-04-16T04:55:33.000Z", "sourceAppARI": "", "sourceLocationARI": "", "destinationLocationARI": "", "properties": {}}

In the above:

fileId is a key you can use to download the event file.
fullName gives a file name provided by the exporter that describes which exported file it is (in a form that varies based on the exporter - for the Atlassian DC Exporter, see here).
incremental tells you whether the export is purely a snapshot (set to false), or if it might be a diff that includes removals / updates (set to true).
createdAt tells you when the event file was registered as created.
sourceAppARI has a format like ari:cloud:identity:{siteId}:forge-installation/{appId}/{envId} where siteId, appId and envId are UUIDs. You should use it only for metadata (logging etc...) to ensure that your importer works for data from multiple sources. Note that this field is nullable; not all data originates from an app (for example, mappings do not).
sourceLocationARI tells you where the data came from. There are multiple possible sources depending on the type of import, so you should rely on it only for logging / identifying what happened, and ensure your code is robust to different values.
destinationLocationARI tells you what destination the event file was created for. Note that most event files are not specific to a particular destination location, and so will have this value as null.
properties is a JSON object that contains any metadata about the event file provided by the exporter. Use this to decide whether you need to process the event file without having to download it.

Download Event Files

You can make a POST request to https://api.atlassian.com/migration/forge/v1/event-file/urls. In the body, you need to provide 1-100 Event File IDs (taken from the fileId in the File List):

1
2
{"eventFileIds": ["someid"]}

In the response, you'll get back a list of URLs like this:

1
2
{
  "eventFiles": [
    {"fileId": "someid", "presignedUrl": "https://example.org/download-url?authorisation_parameters"}
  ]
}

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

Event Files are JSONL files. The first JSON row is a 'header' row containing metadata about the file, while subsequent rows contain records (representing an upsert or removal of data). The exact format of the JSON within the Event File is dependent on the type of event file.

Updating the status of Event Files

As an Importer, you are expected to acknowledge every Event File, even if it is one you decide not to process. Doing so for every single event file in the migration will trigger the completion of the import.

To acknowledge an Event File, use the https://api.atlassian.com/migration/forge/v1/event-files/status endpoint with a request of the following type:

1
2
{
  "transferId": "the-app-data-movement-uuid",
  "eventFileIds": ["eventFileId1", "eventFileId2"],
  "eventStatus": "SUCCESS"
}

Note that you can acknowledge up to 100 event files in the same request. The eventStatus can be either SUCCESS (appropriate if you either did nothing, or processed the event file successfully) and FAILED (appropriate if you tried and failed to process the event file, and so a failure should be returned back to the user initiating the Movement).