Confluence Space Inventory

• 1: How to map Confluence Spaces to SharePoint Sites
• 2: How to migrate Confluence Pages using CQL Query Selectors

Facts about the Confluence Space Inventory

The Confluence Space Inventory - or short Space Inventory - is a SharePoint list that serves the following purposes:

1. show each Confluence space for you to select for migration
2. allow adding additional selectors for Confluence pages to migrate, mainly CQL queries
3. serve as the lookup table when resolving cross-page and cross-space links

Selectors

A source selector is either a Confluence space key, or a CQL query. When selected for migration, all pages covered by the source selector will be scheduled for migration.

Note

CQL query selectors have been first introduced in WikiTraccs release v1.8.0.

WikiTraccs creates the Space Inventory and adds information about Confluence spaces.

You use the Space Inventory to select source pages to migrate, and to specify target SharePoint sites. WikiTraccs will use this information to decide which content to migrate, and how to resolve links between pages.

The Space Inventory is created and updated by WikiTraccs.GUI when selecting the Update space inventory and WikiTraccs site button:

Note: WikiTraccs.Console will also check and create the Space Inventory, if necessary.

The Space Inventory can be repeatedly updated by selecting the Update space inventory and WikiTraccs site button. Use this to have spaces added to the inventory list that are missing, either because they have been newly created in Confluence, or because they have been deleted from the list.

Accessing the Space Inventory

Selecting the Open Space Inventory to choose source spaces button opens the Space Inventory in a browser:

When the Space Inventory exists, the browser should show the SharePoint list Confluence Space Inventory (WikiTraccs):

If - for whatever reason - the Space Inventory does not exist, the browser will show an error:

If you see above error, make sure to select the Update space inventory and WikiTraccs site button first so that WikiTraccs has a chance to create and update the list.

You can find the Space Inventory without WikiTraccs as well, as it’s just a SharePoint list. Open the WikiTraccs site in a browser, go to Site Contents, and select the Confluence Space Inventory (WikiTraccs) list.

How does it work exactly?

Here’s an image showing how the Space Inventory works:

This image summarized:

