Confluence to XWiki migration guide: from export to customization

25 May 2020 5 min read
Written by Stefana Nazare, Account Manager

Last updated on the 8th of November 2024

🎉 We just launched our new Confluence Migration Toolkit. This is a bundle with all the apps and services that you need to quickly transfer data but also benefit from long-term technical support, including the Confluence Migrator (Pro). Read more about the launch here.

👉 Discover our new Confluence Migrator (Pro) and the 2 steps process to migrate smoothly to XWiki!

💻 You can also check out the article about our latest webinar, which will provide you with insights on all the latest advancements in our migration tools and detailed insights into the migration process. 

This guide has been updated on the 7th of August, 2024.

The number of organizations that choose to migrate from Confluence to XWiki is significantly growing these days due to better organization features, structured data, price reduction, full control over data, extensibility, and many other benefits. If you are considering migrating from Confluence to XWiki but you are not 100% sure yet, you can check out our full comparison between these two products.  

If you are ready to migrate, here's how to do it!

Prerequisites

  • An XWiki instance with administrator rights;
  • Access to your XWiki instance's configuration files (if you are running XWiki on-premises);
  • Confluence Migrator (Pro), Pro Macros and Task Manager (Pro) installed on your XWiki instance. All these come together by default in the Confluence Migration Toolkit;
  • If you wish to migrate Blog posts too, you can find the Blog Application included by default as well in the Confluence Migration Toolkit;
  • Administrator access to the Confluence instance that you wish to migrate content from or a server XML backup file.

Once you have installed the Confluence Migrator Pro, open the prerequisites section and perform the necessary configuration in order to make sure the XWiki instance will support the data migration. 

migrator-1.png

If a prerequisite is met, a checkmark will appear next to its respective line in the dedicated section. 

Data migration

Upload export package into XWiki

In order to migrate your data, first attach the Confluence backup file in the dedicated section of the migrator. 

Note that if you are using a trial, you will be able to import one space and up to 30 pages per migration. All the other functionalities (prerequisites, import configuration, migration report, simultaneous migrations etc.) are available in the trial version. In order to unlock the full capabilities please obtain a license.

migrator-pro-data-import.png

You will be able to attach multiple files and start the data migration from any of them. It is also possible to use a space export. If your Confluence backup fails to upload please make sure that your XWiki instance has enough storage and memory, and also that the attachment limit is not too low. If you are using XWiki in the Cloud, please contact the support team, in order for them to perform the necessary configuration. 

Once you have identified the export file that you wish to use, click on "Select package". You will be redirected to the title page, where you can name your migration and configure the import options. 

migrator-pro-set-title.png

Select export package from server

Alternatively, if the Confluence export packages are placed on a machine that XWiki has access to, please use the "Select an export from server" option: 

migrator-2.png

If you wish to modify the default import configuration, for example, to skip user import or to not preserve history, click on "Advanced migration options". Please see the documentation on each parameter of the Advanced migration options. 

migrator-pro-fs-config.png

Once you are satisfied with the configuration, click on "Save & View". You will be redirected to the package analyser step. The analysis of the package may take a while if the export is very large. 

migrator-pro-analyser.png

Once the analysis of the package is done, the list of spaces will appear. You can select all, multiple or one space and search for a space based on their key. 

migrator-pro-list-spaces.png

After you have selected all the spaces that you wish to migrate in this run, click on "Confirm". You will be redirected on the import log page. The process of importing the pages into their correct location may take a while if the export is very large.

migrator-pro-import-step.png

Finally, when the data migration is done, you will be redirected to the report page, where you will see the pages that have been successfully imported, along with the ones affected by errors.

migrator-4.png

You will be able to also later review the report by clicking on the migration page in the application's homepage. Moreover, you can run multiple migrations in parallel and see their status.

migrator-pro-migration-status.png

Supported confluence macros

XWiki and Confluence both have their sets of macros, usually used to present content in a particular manner. In order for a macro used in Confluence to display in the same manner in XWiki, the macro has to have the same name and supported parameters. In an effort to make the transition as easy as possible for organisations that migrate from Confluence to XWiki, the Pro Applications team has dedicated significant efforts to creating XWiki macros identical to the most used Confluence macros. These macros are all present in the Confluence Migration Toolkit

For the macros that do not support migration and that are used on the Confluence instance, the wiki content will be imported, but they will not be displayed in XWiki identically to the Confluence counterpart. In view mode, an error message will appear, while in wiki edit mode, the syntax and content of the macro will be visible. As the wiki content will be imported and stored, if one of the currently unsupported macros will become available in the Confluence Migration Toolkit, the content will subsequently be displayed identically to the Confluence counterpart following the update and introduction of said macro in the toolkit.

If one or multiple macros are required, the Client may choose to sponsor the development of those macros. Please contact sales@xwiki.com if you would like to inquiry about the development of certain macros.

Need some extra help?

XWiki SAS's architects can help you migrate and organize your Confluence content in your new instance or create the bridge macros that you need. Additionally, we offer complimentary consulting, custom development, and design service, through which we set up, configure, and customize your instance in order to perfectly meet your needs. 

Finally, we offer support subscriptions that will provide you the technical help required to achieve your objectives with your wiki in a timely manner. The technical support will guarantee the well functioning of your instance as our team will fix the issues that you might encounter and will guide you into setting up and configuring your wiki. 

Want us to evaluate your migration project?

SCHEDULE A CALL WITH AN XWIKI SPECIALIST

You may also be interested in:

Best practices

How Santa's elves manage Christmas operations with XWiki

Santa may get all the glory, but it’s the elves, backed by XWiki, who ensure all operations run smoothly like butter biscuits and Christmas magic happens on time. Learn what features are of great help for the elves in supporting Santa Claus to deliver Christmas.

Best practices

Webinar overview: A hands-on guide to migrating from Confluence - Why it’s more than just a technical shift

On November 28th, XWiki SAS hosted a webinar on migrating from Confluence to XWiki. Led by Ștefana Nazare, Product Owner of Pro Apps and an experienced Confluence migration expert, the session offered participants actionable strategies and essential tools for a smooth transition.

Best practices

A hands-on guide to migrating from Confluence - why it’s more than just a technical shift

Discover how migrating from Confluence to XWiki can transform your team's collaboration. Learn about the benefits of open-source freedom, complete data ownership, and flexible customization. XWiki SAS's expert-built Confluence Migration Toolkit ensures a seamless transition with minimal disruptions, backed by continuous support and evolving tools. Ready to make the switch? Join XWiki SAS's webinar!