Last updated Feb 28, 2024

Update links to federated instances

When you split a single Jira Server or Data Center instance into multiple instances in cloud, links between issues that were previously local won’t exist after the migration. You can use REST API to recreate them as remote links. They will be updated to their new destinations at the same time.

Before you begin

Timeframe

You can recreate your links only for 2 weeks after the migration. Afterwards, the migration data that we use to identify those links is deleted for privacy reasons.

Products

You can recreate links to federated instances only for Jira. Confluence and page links aren’t supported.

Type of links

When you use this REST API, it will recreate and update links that were previously local, including issue links and links in user-generated content. For other links, for example links to other products, you can use the same REST API or the Product links view from admin.atlassian.com. Recreating links is supported only through REST API.

Prerequisites

Here are additional prerequisites:

You need to be a site admin of the site where the product lives or an organization admin.
You need to be an admin of the product.
You need to create an application link between the product and destination product (cloud). If both live in the same cloud site, the app link should be created automatically.
You need to generate an API token in cloud. Generate API token
You'll need to provide your Site ID in the APIs. To get it, go to https://{SITE_URL}/_edge/tenant_info, for example https://jira.atlassian.net/_edge/tenant_info

Authentication

Your requests will be authenticated via HTTP basic auth by using your personal API token. You need to attach the following header to each request:

1
2
Authorization: Basic $BASE64_TOKEN

The $BASE64_TOKEN is a base64 encoded string that consists of your email address and API token, like in the following snippet:

1
2
$YOUR_EMAIL:$YOUR_API_TOKEN

That’s a standard basic auth header. You can generate it by using, for example, curl:

1
2
curl -u "$YOUR_EMAIL:$YOUR_API_TOKEN" ...

Authorize the app links between federated instances

Before you can run a link update, you need to authorize the app links. This is only required when you’re recreating the links, it’s not needed for regular link updates.

To authorize the app link:

Open the Jira instance that has links you want to update.
Open any issue and start creating an issue link. To do this, select Link issue.
Expand the Local drop-down and search for the destination Jira instance.
Select Authorize and search, and follow instructions on the screen.

You don’t need to complete the issue link, but only authorize the access to the federated instance. If you’re updating links on multiple federated instances, repeat these steps on each of them.

Run a link update to recreate the previously local links and update them

You will use the same REST API resources as for other link updates, with an additional recreateAsRemote parameter.

To run a link update, use the following request:

1
2
curl \
  -u "$YOUR_EMAIL:YOUR_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -XPOST "https://api.atlassian.com/links/v1/${SITE_ID}/jobs/cma" \
  --data "$REQUEST_BODY"

Request body

Parameter	Description
product	The cloud product that has links you want to update: Jira or Confluence. The default is Jira. You will run a separate update for every federated instance.
productURL	The URL of the cloud product that has links you want to update.
destinationURL	The URL of the cloud product that will be a new destination for links. We’ll update existing links to this URL. It can be a different cloud product (remote links) or the same as the one you’re updating (local links).
migratedFrom	The Base URL of the Server or Data Center instance from which you migrated data to the destination product represented by destinationURL.
migratedFromOverride	(Optional) If you migrated from a staging or backup instance, provide the Base URL of the corresponding production instance so we can properly map the links. If you migrated from a production instance, skip this parameter.
recreateAsRemote	This parameter recreates local links as remote ones. It’s required for this case.
createBackup	When set to true, we’ll create a backup of your Jira Cloud instance before updating links. The default is false. Available only for Jira Cloud.

Example request body

1
2
{
    "product":               "jira",
    "productURL":            "https://jira.atlassian.net",
    "destinationURL":        "https://confluence.atlassian.net",
    "migratedFrom":          "https://confluence-datacenter.com",
    "migratedFromOverride":  "https://confluence-dc-production.com",
    "recreateAsRemote":      "true",
    "createBackup":          "true"
}

Example full request

1
2
export YOUR_EMAIL=charlie@atlassian.com
export YOUR_API_TOKEN=21Iv4we2ZtoLixXX21OUQiF06a
export SITE_ID=b436336f-99ce-2fbc-4520-7301132h1674
export REQUEST_BODY="{
    \"product\":                 \"jira\",
    \"productURL\":              \"https://jira.atlassian.net\",
    \"destinationURL\":          \"https://confluence.atlassian.net\",
    \"migratedFrom\":            \"https://confluence-datacenter.com\",
    \"migratedFromOverride\":    \"https://confluence-dc-production.com\",
    \"recreateAsRemote\":        \"true\",
    \"createBackup\":            \"true\"
}"
 
curl \
  -u "$YOUR_EMAIL:$YOUR_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -XPOST "https://api.atlassian.com/links/v1/${SITE_ID}/jobs/cma" \
  --data "$REQUEST_BODY"

Next steps

Check the status and results