• the Space Inventory list contains multiple source to target mappings that tell WikiTraccs what to migrate, and where
• each row contains at least the following mandatory information:
  • WT_In_CfSiteId - the Confluence site identifier; this corresponds to the Confluence base URL (example: https://wiki.contoso.com)
  • WT_In_CfSpaceKey - the source selector, telling WikiTraccs which pages to migrate; this can be the Confluence space key, but starting with release 1.8 of WikiTraccs this field can also contain a CQL query (example for space key: HR, example for CQL query: label=“archive”)
  • WT_Setting_RequestTransformation - if this is checked, WikiTraccs will migrate all pages covered by the the source selector from Confluence to SharePoint; otherwise this mapping is only used for link resolution
  • WT_Setting_TargetSiteRootUrl - the target SharePoint site for all pages covered by the source selector; this is relevant for migrating pages covered by the source selector, but also for creating the correct links to target pages (example: https://contoso.sharepoint.com/sites/target1); if this is left empty, the default target site URL as configured via WikiTraccs.GUI will be used
• when starting the migration, WikiTraccs will collect all pages from all source selectors that have been chosen for migration, and schedule them for migration; this queue is processed one page after another
• when a page contains a link to a space, page or attachment, WikiTraccs will look up the SharePoint target site in the Space Inventory and create the link based on the found mapping; if there is no mapping a transformation error will be logged for the page (see Measuring page migration success on where to find this metric)

Using the Confluence Space Inventory

To learn how to migrate whole Confluence spaces to SharePoint refer to How to map Confluence Spaces to SharePoint Sites.

To learn about using CQL query selectors to choose Confluence pages to migrate to SharePoint refer to How to migrate Confluence Pages using CQL Query Selectors.

Here are other resources showing how the Space Inventory is used:

• The quick start guide covers selecting which spaces to migrate: Getting Started
• Why mapping to target sites is important for resolving migrated links: Cross-space links and target sites

1 - How to map Confluence Spaces to SharePoint Sites

WikiTraccs allows to define a target site collection for every space it migrates.

Migrate to one target site by default

WikiTraccs by default migrates everything to the default target site.

When using WikiTraccs.GUI you enter the default target site URL into the Default target site input field:

Default Target Site Configuration in WikiTraccs.GUI

When you don’t configure anything else, WikiTraccs will migrate all Confluence pages to this SharePoint site.

Configure a different target site for spaces

When you want WikiTraccs to migrate pages from different spaces to different target sites, you configure this mapping in the Confluence Space Inventory list in the WikiTraccs site.

The Confluence Space Inventory list has a column WT_Setting_TargetSiteRootUrl. Enter the target site root URL there.

Target Site Root URL Column

When the WT_Setting_TargetSiteRootUrl column is empty, WikiTraccs falls back to using the default target site URL for that space. It is totally valid to set a target site URL only for some spaces.

Cross-space links and target sites

In general, when migrating pages, WikiTraccs translates links between Confluence pages to proper links between SharePoint pages.

The target site mapping is important to properly resolve cross-space links.

When migrating a Confluence page that points to a page in a different Confluence space, WikiTraccs looks up the target site URL for that space the page links to. It then uses this target site URL to create the proper link in SharePoint.

The links WikiTraccs creates in SharePoint follow a specific naming convention. This convention is roughly as follows (for pages):

<targetsiteurl>/SitePages/<spacekey><pagetitle><pageid>.aspx

(The resulting page file name is stripped of any characters that are not allowed in SharePoint.)

When a Confluence page is migrated to SharePoint and this page links to another page or space that has not yet been migrated WikiTraccs can nevertheless create the link. WikiTraccs doesn’t care if the target exists. It will exist once it will have been migrated.

This allows WikiTraccs to migrate a Confluence space where pages link to other pages or spaces that have not yet been migrated, while still creating valid links.

2 - How to migrate Confluence Pages using CQL Query Selectors

WikiTraccs allows selecting source pages for migration using CQL queries.

Migrating spaces vs. migrating via CQL query

Before release 1.8.0 WikiTraccs only supported the configuration of entire Confluence spaces for migration and for link resolution. This meant that all pages of a given source space would be migrated to the configured target site.

Feedback from clients let to the introduction of an additional, more flexible way to select source pages: pages can now also be selected via CQL query. This allows to select specific pages for migration.

For WikiTraccs the technical difference is minimal, from a page selection perspective.

For you, the difference is also minimal, from a configuration perspective. The Space Inventory list is still used to configure which pages should be migrated to which target. Simply write your CQL query to the WT_In_SpaceKey field.

The following screenshot shows how different CQL queries are used to select pages by their label, migrating each label to a different target site:

Space Inventory list showing CQL query selectors for source page selection.

Note: the field is still named WT_In_SpaceKey since initially only a space key was supported there.

Everything else from the space selector article applies as well, so please refer to this article: How to map Confluence Spaces to SharePoint Sites. The target site can be configured. If there is no target site set, the default target site will be chosen.

There are some consequences though, when using CQL queries.

The consequences of using CQL queries source selectors

Here’s the list of topics that can get more complicated when dealing with CQL queries:

• Restricted Pages: see note above
• Link Resolution: Confluence pages linking to other spaces, pages, or attachments require more time to migrate, and put more load on Confluence
• Query Result Size: using CQL queries you can select a large amount of pages (potentially all)
• Duplicate Pages: one page can be selected by multiple CQL queries, leading to pages being migrated multiple times

Link resolution is more difficult

For each CQL query selector you add to the Space Inventory WikiTraccs has to issue one additional request to Confluence for each link it needs to resolve.

Assume you are migrating 10,000 pages, with 2 links to other pages on each of those 10,000 pages. Further assume you configured 100 CQL query selectors in the Space Inventory list. That means that 2*100 callbacks to Confluence would need to be issued for each of those 10,000 pages, amounting to 2,000,000 calls overall during the migration of those 10,000 pages.

Why is that?

To transform links from Confluence to SharePoint, WikiTraccs needs to know which target site a page will be migrated to. But how would WikiTraccs know which CQL query contains which page? To learn this WikiTraccs asks Confluence for each CQL query if a given page is included.

Example:

• page A links to page B with ID 2000
• WikiTraccs needs to find out which SharePoint site page B will be migrated to, to create the proper SharePoint link
• there are two CQL queries configured: label="one", mapped to target site https://contoso.sharepoint.com/sites/one, and label="two", mapped to target site https://contoso.sharepoint.com/sites/two
• WikiTraccs creates a modified CQL query (label="one") AND (id=2000) to check if page B is covered by CQL query label="one"
  • there are no results - page B is not covered
• WikiTraccs creates a second modified CQL query (label="two") AND (id=2000) to check if page B is covered by CQL query label="two"
  • there is one result - page B is covered!
• WikiTraccs now knows that page B will be migrated to site https://contoso.sharepoint.com/sites/two
• thus the correct link to page B is something like https://contoso.sharepoint.com/sites/two/SitePages/SPC-Page-B-2000.aspx

Note: WikiTraccs does not have to do this when only performing space-based migrations (without any CQL queries), since the target site can easily be looked up via each page’s space key in the Space Inventory list.

Duplicate pages can be created

You can write CQL queries might include overlapping results.

Take for example the CQL queries label="one" and label="two".

If Confluence pages only ever have one of the labels one or two, those selectors choose two disjuct sets of pages. Which is good.

But what about pages having both labels one and two? Those pages will be chosen by both CQL queries, migrating each of those pages two times.

The consequences are:

• duplicate content in SharePoint as multiple copies of a page are present
• fuzziness when it comes to linking to those pages as other SharePoint pages can only link to one of the duplicates; which one is not defined