App Data Migration Developer

App Data Migration Developer

Last updatedNov 5, 2020

Rate this page:

Mappings

The mappings provide information about how the data migrated from server is identified in cloud by the App migration platform. You can retrieve the mapping for a specific namespace by making a query to the App migration platform from either the server side or the cloud side of your app.

Mappings format

A mapping is combination of a source and a destination ID for an entity that details how the App migration platform identifies an entity in server and in cloud.

Each mapping is expressed as a key/value pair, where key is the server ID, and value the corresponding cloud ID.

1
2
3
4
5
6
{
    "server-id-1": "cloud-id-1",
    "server-id-2": "cloud-id-2",
    ...
    "server-id-99": "cloud-id-99",     
}

Server key prefixes

For some entities (see user mappings below), the mapping key (server ID) can be prefixed with a literal which defines which property of the entity is mapped.

1
2
3
4
{
    "<prefix>/server-id-1-a": "cloud-id-1",
    "<prefix>/server-id-1-b": "cloud-id-1",  
}

So, a unique cloud user can have more than one mapping to server available as follows:

1
2
3
4
5
{
    "email/jsmith@example.com": "1234",
    "jira.userkey/JIRAUSER1410": "1234",
    "jira.username/jsmith": "1234",
}

Mappings namespaces and entities

The lists display all the namespaces that you can query to get information about how the App migration platform maps data from server to cloud.

User mappings

NamespacePrefix
identity:useremail/
identity:userjira.userkey/
identity:userjira.username/
identity:userconfluence.userkey/

Jira mappings

Namespace
jira:comment
jira:fileAttachment
jira:issue
jira:issueLink
jira:issueLinkType
jira:priority
jira:projectCategory
jira:projectComponent
jira:projectRole
jira:projectVersion
jira:resolution
jira/classic:customField
jira/classic:customFieldOption
jira/classic:issueStatus
jira/classic:issueType
jira/classic:project
jira/classic:screen
jira/classic/software:rapidView
jira/classic/software:sprint

Confluence mappings

Namespace
confluence:space
confluence:page
confluence:comment
confluence:attachment
confluence:blogPost
confluence:outgoingLink
confluence:referralLink
confluence:customContentEntityObject

Lifespan of mappings

You can retrieve mappings using the Pagination API before the end of the lifespan for each namespace. The table below lists the lifespan of each mappings namespace.

NamespaceLifespan
identify:user5 days
confluence:*2 years
jira:*2 years

Retrieve mappings using the Pagination API

Use the Pagination API to customize the page size of mappings you want to retrieve from the App migration platform.

Request endpoint:

1
https://your-site.atlassian.net/rest/atlassian-connect/1/migration/mapping/{transferId}/page?namespace=<VAL>&pageSize=<VAL>&lastEntity=<VAL>

The response will look like

1
2
3
4
5
6
7
8
9
10
11
{
    "meta": {
        "pageSize": 2,
        "hasNext": true,
        "lastEntity": "key2"
    },
    "items": {
        "key1": "value1",
        "key2": "value2"
    }
}

If the response can't be fit in a single page, hasNext will be true and the lastEntity property will contain the key you can use to fetch the next available page with the query parameter lastEntity={lastEntity}

Query parameters

Parameter nameRequiredDescription
namespaceYESNamespace value
pageSize[Optional] NODefault Size = 5000, Max Size = 5000, Min Size = 1. Validation exception will be thrown, if outside the given range.
lastEntity[Optional] NOValue can be extracted from the first response in the meta section.
It is mandatory to have namespace as the query parameter. You can use the pageSize and lastEntity parameters in your mappings request to the Pagination API. The code examples that follow illustrate how to use the Pagination API.

Once your server app gets registered for transfer, means a migration is about to start, the corresponding webhooks will be informed with the transferid.

When sending a mappings query to the Pagination API, it is important to consider that mappings can be large. Depending on the customer's instance, a single mapping namespace can contain a large number of records.

Request mappings without defining page size of mappings list

This will return minimum of two - 5000 or number of entries available in the namespace.

  • Sample request

    1
    curl -X GET "https://your-site.atlassian.net/rest/atlassian-connect/1/migration/mapping/26925583-10bd-49fb-b67c-15fc2447a97b/page?namespace=identity:user" 
  • Sample response

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    {
        "meta": {
            "pageSize": 5000,
            "hasNext": false,
            "lastEntity": "server-id-100"
        },
        "items": {
            "server-id-1": "cloud-id-1",
            "server-id-10": "cloud-id-10",
            ...
            "server-id-100": "cloud-id-100",
        }
    }

Request mappings with defining page size of mappings list

Use the pageSize query parameter to control the maximum number of mappings returned for a request. The following shows a request for page size 10.

  • Sample request

    1
    curl -X GET "https://your-site.atlassian.net/rest/atlassian-connect/1/migration/mapping/26925583-10bd-49fb-b67c-15fc2447a97b/page?namespace=jira:priority&pageSize=10"
  • Sample response

    The response contains the first 10 mappings.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    {
        "meta": {
            "pageSize": 10,
            "hasNext": true,
            "lastEntity": "server-id-10"
        },
        "items": {
            "server-id-1": "cloud-id-1",
            "server-id-2": "cloud-id-2",
            "server-id-3": "cloud-id-3",
            "server-id-4": "cloud-id-4",
            "server-id-5": "cloud-id-5",
            "server-id-6": "cloud-id-6",
            "server-id-7": "cloud-id-7",
            "server-id-8": "cloud-id-8",
            "server-id-9": "cloud-id-9",
            "server-id-10": "cloud-id-10",
        }
    }

Request mappings using the lastentity parameter

See an example

The following example uses the lastentity parameter. This parameter is similar to requesting the next page of mappings. The request returns the mapping list after the lastEntity.

  • Sample request

    1
    curl -X GET "https://your-site.atlassian.net/rest/atlassian-connect/1/migration/mapping/26925583-10bd-49fb-b67c-15fc2447a97b/page?namespace=jira:priority&pageSize=10&lastEntity=server-id-15"
  • Sample response

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    {
        "meta": {
            "pageSize": 10,
            "hasNext": true,
            "lastEntity": "server-id-24"
        },
        "items": {
            "server-id-16": "cloud-id-16",
            "server-id-17": "cloud-id-17",
            "server-id-18": "cloud-id-18",
            "server-id-19": "cloud-id-19",
            "server-id-20": "cloud-id-20",
            "server-id-21": "cloud-id-21",
            "server-id-22": "cloud-id-22",
            "server-id-23": "cloud-id-23",
            "server-id-24": "cloud-id-24",
        }
     }

Retrieve mappings using the Filtered IDs API

You can also filter only the IDs you want to resolve. Up to 99 IDs can be used as filter and there will be no pagination. IDs that aren't found won't be returned.

MethodURL
POST/migration/mapping/{transferId}/find?namespace={namespace}

The IDs of interest should be provided in the payload. And the response will look like:

1
2
3
4
{
    "key1": "value1",
    "key2": "value2"
}

Please find below another practical example using curl

1
curl -v -d '[1,2,3]' 'https://your-site.atlassian.net/rest/atlassian-connect/1/migration/mapping/<transferID>/find?namespace=confluence:page'

Rate this page: