After a successful server to cloud migration URL links are broken in the new cloud instance

Still need help?

The Atlassian Community is here for you.

Ask the community

Platform Notice: Cloud and Data Center - This article applies equally to both cloud and data center platforms.

Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

This page describes the problem of broken links after migrating from Server or Data Center to Cloud.

What about cloud-to-cloud migrations?

This page focuses on migrations from Server or Data Center to Cloud. If you have broken links after a cloud-to-cloud migration, you need to reach out to Atlassian Support. To do this,  and select Migration support. Related feature request

If you chose the migration option to "Migration all data at once", products will not appear under product link fixing. To fix these broken links, you can use the Rest API. If you have any problems, contact Support.

Summary

After migrating Jira or Confluence (Server or Data Center) to Atlassian Cloud, some URLs in the recently migrated products might appear broken as they still point at the old Server or Data Center instances. This includes any links between individual entities in the migrated Atlassian products, for example:

  • Remote links between Jira issues or Confluence pages

  • Links to attachments

  • Links pasted by users as URLs into comments or pages

Cause

After migrating Atlassian products to cloud, they live under different URLs, because they’re essentially new products. Any links from other products (Jira or Confluence) would still reference the old Server URLs, which either no longer work or represent the pre-migration Server instances. Such links aren’t automatically updater after the migration.

To fix such links, you need to complete a post-migration task that updates all broken links to their new cloud destinations.

Solutions

You can update broken links in your migrated products by using the Product links view in admin.atlassian.com.

Should running the product link fix process outlined below not repair a supported link type after completing the final production migration, please contact our migrations support team providing the information requested in the 'Solution' section of the legacy link-fixing documentation

Before you begin

Permissions

  • 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 that has links you want to update.

Multiple linked products in cloud

If you have multiple linked products in cloud, for each of them you need to run a link update that includes the details of:

  1. The product you're updating, for example Jira, to update local links.
  2. Another product linked to it, for example Confluence, to update remote links.

By default, you specify one product in your link update. You can add another one to the same update by selecting Add another product and specifying its details.

The following page explains what links (local and remote) need to be updated in more detail:

Learn more about examples and use cases

1. Update links from admin.atlassian.com

To update links:

  1. Go to admin.atlassian.com, and select your organization.

  2. Go to Settings > Product links.

  3. For each product that has links you want to update, select … > Update links. You will repeat this step for every product. Landing page of product links in admin.atlassian.com

2. Select destinations

After selecting Update links, you'll specify new destinations for existing links.

To select destinations:

  1. In the Destination product section, choose the same product as the one you're updating, for example Jira. This will include all local links within Jira in your update.
  2. (If you have other products in cloud) Next, select Add another product, and choose a product linked to Jira, for example Confluence. This will include all remote links from Jira to Confluence in your update. Adding an additional destination product to the same link update
  3. When you're ready, select Review to see the summary, and then Update links to start your update. 

3. View the results

When your update is complete, you can download the audit log and history report that show results:

  • Audit log: Shows links that were successfully updated in a given product in the last 29 days, consolidating results of all link updates. This report focuses on specific modifications.

  • History log: Shows the summary of all link updates performed on a given product. This report focuses on the summary of link updates rather than specific modifications.

The history report shows a summary of updated or failed links. Failed links usually include links that are incompatible and can’t be fixed, because:

  • The link goes to an entity that was renamed or doesn’t exist anymore.

  • The link was manually modified to an incompatible pattern. For example, its ID was changed.

However, it might happen that we couldn’t save a link because of an error. If the number is high, try updating the links again.

Failed links don’t include links that are unsupported. We don’t count unsupported links.

In some cases, we’ll skip updating links if they go to entities that haven’t been migrated yet, which is a common case in phased migrations. We don’t record the skipped links in any of the reports, but you might notice that some links still go to the old URLs. If you migrate in phases, do another link update after you migrate the entire product to cloud. The previously skipped links will be updated if their target entities exist.

Learn more about results and statuses

The link update described above would update local links within Jira and outgoing links to Confluence. Reciprocal links in Confluence won't be updated at the same time, so you need to run a similar update for Confluence.

More information and docs

For more information and use cases, see the documentation:

Learn how to update product links after the migration

Reaching out to support in case of problems

You should reach out to Atlassian Support only if you encounter problems with the solution described above. In this case, Atlassian Support can use this or a similar legacy way to fix the links for you.

Contact Atlassian Support

To reach out to Atlassian Support, raise a request, and select Migration support.

Provide the data

To update the links in your products, we’ll need information about the destinations of links:

  • Current URL in cloud: URL of the cloud product that will be the new destination for links.

  • Original URL in server: URL of the server product from which it was migrated. If possible, also provide Server ID.

  • (Optional) Production instance URL: If this product was migrated from a staging instance, also provide the URL of the corresponding production instance. If possible, also provide Server ID.

If you’d like to fix links between products in different cloud sites, we’ll also need the URLs of both sites. In this case, you also need to create application links between your products before reaching out to us (for products that live in a single site, app links are created automatically). Learn how to create app links

Types of links that can be fixed

The following lists show the types of links that can be updated. 

Type of link

Example (if applicable)

Remote links to Jira issues or their comments

Links to Jira issues added by users (description, comments)

Remote links to Confluence pages

Links to Confluence pages added by users, including TinyURLs and blog posts:

  • View page (pageID) format

  • Edit page format

  • Page title format

  • Display format

  • TinyURLs, blog posts

Links to Jira source site URLs added by users (description, comments):

  • source-site/browse/

  • source-site/secure/

  • source-site/projects/

  • source-site/issues/

Links to Confluence that use the following URL (usually, this includes links to the space’s main page): <BaseURL>/display/*

-

Links to customer portals that contain issue keys in the URL. Links without keys aren't supported.

https://acmecorp.com/servicedesk/customer/portal/197/ACME-1

Jira Macros need to be fixed separately

Broken Jira macros are different from the types of links described here. To fix them, run the Jira Macro Repair tool on the following URL:

<YourSiteName>.atlassian.net/wiki/admin/jim-validator/view.action

For more info on the tool, see Using the Jira Macro Repair. If you’re unable to fix broken macros, reach out to our Support team.

Any links that aren’t mentioned in the lists above aren’t supported.

Related issues

There are several features in development to either support more links or improve the whole process:

  • MIG-1279 - Getting issue details... STATUS
  • MIG-1418 - Getting issue details... STATUS
  • MIG-1432 - Getting issue details... STATUS
  • MIG-1457 - Getting issue details... STATUS

We also have a legacy way of requesting link fixes. If the steps described here don’t work for you, you can try it instead. In some cases, you might also be asked by our Support team to complete it. For more information, see: Legacy way of fixing links.


Last modified on Dec 9, 2024

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.