Update Jira and Confluence links after server-to-cloud migration

[#1]

Hello, my name is Ali, and I am a product manager on Atlassian's Migration team, working on the tools to help you migrate your data from self-managed infrastructure (Server and Data Center) to Cloud. For those of you in the middle of a cloud migration or about to start one, I would like to invite you to use the Link Migration Service user interface (known as Product links) to update Jira and Confluence product links following a server-to-cloud migration.

What are product links?

Product links are URLs that direct users to entities such as Jira issues or Confluence pages. For example, users may link to a Jira ticket where they are tracking work on a Confluence page that explains the work they’re doing and why. These kinds of links are incredibly important for providing more context and giving teammates and stakeholders the visibility they need.

The most familiar examples of product links include:

• Links between Jira issues in different instances

• Links from Jira issues to Confluence pages

• Links from Confluence pages to Jira issues

How does Link Migration Service help?

When you migrate your products to the cloud, many product links may not function correctly. This issue occurs because the links continue to point toward the resources to which they were originally configured, resulting in redirected traffic to your old Server or Data Center instances or to resources that are no longer available, like in the following example:

Until recently, there wasn't a solution to update these links without reaching out to Atlassian Support. We are now changing that to make it easier and faster for you to update these broken links and, as a result, get up and running in cloud sooner.

What is new?

You’ll have access to a new view on admin.atlassian.com called 'Product links.' Under the 'Product links' section, you’ll be able to see your migrated products, and for each product, you’ll have the ability to update all supported product links by executing link updates.

You can even use 'Product Links' to update links after test migrations so you can complete proper user acceptance testing of links before production migrations.

How to use the feature

1. Access feature

After a migration from Server or DC to Cloud, go to admin.atlassian.com, and select Settings > Product links.

2. Select product

Select the product in which you want to update links. For example, if you wish to update links in Jira issues that point to Confluence pages, choose the Jira product to update these links within the Jira issues.

3. Map links

For each link update, you’ll need to provide details of the products that were linked to the cloud product you are updating. This process involves mapping pre- and post-migration URLs. This mapping will be used to locate links and update them accordingly. You can add more linked products by selecting Add another product and mapping another set of URLs.

If you’re updating a product that was migrated from a staging environment, tick Migrated from a staging instance and provide the source server URL. This will help us find the links you’re trying to fix.

4. Update product links

When you hit Update links, it will identify any obsolete links, replace their server URLs with the corresponding cloud URLs, and update resource IDs to align with the new cloud IDs of migrated resources. During this process, the ‘Last update status' next to the product being updated will display 'In-progress.’

5. Reviewing the results

Once a link update job is complete (as indicated by the ‘Last update status'), you can review the results using the audit log. The audit log provides a detailed view of each modified resource. You can also use the 'History report’ to see summarized results of the completed link updates. To double-check that the link updates went through successfully, browse your Jira and Confluence instances to make sure the links now accurately point to the correct cloud sites.

More information

Leave a comment on this post if you have any questions or feedback. To learn more about this product, see Update product links after the migration.

Product links REST API

Apart from the user interface, we also offer APIs to update links. If you prefer using APIs, you can find the API documentation following the links provided below.

API docs on Atlassian Developer portal 

API docs on Support portal

[JG Meillaud .]

This is great,

If I understand correctly this will allow to spread the migration across more, smaller batches without relying on Atlassian support for these essential link fixes.

[Ali BenCafu]

@JG Meillaud . Yes, you're spot on! You can fix links between small migration batches without relying on Atlassian support.

[JG Meillaud]

Hi @Ali BenCafu ,

I tried it on our sandbox and it seems to be working perfectly!

Very happy that you have included the option to differentiate the URLs in case of a migration from a backup (which is our case).

Cheers,
JG

[JG Meillaud .]

Hi @Ali BenCafu

We used it after a migration to our live site and so far so good!

However, we noticed 1 unexpected behaviour:

When there is a link fix on a Confluence task

It sends a someone has edited a task to the users mentionned on the task

Which is confusing for them

Cheers,
JG

[Heather Mardis]

I have used this 'update links' feature on my jira/confluence cloud and a review of the results does seem to have update all the links, See image below: each of my products show with a 'SANDBOX' note in blue, but I do not have a sandbox available for either product, what does this mean?

I look at the sites both jira/confluence and the pre-updated links still seem to be in place but there are no instructions for how to 'publish' the sandbox updates? Nor is there any reference to this 'SANDBOX' behavior in the instructions.


I had old sandboxes we used to test our migration, do I need to create a new sanbox before runnin this?

[Ali BenCafu]

@JG Meillaud . @Heather Mardis I will engage engineering to check for you. Thanks for using the product and raising these points.

[Daniel Serkowski]

Hello. 

I am Daniel from the Link Migration Service engineering team. Thank you for using the product, and bringing these issues to our attention!

@Heather Mardis , we have created a ticket in our backlog to fix this bug.
@JG Meillaud , we are investigating the cause of this issue, and we will get to you as soon as I have more information.

Best,
Daniel

[Daniel Serkowski]

Hello @JG Meillaud . ,  @Heather Mardis, 

We are happy to say that both issues you reported were resolved!

Feel free to let us know if you have more feedback.

Best,
Daniel

[Dan W]

has access to the EAP closed?  We are in the middle of our migration and wanted to know if it was still available.  The form above to join says it doesn't exist.

Update -  Never mind it looks like we have it already

[Dan W]

We are in the middle of our migration currently and I have a couple of questions on how this works.

I only see our sandbox instances currently, is that because we have only migrated to our sandbox will production show up after we do a production migration?

I am assuming I need to run the Update Links option on each app, Confluence, Jira Software, and Jira Service Management.  Is that correct?  Does it matter which order I run it in?

[Ali BenCafu]

@Dan W - Product links is now GA, and you can use it to update links on migrated Jira Software, Jira Service Management, and Confluence products.

Please note that a product is made available to update links upon performing a migration within that product. You need to update links per product (where links are not working).

Let me know if you managed to use the product.

[eric_gagnon_banq]

Hello,

I was keeping an eye on availability of this tool wich could give us more flexibility in our planning (not having to coordinate with Atlassian / being able to do this during weekend).

I wanted to give a try in a sandbox but there is a few questions I was not able to answer from the documentation.

- Does the source server need to be accessible on internet? The previous documented method to update products links with Atlassian support required to parse migration logs. The tool need to be able to gather those remotely? I did notice that the rest api require configuration of product link, is there such dependency for the admin tool too?

- Is there dependency of version of the source server version / migration assistant tool version?

- Why is the menu "Migrated from (Base URL)" fixed and what define the url options offered (I did noticed the list is different if our target prod instance instead of the sanbox) ? In the sandbox by exemple, I see one url that refer to one of our server "staging" instance, not the prod url from wich the current sandbox content is from.

I have the option to ask my questions through migration support but asking here in case the answer could be useful to others.

Thanks for the tool,

Eric

[Thomas Wohlwend]

Doesn't work for me. It only shows the Jira Work Management Product but not my Confluence Product. 

[Ali BenCafu]

Hi @eric_gagnon_banq, thanks for reaching out!

- The tool's UI on Admin Hub and the API don't require the on-premise instances to be connected to the internet. We fetch the mapping source, destination links, and IDs directly from the migration platform after migration. The configuration is necessary on both the UI and API to help guide the tool to fetch the mappings from the migration platform without connecting to the on-premise instances.

- There is no dependency on the version of the server and migration tooling as long as the migration was performed by the Jira or Confluence Cloud Migration Assistants.

- When you select the “Destination URL,” the tool filters the list of "Migrated from" instances to display the instance from which the selected destination was migrated from. This filtering is based on the data saved during the migration in the migration platform.

Generally speaking, the tool scans the selected product for links of the selected “Migrated From” URL. If such links exist, the tool verifies whether they map to the selected “Destination URL” on the migration platform. If they do, the tool will proceed with the update.

In the sandbox case, the data was migrated from your "staging" on-premise instance, so when you select the sandbox as your "Destination URL", it provides you with the "staging" environment as the option for "Migrated from".

Hope this helps. Let me know if you have more questions.

[Ali BenCafu]

Hi, @Thomas Wohlwend, could you expand on this so we can help you? Did you migrate your Confluence product? What tool did you use for the migration?

[Thomas Wohlwend]

Hi @Ali BenCafu 

The migration assistant did not work on my Confluence server instance, it only showed a blank page, I had reported that in a separate support ticket which has never been answered. So I resorted to manual export / import of my spaces. Which worked fine and also fixing the links to Jira issues worked. I had previously migrated Jira with the migration assistant. Only, I can‘t fix the links from Jira to Confluence. I tried with the REST API and reported this in yet another ticket. And I understand why. Without the migration logs of the MA there is probably no way to fix the links. Will support be able to fix those on the DB level? Or will I have to export / import to stageing first and then migrate from there?

[Łukasz Halicki]

@Thomas Wohlwend yes, if you didn't migrate via Migration Assistant our solution won't be able to cover this as we rely on information captured by those during the proces. But DB scripts run via our support should be able to handle this case and fix links.