This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Wiki Transformation Project Blog

This is the blog section. It has two categories: News and Releases.

Files in these directories will be listed in reverse chronological order.

News About WikiTraccs

Confluence vs. SharePoint - Part 1: Overall structure

In this post we look at how content is structured in both Confluence and SharePoint.

Confluence

When looking at a Confluence page the basic structure looks like this:

A Confluence page

The following parts make up a Confluence page:

  • Page Content, including
    • Versions
    • Inline Comments
    • Inline Tasks
    • @-Mentions
    • Macros
  • Attachments, including
    • Versions
    • Comments
  • Footer Comments
    • like page content…
  • Restrictions
  • Metadata, including
    • Title
    • Creator, Author
    • Creation Date, Modification Date
    • Likes
    • Labels

Each page lives in a Confluence space where each space can contain hundreds, thousands, or even tens of thousands of pages.

Pages within a space usually form a hierarchy. This means there are parent pages, child pages, and leaves, like a tree:

A Confluence space contains many pages

Access to pages can be restricted at each level of the tree, which also affects all child pages. If a user is not allowed to access a parent page, they cannot access any of the child pages as well.

Confluence can have many spaces. A typical instance has dozens or a couple of hundred space, but there’s also instances with a couple of thousand spaces.

The following parts make up a Confluence space:

  • Pages
  • Metadata
    • Title
    • Description
    • Archived or not
  • Restrictions

Spaces have no hierarchy:

Confluence organizes content in spaces

SharePoint

While Confluence consists of spaces, SharePoint consists of sites, which serve a similar purpose.

The following parts make up a SharePoint site:

  • Lists (note: those are like a table)
    • List Items
      • Item Data in List Columns
      • List Item Permissions
    • List Permissions
  • Document Libraries (note: those are like a drive or folder)
    • Files
      • File Metadata in List Columns
      • File Permissions
    • Document Library Permissions
  • Site Permissions
  • Apps

A SharePoint site

Some SharePoint document libraries are “special” in that they serve a specific purpose. With regard to pages, there’s the Site Pages library and the Site Assets library.

All SharePoint pages are stored in the Site Pages library. For SharePoint, pages are just files with some metadata. There is no page hierarchy and all pages are stored flat in the Site Pages library.

Page attachments are stored in the Site Assets library, in a folder that belongs to the page. Each page has its own folder.

When setting the permissions for a SharePoint page, SharePoint takes care of setting those permissions on the page’s folder as well.

How does it map?

Often Confluence spaces are compared to SharePoint sites.

I’d say this is a fair comparison, when focusing on wiki functionality.

Confluence spaces and SharePoint sites have some things in common. Both:

  • have a title and description
  • have owners
  • can be access restricted to users and groups
  • contain wiki pages and files
  • have their content surfaced via search
  • have no strict technical hierarchy (bear with me on this one)
  • pages inherit permissions but can also have their own

Confluence pages and SharePoint pages also have some things in common. Both:

  • support the basic text formatting capabilities, like bold, headings, tables, images, etc.
  • can be created from templates
  • can have sections to structure page content

Here are the areas where Confluence and SharePoint differ:

ConfluenceSharePoint Online
pages form a hierarchy (with parent and child pages)pages are flat, without a hierarchy
page breadcrumb navigation above pagesno page breadcrumb navigation
pages have attachmentspages have no attachments (we can make it look like they have)
attachments (files) are bound to pagesfiles are stored in document libraries and linked to by pages
pages seem better suited for documenting knowledgepages seem more focused on presenting content nicely
macros can be nestedweb parts cannot be nested
page restrictions have a hierarchyitem level permissions for pages have no hierarchy
rich app marketplacemarketplaces are not Microsoft’s strength
pages support @-mentioning other usersno @-mention support on pages
comments under pages with rich formatting, deeply nestedplain text comments under pages, 2 levels
inline comments on pagesno inline comments
inline tasks on pagesno inline tasks
integration with Jirano integration with Jira
pages can easily be moved to other Confluence spaces (due to their self-contained nature)pages cannot easily be moved to other SharePoint sites (at least not without breaking links or attached metadata)

Confluence Cloud introduces some new restrictions compared to Confluence Server and Data Center, for example with regard to formatting content and nesting macros.

Confluence Link Types Explained

This post shows the different link types in Confluence and highlights the difference between soft links and hard links. It covers the relevance of knowing link types and variations for migration tools.

Migration tools like WikiTraccs needs to take care of Confluence links, because otherwise those are broken after a migration.

WikiTraccs will translate links within Confluence to proper SharePoint links. This includes page links, space links, and attachment links.

There is one challenge for migration tools when analyzing Confluence links and that is properly detecting both the two link types (soft links and hard links), and the different hard link variations.

I get that asked quite a lot. From an end user perspective the difference normally is not visible.

Here is an example of one soft link and one hard link, both linking to another Confluence page, as seen by an end user:

Can you spot the difference?

The difference can only be seen when looking at the page’s storage format, which looks like this:

<ac:link>
   <ri:page ri:space-key="linktarget" ri:content-title="Get the most out of your team space"
      ri:version-at-save="1" />
   <ac:link-body>Get the most out of your team space</ac:link-body>
</ac:link>
<a
   href="//wikitransformationproject.atlassian.net/wiki/spaces/linktarget/pages/60162329/Get+the+most+out+of+your+team+space">Get
   the most out of your team space
</a>

This is how tools like WikiTraccs “see” the page when migrating it to SharePoint Online, or processing it in any other way.

The first link - a soft link - is represented as ac:link element that has metadata attached that allows WikiTraccs to look up information about this page.

The soft link contains readily available metadata, like the target space key (linktarget) and the title of the page (Get the most out of your team space). This is easy to handle for a tool like WikiTraccs. And most importantly, Confluence is able to keep this link up-to-date even if the target page changes.

The second link - a hard link - is a plain HTML link. It also points to the target page, but uses the absolute page address to do so.

The hard link doesn’t contain easily accessible page metadata. If you look closely you’ll see information like the space key, page ID, and so on; those certainly help, but there are many variations of those links, and we look at those further down. Confluence will not keep hard links up-to-date, so, if the target page changes, the link might be broken.

Let’s create one.

Ideally, there shouldn’t be hard links at all. When pasting a link onto a Confluence page, Confluence analyzes the link, detects the content it links to, and creates a proper soft link.

Nevertheless, hard links are often present in more complex content that has been copy and pasted into pages. Confluence’s hard link conversion does not always kick in.

Here’s a sample of how to fool the hard link detection and create a soft link and a hard link:

Above animation shows the following:

  1. we copy a link to a Confluence Cloud page to the clipboard
  2. we paste the link as plain text
  3. Confluence recognizes that this is a hard link and converts it to a soft link
  4. we change the settings of that soft link to look like a regular link
  5. we paste the link a second time
  6. we edit the second link to remove the https: part; the result is still a proper and valid hard link, but it fools Confluence’s logic and it leaves the hard link in place
  7. we save the page

The result is a page containing one soft link and one hard link.

It is relevant if you migrate content from one Confluence environment into another environment.

So, it is relevant for those use cases:

  • Confluence Cloud site to site migrations
  • Confluence Data Center to Confluence Cloud migrations
  • Confluence to SharePoint Online migrations

In all those cases, links between migrated pages will be broken, as well as links from external systems, like Jira descriptions and comments.

To fix those broken links, you need to:

  1. identify the links
  2. modify the links to point to the new location (or redirect)

Knowing that hard links and soft links exist is crucial for identifying the links in the first place.

Ideally, migration tools cover that, so you don’t have to care. WikiTraccs covers this.

We used a very simple hard link example so far (from Confluence Cloud):

wiki/spaces/linktarget/pages/60162329/Get+the+most+out+of+your+team+space

This link contains lots of metadata to look up the target content:

  • content type (page)
  • content ID (60162329)
  • space key or alias (linktarget)

Here’s a list of other hard link variations:

  • wiki/display/Test (space link)
  • wiki/spaces/Test (space link, cloud)
  • wiki/pages/viewpage.action?pageId=10162329 (page link)
  • wiki/pages/viewpage.action?pageId=10162329&pageVersion=1 (link to page version)
  • wiki/x/xYBtAQ (tiny page link)
  • wiki/display/Test/news (page link)
  • wiki/spaces/Test/blog/2024/10/24/181542831/news (blog post link, cloud)
  • wiki/spaces/Test/blog/181542831 (blog post link, cloud)
  • wiki/spaces/Test/pages/edit-v2/2123259301 (page edit link, cloud)
  • wiki/pages/viewpageattachments.action?pageId=60162247&preview=/60162247/174891441/image.png (attachment view link)
  • wiki/download/attachments/10162247/image.png (attachment download link)

Wrap

In this post we learned about soft link and hard links, and looked at different hard link variations.

When moving content from one Confluence environment to another environment (Confluence, SharePoint Online, …) links to pages, attachments, and spaces will break. Those links need to be taken care of, either by tools like WikiTraccs, or proxy solutions that recognize those links and redirect to the new location.

Mapping user accounts from Confluence to SharePoint

This blog post shows a basic user mapping.

In this blog post we’ll create a Confluence page, look at author and editor, migrate the page, configure user mappings, look at the resulting SharePoint page, and update the page’s metadata - to demonstrate how to map users from Confluence to SharePoint.

We start with at a single Confluence source page.

Confluence Source Page

This Confluence page was created by Admin, and last edited by Parzival.

Here are those users in the Confluence administration:

Those users are local Confluence users, so not synchronized with Entra ID or other external directories.

However, note that the email address of Parzival corresponds to the email address of their Entra ID user. We’ll come back to that fact at a later point.

Migrating the Source Page to SharePoint

We now migrate the page to SharePoint.

When migrating pages, WikiTraccs looks at each page and “collects” user accounts from metadata fields and page restrictions.

Information about those user accounts will be stored in the Confluence User and Group Mapping (WikiTraccs) table, in the WikiTraccs site in SharePoint:

This list contains information like:

  • Principal Type (user or group)
  • Display Name
  • Internal Name
  • Key
  • Email Address (note: only if one could be gotten)
  • Principal Source (note: the source is either onprem for Confluence Server and Data Center, or cloud for Confluence Cloud; it does not refer to specific user directories or their location)

The column WT_Setting_MapForDataAndMentions is where the corresponding Entra ID account has to be entered.

Filling in the WT_Setting_MapForDataAndMentions column is a manual task, but can also be automated via PowerShell. Clients also had success filling that via Excel.

There is an automapping feature built into WikiTraccs, though. WikiTraccs tries to find a matching Entra ID account based on the Confluence account’s email address.

That is why (in above screenshot) the mapping for Parzival is already filled in; this account has the same email address in Confluence and Entra ID.

For all other accounts the mapping has to be filled in manually (by you).

Looking at the Migration Result

What we’ve got so far is:

  • one page migrated from Confluence to SharePoint
  • the page author in Confluence is Admin, page editor is Parzival
  • the user mapping for Parzival has been automapped by WikiTraccs in the Confluence User and Group Mapping (WikiTraccs) table
  • the user mapping for Admin is yet to be done
  • the migration account used to log in to SharePoint was WikiTraccs

The metadata of the resulting SharePoint page will look like this:

The creator of the SharePoint page is the Entra ID account WikiTraccs, not Admin. That is because there is no mapping configured for Admin, yet. So, the creator is set to the account doing the migration.

The editor of the SharePoint page is set to Parzi Val, which is the Entra ID account that matches (via email address) the Confluence account Parzival.

We now want to update the mapping for Admin.

Updating Mappings, Updating Pages

So far everything is going as planned.

We migrated some content and got a mapping to do.

Let’s configure the mapping for the Confluence Admin account which we map to the Heinrich Entra ID account:

But how to update the SharePoint page?

WikiTraccs has an update mode built-in for this specific case. In the blue WikiTraccs window, choose it in the Settings dialog:

Update mode that updates page metadata based on configured account mappings

Leave all other settings in place and start the migration again.

WikiTraccs will now run over all migrated pages where a mapping was missing and update the page metadata.

How does WikiTraccs know where a mapping was missing? Those pages have been marked via the Check Principal Mapping column, in the Site Pages library:

After successfully updating author and editor metadata of a page (and only then), WikiTraccs removes this check mark. (Note: If you ever want to force an update of author and editor, set the check mark again before running the migration in update mode.)

After WikiTraccs is finished with the update mode run the SharePoint page should now look like this:

Creator and author are properly set to what was configured via the Confluence User and Group Mapping (WikiTraccs) table.

Confluence Authentication Overview

This post summarizes the different Confluence authentication options that WikiTraccs supports, with a focus on navigating some harder cases.

When starting a Confluence to SharePoint migration with WikiTraccs, you need to authenticate with Confluence so that WikiTraccs can access content.

You’ll need a Confluence user account for the migration

You’ll need a Confluence user account to log in with (“migration account”). WikiTraccs’ access to Confluence happens as this user.

WikiTraccs does not support “application permissions” where it would access Confluence as “itself”. WikiTraccs will always access Confluence in the context of a user account.

Anonymous access

There is one exception to the rule that you always need to use a migration account, and that is a Confluence instance with anonymous access enabled.

Anonymous access is good for testing or demo purposes. The quick start tutorial also uses that with a publicly available Confluence instance.

Anonymous access is not recommended for production migrations as certain metadata cannot be retrieved, like information about users (name, email address) and permission configuration.

Interactive login

Interactive Login is the easiest and most compatible authentication type.

WikiTraccs opens a browser window that you’ll use to log in to Confluence with the migration account. WikiTraccs takes over the user session and all requests to Confluence will be made in the context of the migration user account.

Here is more information: Cookie-based authentication / Interactive login.

The session cookies that WikiTraccs uses to take over the user session are:

  • JSESSIONID
  • seraph.confluence
  • tenant.session.token (Confluence Cloud)
  • _shibsession* (Shibboleth identity provider)

In case your identity provider needs additional cookies to identify a logged in user, click the Advanced Settings button and enter those cookie names:

If there are issues with interactive login, like WikiTraccs not being able to start the Chrome browser for interactive login, refer to the troubleshooting article dedicated to getting around those issues: Confluence Authentication Issues.

Personal Token

The Personal Token authentication type uses a special kind of password (“token” or “key”) to log in. This password is created in Confluence in the context of a Confluence user account.

Please refer to this article for configuration details: Personal Access Token.

Confluence Server and Data Center just need the token

Confluence Cloud needs the name as well

The Personal Token is also referred to as Personal Access Token, API Token, or API Key.

Confluence 7.9 started supporting this authentication type.

In Confluence Cloud some transformations may not avilable with this authentication type (Jira Issue List).

The harder cases…

What are hard cases with regard to Confluence authentication?

Here are some hallmarks of a hard case:

  • Interactive Login authentication does not work immediately
  • Personal Token authentication is not available because Confluence is older than version 7.9 or because of multi-factor or other requirements
  • the cookies.txt workaround to provide session cookies manually for Interactive Login does not work

Over time, I encountered the following hard cases:

  • Kerberos prevented WikiTraccs from taking over the session cookies from Interactive Login; only connections made from the Chrome browser were considered valid by the Confluence backend
  • WikiTraccs once could not detect a successful login to Confluence and was thus not able to get the session cookies for Interactive Login; cookies.txt also did not work; reason unknown
  • Confluence could only be connected to using TLS 1.3-secured connections; Windows and the Confluence backend could not negotiate a mutual TLS 1.3 cipher to use; this issue does not affect the Chrome browser as Chrome brings its own cryptographic stack that operates independently of Windows

Note that those cases were the exception and not the rule.

Nevertheless, those cases needed to be handled as some of them were introduced by configuration changes that were made while migrating and thus blockers. So, WikiTraccs got something called the proxy mode.

Proxy Mode

The proxy mode is a workaround for all of the above issues with the Interactive Login authentication type.

