Mapping principals and migrating permissions

This blog post covers new features allowing to migrate permissions and map users and groups from Confluence to SharePoint.


We need to define some terms before starting into the topic.

The term permissions is used broadly to describe which audiences can access which content in Confluence or SharePoint, and to which extent. Those audiences can be users and groups. Users and groups are collectively referred to as principals.

When explicitly talking about permissions for Confluence pages the term page restrictions will be used as this is the correct Confluence terminology.

A sample permission migration

We’ll do a sample permission migration. Screenshots from this migration will be shown throughout the blog post.

For the sake of this sample migration, let’s assume we want to migrate the following Confluence pages:

Confluence Pages

Each of those pages has a different permission configuration. Some pages have view and edit restrictions set. Some for users, some for groups, and some for both. And some pages form a hierarchy to illustrate the challenges associated with that.

How to migrate permissions with WikiTraccs

WikiTraccs can migrate page restrictions from Confluence to SharePoint (within certain limits, more on that later). Migrating page restrictions is done in three steps.

STEP 1: Migrate content and configure mappings for users and groups

First, you migrate page contents. WikiTraccs stores Confluence page restriction and principal information in SharePoint lists, along the way.

When a page is migrated, WikiTraccs also receives page restrictions for this page as well as information about users and groups involved in those restrictions.

No permission configuration is applied to SharePoint pages, yet.

After successfully migrating the Confluence pages shown earlier (only content!) this is how the Pages Library of the migration target site looks:

Migrated Confluence Pages in SharePoint Pages Library

In addition, the document library Confluence Page Permission Snapshots (located in the WikiTraccs site) now contains permission snapshots for those pages, waiting to be applied by WikiTraccs:

Confluence Page Permission Snapshots

Those permission snapshots contain information about a page’s restrictions.

Then there’s a third list that WikiTraccs populates, the Confluence User and Group Mappings list (also located in the WikiTraccs site):

Confluence Users and Groups

You now configure the user and group mapping in this list. WikiTraccs needs to know which Confluence principal maps to which SharePoint principal.

STEP 2: Mapping Confluence users and groups to SharePoint

One factor for a successful permission migration is the mapping of Confluence users and groups to their counterparts in SharePoint. You configure this mapping manually.

Let’s configure the mapping like this, in the Confluence User and Group Mappings table (located in the WikiTraccs site):

Mapping Confluence to SharePoint Principals

The highlighted column WT_Setting_MapForPermissions contains accounts from Entra ID and SharePoint groups.

Those two mappings shall be highlighted in particular, as we’ll revisit them in STEP 3:

  • the Admin Heinrich (admin) Confluence account is mapped to two target accounts Wiki SpaceAdmin and Heinrich Admin Ulbricht
  • the Wiki Reader (wiki.reader) Confluence user is mapped to the Wiki Reader AD account

When you are done with the mapping, proceed with the next step.

STEP 3: Apply permissions to SharePoint pages

In this last step WikiTraccs applies the stored permission information to the already migrated SharePoint pages. This step has to be started manually and separately from the first step.

After choosing permission migration mode, start the migration as usual. WikiTraccs now applies the already migrated permission information to the already migrated pages in SharePoint.

We now have a look at a page permission migration result in depth.

In Confluence, the restrictions for page Page with view-only restriction for Wiki Reader look like this:

Restrictions of Page "Page with view-only restriction for Wiki Reader" in Confluence

Here’s the resulting permissions for the migrated SharePoint page:

Permissions of the Migrated SharePoint Page

Looking at the principals and permission levels this is what happened:

  • Confluence account “wiki.reader” was mapped to the “Wiki Reader” AD account and got Read permissions which corresponds to the Confluence view restriction
  • Confluence account “admin” was mapped to both the “Heinrich Admin Ulbricht” and the “Wiki SpaceAdmin” accounts and got Contribute permissions which corresponds to the Confluence edit permission
  • “WikiTraccs Admin” is the migration account and got Full Control permissions (the migration account is always added)

The basis for this permission configuration had been layed in step 2 when you configured the principal mappings.

Tracking permission migration progress

WikiTraccs logs the result of each page permission migration in the Page Transactions list, that is located in each migration target site in SharePoint.

For our sample migration this looks like this:

Permission Migration Results

There are several reasons why migrating Confluence page restrictions to SharePoint might fail.

The good thing is that a range of permission migration failures can be fixed easily. The permission migration can be run multiple times and will retry failed migrations. This can be repeated until all resolvable errors have been resolved.

Going back to our sample migration you might have noticed that (in the last screenshot) two permission migrations where not successful. For two pages the result is cannot merge hierarchical group restrictions when calculating merged page restrictions which means that for those pages restrictions could not be migrated.

The next section takes a deeper look at what WikiTraccs currently can and cannot do when it comes to migrating permissions.

Capabilities and limitations with regard to migrating permissions

WikiTraccs currently has two types of limitations when it comes to permission migrations: not-implemented features and nearly-impossible-to-add features.

But first, here is what WikiTraccs will do:

  • apply Confluence user and group page restrictions to SharePoint modern pages, when no hierarchy of page restrictions is involved
  • apply hierarchical page restrictions from Confluence to SharePoint modern pages in certain narrow circumstances (e.g. only users are involved)
  • provide a mapping opportunity for each Confluence principal to one or more Entra ID accounts and SharePoint groups
  • map the Confluence view and edit restrictions to corresponding SharePoint permission levels via a hard-wired logic

Features that might be useful in the future, but are not currently implemented:

  • using other group types than SharePoint groups as mapping target
  • provide fallbacks for when a mapping is missing or empty
  • configurable behavior for failed permission migrations (should the SharePoint page be restricted or not?)
  • more control over the permission migration scope (single pages, spaces, …)
  • migrating space and global permissions (those are currently not migrated and need to be set manually on the SharePoint site or sub site level)
  • allowing to configure SharePoint permission levels to be used in the target page (currently the out-of-the-box permission levels are used)
  • regularly updating SharePoint permission based on a configurable schedule

Features that will be hard or impossible to add:

  • migrating arbitrary hierarchies of page restrictions

Re-apply permissions after changing principal mappings

You can change the principal mapping that you configured in STEP 2, even during or after a permission migration.

To do so, proceed as follows:

  1. in the WikiTraccs SharePoint site, change principal mappings via the Confluence User and Group Mappings list
  2. in each migration target SharePoint site, delete entries from the Page Transactions table for pages that should have their permission configuration updated; otherwise WikiTraccs won’t update those pages
  3. in WikiTraccs, choose Permission Migration mode and start the migration

WikiTraccs will now apply page permissions again, using the already migrated information about Confluence page restrictions, and the updated principal mapping.


With the next release WikiTraccs adds the ability to migrate page restrictions from Confluence to SharePoint.

You’ll be able to configure which Confluence users and groups correspond to which SharePoint users and groups. WikiTraccs uses this information when applying unique permissions to SharePoint pages.

This release marks a milestone from which further development will be driven by your feedback. WikiTraccs could support several additional scenarios and development effort will be directed to areas with the most demand.

Furthermore, user and group mappings will be the basis for the migration of page metadata like author and editor.

Give it a try

Give WikiTraccs a try and check out its transformation capabilities!

Quick start guide >>

Start today with WikiTraccs’ free Trial Version:

Download FREE WikiTraccs now

Or get in touch via email if you are interested in a demo. Give it 45 minutes and you’ll be up to speed on how WikiTraccs can help you.