Binary data (such as attachments and other uploaded files) is packaged by Atlassian and made available to your cloud app during a Simplified App Migration. Unlike tabular exports (AO tables and mappings), binary files are transferred as their original file content rather than as JSONL records.

The binary exporter is scoped to files under the Jira home directory. It runs incrementally: an initial snapshot of the matching files is followed by incremental exports that capture only what changed since the previous run. Changes that trigger a new export include new files, deleted files, changes to file contents, and changes to the directories you have declared for export.

Onboarding

Please reach out to Atlassian to test the early access feature.

After reaching out to Atlassian, to receive binary data, declare the binary key under the migration:managedExports module in your cloud app's manifest.yml:

1
2
3
4
5
modules:
  migration:managedExports:
    - key: binary
      directoryPrefix: [ "assets", "uploads/app" ]

The directoryPrefix property lists the directory prefixes containing binary data that Atlassian should package for export. Only files under the listed prefixes are included, relative to the app's home directory. For example, assets and uploads/app would include /jira/home/assets/upload.jpeg and /jira/home/uploads/app/my_doc.pdf.

Running the binary exporter

During the early access program, the binary exporter is started manually with an API call against the Data Center instance. Before you start, you must have consented to upload data and linked a Data Center instance to at least one cloud site.

The endpoints are exposed under the migration REST base path and are restricted to system administrators.

Start an export

Send a POST request to the app-incremental/start endpoint, listing the exporters to run. Use BINARY for the binary exporter:

1
2
3
4
curl -u admin:admin -X POST "http://localhost:8080/jira/rest/migration/latest/app-incremental/start" \
  -H "Content-Type: application/json" \
  -d '{"exporters": ["BINARY"]}'

The response is the current exporter status (see Check the export status).

Check the export status

Send a GET request to the app-incremental/status endpoint:

1
2
curl -u admin:admin -X GET "http://localhost:8080/jira/rest/migration/latest/app-incremental/status"

The response reports the state of each exporter:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "databaseExporter": {
    "running": false,
    "started": false,
    "message": "PLACEHOLDER"
  },
  "binaryExporter": {
    "running": true,
    "started": true,
    "message": "PLACEHOLDER"
  }
}

Field	Description
`running`	`true` while an export is actively running on this node.
`started`	`true` if the exporter has been started at least once since the node started.
`message`	A human-readable status message. `PLACEHOLDER`

Consuming exported data

When exported data is ready, your cloud app receives an avi:ecosystem.migration:uploaded:event_file_list event with the BINARY label. From there, the flow matches the standard Simplified App Migration consumption flow:

Receive the event, which references the File Listing and identifies the data movement.
Download the File Listing to find the event files for this export.
Download each event file to find the changed files and their binary file references.
Use each event file's binary file reference to download the file's contents.
Report SUCCESS or FAILED for the event files you processed.

For the request and response bodies of each endpoint, see the Event Specification. For how binary data is laid out in the export, see the DC Export Format.

Multi-node Data Center instances

The binary exporter runs on a single Data Center node and holds its runnable state in memory for the duration of a run. It is not designed to run across multiple nodes at the same time, and running it on more than one node simultaneously is not supported.

During an export, the exporter generates high disk IOPS and high network bandwidth on the node it runs on. If you run Jira on burstable instances (for example, t3-tier EC2 instances) on the assumption that load is spread evenly across the fleet, be aware that this load is concentrated on the single node that runs the export.

Follow this guidance when running against a multi-node Data Center:

Start the export on the node you want to target. The start endpoint acts on the node that receives the request, so send it directly to that node rather than through a load balancer.
Run only one export at a time. Do not start the exporter on another node while a run is in progress.
Check status on the same node. Exporter status is tracked in memory on the node that started the export, so poll the status endpoint on that node to see the state of the run.

Example

Metadata Header (First Row)

Example metadata line (formatted for readability)

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "exportTime":"2026-08-18T00:16:51.915527507Z",
  "type":"objects",
  "columns":[
    {"name":"fileId","type":"String","size":-1,"nullable":true},
    {"name":"filepath","type":"String","size":-1,"nullable":false},
    {"name":"objectType","type":"String","size":-1,"nullable":false},
    {"name":"DELETED","type":"boolean","size":1,"nullable":false},
    {"name":"TXN_SEQUENCE","type":"integer","size":19,"nullable":false}
  ],
  "primaryKeys":["filepath"]
}

Data Record Lines

The data records lines contain the data from the file system.

Example data record line (formatted for readability)

1
2
3
4
5
6
7
8
{
  "fileId": "binary_file/a5719733-df98-491d-ae34-8dc3da59530c",
  "filepath": "assets/upload.jpeg",
  "objectType": "FILE",
  "DELETED": false, 
  "TXN_SEQUENCE": 1
}