Confluence to XWiki migration guide: from export to customization

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

Important updates

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

📢 Join us on May 30, 2024, 16:00 CET, for a new webinar where we'll showcase the latest macros and improvements for an even faster and easier migration from Confluence to XWiki! Save your seat here.

💻 You can also check out our previous webinar article which will provide you with insights on all the features of the new Confluence Migrator (Pro), a demo of the migration process, and the transcript for the Q&A session.

This guide has been updated on the 16th of May, 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!


  • an XWiki instance with administrator rights
  • access to your XWiki instance's configuration files (if you are running XWiki on premise)
  • Confluence Migrator Pro, Pro Macros and Task Manager Pro installed on your XWiki instance
  • if you wish to migrate Blog posts too, install the Blog Application as well
  • 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. 


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.


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. 


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: 


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. 


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. 


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. 


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.


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.


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.


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 Pro Macros bundle. 

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 Pro Macros package, the content will subsequently be displayed identically to the Confluence counterpart following the update and introduction of said macro in the Pro Macros.

If one or multiple macros are required, the Client may choose to sponsor the development of those macros. Please contact 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?


You may also be interested in:

Best practices

Run your on-prem wiki instance like a pro with Admin Tools Application (Pro)

XWiki SAS has released the Admin Tools Application (Pro) v1.0, one of the many business-ready Pro Apps, available in the XWiki SAS store. Through this app, you can optimize your XWiki on-prem installation, maintenance, and resources allocation — all from one central dashboard. Read the full article here.