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 or 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 migration

To illustrate the topic we’ll be going along with a sample 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 WikiTraccs does permission migrations

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

First migration step: WikiTraccs and you prepare everything needed to apply permissions to SharePoint

In a first step WikiTraccs stores Confluence page restriction and principal information in SharePoint lists. This is done while migrating page contents.

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, yet.

After successfully migrating the Confluence pages shown earlier (only content!) this is how the Pages Library should look:

Migrated Confluence Pages in SharePoint Pages Library

In addition, the document library Confluence Page Permission Snapshots 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 prepares, the Confluence User and Group Mappings list:

Confluence Users and Groups

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

After the mapping has been configured WikiTraccs can start with the next migration step.

Second migration step: WikiTraccs applies permissions to SharePoint pages

In a second 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. (More on how to do that in another blog post.)

Let’s assume WikiTraccs migrated the permissions.

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

Here’s the restrictions for page Page with view-only restriction for Wiki Reader in Confluence:

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)

In the next section we’ll look at how the mapping table has to look like to achieve this result.

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.

To achieve the result shown in the previous section the mapping table Confluence User and Group Mappings looks like this:

Mapping Confluence to SharePoint Principals

The highlighted column WT_Setting_MapForPermissions contains accounts from Azure AD and SharePoint groups.

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

When migrating restrictions for the page “Page with view-only restriction for Wiki Reader” WikiTraccs used those mappings to determine who should have access on the SharePoint page.

Tracking permission migration progress

WikiTraccs logs the result of each page permission migration in the Job Results list 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 Azure AD 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


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.