A mapping file is generated for each entity type. There may be more than one mapping file per type, as files may be provided incrementally or split across multiple files when they exceed the chunking limit.

We will generate the mapping file once the core migration has finished and send the event to your cloud sites typically within a few minutes of your app migration starting.

Onboarding

To receive mapping data, declare the mapping key under the migration:managedExports module in your cloud app's manifest.yml:

1
2
3
4
5
modules:
  migration:managedExports:
    - key: mapping
      entityTypes: [ "jira:issue", "confluence:page" ]

The entityTypes is a list of all entity types that are required to migrate your app.

File listing example

Example JSONL file listing entry that will be received by your app (formatted for readability)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "fileId": "event_file/4ec666f2-bbe5-4fa8-90ef-78f89d921404",
  "fullName": "id_mapping-jira/classic:workflowRule-full-0-2026-08-21T04:59:20.764633069Z.jsonl",
  "label": "MAPPINGS",
  "incremental": false,
  "createdAt": "2026-08-21T04:59:20.764666560Z",
  "sourceAppARI": null,
  "sourceLocationARI": "ari:cloud:app-migration::dc-instance-identity/ltworpt0BNz6s5rhHguiSWqui6g_OJ9KQmotEg_pGbk",
  "destinationLocationARI": "ari:cloud:jira::site/1234567-abcd-1234-abcd-1234567",
  "exporterARI": "ari:cloud:app-migration::exporter/app-incremental",
  "properties": {
    "entityType": "jira/classic:workflowRule",
    "migrationId": "987654-abcd-1234-abcd-1234567",
    "migrationScopeId": "abc4567-abcd-1234-abcd-1234567"
  }
}

Metadata Header (First Row)

The first line of every export file contains metadata about the export. The meta contains the entity type as the table name (e.g. jira:comment), and standard mapping columns definitions.

The column definitions are:

Property	Type	Description
`entityType`	varchar	The entity type for this item (e.g. `jira:issue`). Entity Types
`sourceId`	number	Source system identifier.
`targetId`	number	Destination system identifier.
`migrationScopeId`	varchar	A UUID identifying the migration scope (the combination of source and destination) for this item.
`createdAtTimestamp`	timestamp	Time the mapping was created.
`DELETED`	boolean	Indicates if this mapping has been deleted.
`TXN_SEQUENCE`	integer	Identifier indicating the sequence number of the mapping updates.

Example metadata line (formatted for readability)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "columns":[
    {"name":"sourceId","type":"number","size":19,"nullable":false},
    {"name":"targetId","type":"number","size":19,"nullable":false},
    {"name":"entityType","type":"varchar","size":100,"nullable":false},
    {"name":"migrationScopeId","type":"varchar","size":255,"nullable":true}, 
    {"name":"createdAtTimestamp","type":"timestamp","size":-1,"nullable":false},
    {"name":"DELETED","type":"boolean","size":1,"nullable":false},
    {"name":"TXN_SEQUENCE","type":"integer","size":19,"nullable":false}
  ],
  "primaryKeys":["sourceId","entityType"],
  "table":"jira:comment",
  "rowCount":1000,
  "TYPE":"METADATA"
}

Example mapping file data row (formatted for readability)

1
2
3
4
5
6
7
8
9
10
{
  "sourceId":36778,
  "targetId":136830,
  "entityType":"jira:comment",
  "migrationScopeId":"migration_scope_001",
  "createdAtTimestamp":"2026-04-17T05:30:07.477354Z",
  "DELETED":false,
  "TXN_SEQUENCE":29606730
}