RSS

Making Sure Migrated Links Work

This blog post explains how to keep links working during and after migration, and what you should do before and after to help WikiTraccs.
By Heinrich Ulbricht |

Important questions you might have about link migration:

Will links keep working after migrating from Confluence to SharePoint?

Yes. WikiTraccs takes care of this. Links between Confluence pages are converted to links between SharePoint pages; the same applies to attachments.

Do I have to migrate everything in one go for links to work in SharePoint?

No. You don’t have to migrate everything in a single run; you can migrate in waves over time.

A key element is that WikiTraccs can create links to content that has not yet been migrated, by “calculating” links.

How does link migration work and how should you prepare?

Configure target site mappings before you start the migration. Run the link fixer after each migration wave.

Configure a Complete Target Site Mapping (BEFORE MIGRATING)

Before you start a migration, tell WikiTraccs which Confluence content to migrate (using selectors), and where to migrate to in SharePoint, by mapping selectors to target sites.

You configure the target site mapping in the Space Inventory, a SharePoint list. Most importantly for links, it tells WikiTraccs which SharePoint sites to store the migrated pages in.

If you’ve ever migrated content with WikiTraccs, you’ve had the Space Inventory open at least once, to tick a selector for transformation.

Here’s the recommendation:

Configure a complete target site mapping for all selectors before migrating the first Confluence page. This tells WikiTraccs where content will end up in SharePoint when selectors are migrated. You don’t have to migrate everything right away - just define where the content will end up later.

Run Page Refinement to Fix Broken Links (AFTER MIGRATING)

Using Page Refinement, WikiTraccs can detect and fix broken links. WikiTraccs acts as a “link fixer.”

After migration, refer to Page Refinement about the general concept and specifically to Page Refinement - Fix Broken Links.

How are Page Links “Calculated” by WikiTraccs?

How can WikiTraccs “calculate” links to SharePoint pages without having to migrate their content first?

Let’s look at the address of a migrated SharePoint page:

https://​contoso.sharepoint.com/sites/People-Portal/SitePages/HR-New-Hire-Guide-12345.aspx

WikiTraccs can create the SharePoint page file name from any Confluence page’s space key (HR), page title (New Hire Guide), and page ID (12345).

To find the target SharePoint site (People-Portal) WikiTraccs looks at the Space Inventory and expects to find a target site mapping, that includes the linked-to page.

In this example, WikiTraccs might find a space selector for the HR space that is mapped to the target site https://​contoso.sharepoint.com/sites/People-Portal. It thus knows that all pages from the HR space will at some point be migrated to the People-Portal SharePoint site.

If WikiTraccs cannot find a target site configuration for a linked-to page, it uses the default target site value that you entered in the blue WikiTraccs window.

A dead link is a link that shows a “page not found” (or 404) error when you click it.

During migration, there are often dead links on already migrated pages.

Let’s look at the two most common causes for dead links.

Missing Target Page (Will be Migrated Later)

The target page of the link might not have been migrated, yet. It can be as simple as that.

WikiTraccs can “calculate” links to any page, migrated or not, as shown in the previous section. As soon as the target page has been migrated, the link starts working.

Nothing to do here.

Broken links are often a result of changing target site mappings mid-migration.

Let’s assume the following selector-to-target-site mapping in the Space Inventory:

  • “all pages of the HR space shall be migrated to the SharePoint site https://​contoso.sharepoint.com/sites/People-Portal”

This is just a mapping; let’s assume the HR space has not been migrated, yet.

When a page is migrated that links to the New Hire Guide page (which lives in the HR space), the following link will be calculated by WikiTraccs and inserted into the page:

https://​contoso.sharepoint.com/sites/People-Portal/SitePages/HR-New-Hire-Guide-12345.aspx

WikiTraccs used metadata available at the time of migration (target site, space key, page title, page ID) to calculate the link.

Now, before migrating the HR space, suppose you change its target site mapping to:

  • “all pages of the HR space shall be migrated to https://​contoso.sharepoint.com/sites/HR-Hub”

Then, after you migrate the HR space, you’ll find the migrated New Hire Guide page at:

https://​contoso.sharepoint.com/sites/HR-Hub/SitePages/HR-New-Hire-Guide-12345.aspx

Since pages from HR will now end up in the HR-Hub site, links to the People-Portal site (created based on the initial target site mapping) are now dead.

This is resolved by the link fixer, which will - in our case - adjust the target site part from People-Portal to HR-Hub in all links it can find.

Recommendations

Run the Page Refiner with Log action first: Page Refinement - Log Broken Links. Review the text file it creates. It lists all links that need fixing, and the new target for each link (if one could be found).

After reviewing, run the Page Refiner with Fix action: Page Refinement - Fix Broken Links. This will fix the links by editing affected pages.

Running the page refiner on migrated SharePoint pages is about ten times faster than migrating them.

You can run the Page Refiner repeatedly.

Notes

This post mostly talks about page links, but everything also applies to attachment links.