Retrieve data mappings

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

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

See an example in repository

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.

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

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.

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"
}