Simplified App Migration is currently available for early-access testing for AO tables, attachments, custom fields, and entity properties. Mapping information exports are available for production migrations in preview. Contact Atlassian to enable SAM for your test sites.

Do I need to replace my existing migration implementation?

No. You can continue to use your existing Data Center migration code and adopt SAM incrementally. For example, you can use SAM to consume Atlassian-packaged exports or mapping information while retaining the parts of your existing implementation that you still need.

What data can SAM package for my app?

SAM can package AO tables, attachments, custom fields, entity properties, and mapping information. Your app declares the managed export categories it needs in the migration:managedExports module in its cloud app manifest. See Onboarding to SAM and the export file specification for details.

When can my app process migration data?

Your app can process data incrementally as each export becomes available, including during the pre-migration phase. It can also wait until the All Migration Data Ready event and process the data in bulk. Processing data earlier can reduce the migration outage time.

How does my app know that data is ready?

The migration platform notifies your app through the event-file-list-uploaded event when an export category is available. Your app should then consume the exported files and report its migration progress and completion to the platform. See the Event Specification.

File List notifications

How many `MAPPINGS` notifications will my app receive for a migration?

Your app receives one event-file-list-uploaded notification with label: MAPPINGS for each app data movement (migration). If you opt in to additional exporters, such as BINARY or DATABASE, you receive one notification for each exporter. Each notification has a different File List key.

Are File Lists incremental?

File Lists are additive within an app data movement. A later File List includes the event files from earlier File Lists plus new files. File Lists can also include BINARY or DATABASE files from earlier migrations from the same Data Center instance, but do not include MAPPINGS files from earlier migrations.

What does `isComplete: true` mean?

isComplete applies to the entire app data movement, rather than to an individual exporter. 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. For an app using only the MAPPINGS exporter, its single MAPPINGS notification has isComplete: true. If the app enables other exporters, the MAPPINGS notification alone does not indicate that all EventFiles have been sent.

How should I handle out-of-order events?

Use isComplete: true to determine that all File Lists are contained within this eventFile. If your app currently uses only the MAPPINGS exporter, the single mapping notification has isComplete: true.

Identifiers and scopes

Is `movementDetails.appDataMovementId` the same as `transferId` for a hybrid Forge Remote migration?

Yes. For a hybrid Forge Remote migration, movementDetails.appDataMovementId and the top-level transferId have the same value.