After a successful server to cloud migration URL links are broken in the new cloud instance
This pages describes the problem of broken links after migrating from Server or Data Center to Cloud.
What about cloud-to-cloud migrations?
This pages 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:
- The product you're updating, for example Jira, to update local links.
- 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:
Go to admin.atlassian.com, and select your organization.
Go to Settings > Product links.
For each product that has links you want to update, select … > Update links. You will repeat this step for every product.
2. Select destinations
After selecting Update links, you'll specify new destinations for existing links.
To select destinations:
- 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.
- (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.
- 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.
Failed links
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.
Skipped 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
Reciprocal links
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.
Additional data and app links
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.
Jira applications - supported links
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:
| |
Links to Jira source site URLs added by users (description, comments):
| |
Links to Confluence that use the following URL (usually, this includes links to the space’s main page): | - |
Links to customer portals in Jira Service Management |
Confluence - supported links
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.
Type of link | Example (if applicable) |
|---|---|
Links from a Confluence page to other pages:
|
|
Links to Confluence attachments | |
Links to Confluence comments | |
Outgoing links in Page information | - |
Remote links to Jira (not Jira Macros) |
Unsupported links
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
Legacy way of fixing links
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.