Normally, connection and authentication issues tend to be absent when a user logs in to Confluence in the browser, but start appearing once WikiTraccs starts talking to Confluence directly.

If those issues cannot be resolved, there is only one way left: go back to using the browser to connect to Confluence.

That’s what the proxy mode does. WikiTraccs will keep an automated Chrome browser window open and route all requests to Confluence right through that browser.

This comes with some drawbacks as well. Routing everything through the browser is slower. Also, the proxy mode is not perfectly polished, as it is only thought as a workaround. So WikiTraccs might get confused at times with regard to automating the Chrome browser window, which can be resolved by closing and reopening all windows.

But overall the proxy mode is like the silver bullet to authentication issues.

You activate the proxy mode in WikiTraccs Settings -> Misc -> Proxy Confluence API calls through browser:

Summary

When it comes to authenticating with Confluence those are the steps to take:

In WikiTraccs:

  1. Choose the Interactive Login authentication type and test connecting; if that doesn’t work immediately:
  2. Choose the Personal Token authentication type and test connecting; if that isn’t available:
  3. Use the cookies.txt workaround and test connecting using the Interactive Login;
    • if that does work: good; find the missing cookie names and enter them in the Advanced Settings dialog
    • if that doesn’t work:
  4. Use the Proxy Mode in combination with Interactive Login

If your environment blocks connections to certain endpoints, it might also be necessary to provide the Chrome Driver manually. WikiTracccs uses the Chrome Driver to automate the Chrome browser.

General considerations:

  • check if the migration account can be enabled for Personal Token authentication
  • make sure all endpoints can be reached by WikiTraccs, e.g. to download the Chrome driver needed to automate the Chrome browser for Interactive Login
  • make sure the Confluence backend and Windows can work together with regard to supported TLS versions and ciphers

Usually, none of the workarounds are necessary. But now and then they are needed. That’s why they are available.

And if nothing works - get in touch and we’ll have a look.

Confluence might misreport space contents

This post highlights a challenge some Confluence instances pose - they misreport the content of spaces.

There is one specific issue that customers have now and then: not all pages of a space are being migrated. Some pages will be missing in SharePoint.

Why is that?

While there can be multiple reasons, one is Confluence itself misreporting the contents of spaces.

Let’s look at the root issue and how WikiTraccs tries to work around it.

The root issue: Confluence lies about its space contents

If the Confluence issue is present, it affects the most convenient type of WikiTraccs’ source content selectors, the Space Selector.

When WikiTraccs starts migrating a space it asks Confluence about the contents of this space, like “give me all page IDs in this space”.

Confluence will happily answer and the list of page IDs it returns might look like this: 00001, 00002, 00003, 00004, 00005, 00006. This would be 6 pages to migrate. That’s what we expect.

But sometimes the result looks different, although all 6 pages are definitely there. Confluence might report the list of page IDs like this: 00001, 00002, 00002, 00002, 00005, 00006.

Notice the difference? Page ID 00002 is listed three times, while 00003 and 00004 are missing.

This is a problem. Why is Confluence lying to us? I don’t know.

WikiTraccs tries to work around this issue

The latest release of WikiTraccs contains a workaround for this Confluence issue.

WikiTraccs detects duplicate page IDs and will take that as a hint that page IDs will be missing as well. It will then use a different method to retrieve the page IDs for a space.

One caveat of this workaround is that it’s significantly slower than just getting the list of page IDs handed by Confluence. But at least it should retrieve a complete list.

How to verify that all pages have been migrated?

When Confluence is not lying to us, WikiTraccs’ progress log files are the way to go. The __30-aggregated-info file shows a summary of a space’s migration progress. This is the happy path.

If you have a hunch (or see it in the logs) that Confluence might be lying about the contents of a space, your only chance is to look at and compare with the Confluence database.

Here’s how to get a list of page IDs from the Confluence database, for a given space: Getting a list of pages per space.

Compare the list of page IDs you got from the database with the list of pages WikiTraccs got handed by Confluence. The pages WikiTraccs knows about for a space can be seen in the __25-update-state-of-migrated-pages progress log file.

Hints about duplicates in the WikiTraccs log file

The WikiTraccs common log files contain information about duplicate page detection and applied workarounds.

You want to find this message for each space that has been selected for migration:

No duplicate IDs found for selector (Type=ConfluenceSpaceKey; Query=GOOD)

Above log message says that all is fine for space with key GOOD, as there were no duplicate page IDs. Also, WikiTracccs takes this as a hint that there won’t be page IDs missing (note: this is an assumption that is yet to be proven wrong).

To the contrary, the following log message indicates that duplicates where found for space with key DUPE:

Duplicate content IDs found for selector (Type=ConfluenceSpaceKey; Query=DUPE)

Searching for the text [DUPLICATES] in the WikiTraccs log files will surface further details about the affected spaces, like which pages are affected and which pages could only be retrieved via the built-in workaround.

Working around the issue with the Content ID Selector

The issue only affects Space Selectors as for those WikiTraccs will ask Confluence about space’s contents. Consequently Confluence might choose to lie to us.

To prevent this kind of issue, you might choose Content ID Selectors instead to tell WikiTraccs the page IDs it should migrate. With this type of selector you take the “page ID retrieval” part in your own hands. Have a look at the documentation about the details.

In general, Space Selectors are easier to handle than Content ID Selectors. So in an ideal world, there would be no need to choose one over the other to work around Confluence issues.

How to fix this Confluence issue?

I don’t know. Let me know if you find a solution.

Can feature 'XYZ' be added to WikiTraccs?

This post outlines how I add new features to WikiTraccs and how we can help each other.

It depends.

Adding XYZ to WikiTraccs vs. project-specific solutions

The development of WikiTraccs is mostly driven by customer demand. That, and changes by Microsoft and Atlassian to their services.

Every environment and migration project is different, but there are similar challenges. If customers (or I) face the same challenge over and over again, it’s usually time to think about extending WikiTraccs to support the underlying use cases.

New WikiTraccs feature?

I’m open to extending WikiTraccs if the new feature helps with an often-faced challenge that is not isolated to a specific migration project.

New WikiTraccs features must:

  1. ✅ work in a standard SharePoint Online environment, without having to install third-party apps
  2. ✅ solve a challenge for multiple clients
  3. ✅ have a technical solution
  4. ✅ take reasonable time to implement

If some of those boxes cannot be checked then the solution is usually project-specific, although we should definitely talk this through.

Project-specific solution?

Project-specific solutions solve challenges for a specific migration project or a specific environment.

Modifying the page header to comply with CI/CD? Turn off the comments section on pages? Add page metadata for HR? Those are unique requirements within a project.

Project-specific solutions usually involve a combination of configuration (search configuration, content types, managed metadata), low-code solutions (Power Automate workflows), and scripting (PowerShell, JavaScript).

Missing feature XYZ is a blocker for me - can you add it to WikiTraccs?

I’d like to learn more. Does the feature check all of above boxes? That’s a good start.

The less time it takes to implement a feature, the more likely it is that I’ll add it for you. The more time it takes, the more useful it has to be in a broader sense.

I consider anything below ~2 days of end-to-end development effort as relatively low effort. Adding transformations for yet-unknown but simple-to-handle macros fall into that category. Or adjustments to text placeholders.

Note that I cannot give a guarantee that or when a feature will be added.

That being said - I’m always open for feature proposals as this is the way for me to learn about real-world challenges.

If we haven’t been already in touch via a demo or email or GitHub, please get in touch!

Help me help you

When looking at your challenge, I need to understand it first. Please help me with that.

Screenshots help illustrate your case

Screenshots are a good way to start diagnosing migration results.

Something looks unexpected after migrating pages to SharePoint? Take a screenshot of the source Confluence page and a screenshot of the migrated page in SharePoint. Highlight your expectations in the screenshots and write some lines about what you expect.

Create the expected outcome manually in SharePoint

Help me see the SharePoint page as you envision it to look after the migration.

Create a new modern SharePoint page and edit it. Manually add all the necessary elements to make it resemble the source Confluence page as closely as possible. Use only out-of-the-box SharePoint web parts - no PnP, no third-party tools (I nevertheless like to hear about those as well! Maybe it’s the exception to the rule).

Send me a screenshot of both the source Confluence page and target SharePoint page.

This ensures that it is technically possible to achieve what you’d like to see on the SharePoint side and serves as a mockup for me to understand your requirements.

Furthermore, It would help a great deal if you could send me the SharePoint storage format of the page. Here’s how to get that: Get the SharePoint Storage Format

Send me the Confluence page’s storage format XML

There is a Confluence page that contains something that you’d like to see migrated differently? Like a macro that ends up being a placeholder in SharePoint?

Send me a screenshot of the Confluence page.

I also need to see the page how WikiTraccs sees it to estimate how much effort it takes to support new transformations.

Send me the storage format XML. Here’s how to get that: Get the Confluence Storage Format.

The storage format XML contains a page’s text content, structure, formatting, and most importantly information about all macros, including their parameters.

Closing note

Please review the existing feature proposals in the GitHub issue list and vote for those you’d like to see gain traction. Alternatively, you can create a new feature proposal or start a discussion.

Converting Gliffy and draw.io to SVG

This blog post shows how to convert popular diagramming solutions to SVG.

Motivation

The motivation behind this blog post is a customer request:

When migrating from Confluence to SharePoint, how to migrate Gliffy diagrams as SVG files?

Unfortunately, WikiTraccs cannot do much in this regard. WikiTraccs migrates Confluence page attachments, which include the diagram file (from Gliffy or draw.io) and the diagram’s preview image. Read the previous blog post for details on that.

At least you end up having the diagram file in SharePoint Online.

Having the diagram file in SharePoint is a good thing, because it gives us the option to work with those diagrams even when Confluence is not around anymore.

How to export diagrams as SVG files

Let’s look at our options to export diagrams as SVG.

Gliffy => SVG

When Confluence is still around, you can export from Confluence:

  1. Open Confluence page
  2. Edit Gliffy diagram
  3. File… > Export > SVG

After having migrated to SharePoint Online, you need to work with the diagram file instead:

  1. Open a migrated SharePoint page
  2. Download the migrated Gliffy diagram file from the page’s attachments
  3. Open app.diagrams.net (a free online diagram software) in browser
  1. Drag the diagram file into the browser
  2. File > Export as > SVG…

draw.io => SVG

When Confluence is still around, you can export from Confluence:

  1. Open Confluence page
  2. Edit draw.io diagram
  3. File > Export as > SVG…

After having migrated to SharePoint Online, you need to work with the diagram file instead:

  1. Open migrated SharePoint page
  2. Download migrated draw.io diagram file from the page’s attachments
  3. Open app.diagrams.net?offline=1 in browser (a free online diagram software), in offline mode
  4. Drag the diagram file into the browser
  5. File > Export as > SVG…

Note that this doesn’t seem to upload the diagram file as it already has the draw.io format.

Privacy Considerations

When Confluence is not around anymore and you end up using app.diagrams.net (note: which is the only free tool I know of that can convert Gliffy to draw.io), there is one fundamental difference between Gliffy and draw.io files.

The app.diagrams.net online editor needs to convert Gliffy diagrams to draw.io diagrams first. This is done at a remote location. This means your diagram files will be uploaded to a third party.

This is contrary to draw.io diagram files. When loading those into the app.diagrams.net online editor, no upload seems to happen.

draw.io Desktop (free)

There is an alternative to app.diagrams.net and that is the draw.io Desktop application. You can download it at drawio.com.

draw.io Desktop seems to have the same capabilities as app.diagram.net. There is one important exception: the desktop version cannot convert Gliffy files to the draw.io format. Which is unfortunate when you only have Gliffy files that you want to convert to SVG.

There is no free offline tool available that I know of that can convert from Gliffy to draw.io.

Gliffy-to-draw.io Mass Conversion (paid-for)

There is a paid option available to convert Gliffy to draw.io when Confluence is still around.

The draw.io Confluence plugin can convert Gliffy to draw.io.

According to its documentation, it can do mass conversions of all Gliffy diagrams in a Confluence instance:

Also according to the documentation, it doesn’t require a license to do the actual conversion. But it will convert all Gliffy macros to draw.io macros as well, so having no license doesn’t seem to make sense.

Mass-converting Gliffy to draw.io before migrating to SharePoint seems like an option to have those draw.io files ready in SharePoint, in case users want to work with those diagrams using either app.diagrams.net or the draw.io Desktop app.

Migrating Gliffy and draw.io macros to SharePoint Online

WikiTraccs migrates Gliffy and Draw.io macros. This article has insights.

We first look at how Gliffy and draw.io work in Confluence, then we look at a migration result.

How are the diagrams stored in Confluence?

This is a sample Confluence page (in edit mode) containing both the Gliffy and draw.io macro:

Both macros create two page attachments when you create a diagram.

One attachment file is the diagram file, containing the digram definition in a macro-specific format. The other attachment is the preview image that is shown on the page.

Here’s how the page attachmens for above sample page look. It’s two attachments per macro:

How do Gliffy and draw.io look in SharePoint Online?

First of all, WikiTraccs migrates the page content and page attachments as usual. So, both the diagram file and the preview image will be available in SharePoint as well.

When migrating page contents, WikiTraccs looks out for Gliffy and draw.io, and replaces those macros with a SharePoint image web part. The image web part is configured to show the respective macro preview image:

Looking at the SharePoint page’s attachments we can see the same files as in Confluence:

This is the result you can expect after migrating Confluence pages with Gliffy or draw.io macros to SharePoint Online using Wikitraccs.

Transforming even more colors from Confluence to SharePoint!

This post describes the latest additions and changes with regard to text colors, highlight colors, and table cell colors.

The latest release of WikiTraccs contains multiple improvements with regard to colors.

Text colors, the newly introduced text highlight colors (Confluence Cloud) and table cell colors got some attention.

What has SharePoint Online to offer in terms of colors?

The SharePoint Online color palette for text looks like this:

Note that we cannot really use the theme colors as they change, depending on the theme. That leaves us with 11 text colors.

The SharePoint Online color palette for highlights looks like this:

That’s a whopping 15 colors.

What about table cell colors? SharePoint does not have those. We’ll see how WikiTraccs handles that further down.

Text Color Transformation

Those are the 21 text colors available (at least at the moment) in Confluence Cloud:

Text Colors in Confluence Cloud

WikiTraccs maps those colors to the visually nearest available text color in SharePoint Online:

Text Colors in SharePoint Online

Here’s another example from Confluence Server, which has 40 colors to offer:

Text Colors in Confluence Server 6

This is how it’s transformed to SharePoint:

Text Colors in SharePoint Online

Highlight Color Transformation (new)

Now for the new highlight colors in Confluence Cloud:

Highlights in Confluence Cloud

Those map pretty well to SharePoint Online in terms of available colors:

Highlights in SharePoint Online

SharePoint’s highlight colors are way darker than in Confluence which makes black text hard to read for the teal and purple highlights.

Table Cell Color Transformation

Here’s how table cell colors look in Confluence Cloud:

Table cell colors in Confluence Cloud

SharePoint does not support setting colors for table cells. Maybe that’s coming in the future, but so far I did not spot anything related on the roadmap. (Let me know if you see or hear something!)

WikiTraccs is using a workaround to at least indicate in SharePoint, that the table cell was colored in Confluence.

"Table cell colors" in SharePoint Online

Here’s another sample from Confluence Server 6, which has less cell colors to offer:

Table cell colors in Confluence Server 6

This is how it’s transformed to SharePoint:

Table cell colors in Confluence Server 6

In both instances, WikiTraccs adds a block of colored spaces to each formerly colored table cell, serving as a “color marker”. And again, it is restricted to colors that SharePoint has to offer.

What did change in the latest WikiTraccs release?

The latest release handles text highlight colors that have been introduced by Atlassian in June 2024.

Furthermore, the color markers for table cells now support the full range of text colors available in SharePoint. Previously, WikiTraccs used colored emoji squares like 🟩 as marker - but those only come in very few colors.

And last but not least: the algorithm to calculate the visual distance between colors has been improved. This maps Confluence colors even more closely to their SharePoint equivalents.

How to run parallel WikiTraccs migrations?

You might want to run multiple WikiTraccs migrations in parallel, to speed up things. Let’s take a look on how to do this and what to look after.

You can run multiple WikiTraccs instances in parallel to speed up the overall migration. You’ll need a separate machine or VM per WikiTraccs instance as only one instance is allowed to run on the same machine.

Some definitions

The computer or virtual machine (VM) WikiTraccs is running on is the machine or migration machine.

We’ll call the running WikiTraccs program a WikiTraccs instance. When two WikiTraccs programs are running, that would be two instances.

The central SharePoint site that WikiTraccs needs and where the Space Inventory list (and more) is located is called WikiTraccs site.

One WikiTraccs instance is allowed to run on one machine.

How to run multiple WikiTraccs instances in parallel?

Looking at client’s projects I see different approaches.

Some create cloud-based virtual machines in Azure or AWS. Some use spare laptops.

Install WikiTraccs to each of those machines and your are good to go.

Configuring WikiTraccs when parallelizing the migration

There is local and shared configuration.

Configure locally on all machines

Make sure you configure the WikiTraccs settings on all machines. This affects things like comments migration, macro ignore list, migration mode etc. They can be different on different machines, but usually are the same.

Locally stored settings are:

  • everything you enter into the blue WikiTraccs.GUI window
  • settings available in the blue WikiTraccs.GUI window via the Settings menu
  • any settings configured via appsettings.json

Note that the Space Inventory that contains the source-to-target mapping is NOT a local setting, but stored in SharePoint, in the WikiTraccs site. But the link to the WikiTraccs site (that contains the Space Inventory) is part of the local settings.

Be aware of shared configuration via WikiTraccs site

One WikiTraccs site can be used by multiple WikiTraccs instances, or each instance can use their own WikiTraccs site.

With the same WikiTraccs site, multiple WikiTraccs instances share the same mappings.

There is one caveat of sharing one WikiTraccs site: they will also want to migrate all the same content.

We’ll look at two two scenarios now: one with shared WikiTraccs site, one without.

Parallelization Scenario - Shared WikiTraccs Site

Multiple WikiTraccs instances share the same WikiTraccs site.

Two WikiTraccs instances sharing a single WikiTraccs site.

To achieve that, simply configure the same WikiTracc site address for all WikiTraccs instances.

Pro:

  • you need to configure the mapping in the Space Inventory only once
  • you need to configure the user and group mapping only once
  • easy, as there is only one WikiTraccs site

Contra:

  • (note: before WikiTraccs v1.18) you need to change the WT_Setting_RequestTransformation value in the Space Inventory before starting each WikiTraccs instance as otherwise multiple instances migrate the same pages (!); one approach is to use PnP.PowerShell to manipulate the space inventory

Parallelization Scenario - Separate WikiTraccs Sites

Two WikiTraccs instances each using their own WikiTraccs site.

To achieve that, use a different WikiTracc site address for each WikiTraccs instance.

Pro:

  • the WT_Setting_RequestTransformation value in the Space Inventory can be configured per WikiTraccs instance, as each instance has its own Space Inventory
  • the snapshots that WikiTraccs takes of pages (in the Confluence Content Snapshots library), that are stored in the WikiTraccs site, are now scattered across multiple WikiTraccs sites, which can be an advantage permission-wise (when different teams do the migration that are not allowed to see each other’s content)

Contra:

  • the mapping in the Space Inventory needs to be configured in all WikiTraccs sites, for all spaces and CQL selectors (!)
  • the user and group mapping needs to be configured in all WikiTraccs sites

General parallelization notes

Multiple instances can migrate to the same target SharePoint site, as long as they don’t migrate the same content at the same time to the same target.

Parallel migration is covered by the WikiTraccs license, without limits.

You shouldn’t go too crazy with the parallel instances. There are limits in place set by Microsoft on how fast an application can access the Microsoft 365 services. Microsoft will throttle WikiTraccs, if it goes to fast. This means: WikiTraccs will have to wait some time (a couple of seconds, or even minutes) until it is again allowed to send content. Those limits are set by Microsoft, adjusted to overall cloud load, and dependent on the number of licenses in the tenant (among other factors).

Fixing image positioning in SharePoint

How to cope with the new way SharePoint handles images that are placed next to each other.

Summary of what happened images in SharePoint

Up until about mid-2023 SharePoint text web parts were able to display inline images next to each other. Then Microsoft started upgrading the editor component that powers the text web part, while at the same time introducing changes to the overall page style. This broke adjacent image positioning.

Specifially, when editing a SharePoint page, its text web parts are auto-upgraded to the new editor version which positions once-adjacent images now vertically, not horizontally:

So what are our options to fix this?

How to fix image positioning? And who?

The SharePoint text web part, at the time of this writing, does not support putting multiple images next to each other. Neither in the browser editor, nor via programmatic means.

Here’s a list of parties that could influence image positioning in text web parts, in principle:

  1. Microsoft - but they say the current behavior is by design, so they won’t help
  2. WikiTraccs
  3. You

Number one is out, let’s look at the other two options.

What can WikiTraccs do?

Short version:

At the moment, nothing.

Longer version:

When migrating Confluence pages to SharePoint, WikiTraccs creates pages that still show adjacent images. That’s because it’s generating pages in a version that still supports this. SharePoint supports displaying pages that use the (now) older version.

As soon as you edit such a page it is upgraded to a newer version that doesn’t support adjacent images anymore.

The only thing that WikiTraccs could do is starting to generate pages in such a way that images won’t be adjacent anymore, to begin with. You’d then see the non-adjacent version right away, without having to edit the page.

I’ll look into such options as soon as the new way to display pages is confirmed as generally available by Microsoft. I don’t have such a confirmation, yet.

That means that WikiTraccs cannot do anything at the moment.

What can you do?

You have two options:

  1. Re-arrange images and content when you edit a page.
  2. Roll back the layout change that Microsoft did to screw up image positioning.

Option 1 is straightforward: you edit a page, adjacent images are not next to each other anymore, you have to clean up.

Option 2 involves rolling back a single layout change that Microsoft introduces when upgrading the text web part.

The Wiki Transformation Project provides a tool to achieve option 2: the WikiTraccs Page Companion.

Introducing the WikiTraccs Page Companion

For option 2 to work, we need to change pages as they are displayed in the browser. It’s like duct taping a small piece of paper over a bad part of the page, using duct tape that can be removed without traces.

Fortunately Microsoft provides a supported means of integrating with SharePoint pages: SharePoint Framework (SPFx) Application Customizer. Using such a customizer, we can hook into each page as it is being displayed in the browser.

Regrettable, the change we need to make to how pages are being displayed is not officially supported by Microsoft. We need to accept that if we want to proceed with this duct tape option.

Here’s a demo video of the WikiTraccs Page Companion in action. About 11 seconds into the video, note the little box reading Legacy image positioning (by WikiTraccs) in the lower right corner, that’s the extension:

(Note, because I get asked: the page tree you see in the video is WikiPakk, the SharePoint page tree experience.)

The toggle button can be used to toggle the image positioning fix on and off on a per-page basis. On means, the duct tape is applied. Off means, the duct tape is being removed, again. It is opt-in, so not enabled by default.

As an author, you would check the page you are editing, and toggle the button as needed. The fix affects the page both when being edited and being viewed.

The WikiTraccs Page Companion is available as pre-compiled download (to be deployed to a SharePoint app catalog), and also as source code for you to build yourself. It’s all on GitHub: WikiTraccs Page Companion.

Note that the non-standard nature of this option means that it might stop working when Microsoft makes changes to pages. If that happens, the adjustments that need to be done need to be re-evaluated.

I’m putting the source code out there, so that you are in control as well.

Get in touch if you have any questions.

Broken inline image positioning in SharePoint

A recent update to the text editor web part seems to break positioning for adjacent images.

In general, SharePoint is behind Confluence when it comes to positioning images in relation to each other and to surrounding content.

But at least putting images next to each other is possible. Is? Was. s Those two blog posts took a deep dive into the topic of images:

Unfortunately a recent update to the SharePoint text editor web part breaks adjacent images. They aren’t adjacent anymore when editing a page.

Microsoft is upgrading the editor version of SharePoint pages - and the trouble starts

The text editor web part is powered by the CKEditor editor component. It can be licensed by any third party to build rich editor experiences in the browser. Microsoft did that.

The following things define how the text editor web part behaves:

  1. the features that CKEditor provides - like formatting highlighted text, adding tables and so on
  2. add-ons to the editor that Microsoft develops
  3. internal settings set by Microsoft defining which features are available to users
  4. surrounding styles (CSS) that define how things look (e.g. font size)
  5. page contents

The most recent version of CKEditor is version 5 (v5). So far SharePoint used version 4 (v4) of CKEditor.

Microsoft now upgrades pages to use CKEditor v5.

Why is this important for content creators? Because the content of SharePoint pages is somewhat coupled to the editor version of the text editor web part. Microsoft cannot just upgrade from CKEditor v4 to v5 without breaking old pages. Therefore Microsoft auto-upgrade pages when they are being edited. And that modifies the page content.

When you start editing a page and its content briefly disappears and then comes back - this might have been an auto-upgrade.

And somewhere along the way of this auto-upgrade the handling of inline images changed.

How does the page upgrade affect adjacent inline images?

Here are three visuals showing how pages used to behave, and how they behave now.

How it used to be…

This is a page with three adjacent images in view mode, using CKEditor v4:

This is the same page in edit mode, using CKEditor v4:

How it’s now…

And here is a video that shows what happens when the auto-upgrade to v5 for this page kicks in:

Note: I used the browser’s developer tools to slow down the internet connection, which allows us to watch everything in slow motion.

What can be seen in above video:

  1. the page enters edit mode and the three inline images can be seen next to each other for a brief moment
  2. then all web part content vanishes; the auto-upgrade happens where SharePoint converts the content from CKEditor v4 to CKEditor v5
  3. the web part content reappears; the images are placed on top of each other (NOT GOOD)
  4. bonus: all images are gone! (this was a first when recording this video) (NOT GOOD)

Editing this page worked perfectly fine for at least the last 12 months. Images stayed in place, no problems.

Now broken.

What does this mean for pages that WikiTraccs migrated from Confluence to SharePoint?

Pages migrated by WikiTraccs use CKEditor v4. Adjacent images look fine when viewing those pages.

When editing a page with adjacent images SharePoint might decide to skip upgrading this page to v5. The page will look fine in view and edit mode.

When editing a page with adjacent images SharePoint might decide to upgrade this page to v5. Adjacent images won’t be adjacent anymore in edit mode and need to be re-arranged manually. This looks like a newly introduced technical limitation of SharePoint. Note that currently there is no way to put images next to each other via the browser editor.

Note: the same applies to pages transformed by other tools, e.g. when transforming classic SharePoint pages to modern SharePoint pages using the PnP Modernization Tooling.

Resources

I’m keeping track of topics related to page upgrades here.

Adjacent image positioning issues

Issues with adjacent image positioning are reported by the first WikiTraccs client in mid-September.

I created a Microsoft Tech Community post to get input: Modern pages with text web parts upgraded from CKEditor v4 to v5 lose image positioning.

I also created a minimal PowerShell script that can be used to create a SharePoint page with adjacent images to test the page upgrade: GitHub repository. To showcase and pinpoint the issue.

Furthermore I opened a case with Microsoft support, which is closed now. The case ID is 2310071420000151. According to them this is expected behavior.

Other known issues

There were issues with tables when upgrading pages from CKEditor v4 to v5:

There are issues with the new spacing between paragraphs:

Wrapping up

It’s not clear what exactly breaks image positioning on modern pages after upgrading the editor from v4 to v5.

It might be the content upgrade for those pages. But it might also be the changed surrounding styles that come with the upgrade.

I really hope that there will be a proper solution to putting images next to each other on a MODERN SharePoint page. Nothing more. Just some images. Next to each other.

How to migrate rich Confluence tables to limited SharePoint tables?

This blog post covers table migrations and how SharePoint differs from Confluence in this regard.

What are different table capabilities of Confluence and SharePoint?

The following table formatting options are available in Confluence:

  • setting the background color for table cells
  • having multiple header rows or columns
  • nesting tables
  • merging table cells

All of the above is not possible in SharePoint at the time of this writing.

Let’s see how WikiTraccs works around that.

How does WikiTraccs adjust for table formatting limitations in SharePoint?

WikiTraccs has to get creative when it comes to mimicking the full range of Confluence table formatting options.

Table cell background color is transformed to colored emojis. The color is moved from the cell background to the cell content, as there are no colored table cells in SharePoint.

Confluence table with colored cells

Table after migrating to SharePoint, with color markers

Only a limited set of rectangular colored emojis is available to do this, so the color often will be off.

Multiple header rows or columns are represented as normal table rows and columns in SharePoint where the text content is formatted bold.

Confluence table with multiple header rows and columns

Table after migrating to SharePoint, with bold text simulating the headers

Nested tables are de-nested. This approach is analoguous to how the the Microsoft SharePoint Migrations tool does it for SharePoint on-prem to SharePoint Online migrations.

Merged table cells cannot be created in SharePoint Online. But WikiTraccs marks those cells that once were merged (as of WikiTraccsrelease v1.3.11).

Here is an example of how it looks after migrating a table with merged cells from Confluence to SharePoint:

Confluence table with merged table cells

Table after migrating to SharePoint, without marking former merged cells (note: default behavior before WikiTraccs v1.3.11)

Table after migrating to SharePoint, with marking former merged cells (note: default behavior as of WikiTraccs v1.3.11)

The little arrow in former merged cells points in the direction of the cell it had been merged with before having been migrated.

Marking former merged table cells is standard as of WikiTraccs v1.3.11.

Wrap-up

WikiTraccs needs to get creative when it comes to transforming Confluence tables to SharePoint tables. The results depend on the complexity of the tables that are migrated from Confluence to SharePoint and a manual content review does not hurt.

Let’s hope that SharePoint keeps maturing to a point where formatting tables is on a par with what’s possible in Confluence.

Migrating large Confluence spaces to SharePoint

This post is about migrating spaces with 10000+ pages which can be challenging due to long page retrieval times.

How does WikiTraccs determine which pages to migrate for a space?

When WikiTraccs starts to migrate a space to SharePoint it retrieves the full list of pages for this space.

Say a space contains 20000 pages. WikiTraccs retrieves basic information about those 20000 pages and adds them to a migration queue. (Later, when migrating each page, WikiTraccs retrieves the contents of this page and creates the corresponding SharePoint page.)

Confluence doesn’t allow retrieving information of more than 200 pages at once. So to retrieve information about 20000 pages WikiTraccs needs to request 100 batches of 200 pages, as that is supported.

This paged retrieval is where things get interesting for larger spaces.

Why can large Confluence spaces pose a challenge?

The more pages a space contains the longer it takes to retrieve a batch of pages.

Here are numbers from a Confluence 6 test migration of a space with about 23000 pages:

  • retrieving batch 1 takes < 1 second
  • retrieving batch 10 takes about 2 seconds
  • retrieving batch 25 takes about 4 seconds
  • retrieving batch 50 takes about 6 seconds
  • retrieving batch 75 takes about 10 seconds
  • retrieving batch 100 takes about 14 seconds

Assuming retrieving each batch of 200 pages takes a mean of 8 seconds, retrieving 20000 space pages would take 100*8=800 seconds, which is about 14 minutes.

Exporting this space (with empty dummy pages) via the Confluence space export function takes about 16 minutes:

Successful page migrations

Unfortunately there is not much that can be done about the time it takes to retrieve the list of pages. With release v1.6.8 WikiTraccs started to migrate pages while still retrieving the list of pages for a space. This at least allows the waiting times to be used to migrate the first pages.

Confluence 7.18 introduced an API that allows for faster page retrieval, but so far there was no demand I am aware of as migrated environments were older. If you are migrating a Confluence version 7.18 or newer then please comment here to make this demand visible: User faster page retrieval API (Confluence 7.18 and up).

Conclusion

Large Confluence spaces (more than 10000 pages) can add significantly to the migration time.

When WikiTraccs starts migrating a space it retrieves a list of all space pages, which can take several minutes for those large spaces. The list of pages is retrieved multiple times, for example after migrating the space to check if all pages were migrated.

Those times can add up.

So it’s good to know the spaces with large page numbers beforehand, or to learn about them during a test migration.

Ignoring macros when migrating pages from Confluence to SharePoint

This post describes the new macro ignore list feature of WikiTraccs.

Why do I need a macro ignore list?

Certain Confluence macros are only visible when editing a wiki page. Often WikiTraccs can see those macros and migrates them to the SharePoint page - where they will be visible for visitors as well.

One sample is the Excerpt macro with the hidden option set.

WikiTraccs offers a macro ignore list that can be used to exclude such macros from the migration.

How to use the macro ignore list?

This series of screenshots shows how to identify macros to ignore and how to configure the ignore list.

Here’s a Confluence page with one visible macro, as shown for readers:

The Confluence page in edit mode reveals the second hidden Excerpt macro:

Without a configured Macro Ignore List WikiTraccs will migrate the hidden macro to SharePoint, making it visible. Here’s a screenshot of such SharePoint page:

To solve this, open the Confluence page, choose View Storage Format for the page and copy the offending macro XML:

In WikiTraccs.GUI, in the menu bar, choose Settings > Configure Transformation. Paste the macro XML to the Macro Ignore List:

In the Macro Ignore List, remove every macro parameter except hidden:

Delete previously migrated pages as needed after changing the Macro Ignore List, and start the migration.

The macro is now removed by WikiTraccs. Here’s the migrated page again as it looks in SharePoint:

Any macro can be added to the Macro Ignore List. Macros matching the Macro Ignore List will be removed from all pages in the Confluence to SharePoint migration.

During migration, WikiTraccs looks at the macro name and its parameters. If it sees a macro that has the same name, and all of the parameters and parameter values as a macro in the Macro Ignore List it will skip this macro and won’t add it to the SharePoint page.

How to monitor if the filter works as expected?

WikiTraccs logs removed macros while migrating pages from Confluence to SharePoint.

Search for the phrase Removed macro via config by matching template in the WikiTraccs log file to see which macros were removed and which template from the Macro Ignore List did match.

In addition, the Site Pages column WT: Transformation Log contains this information as well.

Wrap-up

The Macro Ignore List allows to specify which macros should be skipped in any Confluence to SharePoint page transformation.

It is one feature that was born directly from customer feedback. And it’s another step in the direction of a more configurable transformation process.

Get your migration started today!

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.

Registering WikiTraccs as app in Azure AD

Azure AD is now Entra ID - please refer to the updated documentation: Registering WikiTraccs as app in Entra ID.

Registering WikiTraccs as app in Entra ID

This post shows how to get that Client ID needed by WikiTraccs.GUI.

I recently got the following inquiry about WikiTraccs:

Please explain again briefly what the Tenant ID and Azure Client IDs are and how to acquire them.

This request is not the first of its kind and totally understandable. It refers to the following configuration in WikiTraccs.GUI:

Unless you are a Microsoft 365 developer or admin you normally never have to care about those IDs.

Why do I have to enter Tenant ID and Client ID in WikiTraccs? Where do those come from?

When WikiTraccs creates your migrated pages in SharePoint it needs to access APIs provided by Microsoft. Those are the SharePoint API and the Microsoft Graph API.

Accessing SharePoint in any form requires authentication. Open <company>.sharepoint.com (replace ‘<company>’ with the actual value of your SharePoint) in a private browser tab and it will ask for your credentials like email address and password.

Authentication is also required when WikiTraccs starts the migration. It will open a browser window for you to sign in.

Besides users, applications like WikiTraccs have to authenticate as well to access SharePoint.

To allow an application to authenticate, it has to be registered in Entra ID (formerly known as Azure Active Directory, or Azure AD). This is a manual configuration that needs to be done once.

A registered application has an ID - the Client ID. And the Entra ID tenant it is created in also has an ID - the Tenant ID. Those are the IDs needed by WikiTraccs.GUI.

How to register WikiTraccs as Application in Entra ID?

In a browser, navigate to https://entra.microsoft.com.

Sign in with an account that has the Application Developer role in Entra ID.

The Microsoft Entra admin center (former Azure Active Directory portal) opens.

In the left menu, under Applications, select App registrations, then New registration:

The Register an application blade opens:

Configure the following:

  • under Name enter WikiTraccs Migration Tool (note: or any other name of your choosing)
  • under Supported account types select Accounts in this organizational directory only
  • under Redirect URI (optional) choose Public client/native (mobile & desktop) and type http://localhost in the edit field

Select Register to confirm the app registration.

The application’s settings are now open:

In the left menu, under Manage, choose API permissions.

Choose Add a permission to add the following permissions:

  • Microsoft Graph > Sites.FullControl.All (delegated)
  • SharePoint > AllSites.FullControl (delegated)

Make sure to select the Delegated permissions (not application permissions). Here’s a sample screenshot:

The configured permissions need to be consented by the tenant admin.

As a tenant admin, choose Grant admin consent for… and confirm:

In the left menu choose Overview and make note of both the Tenant ID (aka Directory ID) and Client ID (aka Application ID):

Those IDs need to be entered in WikiTraccs.GUI as Tenant ID and Azure AD Application Client ID.

What did I just configure? Can WikiTraccs now access all content in SharePoint?

NO, WikiTraccs can NOT access all content in SharePoint.

Let me explain.

When starting a migration with WikiTraccs you have to log in with a Microsoft 365 account.

Now the permissions WikiTraccs gets are the intersection of two things:

  • the delegated permissions you configured above (that is Sites.FullControl.All, AllSites.FullControl) AND
  • the permissions of the account you logged in with

This is the magic behind delegated permissions. WikiTraccs can only access as much of SharePoint as the logged-in account.

If you log in with an account that is owner in all sites - sure, WikiTraccs could now access those sites.

But if you log in with a dedicated migration account that has only access to some sites - WikiTraccs can now only access those, nothing more.

Are there alternatives to those permissions?

I hear from customers who have trouble to get the tenant admin to consent permissions.

Use less permissions, get less things migrated

If you can’t get admin consent you can try using the following permissions instead:

  • Microsoft Graph > Sites.Manage.All (delegated)
  • SharePoint > AllSites.Manage (delegated)

Those allow a content migration as well.

But the functionality of WikiTraccs will be limited somewhat:

  • page permissions cannot be configured, as WikiTraccs won’t be allowed to do so
  • out-of-the-box SharePoint page and file metadata Created By, Created (Date), Modified By, Modified (Date) cannot be set, as this requires the same permissions as configuring permissions

Use an existing application

If you have access to another Entra ID application that has the required permissions configured you can use the Client ID of this existing app.

That’s why there is the Use M365 PnP Client ID button in WikiTraccs.GUI. It enters the well-known ID of the application used by PnP.PowerShell. This only works, if you have access to and the needed permissions are configured for the application (this is not always the case!). Note: The multitenant PnP.PowerShell enterprise application has been retired by Microsoft.

Troubleshooting

Check the platform

There is one common oversight when configuring the Entra ID application: selecting the right platform.

You might see the following error when testing the connection to SharePoint or starting the migration if the platform is not correct:

“A configuration issue is preventing authentication - check the error message from the server for details. You can modify the configuration in the application registration portal. See https://aka.ms/msal-net-invalid-client for details. Original exception: AADSTS7000218: The request body must contain the following parameter: ‘client_assertion’ or ‘client_secret’.”

This error happens when the platform of the Entra ID application has been set to Web instead of Public client/native (mobile & desktop).

Change the platform to Public client/native (mobile & desktop), which then shows up as Mobile and desktop applications here:

The error should now be gone.

Check the redirect address after authenticating

After logging in to Microsoft 365 via the browser, a redirect to http://localhost happens in the browser address bar.

This has to look like this:

Normally WikiTraccs takes over from this point. Get in touch if there are issues.

Test connecting with PnP.PowerShell

You can use PnP.PowerShell to check if an authentication issue is related to your Entra ID application configuration, or related to WikiTraccs doing something wrong.

Start PowerShell 7 and install the PnP.PowerShell module.

Configure and run the following script:

# make sure to use PowerShell 7 and install the PnP.PowerShell module; use the following command for that
# Install-Module PnP.PowerShell -Scope CurrentUser

# enter your SharePoint site to connect to here (the same as in WikiTraccs, either WikiTraccs site or default target site):
$siteUrl = "https://contoso.sharepoint.com/sites/somesite"
# enter your Entra ID application client id (application id) here (the same as in WikiTraccs):
$clientId = "017d043a-df74-4ab0-a411-430104faeaa4"

# authenticate with app, as user, and open login dialog in new browser window
Connect-PnPOnline -Url $siteUrl -ClientId $clientId -Interactive -LaunchBrowser:$true
# this should print the title of the site we connected to, if the connection was successful
Get-PnPWeb

This PowerShell script should open the Microsoft 365 login experience in the browser, just like WikiTraccs does. After logging in, it should print the title of the site you connected to. Otherwise, there will be an error that might help diagnose the app configuration issue.

Wrap-up

WikiTraccs needs an Entra ID application registration to access SharePoint. This is true for all applications integrating with Microsoft 365 services.

A common challenge is getting the right people to consent the configuration. The purpose of the app needs to be communicated clearly.

Technically, registering the app registration is quickly done following the steps in this post.

Try WikiTraccs!

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.

The art of positioning images - part 2 of 2

How are images handled when migrating pages? In this blog post we look at actual migration results.

This blog post is the second of a two-parter about images in the context of a Confluence to SharePoint migration:

In the last post we looked at image positioning options in Confluence and SharePoint. How can images be formatted in Confluence? How in SharePoint?

Now we look at actual migration results.

The easy ones: images in their own paragraph

An image in a separate paragraph:

ConfluenceSharePoint

Apart from SharePoint taking more space in general the layout looks comparable.

Now a centered, floating image:

ConfluenceSharePoint

SharePoint can do that, good.

Off to something SharePoint cannot do well.

The problematic ones: images as “characters” in the text flow

Here is something that SharePoint cannot do: putting an image at the end of a line:

ConfluenceSharePoint

How about putting text to the right of an image:

ConfluenceSharePoint

This looks better, although WikiTraccs has to cheat here to make it look like this. This image is converted to a floating one, with the text flowing to the right. More on floating images in the next section.

By the way, putting images next to each other for Confluence is like putting characters next to each other. WikiTraccs lets those images float as well, which can look pretty decent in SharePoint:

ConfluenceSharePoint

And something that is just not possible in SharePoint: putting an image right inside the text, like a “giant character”:

ConfluenceSharePoint

Now we have a look at floating images.

The compatible ones: floating images

Text can flow around floating images on the left or on the right side.

Here is a left-floated image, with text flowing around it on the right side:

ConfluenceSharePoint

And here is a right-floated image, with text flowing around it on the left side:

ConfluenceSharePoint

A special case…

A common pattern that I could observe on Confluence pages is to put some explanatory text next to an image like so:

ConfluenceSharePoint

There is a trick WikiTracks needs to play to make this work at all.

WikiTraccs did insert a one-pixel “floatbreaker” image to wrap the text at the right spot, after the sentence “One lone sentence next to the image”.

Here you see the SharePoint page in edit mode, on the left with floatbreaker (selected in the editor), on the right after deleting it.

SharePoint with “floatbreaker”SharePoint without “floatbreaker”

The floatbreaker is another tiny, invisible image in the SharePoint page with positioning set to center. That breaks the text flow where it’s needed. And it’s the only way I found to stop the other text from flowing around as well.

Kind of hacky, but it works and it survives entering the page edit mode. Of course page authors are free to remove the dummy image and change the formatting.

Wrap-up

Migrating images from Confluence to SharePoint is no easy task for WikiTraccs. Confluence provides more formatting options than SharePoint.

And don’t mention Confluence pages that were created by importing from Word files! Somebody will start crying.

But WikiTraccs will make sense of the most common cases it finds. This should make those image-laden instruction pages readable in SharePoint as well.

Try WikiTraccs!

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.

The art of positioning images - part 1 of 2

How are images handled when migrating pages? In this blog post we look at what is possible in Confluence and SharePoint.

This blog post is the first of a two-parter about images in the context of a Confluence to SharePoint migration:

Off we go.

Why is image positioning important?

Hey ChatGPT, why is image positioning important in a Confluence wiki page?

Sounds about right.

Let’s look at what Confluence has up its sleeve for images.

How can images be positioned in Confluence?

Images as a “giant characters”

You can upload images and add them anywhere on a wiki page.

When inserting an image into text it behaves like one big character:

The image cut the word in half and sits there as if it were text, while taking its space.

Spoiler alert: SharePoint cannot do this. This will become relevant when looking at how WikiTraccs migrates such images to SharePoint.

Here is another sample, looking at it from different angles.

First there is the image, without text around it.

Then a line break on the right edge is removed, hoisting text up next to the image.

Then the image itself is hoisted up, now having text on its left edge.

And then the image is again put right into the text, and when making it smaller it starts to fit in.

This mode of positioning images works especially well for putting multiple images next to each other:

Now let’s look at another image positioning option.

Floating Images

There is a different way of positioning Confluence images known as floating.

Text can flow or wrap around such images.

Here is a sample on how to do this in Confluence Server 8:

And that’s it. Now we look at SharePoint.

How can images be positioned in SharePoint Online?

SharePoint does only support the second way of positioning images - floating them.

Here’s a demo of how inserting an image into text works in SharePoint:

The text is split into two parts above and below the image, the image is centered.

Selecting the image shows buttons that control image positioning:

This behavior looks like in Confluence.

Content is either wrapping on the left or right of the image, or the image is centered with text above and below it.

Now I tried to put two images next to each other.

I tried copy and paste. I tried to insert multiple at once. I tried moving them around.

Here’s me failing to position two images next to each other:

And that sums up the state of inline images in SharePoint pretty well. I was not able to put images next to each other.

Luckily WikiTraccs can control the content on a finer level than me with the mouse, while still creating content that adheres to SharePoint standard. More on that in the next post.

Try WikiTraccs!

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.

Confluence Page Tree in SharePoint

This post demos hierarchical page navigation in SharePoint.

How to create a dynamic page tree in SharePoint?

That is a question I hear time and time again.

Pages in SharePoint have no hierarchy (in contrast to Confluence). All modern pages are basically stored at the same level in the Site Pages Library.

Ever since starting working with SharePoint over 10 years ago I helped customers build trees of different sorts:

  • Search-driven page trees
  • Static page trees (deeper that the standard allows)
  • Taxonomy-driven page trees
  • Metadata-driven page trees

There is still no ready-made solution we can take and use to make navigating migrated pages easier. At least none that is free. (If you know one get in touch and I’ll update the post!)

Let’s effin build a page tree!

You’ll probably need a page tree in SharePoint if you are using WikiTraccs to migrate pages from Confluence. Users might be lost without it, depending on the number of pages.

Here is a demo of how such a page tree can look in SharePoint:

What are we seeing here?

The animation starts with a view of the Site Pages library. WikiTraccs was used to migrate the shown pages from Confluence to SharePoint.

Then a page is clicked, opening this page.

Above the page you can see a new bread crumb navigation and a page tree icon.

Clicking the page tree icon opens a panel on the right side that shows a dynamic page tree. The current page is highlighted. Any other page can be opened by selecting it in the tree.

Note: the page trees that are shown as part of the page content are static views of the Confluence page tree macro. This could be the next step: replacing those static placeholders with dynamic web parts. But that is something for the future.

How was it done?

The bread crumb and page tree above are metadata-driven.

When migrating pages to SharePoint WikiTraccs takes care of migrating page tree metadata as well:

  • Page ID
  • Parent page ID
  • Page order

Every migrated page carries this information in the Site Pages library.

The bread crumb and page tree are part of a SharePoint Framework (SPFx) solution.

The bread crumb is inserted above every page as application customizer SPFx extension.

Data is read from SharePoint using PnPjs.

And finally the user interface is a combination of Fluent UI and Material UI.

No additional backend code is involved, this is pure client-side code.

I want such a page tree!

Ok you can have it 😇.

Although it’s more of a demo to see if a page tree in this form proves useful.

Some things could certainly be done feature-wise. It also needs polishing in non-migrated-page contexts.

You could also build one on your own - the metadata is there!

Anyway, let me know if you want to try it. There is no official release, yet.

I’m trying to get the SPFx solution into Microsofts store AppSource. But I heard that this can be pretty complicated, so not sure if this will succeed. Fingers crossed.

As always: Try WikiTraccs!

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.

What about those Confluence Macros?

When referring to content migration it’s good to know which content is handled how, and macros are a big part of that.

Let’s start with something that has different meanings depending on context.

Content

Page content for space owners might encompass everything on and around a Confluence page: text, macros, attachments, metadata and maybe also comments and permissions.

All those things would ideally be migrated 1:1 to SharePoint. Migrate, turn off Confluence, done.

As you might expect: it’s not that easy.

There are different angles to approach this topic and the different types of content one might expect to be migrated.

For today I want to highlight one type of content that needs awareness and preparation: macros.

What’s in a macro?

Confluence macros can be used to display different types of content.

Macros can aggregate content from other pages. Or they can show search results. They also allow entering unique content, like the Code or Info macro.

When WikiTraccs encounters macros it has different strategies to handle them:

  • replace by something similar in SharePoint
  • replace by a static representation (e.g. Page Attachments and Page Tree macros)
  • replace by its rich content (e.g. Expand macro)
  • replace by a mere text placeholder

Let’s look at an example page in edit mode:

Above Confluence page features text and three macros:

  1. the Info macro, containing text that I entered
  2. the Favorite Pages macro that shows my favorite pages
  3. the Lorem Ipsum macro that generates a random paragraph of text

Here’s how this page looks after having been migrated to SharePoint:

This looks pretty similar.

WikiTraccs, when migrating the page, retrieved text, the Info macro plus content and markers for the other two macros. And because Favorite Pages and Lorem Ipsum web parts don’t exist in SharePoint they are represented by a text placeholder in the resulting page.

Let’s now look at the page in Confluence without being in edit mode:

Confluence knows what Favorite Pages and Lorem Ipsum macros are supposed to do and shows additional, dynamically generated, content.

This, of course, is not possible to replicate in SharePoint.

Now what?

There’s not much WikiTraccs can do about macros not being available in SharePoint.

WikiTraccs already has special handling built-in for a handful of frequently used macros, like the Page Attachments and Page Tree macros.

For many macros you’ll see a placeholder in the migrated page.

Let’s zoom out for a moment.

It’s best to see this as a chance rather than an obstacle. SharePoint is different from Confluence. And as part of Microsoft 365 there is a good chance that something powerful can be built on the Microsoft-side of things.

And zooming in again here are some points for the migration-planning check list:

  • create an inventory of spaces and check which can be excluded from the migration
  • create an inventory of macros that are in use on Confluence pages in to-be-migrated spaces
  • evaluate how removing macros might affect legibility and understandability of pages
  • take a look at SharePoint standard web parts as well as community solutions like PnP Samples
  • think about how the content will be used in SharePoint; is it like an archive or will the content be worked on?
  • identify use cases that are affected by macros not being available in SharePoint anymore
  • re-think use cases to SharePoint / Microsoft 365 where needed (don’t forget about Microsoft Teams, Viva, the Power Platform etc.)

Something wholistic like a transformation workshop or down-to-earth requirements analysis might be in place. (My colleagues at Communardo can support with those.)

With WikiTraccs it’s free and easy to just test the migration. Looking at the results can spark meaningful discussions as well.

Get started today!

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.

What to expect from WikiTraccs?

So what can you expect from the migration tool WikiTraccs? Or even more general: What to expect from any migration tool?

I often demo WikiTraccs to potential customers. Those demos spark discussions around the future structure, navigation patterns, usage scenarios, and more.

These are all topics that need to be worked on in the context of a migration project.

WikiTraccs can support your migration efforts.

It can migrate content from spaces to sites. It can migrate permissions and metadata. It has certain limitations. And it has distinct capabilities.

But there are things that WikiTraccs is not meant to do.

So let’s turn the headline around.

What to not expect from WikiTraccs

The following topics need to be worked on in the context of a transformation workshop, a migration project, or whatever format you choose to generate answers:

  • choose what to migrate - content only? metadata? permissions?
  • make decisions about which content goes from where to where - which spaces need to be migrated? which archived? which deleted? which sites do we migrate to? how many are there? how are they created? use new ones or existing ones?
  • know the amount of content to migrate (at least not in a demo context) - 10, 100 or 1000 spaces? 1000, 10000 or 100000 pages? 10, 100 or 1000 GB of attachments?
  • plan an access scheme for the SharePoint sites - users, groups, permissions given at which level in the SharePoint hierarchy of elements?
  • decide which macros are important for users, and which not
  • choose a strategy for your migration - big bang or in waves? who needs to be informed? how? when?
  • choose migration environments - need test environments? how many? where do those come from? how exact do they need resemble the production environment?
  • …and more, driven by your use cases

WikiTraccs cannot do this for you.

So what to expect from WikiTraccs?

WikiTraccs will help you realize the plans you made.

Let’s assume the following simplified migration plan:

  • 📄 migrate all Confluence pages, from all spaces (10000 pages overall; 20000 attachments, mostly images)
  • 🏗️ one target site for each source space
  • 👥 keep page author and editor, no permissions
  • 📝 accept that macros will mostly be lost and plan to educate users accordingly
  • ⚙️ run multiple test migrations
  • 📅 choose a weekend for the final migration

Here’s how WikiTraccs has got your back:

  • 📄 WikiTraccs migrates content and metadata
  • 🏗️ WikiTraccs migrates according to your space-to-site mapping
  • 👥 WikiTraccs replaces Confluence user accounts by Azure AD accounts according to your mapping
  • 📝 WikiTraccs handles macros according to the known macros list
  • ⚙️ you test-migrate as often as you need (the license is not bound to volumes of data)
  • 📅 using the experience from multiple test migrations verify a migration time of about 2 days

A demo is a good way to see this in action.

Testing yourself is even better. You can quickly put above steps into action in your environment.

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.

New attachments macro transformation

What’s new regarding page attachments discoverability in SharePoint and the new attachments macro transformation?

WikiTraccs migrates a snapshot of the attachments macro

The Confluence attachments macro shows a list of page attachments, which looks like this:

A Confluence page with attachments macro.

WikiTraccs now transforms this macro to a table in the target SharePoint page. The result looks like this:

A SharePoint page with attachment links in a table.

This feels a lot better than the placeholder that has been generated before.

And do you see the Page Attachments section at the bottom? Let’s talk about that.

Attachments are also available via SharePoint web part

WikiTraccs creates a Page Attachments section on each SharePoint page with attachments. This allows for easy access of page attachments even on pages that had no page attachments macro.

The section is collapsed by default. Click the section title to expand it:

SharePoint list web part showing page attachments.

This section contains a standard SharePoint list web part. It shows all attachments of the page.

Where are those page attachments even stored??

SharePoint puts files that belong to pages in the Site Assets library. Each page has its own folder. And this is where WikiTraccs puts page attachments when migrating a page from Confluence to SharePoint.

The Site Assets library contains all page attachmetns.

The web part in a page’s Page Attachments section shows the content of the page’s folder.

Summary

Both the page attachment macro transformation and the list web part that shows page attachments should make working with page attachments a lot smoother. They are an addition to the latest release of WikiTraccs.

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.

Mapping principals and migrating permissions

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

Terminology

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.

Summary

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.

WikiTraccs Quick Start Video out now!

You can have your first migration running in less than 30 minutes.

This quick start video is all you need:

Download FREE WikiTraccs now

New release - UI overhaul

This covers the latest release 0.0.222 and its changes.

The user interface got some additions

The WikiTraccs.GUI user interface has been changed.

The settings have been grouped into steps: First configure the source, then configure the target, then test the configuration, and then start the migration.

Some configuration options are gone. You now use a SharePoint list to configure the Confluence spaces to migrate. This list shows basic information about all Confluence spaces and is filled by WikiTraccs.

Note: The idea behind using SharePoint lists for configuration has been described in more detail here: A new approach to configuring WikiTraccs

A big improvement are the progress indicators. You no longer have to rely on the console output of WikiTraccs to see progress. Instead, you get a progress bar for overall page progress and the progress of each migrating Confluence space:

Migration progress

Laying the foundation for user and group mapping, and permission migration

Starting with the current WikiTraccs release 0.0.222, you need to create a SharePoint site dedicated to WikiTraccs. This is the “WikiTraccs site”. You use this site to configure WikiTraccs, like choosing the spaces to migrate. And WikiTraccs uses the site to store metadata about the migration.

This site also holds two SharePoint lists, Confluence User and Group Mapping and Confluence Permission Snapshots. You will notice that those will be filled while migrating.

The current release does not yet support user or group mappings, or permission migration. But a future release might make use of this data.

Fixes and improvements

When migrating pages with large file attachments WikiTraccs could run into timeouts. This has been fixed.

Parallel file downloads have been added. WikiTraccs now loads two attachment files from Confluence at the same time, optimizing for large and small files.

The list of known edge cases in Confluence page content transformation has been expanded.

The retrieval of Jira issue information has been improved for pages with a large amount of linked Jira issues.

Summary

This release is a big step and lays the foundation to add two big missing features: user and group mapping, and permission migration. I’m excited for the next releases as they will bring WikiTraccs further to what one would expect from a migration tool.

Give WikiTraccs a try and check out its transformation capabilities!

Quick start guide >>

Start today with WikiTraccs’ free Trial Version:

Download FREE WikiTraccs now

I’m also eager to get feedback, so get in touch when you try it: Contact.

Measuring page migration success

This post is about the metrics that WikiTraccs provides about migrated Confluence pages.

Which metrics measure page migration success?

Each Confluence page consists of content, formatting, layout, attachments, links, mentions and more that has to be handled when transforming the page to SharePoint.

WikiTraccs calculates the following metrics for each migrated page:

  • the percentage of characters in the page that was migrated
  • the number of unknown macros
  • the number of links that could not be resolved
  • the number of migrated images
  • the number of user references in the page that could not be resolved
  • the number of transformation errors

Those numbers are saved as page metadata.

A SharePoint view for the Site Pages library can be used to visualize those numbers. Here is a migration result indicating success:

Successful page migrations

Source content issues

Below image shows the result for a page where not everything could be migrated. Not all images could be transferred. And there were two links to inaccessible pages:

Missing images and inaccessible pages

Errors like missing images and inaccessible content can often be solved by fixing permissions or broken content in the source Confluence system.

Also note the “3” in the “Crystal Ball Transformations” column. This means there were 3 macros that WikiTraccs doesn’t know yet. It used a generic transformation approach for those macros.

Transformation issues

Sometimes WikiTraccs cannot handle content properly (for whatever reason):

Migration errors

Above image shows that 12 elements in a page could not be transformed and only 51% of the page’s text content made it to the SharePoint page.

Those issues can be caused by faulty Confluence pages triggering transformation errors. There are already dozens of special cases and quirks that WikiTraccs works around. But there will always be cases that are new and need to be looked into.

For such a page, click on “View Entries” to see the content that cause the transformation issue. And ultimately a good thing to do might be opening an issue on GitHub.

Summary

In this post we looked at the metrics WikiTraccs uses to highlight migration success and migration issues. Everything being green is a good indication of a successful migration.

WikiTraccs counts content characters in each Confluence page and again counts characters in the target SharePoint pages. The result will be reported as “Text Transferred Percent”. This percentage is a good indicator if content is missing or not.

A new approach to configuring WikiTraccs

This post is about configuring WikiTraccs with SharePoint lists, a different approach to the GUI-based one planned so far.

So far my plan was to establish WikiTraccs.GUI as a visual frontend for configuring WikiTraccs.Console.

But I decided to change that approach a bit. WikiTraccs.GUI will still be application you start transformations with. But the configuration will mainly be done in SharePoint.

How is SharePoint used to configure WikiTraccs?

WikiTraccs stores information about the migration into SharePoint lists. You will create a site collection for WikiTraccs to use. This could be called “WikiTraccs Store” and holds data during the migration. It can be deleted after the migration.

When starting WikiTraccs it will create several lists there. One is the Confluence Space Inventory list. This list stores information about all spaces in Confluence, like space name and space key. But it also allows you to select the spaces to be migrated:

Confluence Space Inventory List in SharePoint

Above image shows the Confluence Space Inventory list that shows some spaces from a publicly available Confluence instance.

In the image on the right side, marked with a red rectangle, are two columns that allow you to:

  1. mark a space for migration via Yes/No column
  2. specify the target site for the migration via a text column to put the target site URL in

More columns might follow as needed. (Note: the column names are still technical and are yet to be named properly.)

Why use SharePoint for configuration?

One benefit of using SharePoint lists for configuration is that they already provide a way to display tabular data, like the space inventory. This data can be sorted and filtered out of the box.

List data can be exported to and imported from Excel files for others to review. So the list of spaces could be given to stakeholders to decide which spaces should be migrated. Then they are imported again and WikiTraccs migrates only the selected spaces.

Using SharePoint as a user interface also means there is less potential for programming errors in WikiTraccs since the interface is owned by Microsft.

SharePoint lists provide a familiar user interface, if users are already used to working with SharePoint. There is no new UI that has to be learned.

The data can be shared with select stakeholders by using SharePoint list or list item permissions.

You are free to run WikiTraccs on any machine, even multiple ones, and change the machine at will. Every instance of WikiTraccs will operate on the same configuration.

And last but not least you have the SharePoint Search at your disposal to locate information you need.

Wrap up

That’s it for the latest update. What do you think about using SharePoint lists for configuring a migration? Get in contact and let me know!

There are more lists that are relevant to WikiTraccs that will be covered in future blog posts:

  • Confluence User and Group Mapping
  • Confluence Permission Snapshots

As the names suggest those are relevant for mapping Confluence users and groups to SharePoint and to ensure the permissions and metadata can be rebuilt properly.

Announcing WikiTraccs

WikiTraccs migrates content from Confluence to SharePoint Online

I’m delighted to announce the first public release of WikiTraccs.

What is WikiTraccs?

WikiTraccs is a migration tool for Confluence to SharePoint Online migrations.

Which problem does it solve and who needs it?

WikiTraccs makes migrating content from Atlassian Confluence to SharePoint Online easier. It contains hundreds of transformation rules for a wide range of Confluence formattings, structures and macros.

A migration from Confluence might be beneficial for:

  • users of Confluence Server, since Atlassian will eventually phase out Server, urging users to migrate to Confluence Data Center or Confluence Cloud
  • users of Confluence Data Center, because it only buys some time before migrating to the Atlassian cloud might be inevitable
  • users of Confluence Cloud, because of license costs

Often Microsoft 365 licenses are available already, covering the use of SharePoint Online modern pages to display wiki content. In this case SharePoint Online is a potential target for the migration.

Is it ready for production?

No, not yet. The current release is an early access version. This means the basics work but a lot is still to be done.

The focus of this first release is to migrate content and structure of Confluence pages as reliable as possible. This includes:

  • Text
  • Formatting like bold, italics, underline etc.
  • Text colors and background colors
  • Headings
  • Task lists
  • Emoticons
  • Complex tables
  • Images, internal and external
  • Mentions
  • Page and attachment links, on the same page and to different pages and spaces
  • Layouts with multiple columns and rows
  • Macros - a wide range is supported out of the box, for unknown ones generic rules are applied

It has been tested on thousands of Confluence pages and dozens of gigabytes of images and attachments. Since every Confluence is unique with regard to its content there will be cases not covered. But those will be covered over time as feedback comes in.

WikiTraccs keeps track of every word that is present in a source Confluence page and checks if it is present in the target SharePoint page as well. It highlights pages where this is not the case. Thus pages with lacking transformation success can be identified easily and immediately.

The Feature Overview page will eventually cover all supported and not yet supported types of Confluence content and metadata.

You can also read more about how WikiTraccs works in How does WikiTraccs work?.

Which Confluence versions are supported?

WikiTraccs supports Confluence 6 and up, including Confluence Cloud. Confluence 5 and older are not supported.

How do I get started?

Have a look at How to get started?

If you want to get in touch have a look at the options you have for logging issues, start discussions or just give feedback.

What’s the meaning of “WikiTraccs”?

“WikiTraccs” is short for “Wiki Transformation Accelerators”. WikiTraccs for Confluence should indeed accelerate things compared to a manual migration.

There are a lot of interesting topics to be covered which will be done in a future posts!

New Releases

WikiTraccs 1.20.35 (Prerelease)

Support for hard link transformation has been extended. For both Confluence on-prem and Cloud hard links are now properly transformed to SharePoint links when using API Keys to authenticate with Confluence.

Furthermore, support for additional Confluence Cloud hard link variations has been added (solves #117 and #119).

Read the blog post for more information about hard links and soft links: Confluence Link Types Explained.

Other Improvements

Confluence Cloud

  • improved: user name resolution for @-mentions via user key (this affects pages that have been migrated from Confluence on-prem to the cloud) (solves #114)
  • fix: some pages have no position set, making their order undefined (which would affect WikiPakk); falling now back to manual on-prem order logic (might only affect migrated pages; let’s see if we can find that out)

WikiTraccs 1.20.31

Confluence Cloud - Migrating Whiteboards

This release is capable of migrating Confluence Cloud whiteboards to SharePoint Online.

Whiteboards will be exported as image, the SharePoint page will show this image. Whiteboard export is currently opt-in and needs to be enabled in the settings. It is in experimental state and needs to evolve as the number of whiteboard migration grows.

Note: Atlassian does not provide an official way for applications like WikiTraccs to export whiteboards automatically and at scale. WikiTraccs thus resorts to browser automation. It will open whiteboards in a browser and automatically “click” the buttons needed to export the whiteboard as image. This method can work well, but is prone to breaking if Atlassian changes the user interface. This will need to be adjusted as needed - until Atlassian provides a proper export endpoint. This ask is tracked in CONFCLOUD-76634.

Note: WikiTraccs cannot yet detect empty whiteboards and those fail to export. This is a known limitation.

Other Improvements

Confluence Cloud and On-prem

  • improved: image scaling; image sizes now match the source more closely, and scrollbars in tables are prevented
  • improved: only accounts of page authors were added to the user mapping table, now the last editor is added as well
  • improved: better handling of more complex link contents
    • sometimes you might see this in pages, where WikiTraccs wasn’t able to handle a link that had some “content” in it: image
    • this should now look like this instead, which helps de-cluttering pages: image
  • improved: converting three-column layouts with empty columns left and right to one-column in SharePoint, to use available space
  • fix: page tree macro conversion fails if the search box is on in the macro settings
  • fix: images that link to PSD files were converted to text placeholder; will become attachment links now
  • fix: SVG image scaling to zero size issue, making images appear missing
  • fix: file names with control characters could prevent a page from being created (how does “Ctrl+C” end up in a file name?)
  • fix: special characters in commentators names could make page transformation fail
  • fix: link resolution might fail for ID-only links that miss the target content type

Confluence Cloud

  • new: added transformation for decision lists
  • fix: modification date and author for new content types (whiteboard, database, etc.) were missing in the last prerelease
  • fix: emoji conversion - cloud-specific ones are now handled correctly (#27)

WikiTraccs 1.20.15 (Prerelease)

General Improvements

  • new: the Include Page macro is transformed to a link to the corresponding SharePoint page
  • improved: removing empty entries from transformed Table of Contents macro

Confluence Cloud - Preparing for Migration of new Content Types

This release adds further support for the new Confluence content types like whiteboard, database, folder, and smart link. Those will not be migrated yet. But a new SharePoint page will already be created, although an empty one. Future releases of WikiTraccs will add migration support for those new content types.

Migrating the new content types to empty pages has already one benefit: all metadata will be present in SharePoint that is required to rebuilt the Confluence page tree. If you use WikiPakk to show the Confluence page tree in SharePoint, this will now show the whole tree, regardless of content type.

Proxy Mode Improvements

Note: Those changes only apply if you have the “Proxy Confluence API calls through browser” setting activated.

  • improvement: automated browser is more resilient against accidental closing; will reopen
  • fix: relative link issue in proxy mode with cloud site that redirects after logging in
  • fix: modified JavaScript to handle missing page body (when page loads slowly)
  • fix: adding CORS error handling
  • fix: failed external file downloads could cause a lot of retries with way too long timeouts

Updating to .NET 8

Microsoft is deprecating .NET 6 in a couple of weeks, forcing the update to .NET 8. This should make no difference from an end-user point of view.

WikiTraccs 1.20.6 (Prerelease)

New transformation capabilities

  • new: page header template support; here’s how:
    1. create a SharePoint page template with name migration-template.aspx (that is the file name, not the page title; the title of the template page doesn’t matter)
    2. all newly migrated pages will now get the same header as the template page in the same site
    • note: this is a per-site configuration; each site can have their own migration-template.aspx that applies to all pages migrated to the same site; sharing a template across sites is not possible at the moment
  • new: macro placeholder customization using transformation templates
  • new: adding explicit support for language macros from Bitvoodoo’s Translation for Confluence

Lots of small improvements (PART 3)

  • improved: better handling of certain cases of nested sections, columns, and macros
  • improved: support for horribly broken macros in pages; WikiTraccs tries some fixing
  • improved: memory management to better support long-running migrations under low-memory conditions
  • improved: more diagnostic output for rare “Not a GET query” connection issue
  • improved: Draw.io embed macro transformation now supports diagrams embedded from other pages
  • fix: nested aui tab macros screw with the “handled macro percent” metric
  • fix: “non breaking space” unicode character in page titles breaks attachment links
  • fix: images with links were not immediately clickable, but required a page edit first
  • removed the “Use M365 PnP Client ID” shortcut button as Microsoft retired the PnP Entra ID application on September 9, 2024

Confluence Cloud

  • improved: panel transformation now takes the panel’s emoji and color into account

WikiTraccs 1.19.13

Lots of small improvements (PART 2)

Confluence on-prem & Cloud:

  • new: migrating image captions
  • new: handling Spreadsheet macro
  • improved: supporting links on images that start with //
  • improved: handling images that link to non-image files instead of an actual image (like .msg email file); those will be converted to simple links
  • improved: handling of attachment thumbnails; thumbnail images will be downloaded and treated as additional attachments of the page they appear in
  • improved: better error handling and display for connection tests in WikiTraccs.GUI
  • improved: Selenium proxy mode now only downloads one Confluence attachment at a time to increase resilience
  • improved: marker for added table cells
  • improved: handling of even more non-standard tables
  • fix: issue with generated links when more than one view-file macro is on one page
  • fix: handling of inaccessible Jira issue lists as anonymous user
  • fix: Selenium proxy mode could show mixed-content warning when downloading http resource; will upgrade to https and try again
  • fix: Selenium proxy mode could run into timeouts for larger attachments
  • fix: lowering the number of IDs per CQL query for content ID selectors even more to 200 to work around Server Error issue
  • fix: content of non-standard list content in nested lists could be missing (note: this would be indicated by < 100% text transferred metric)
  • fix: handling of empty table filter macro - it will now be removed
  • fix: empty table of contents macro needlessly transforms to text placeholder - will now be removed

Confluence Cloud:

  • improved: link transformation for inline card links

WikiTraccs 1.19.5

Note: the previous preview release v1.19.3 introduced a so far unknown HTTP header conflict that made Confluence on-prem fail to convert the page tree and table of contents macros to HTML. This has been fixed in v1.19.5. Please update to the new release when it becomes available.

Lots of small improvements (PART 1)

Confluence on-prem & Cloud:

  • new: Table of Contents macro migration (as static snapshot)
  • new: transformation of Google Drive Link macro to regular link
  • new: setting storage locations (in WikiTraccs settings dialog)
  • new: setting to disable connection checks for troubleshooting purposes (in WikiTraccs settings dialog)
  • improved: removed “Add caption here” being displayed for transformed images (in SharePoint)
  • improved: transformation of .ico image files with certain MIME types
  • improved: empty code macro transformation result
  • improved: Confluence user name lookup in anonymous auth mode
  • improved: adding more image to emoticon conversions (to prevent smilies from being served as image files)
  • improved: Confluence connection tests (logging, error display, focus on supported TLS versions)
  • improved: default values when opening the settings dialog the first time (enabling comments migration and downloading of external images by default)
  • fix: wrong display size for images when EXIF rotation is set
  • fix: rare case of inline images making code macro transformation fail
  • fix: lowering the number of IDs per CQL query for content ID selectors from 500 to 300 to work around Server Error issue
  • fix: page title with line break prevents page creation in SharePoint

Confluence Cloud:

  • new: Panel extension transformation (#137)

WikiTraccs 1.18.19

  • improved: removing more blocking user interface elements in automated Chrome browser, like the search engine selection dialog
  • improved: better duplicate page remediation; when duplicate page IDs are returned by Confluence (rare cases, but it happens), WikiTraccs falls back to “manual” page tree traversal which seems to reliably get all pages for a space
  • fix: adding option to (hopefully) work around the “DevToolsActivePort file doesn’t exist” error (#136): image

WikiTraccs 1.18.15

  • new: “Embed draw.io Diagram” macro is now supported, migrates just as the “draw.io Diagram” macro
  • improved: applying Gliffy macro width to SharePoint image
  • improved: applying draw.io macro width to SharePoint image
  • fix: page and layer selected in draw.io macros were not respected; the corresponding image will now be shown in SharePoint

Note: this blog post has more information about Gliffy and draw.io: Migrating Gliffy and draw.io macros to SharePoint Online.

WikiTraccs 1.18.13

Transforming even more colors from Confluence to SharePoint!

This covers text colors, the new text highlight colors, and table cell colors.

More details has the blog post.

WikiTraccs 1.18.11

Note: Please have a look at the last preview and beta releases as well for the complete list of changes.

  • new: support of US Government High (GCC High) cloud environment is now confirmed; the other environments should work as well (US Government (GCC), US Government DoD (GCC DoD), Germany, China)
    • note: .us domains default to GCC; to select GCC High or GCC DoD, use appsettings.json
  • improved: delta migration input file parsing now recognizes the marker (“x”) even if not delimited by tab, but only by space
  • improved: toned down the log output for content ID selector
  • fix: delta migration fails with exception being shown in Console

WikiTraccs 1.18.10 (Beta)

This release contains two major new additions: Waves and the Content ID Selector.

Waves

Waves are used to partition the migration into different chunks. Those chunks can then be

  • migrated one after another
  • migrated in parallel by multiple WikiTraccs instances

Waves are numbers that you assign to source selectors in the Space Inventory.

When starting a Confluence to SharePoint migration you can tell WikiTraccs which of those waves it should migrate.

This article has all the info: Migration Waves.

Note: WikiTraccs will add a new column WT_Setting_Waves to the Space Inventory list.

Content ID Selector

So far WikiTraccs has two ways of selecting which content it should migrate: by space key and by CQL query.

This release introduces a new way of selecting content to migrate: by content ID. Give a list of page IDs and blog IDs to WikiTraccs and it’ll migrate exactly those.

The Content ID Selector allows for flexible selection of your source content. You’ll be able to get those IDs from the database (on-premises) or from the space report (cloud), filter as you like, and put the result into WikiTraccs.

This article has all the info: How to migrate Confluence Pages using Content ID Selectors.

Note: WikiTraccs will add a new column WT_Setting_ContentSelectorValue to the Space Inventory list.

Other changes

  • improved: better handling of Confluence Cloud base URLs that have more than just /wiki in them
  • improved: Selenium proxy mode status panel (in browser) can now be moved down to access controls beneath it
  • fix: Selenium proxy mode and the new Confluence connection watcher did not yet work well together
  • sharepoint.us URLs are now treated as GCC High environment (note: this changed in the next release); furthermore, a setting has to be configured via appsettings.json:
    {
      "CustomSettings": {
        "CloudEnvironment": "USGovernmentHigh"
      }
    }
    
    Note: Create a new file appsettings.json, copy above text to this file, and store the file in the folder where the WikiTraccs.GUI.exe is located.

WikiTraccs 1.17.5 (Prerelease)

This release fixes more Confluence Cloud-related issues as part of the WikiTraccs push to the cloud.

Confluence Cloud

  • fix: attachments macro transformation fails, generates text placeholder (#128)
  • fix: PDF macro is not converted to file link, but generates text placeholder (#129)
  • fix: table cell background color is not converted to color emoji anymore (#130)

Other Changes

  • new: Confluence connection monitor that continuously checks if Confluence is down or if the user session got invalid; migration is paused in those cases
  • fix: user mentions in transformed attachments macro still link to Confluence

WikiTraccs 1.17.7 (Preview)

This release fixes more Confluence Cloud-related issues as part of the WikiTraccs push to the cloud.

Confluence Cloud

  • fix: attachments macro transformation fails, generates text placeholder (#128)
  • fix: PDF macro is not converted to file link, but generates text placeholder (#129)
  • fix: table cell background color is not converted to color emoji anymore (#130)

Other Changes

  • new: Confluence connection monitor that continuously checks if Confluence is down or if the user session got invalid; migration is paused in those cases
  • new: adding (possible) resilience for erroneous Confluence API responses when requesting the list of space pages
  • improved: general improvements of table-cell-color-to-emoji-mappings
  • fix: user mentions in transformed attachments macro still kind of link to Confluence
  • fix: verification mode creates new empty pages when already migrated pages have been renamed

WikiTraccs 1.17.4

This release contains a lot of under the hood changes for Confluence Cloud API v2 compatibility (see issue #118 for details). This required some major changes with regard to spaces, as those need to be identified by ID and not alone by key.

Further changes:

  • new: setting to prevent attachment migration; this can be enabled via appsettings.json like so:
    • {
          "CustomSettings": {
              "Features": {
                  "SkipAttachmentDownload": true
              }
          }
      }
      
    • note: setting SkipAttachmentDownload to true pretends that all Confluence pages have no attachments; page transformation will act as if attachments are missing when generating links to attachments and images that are expected to be there
    • note: you’ll see the following log message per transformed page if the setting is active: “Skipping attachment download (by simulating empty attachment list) because Features.SkipAttachmentDownload is set to true | WikiTraccs.Console.Registries.ConfluenceContentRegistry”
  • improvement: speeding up page retrieval by caching already retrieved page contents
  • improvement: sometimes link transformation fails for linked-to pages that are not retrievable via title (for unknown reason); CQL-based retrieval has been added as workaround
  • improvement: reenabling inline images in lists as Microsoft fixed the underlying bug in the page editor
  • fix: space link in Space Inventory is incomplete for personal spaces
  • fix: page links in transformed attachment macro might be broken after the first link
  • fix: link transformation fails for links that point to a blog post by title and there are multiple blog posts with this title
  • fix: issue when downloading external images and the file name is extraordinarily long
  • fix: hard-link resolver tries to get page info for hard-linked page draft; those are now ignored

Confluence Cloud:

  • new: resolving Confluence data cards linking to Jira issue lists (interactive auth only, see #123 for details)

WikiTraccs 1.16.0

  • new: supporting Brikit Theme Press migration to SharePoint Online modern pages
  • new: detection of Confluence attachment hard links and translation to proper SharePoint links
  • improved: transformation of nested ordered lists, where the nesting can be reduced
  • improved: WikiTraccs.GUI nowshows notifications on start-up when appsettings.json or cookies.txt are used do modify authentification behavior
  • fix: configurations via appsettings.json are not applied to WikiTraccs.GUI connection test
  • fix: the combination of cookies.txt, appsettings.json, and anonymous authentication is broken

WikiTraccs 1.16.2

  • new: supporting Brikit Theme Press migration to SharePoint Online modern pages
  • new: detection of Confluence attachment hard links and translation to proper SharePoint links
  • improved: transformation of nested ordered lists, where the nesting can be reduced
  • improved: WikiTraccs.GUI now shows notifications on start-up when appsettings.json or cookies.txt are used do modify authentification behavior
  • improved: added additional authentication detection for interactive cookie-based auth
  • fix: configurations via appsettings.json are not applied to WikiTraccs.GUI connection test
  • fix: the combination of cookies.txt, appsettings.json, and anonymous authentication is broken
  • fix: selecting pages via CQL query in the Space Inventory is broken
  • updating dependencies that have security advisories (ImageSharp, Azure.Identity, Microsoft Identity Client)

WikiTraccs 1.14.13

  • improved: connection check for Confluence now also checks that space information can be retrieved to discover issues faster
  • improved: logging now includes Confluence version, to faster diagnose version-specific issues
  • fix: interactive login (cookie based) broken for Confluence Cloud

WikiTraccs 1.14.10

The LinkTransformationMode introduced in the last release now covers more cases of hard links to pages and spaces. (Hard links are pure “text links” without any Confluence magic.) Note that hard link transformation is (and so far has been) supported for pages and spaces, not attachments. So attachment hard links are always migrated as-is.

WikiTraccs 1.14.6

  • fix: on-prem Confluence groups are not always added to Confluence User and Groups list

WikiTraccs 1.14.8

This release introduces a setting to disable link transformation for unmapped entries in the Space Inventory.

Background: So far, all Confluence links (page links, space links, attachment links) are transformed to SharePoint links. If there are entries in the Space Inventory where the target SharePoint site address is empty, the link will be mapped to the default target site (the address entered in the blue WikiTraccs.GUI window, in step 4).

Now there is a setting to restrict link transformation to only those entries in the Space Inventory that explicitly have a target SharePoint site address set. Other links will point to Confluence.

The setting is available via appsettings.json:

{
    "CustomSettings": {
        "Features": {
            "LinkTransformationMode": "needexplicittargetsite"
        }
    }
}

Note: Hard links to Confluence spaces are not covered, yet. This is a known limitation and will be added in a future release.

Furthermore

  • fix: on-prem Confluence groups are not always added to Confluence User and Groups list (a regression introduced with the previous release 1.14.2)
  • fix: hard links to Confluence attachments were transformed to page links

WikiTraccs 1.14.2

More Authentication Methods

Adding Personal Access Token as authentication method for Confluence, as well as Device Login for SharePoint Online.

Using Personal Access Tokens with Confluence makes the browser automation obsolete, that WikiTraccs so far relied on. This is available as of Confluence 7.9 and makes the authentication experience smoother. We are not dependent on the Chrome browser anymore. This also works with Confluence Cloud (where they are called API tokens).

With Device Login for SharePoint you can authenticate on a different workstation than the one WikiTraccs is running on. There are cases where M365 authentication causes challenges in certain environments and Device Login allows logging in on another workstation.

Performance Improvements

  • improved: page creation speed
  • fix: memory leak causing memory consumption to increase when running for days

There have been adjustments to the page creation logic, as now, while one page is being created, the next page is already being prepared in SharePoint. This can improve page creation speed (the raw page without attachments) up to about 25%. It is currently being monitored if this leads to increased throttling by Microsoft, as we are moving faster than before.

Confluence Cloud Compatibility Push

This release contains a major change regarding how users and groups are identified internally. So far, WikiTraccs used user keys and group names to identify users and groups. The cloud abandons the use of those and rather uses IDs everywhere. WikiTraccs can now handle those as well.

You’ll see a change in user- and group-related fields in the User and Group Mapping list, the Page Transations list, and the Site Pages list. Fields that used to contain user keys like abc123def now contain an identifier like user:key:atlassian:|onprem|abc123def (for users) or group:id:atlassian:|cloud|123456789 (for groups). Those identifiers explicitly specify the type, source, and (of course) value, which is vital for WikiTraccs when looking up and working with users and groups.

This change is backward-compatible. Identifiers that aren’t following the new format are assumed to be on-prem user keys or on-prem group names, respectively.

This change closes two issues which were open on the road to full Confluence Cloud compatibility:

The following issues are addressed at least partially:

The releases also gradually starts using Atlassian’s v2 API in the cloud.

Other Changes

  • change: SharePoint page comments are not disabled anymore for newly created pages, as this speeds up page creation; if you want to disable comments, please use this PowerShell script from the library: ToggleCommentsForPages.ps1
  • fix: path configuration via appsettings.json of WikiTraccs.GUI did not carry over to WikiTraccs.Console (attachment registry path, temp folder path)
  • fix: a current directory that differs from the WikiTraccs.GUI.exe folder could screw things up (appsettings.json not found, logs folder created somewhere else); now the current directory of WikiTraccs.GUI is forced to be the exe location
  • fix: a vertical tab character in a page’s title could prevent another page that link to that page from being created

WikiTraccs 1.13.1

  • fixed: certain empty tables could prevent pages from being transformed; those are now removed from the page

WikiTraccs 1.13.0

  • new: downloading of external images (like: not stored in Confluence) can be disabled in the settings; if disabled, those images will be transformed to links

image

  • fix: some progress bars went missing in the prerelease; those are back
  • fix: fixed a rare race condition when choosing migration target sites

⚠️ You should update to this release to minimize risk of running into the race condition issue.

WikiTraccs 1.12.29

  • new: adding SharePoint page modification time to “25” progress log file
  • improved: page migration speed
  • improvement: working around time zone issues that can affect the “25” progress log file, marking up-to-date pages as changed; differences that can be attributed to time zones being off are now detected and ignored
  • improvement: adding consistency check to check for large file uploads that were interrupted by Microsoft throttling
  • improvement: consolidating local file storage locations; those are now documented here in detail: File Storage
  • fixed: when page restrictions are narrowed down in the hierarchy of pages, dropped users and groups were not removed from the child pages

WikiTraccs 1.12.16

  • new: signed WikiTraccs binaries
  • new: checksum file in release package
  • improvement: adding additional logging to permission migration to better diagnose edge cases
  • fix: WikiTraccs could stop scheduling migration targets when accessing one target site fails; scheduling will now continue

WikiTraccs 1.12.6 (Prerelease)

Permission Migration Improvements

More cases are covered where WikiTraccs would previously give up, mainly in complex permission hierarchies.

WikiTraccs 1.12.5

Google Endpoint Fix

Time for Google’s once a year change of endpoints. WikiTraccs has been adjusted to handle those.

Permission Migration Improvements

  • new: in a hierarchy of restricted pages, when the principals of a parent page are not all mapped, the principals that are mapped will be inherited by the child pages (within narrow boundaries)
  • improvement: hardened permission retrieval against connection losses
  • improvement: when permissions cannot (fully) be applied to a SharePoint page (e.g. due to missing user mapping) permission inheritance for the SharePoint page will be broken nevertheless
  • improvement: better indication when being throttled by Microsoft (in the console and log file)
  • fix: reverted connection timeout back and increased to 600 seconds as it otherwise interferes with throttled requests

Verification Mode

This release introduces the mode Verify page contents.

image

When running in verification mode WikiTraccs will go over all migrated SharePoint pages, pull the corresponding original pages from Confluence, and compare contents. This creates updated progress log files.

WikiTraccs will check the following things:

  • check each code snippet web part for invalid characters in the backing CanvasContent1 list item field
  • check if the Confluence page contains words that are missing in the SharePoint page

The results will be stored in the “25” progress log file.

In the progress log file, each page entry will get an additional state indicator that is one of the following values:

  • skippedverify - did not check a page; this is the state for the progress log file that is created when starting the verification run
  • verified - checked a page and found nothing of interest
  • worddiff - the Confluence page contains words that are not present in the SharePoint page
  • invalidcodesnippetchars - a code snippet web part contains invalid characters in the CanvasContent1 field of the page list item

image

But why?

The reason for the introduction of the verification mode is an incident where pages seemed broken due to invalid characters in the backing field of the page. Note that several weeks had passed since the migration.

The content of a SharePoint page is stored in a list item field called CanvasContent1, in the Site Pages library. It is HTML which needs to adhere to certain rules. One rule is, that special characters like < and > need to be encoded properly. WikiTraccs does this since its inception in 2022. Nevertheless, something changed this content for some pages with HTML code snippet web parts to contain raw < and >. That made page rendering stop there.

The verification run checks for invalid characters in the backing CanvasContent1 field and highlights the affected pages in the progress log files. An easy solution is to delete and remigrate them.

Before recognizing that page content is simply not shown we assumed that page content had gone missing, which would be a blocker (and at the same time nearly impossible, since WikiTraccs already verifies the character count of transformed pages at the time of migration). It turned out that all page content was there, it was just not being displayed. But this initial assumption resulted in the verification run to also check for missing words. Note that updates to either the Confluence or the SharePoint page can also cause this check to be triggered.

In the future, the verification run might be extended with further checks or statistics collection.

Logging Improvements

Since the number of transformation modes is growing, WikiTraccs now shows the mode it is running in:

image

The log file and console also show the mode:

image

Possible values are:

  • MIG - Content migration
  • PRINCIPALS - Update ‘Created by’ & ‘Modified by’, as well as the dates
  • VERIFY - Verify page contents
  • PERM - Permission migration

WikiTraccs.GUI also contains several improvements for its progress bars.

WikiTraccs v1.11.16

  • adjustment: default timeout for connections to SharePoint has been decreased from 100 seconds to 40 seconds - NOTE: this change exacerbated a concurrency issue that showed when being throttled by Microsoft, that will be solved in the next release
  • fix: memory leaks that lead to high RAM usage

Please report back if you see RAM usage that increases over a period of multiple hours and reaches amounts of > 10 GB. Note that WikiTraccs needs at least as much RAM as the largest file that will be uploaded to SharePoint.

WikiTraccs v1.11.12 (Prerelease)

Jira Integration Improvements

So far, there were two assumptions baked into WikiTraccs: Jira can be reached to resolve issue links and issue tables, and WikiTraccs will wait for 60 seconds for Jira to respond. This is now more flexible.

  • the maximum wait time for reaching out to Jira can now be configured via the appsettings.json -> WiggleRoom.JiraMaxWaitTimeSec setting; this wait time is applied each time the the Jira-related Confluence endpoint is called
  • set WiggleRoom.JiraMaxWaitTimeSec to -1 to disable reaching out to Jira while migrating pages from Confluence to SharePoint; this is handy when the Jira application link is no longer functional
  • and a bug has been fixed: issue tables that showed the fixVersion always ran into a timeout when being migrated

WikiTraccs v1.11.9 (Prerelease)

Page Label Migration

Finally page labels are migrated as well. With this release WikiTraccs creates a new field Confluence: Labels (WikiTraccs) for the SharePoint Site Pages Library, that is of type Multiple lines of text, that will contain the labels for each page.

Why not migrate to managed metadata instead of text? Because it complicates things. Migrating as managed metadata would introduce dependencies to the term store, which might pull in additional stakeholders with regard to permissions, administration, and knowledge management. And what if you want to use a choice field instead? Those are decisions specific to each migration effort.

The current migration approach for page labels is to put them all into the Confluence: Labels (WikiTraccs) field, separated by the space character (which cannot occur in a label). All labels have a prefix. Valid prefixes in Confluence are “global”, “team”, and “my”.

So, for a page that has two labels foo and bar, the Site Pages library field Confluence: Labels (WikiTraccs) will have this content: global:foo global:bar.

You can use a PowerShell script to copy those values to another field of type managed metadata. And maybe clean them up a bit in the process.

Other Changes

  • improvement: Confluence code macro titles are now migrated as well, becoming code comments in the SharePoint Code Snippet web part

WikiTraccs v1.11.6 (Prerelease)

Changes

  • new: setting to switch off attachment sections on pages (via appsettings.json)
  • improved: link transformation now creates much shorter HTML for transformed links; this can help with large pages that previously ran into the platform limit of 2 MB per page
  • improved: cross-site attachment handling
  • improved: Confluence connection handling for better performance
  • fix: images linking to pages could lose the link
  • fix: file access issue in Selenium proxy
  • fix: attachment file names that are invalid on Windows could prevent pages from being migrated

Image transformation adjustments

TL;DR: Just for information, nothing to do.

Adjacent images are now transformed to a column of centered images in SharePoint. Adjacent image placement kind of worked for the old text web part that was used by SharePoint pages up until fall of 2023. The new text web part that Microsoft introduced cannot display adjacent images anymore, at all. No chance. So the default image transformation now shows the ugly truth and makes those images appear centered, one by one. I really hope that the SharePoint pages story evolves in the future to support adjacent images.

Converting adjacent images to single centered images is the new default behavior.

Note: You can get the old behavior back via appsettings.json:

"CustomSettings": {
  "Features": {
    "UseCkEditorv5Mode": false
  }
}

Using above setting will continue to create pages that display adjacent images until you edit a page for the first time. SharePoint’s page auto-upgrade will then re-arrange the images.

Note: A future release of WikiTraccs will introduce the option to convert adjacent images to image gallery web parts.

WikiTraccs v1.11.1

Improvements

  • new: you can set an optional Confluence authentication address so that the browser opens this address instead of the Confluence base URL
    • can be used to enter an SSO opt-out URL to authenticate with a different than the current Windows user account image
  • improved: error handling when running WikiTraccs under different Windows user accounts at the same time

WikiTraccs v1.10.24 (Preview)

Adding alternative mode to authenticate with Confluence, to work around authentication issues. See for details: Experimental alternative to obtain cookies.

In addition:

  • fix: update check detects updates when version is already up-to-date
  • fix: Jira issue table macro not transformed if macro has no column definition
  • fix: settings dialog shows leftover characters when switching tabs
  • improved: relaxing the connection check to succeed for on-prem 401/403 results
  • improved: adding sanity check for config file to detect invalid source authentication modes

WikiTraccs v1.10.12

Improvements

  • new: WikiTraccs checks for new releases
    • WikiTraccs shows when a new release is available (by checking this very GitHub release page)
    • the check is on by default but can be switched off in the settings
  • improved: the license key check is now more forgiving with regard to formatting errors and additional text in the license.txt file
  • fixed: code macros that need to be moved out of lists were not labeled and had their order reversed; the are now properly labeled and much easier to identify
  • fixed: character count metric for pages with Jira issue lists could show wrong value, despite the transformation being successful

WikiTraccs v1.10.9

Jira issue table snapshots - part 3

  • improved: links to the Jira issue list are now also added where Confluence normally omits those links (small number of issues)
  • improved: handling of issue lists when access is denied

Content transformation improvements

  • improved: bullet point lists and numbered lists don’t stick together anymore
  • improved: the yellow star emoji from Confluence is converted to a star instead of a circle
  • improved: handling of nested lists and adjacent breaks
  • improved: markers for de-nested tables are more descriptive

WikiTraccs v1.10.8 (Preview)

Jira issue table snapshots - part 2

The last preview release of WikiTraccs did not consider all Jira issue tables for transformation. This has been extended.

@-mention issues - part 2

There was a lingering user cache corruption issue that affected user mentions and could be triggered when switching WikiTraccs releases. This would make user mentions to be displayed as “User {{ID}}” instead of the user name.

I could finally identify and fix the root cause. Thank you Kees for providing me with valuable information. This is self-healing. Broken cache entries will be identified and purged.

Changes to inline images in lists

Microsoft is currently upgrading the technological basis of the text editor web part and breaks certain layouts in the process, but only when you edit pages.

Read about the background here:

With this release WikiTraccs changes the way bullet point lists and numbered lists with images are transformed.

Assume a page that has this content:

1. first point 2. second point with image    <image> 3. third point

Now when editing such a page SharePoint’s auto-upgrade kicks in and modifies the content to look like this:

1. first point <image> 1. second point with image                  2. third point

See how the layout and list numbering is screwed up?

Since I don’t expect Microsoft to do anything about this WikiTraccs now separates the text content and the images, like so:

🚧 Note: Some images were moved beneath the list as SharePoint does not support images in lists 1. first point 2. second point with image    🚧 See image 1.1 3. third point

<image> 🚧 Image 1.1 (moved)

This seemed like the only possible thing to do that doesn’t look too bad. Please let me know if you have better ideas. I just want to emphasize that SharePoint does not allow images to be placed in lists anymore. This is a regression in my books, but maybe it will be possible again in some future.

This change is active as of this release and affects newly migrated pages.

WikiTraccs v1.10.4 (Preview)

Jira issue table snapshots

WikiTraccs now takes a snapshot of Jira issue tables and puts this snapshot into the SharePoint page. The snapshot shows the content you would see when opening the page in Confluence. If the table cannot show all issues of the underlying query, a “show more link” will be added below the table. This follows the logic of Confluence.

Note: So far WikiTraccs already handled links to single Jira issues. Those were converted to hyperlinks pointing to the issue in Jira.

This is a first shot and I’m open for feedback. Does it make sense and where can it be improved? At least it seams better than a plain placeholder text, although the placeholder contained the JQL query. Should the JQL query go back into the pages? Let me know in the discussions.

@-mention issues

I got isolated reports about @-mentions not being transformed to the users’s display name, but to the Confluence user key (like “User {{long-user-key-here}}”). So far I have not been able to reproduce this, but this release contains some caching improvements that might help.

WikiTraccs v1.9.0

Storing the raw Confluence page contents in SharePoint

The raw storage format XML (background) of migrated Confluence pages is now being stored in a SharePoint document library Confluence Content Snapshots (WikiTraccs). You can find this library in the WikiTraccs site, it will be automatically created with your next migration.

The raw page content can help adjusting pages later on, e.g. when new SharePoint web parts become available, and allow the development of client add-ons that conduct additional tasks.

Refer to this sample PowerShell script on how to get the storage format XML for a migrated page: get-confluence-snapshots.

Comments migration

Footer comments can now be migrated and will become content of the migrated page (in case of multiple migrated translations, they will be added to the main page). This is the first approach to tackle #15 (please chime in if you have ideas or feedback).

Notes regarding comments migration:

  • opt-in; you can enable comment migration in the settings, default is off image
  • for now this covers footer comments, not inline comments
  • the raw storage format XML for comments is stored with the page’s in the Confluence Content Snapshots (WikiTraccs) list; this also includes inline comments, including resolved ones; you might access those comments there, if you need
  • migrating comments could bring pages to the maximum size of ~2MB (technical limitation of SharePoint); switch comment migration off if you experience errors

Other changes

  • new: adding a button to quickly jump to the WikiTraccs.GUI config file folder (to back it up or reset it) image
  • improved: the WikiTraccs.GUI settings now properly initialize with the WikiTraccs.Console default migration settings, when being opened for the first time (e.g. blog post migration is on by default)
  • improved: adding hidden excerpt macros to the default Macro Ignore List image
  • improved: the result of the Show Config as Text option is now more compatible with the appsettings.json format, that is used to configure WikiTraccs.Console

WikiTraccs v1.8.6

Increased visual feedback and improvements

  • new: buttons to quickly jump to log and update folders, directly from the blue WikiTraccs.GUI window
  • improved: more environment checks (log folder writable, WikiTraccs.Console blocked, connectivity for new endpoints)
  • improved: more visual feedback about what WikiTraccs.GUI is doing (connection check, logins, etc.)
  • fix: permission migration is prematurely interrupted by auto-shutdown if no content needs to be migrated
  • fix: progress bars for permission migration did not finish after all pages have been handled

WikiTraccs v1.8.4 (Preview Release)

Confluence Query Language (CQL) and Speed

  • new: select source pages via CQL query - see the updated documentation: Confluence Space Inventory
  • improved: cross-page linking to spaces, pages, and attachments has some edge-cases removed
  • improved: page creation and file upload speed increased up to 42%

Enabling CQL queries required changes to the page selection logic. This Preview Release lacks polishing with regard to:

  • labels/logs reading “space” instead of “CQL selector”
  • documentation needs to be updated to reflect that CQL selectors are an alternative to whole-space selectors

Actual page content migration should be unaffected. Please report any other issues you encounter.

WikiTraccs v1.7.6

Transformation improvements

  • improved: code macro transformation maps macro properties to available settings of SharePoint code web part (language, line number toggle, theme)

Furthermore, the license key format has been unified with WikiPakk, enabling future bundling options. Soon, issued WikiTraccs license keys will need this WikiTraccs release or newer.

WikiTraccs v1.7.4

Transformation improvements

  • new: WikiTraccs.Console will now auto-close after having migrated all scheduled pages
  • new: handling auibutton macros, converting them to links
  • improved: marking expand macro content with horizontal rule elements improves readability
  • improved: nested expand macros and panels don’t produce (de)nested tables anymore
  • improved: nested, invisible bullet point lists are now reduced to a single list, improving readability

WikiTraccs v1.7.1 (Update Mode Preview)

New Feature: Update Mode a.k.a. Delta Migrations

With this release it is possible to update previously migrated and now outdated pages in SharePoint. Updating outdated pages might be necessary when users keep editing pages in Confluence that have already been migrated to SharePoint.

You can read everything about this new feature here: Updating previously migrated pages.

WikiTraccs already detects outdated SharePoint pages and logs them to one of its progress log files. With this release you can mark pages you want to update and feed the file right back to WikiTraccs. WikiTraccs will then migrate the marked pages again, overwriting the stale SharePoint pages.

BREAKING CHANGE: This release changes the format of the 25- progress log file. See Monitoring Confluence to SharePoint Page Migration Progress for documentation of the progress log files.

There are some caveats when it comes to renaming already migrated pages in Confluence, that are highlighted in the documentation as well.

Please give it a try and leave feedback whether this is useful for you or not, and which adjustments you would like to see.

WikiTraccs v1.6.35

WikiTraccs.GUI usability improvements

Based on observations how folks use WikiTraccs.GUI some adjustments were made in the user interface. More stringent top-to-bottom flow, added links to the documentation, and more helpful button states.

Furthermore:

  • fix: Confluence Cloud connection check may fail, but shouldn’t

WikiTraccs v1.6.32

  • fix: attachment links to other pages sometimes couldn’t be properly transformed to SharePoint

WikiTraccs v1.6.31

  • fix: Confluence login for Chrome version 115 and up (#73).

WikiTraccs v1.6.29

  • improvement: hardening against connection errors
    • page creation is now retried several times, with increasing delays
    • space page retrieval and site preparation is retried as well
  • improvement: adding logging for throttling; when the app is throttled by Microsoft this is now visible as log message in the console while it previously could sit and wait for minutes without saying anything
  • improvement: lock busting for site preparation locks; when there was an issue during site preparation the stale lock is now undone after a couple of minutes; this should unblock the most common scenarios where provisioning gets stuck at this point
  • improvement: creating a new log file with every start of the application; this allows for easier log analysis
  • improvement: displaying the version number in WikiTraccs.GUI
  • fix: space processing stops when mapped to an inaccessible SharePoint site; this is now skipped and logged
  • fix: enabling/disabling of minor library versions when migrating to multiple new sites

Note: When running on an AWS EC2 instance, in a private subnet, behind a NAT gateway WikiTraccs’ connections to SharePoint are terminated frequently. This seems to be a known issue in said environment when apps use connection pooling. This release should allow migrating nevertheless as it adds retry loops for certain operations. The migration time thus will be increased in such an AWS environment.

WikiTraccs v1.6.11

Highlighting not-anymore merged table cells

Since SharePoint Online does not support merged table cells WikiTraccs cannot transform tables 1:1 to SharePoint. This release adds markers for table cells that once were merged.

For more details about table transformations and merged table cells refer to this blog post: How to migrate rich Confluence tables to limited SharePoint tables?

:grey_exclamation:Marking merged table cells is the new default.:grey_exclamation:

Note: If you want to revert to the former behavior of not marking merged table cells you can use appsettings.json. This page has the snippet needed to configure this: Sample Configurations

Furthermore:

  • fixed a bug that prevented Confluence blog posts from being migrated to SharePoint when a blog post had the same title as a page

WikiTraccs v1.6.8

Better scheduling for large spaces, and Confluence Cloud login fix

So far WikiTraccs first got the list of pages for a space and then started migrating those pages.

Unfortunately, with increasing page count, Confluence gets slower in providing the page list (see #63). This meant so far that you had to wait quite some time until WikiTraccs started migrating a large space.

This has been changed. After retrieving the first pages for a space WikiTraccs already starts migrating those. This should save some time when migrating large spaces (> 15000 pages).

Getting the pages is done in batches, so a list of 15000 pages is not retrieved at once, but in smaller batches. The batch size so far was 100, this has been increased to 200, which seems to be a maximum. Please open a support ticket if this does not work in your environment.

Two issues around Confluence Cloud have been resolved as well, namely #28 and #65, which prevented successful login detection.

Note: This is marked as a pre-release for now because the scheduling logic changed quite a bit and will be monitored until the next release.

WikiTraccs v1.6.6

This release has two additions to features added in the last releases.

Blog posts that have been migrated from Confluence to SharePoint are now promoted to news posts in SharePoint, so they appear in news web parts.

Hard links on Confluence pages that were detected by WikiTraccs but could not be transformed to page links in SharePoint now increase the “Inaccessible pages” and “Inaccessible links” counter that is available as field in the Site Pages library.

WikiTraccs v1.6.4

Confluence kind of monitors links between pages. When updating the title of a page Confluence takes care of updating incoming links to this page. Those links are called soft links and should be the majority of links. When migrating Confluence pages to SharePoint WikiTraccs takes care of transforming soft links to SharePoint page links.

There is another kind of link - the hard link. Those links are plain old HTML links that Confluence is oblivious of. Technically, they appear like any other text content. And also technically, they lack important metadata that is needed to locate the target page (page ID, space key). Sometimes those links make it into a page. And as long as the target page does not change much this works, until it doesn’t and they break.

With this release WikiTraccs looks out for hard links and tries to figure out the target page. If that is successful the hard link is transformed to a proper page link in SharePoint.

There are some limits to this hard link transformation: it works only for links to pages, not attachments. And it only works for links pointing to the current page version. Hard links to older page versions cannot be converted since older page versions are not present in SharePoint. Also, the link text stays as it is - so a link might look like still pointing to the source Confluence system, yet properly links to the migrated SharePoint page.

This addition should reduce the manual post-migration labor a bit. Feedback is appreciated, either as feature proposal or discussion.

WikiTraccs v1.5.0

Migrating blog posts!

So far the focus has been on migrating Confluence pages to SharePoint with blog posts getting not much demand. But this is something of the past.

WikiTraccs now supports migrating blog posts to SharePoint as well.

Blog post migration can be turned on in the settings dialog that is available in the main menu bar of WikiTraccs.GUI via Settings > Configure Transformation. There, choose Migrate blog posts. WikiTraccs then will pick up blog posts in your next migration.

This setting is turned off by default.

WikiTraccs 1.4.6

Bugfixes and more status info in WikiTraccs.GUI

This release fixes a timezone-related bug that could mark all pages as outdated in the progress log files. Note that this only affects the log files and not page metadata.

Furthermore the progress bars showing space migration progress should now behave and properly reach their end after migrating all Confluence pages of a space to SharePoint.

WikiTraccs.GUI got a small log text field highlighting important information like “X outdated pages were found” or “All done”. This information is also available in the live console window and the log files, but it’s friendlier and quicker to have it right in the GUI.

The behavior of the space migration progress bars has been slightly changed. They will reach 100% even if outdated pages were found and subsequently skipped. But the new log text window will highlight the fact that there were outdated pages. The progress log files then provide a detailed list of those pages.

WikiTraccs 1.4.2

Additional Language Migration Mode

This release adds the first additional language migration mode: migrate all languages of a Confluence page to one target SharePoint page.

This is the new default setting.

image

This is relevant for Confluence pages that have been translated using Scroll Translations. WikiTraccs detects those languages and migrates them all, one after another, into one target SharePoint page.

If you want the old default behavior - migrate only the language with most content - you can switch it back in the settings dialog of WikiTraccs.GUI.

This release also increases the default timeout for Confluence API calls to 5 minutes, up from 30 seconds to better cope with slow responses.

WikiTraccs 1.3.14

More Sanity Checks when using WikiTraccs.GUI

There is a list of nuisances that got smaller with this release:

  • the Confluence connection test now also checks if the API can be reached; so far this only happened when starting the migration, creating a confusing state where the connection test succeeded, but starting the migration might still fail
  • the SharePoint connection test now checks that the SharePoint site addresses point to a site root (subsites are not supported)
  • small formatting fix for the video links introduced in v1.3.13

WikiTraccs 1.3.13

Solving very specific Issues

This release solves two issues that cropped up in migrations.

The first issue is #51 that needs support for handling Confluence images that are in fact… videos. WikiTraccs should now detect those and apply the current default handling for videos: adding a link to the page that points to the video file in the attachments.

The second issue is #46 where it surfaced that Confluence can return duplicate page IDs when being asked for a space’s pages. WikiTraccs now de-duplicates the list of pages that it receives from Confluence which hopefully solves this issue (via #52).

Note: Of tremendous help while diagnosing those issues were WikiTraccs log files. There’s a page dedicated to those log files, where to find them, and how they help: Troubleshooting Strategies. It’s best to always send them over as described on the page.

WikiTraccs 1.3.8

This release fixes an issue where preparing a target SharePoint site failed when running WikiTraccs on a non-English system for a site with non-English default language, with a user that has English set as default language.

WikiTraccs 1.3.7

Reliability and Traceability Improvements

This release improves handling of Confluence user accounts that cannot be found in SharePoint. This sometimes caused WikiTraccs to create an empty placeholder page in SharePoint. This has been tuned down.

WikiTraccs will from now on log the missing account names to the Transaction Log field for affected pages and set the Check Principal Mapping flag. This allows to update editors and authors later, after configuring a proper account mapping.

Furthermore the logging of handled pages has been extended. The number and list of page IDs WikiTraccs got for each space can now be seen in the console and log. This can be used to diagnose missing pages and whether this might be due to permission configuration, or some other reason.

WikiTraccs 1.2.2

Macro Ignore List to exclude macros from the migration

This release of WikiTraccs introduces the Macro Ignore List.

Use the Macro Ignore List to remove certain macros from the Confluence migration to SharePoint. This is useful for macros that are only visible when editing a page in Confluence, but are visible on the SharePoint page after migration.

Read all the details in this blog post: Ignoring macros when migrating pages from Confluence to SharePoint

WikiTraccs 1.1.1

More Migration Progress Insights

With this release WikiTraccs will generate progress log files giving more detailed insights into the migration progress.

Which pages have been migrated from Confluence to SharePoint? Which pages are left? Which pages need an update (in preparation of the update feature to come…)?

Those questions can now be answered. Have a look at the documentation on where to find the files and how to interpret them: Monitoring Confluence to SharePoint Migration Progress

GitHub Releases

Releases are available for download on GitHub.