Triggering Id Mapping job

Overview

To generate Id Mappings between your Server/DC and Cloud instances, you need to trigger an asynchronous job using the REST API. This job will analyze both your source (Server/DC) and target (Cloud) sites to create a comprehensive mapping of entity IDs.

Prerequisites

Before triggering an Id Mapping job, ensure you have:

• Admin access to both the source Server/DC instance and target Cloud site
• Authentication credentials (API token or username/password)
• Base URLs for both your source and target instances
• Completed migration from Server/DC to Cloud

Authentication

A server admin can authenticate API calls using either:

• API Token: Recommended for security
• Username and Password: Basic authentication

API Endpoint

POST Trigger Id Mapping Generation

HTTP Method: POST

URL:

1
2
https://api.atlassian.com/migrations/reports/v1/id-mappings/trigger

Content-Type: application/json

Request Format

For Confluence

1
2
{
  "product": "CONFLUENCE",
  "destinationURL": "https://your-confluence-cloud-site.atlassian.net",
  "sourceURL": "https://your-confluence-server-base-url"
}

For Jira

1
2
{
  "product": "JIRA", 
  "destinationURL": "https://your-jira-cloud-site.atlassian.net",
  "sourceURL": "https://your-jira-server-base-url"
}

Request Parameters

Important Notes

• No trailing slashes - Ensure URLs don't end with /
• Exact product names - Use CONFLUENCE or JIRA (case-sensitive)
• Complete URLs - Include the full base URL including protocol (https://)

Response Scenarios

Success (202 ACCEPTED)

1
2
{
  "jobId": "<JOB_ID>",
  "status": "PENDING"
}

What this means: Your Id Mapping job has been accepted and queued for processing. Save the jobId - you'll need it to check status and download the report.

Validation Error (400 BAD REQUEST)

1
2
{
  "status": 400,
  "errorMessage": "Validation failed",
  "errors": [
    "Product must be CONFLUENCE or JIRA"
  ],
  "id": "<REQUEST_ID>"
}

Common causes:

• Invalid product name (must be exactly CONFLUENCE or JIRA)
• Malformed URLs
• Missing required fields

Server Error (500 INTERNAL SERVER ERROR)

1
2
{
  "status": 500,
  "errorMessage": "Internal Server Error", 
  "id": "<REQUEST_ID>"
}

What to do: This indicates a service issue. Wait a few minutes and retry. If the problem persists, contact support with the request ID.

Example with cURL

1
2
curl -X POST \
  https://api.atlassian.com/migrations/reports/v1/id-mappings/trigger \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "JIRA",
    "destinationURL": "https://mycompany.atlassian.net", 
    "sourceURL": "https://jira.mycompany.com"
  }'

What happens next?

1. Job queued: Your request is accepted and queued for processing
2. Analysis begins: The system analyzes both your source and target instances
3. Mapping generation: Id Mappings are created for all migrated entities
4. Report creation: A downloadable report file is generated

The process is asynchronous, so you'll need to check the job status periodically.

Next steps

• Check job status and download the report
• Learn more about Id Mapping