Last updated Nov 8, 2023

Retrieve data mappings

To identify data that has been migrated from the server to the cloud, retrieve data mappings from the app migration platform.

You can retrieve the mapping for a specific namespace from either your server or cloud app. Mappings are linked between the server and cloud site, regardless of how many migrations or transfers are completed.

Mappings format

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

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

1
2
{
    "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 that defines which property of the entity is mapped.

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

A unique cloud user can have more than one mapping to server available as follows:

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

Mappings namespaces and entities

The lists that follow display all the namespaces 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/
identity:groupidentity:group:name/

Jira Work Management and Jira Software mappings

Namespace
jira:comment
jira:fileAttachment
jira:filter
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
jira/classic:workLog

Jira Service Management mappings

Namespace
jira/servicedesk:requestType
jira/servicedesk:customerOrganization

Confluence mappings

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



The list that follow display all the namespaces you can query for information about how the app migration platform maps the app-created entities from server to cloud.

App only Jira mappings

Namespace
jira/classic:workflowRule
jira/classic:appCustomField

Lifespan of mappings

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

Mappings for any namespace do not stay constant throughout their lifespan. Cloud IDs can change over time if the entities are deleted and re-migrated at cloud site.

The table below lists the lifespan of each mappings namespace.

NamespaceLifespan
identity:*14 days
confluence:*2 years
jira:*2 years

Request mappings from your server app

There are two ways to retrieve the mappings from your server app.

Retrieve mappings using the Pagination API

Use the getPaginatedMapping method to retrieve the product mapping from your server app. This will return maximum of 5000 IDs. See the deprecation notice for upcoming change in page size.

See an example

1
2
PaginatedMapping paginatedMapping = gateway.getPaginatedMapping(transferId, "confluence:page", 5);
while (paginatedMapping.next()) {
    try {
        Map<String, String> mappings = paginatedMapping.getMapping();
        log.info("mappings = {}", new ObjectMapper().writeValueAsString(mappings));
    } catch (IOException e) {
        log.error("Error retrieving migration mappings", e);
    }
}

See an example in repository

Retrieve mappings using the filtered IDs API

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

See an example

1
2
Map<String, String> mappingById = gateway.getMappingById(transferId, "identity:user", Collections.singleton("email/admin@example.com"));

See an example in repository

Request mappings from your cloud app

Your cloud app can make requests to the Mappings API for mappings. There are two ways to retrieve mappings from your cloud app.

You can either retrieve all mappings of a specific transferId and namespace in a paginated fashion, or you can specify up to 100 IDs of a specific transferId and namespace you'd like to resolve.

Once the transfer is settled, the Mappings API will return an HTTP 403 error.

We recommend retrying on 5xx errors using an exponential backoff strategy rather than failing an app migration on a single error.

By making your migration path resilient to 5xx errors, you can avoid disrupting a customer migration unnecessarily.

For more on retry strategies, refer to Rate limiting.

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. The platform uses transferId to identify the link between the server and cloud site to return all the linked mappings (with respect to lifespan.) 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. You need to pass lastEntity as query parameter when fetching the next page results. The examples that follow illustrates how to use the Pagination API.

Request endpoint:

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

An example of the response is as follows:

1
2
{
    "meta": {
        "pageSize": 2,
        "hasNext": true,
        "lastEntity": "key2"
    },
    "items": {
        "key1": "value1",
        "key2": "value2"
    }
}

If the response doesn't fit into 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. See the deprecation notice for upcoming change in page size.
lastEntity[Optional] NOValue can be extracted from the first response in the meta section.

When sending 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 many records.

Request mappings without defining page size of mappings list

This will return maximum of 5000 entries available in the namespace.

  • Sample request

    1
    2
    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
    {
        "meta": {
            "pageSize": 5000,
            "hasNext": false,
            "lastEntity": null
        },
        "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 sample below is a request for page size 10.

  • Sample request

    1
    2
    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
    {
        "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

Use the lastEntity parameter request the next page of mappings. The sample below is a request to get the mapping list after the lastEntity.

  • Sample request

    1
    2
    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
    {
        "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 100 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 in an array.

1
2
curl --data-raw '["1","2","3"]' --header 'Content-type: application/json' -X GET "https://your-site.atlassian.net/rest/atlassian-connect/1/migration/mapping/26925583-10bd-49fb-b67c-15fc2447a97b/find?namespace=confluence:page"

The response will look like:

1
2
{
    "1": "value1",
    "2": "value2",
    "3": "value3"
}

Rate this page: