Last updated Nov 10, 2023

What are product links?

Product links are links to entities (for example, Jira issues, Confluence pages) in other Atlassian products or in the same product. Some common examples are:

  • Remote links between Jira issues on different instances

  • Remote links from Jira issues to Confluence pages

  • Local links to Jira issues on the same instance pasted by users as URLs

Product links can be created through built-in features, such as Link issue or Link Confluence page, or manually pasted by users as URLs. Links can be remote (going to other Atlassian products) or local (going to entities within the same product).

Example: Remote link from a Jira issue to a Confluence page Example of a link

After you migrate an Atlassian product to cloud, it lives under a different URL, that’s why all links using the previous URL either no longer work or are incorrect. This usually includes the following types of links:

  • Local links within the migrated product, pasted as URLs

  • Remote links from other cloud products to the migrated one

This feature allows you to update such links in bulk. How often you’ll do it depends on your migration timeframe – you can wait until all products are migrated or do it after every migration.

You update links on every cloud product separately. Before you start, you should identify all Server or Data Center instances that were originally linked to this product.

You will specify their migrated cloud equivalents as new destinations for existing links, and also tell us where they were migrated from, so we can find and update the right links.

Here’s an example request body from the API where you’ll see the products mentioned above:

1
2

{
    "product":       "jira",                               
    "productURL":    "https://jira.atlassian.net",         
    "destinationURL":"https://confluence.atlassian.net",   
    "migratedFrom":  "https://confluence-datacenter.com",  
    ...
}

When you update links, you run a link update on a product – you could also see it as a single task or a job. It updates all existing and compatible links pointing to the old URL (migratedFrom) to the new URL (destinationURL). You’ll most likely need to run multiple link updates on every product, for example if:

  • Some links weren’t updated the first time, because of insufficient permissions or errors

  • You migrated new data into the product, which brought more links

  • You migrated more products to cloud, so you now have more links to update

  • You can run as many link updates as you need. The already updated links won’t be included.

Local links are links to entities within the same instance, so theoretically they shouldn’t need to be updated. That’s true if you created such links through built-in features, such as Link issue – they don’t need updates. However, your users most likely pasted many local links into comments or pages as URLs. Such links include the old Base URL that needs to be updated.

In this case, the Cloud product you’re updating and the new destination for existing links are the same:

1
2

{
    "product":       "jira",
    "productURL":    "https://jira.atlassian.net",
    "destinationURL":"https://jira.atlassian.net",
    "migratedFrom":  "https://jira-datacenter.com",
    ...
}

When you're ready, check out the tutorial or go straitgh to APIs.

Tutorial: Update product links

View REST APIs

Rate this page: