Ignoring macros when migrating pages from Confluence to SharePoint

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

By Heinrich Ulbricht | Friday, May 19, 2023

Note

The Macro Filter is available as of WikiTraccs v1.2.0.

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:

Note that in above screenshot the macro XML has been formatted before pasting it to the Macro Ignore List. This can be done with text editors like Visual Studio Code or Notepad++ to improve readability. But this is optional and not needed for the Macro Ignore List to work.

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.

Note

You can add multiple macro XML templates into the Macro Ignore List, just put them one after another.

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.

←Previous