Confluence to XWiki migration guide: from export to customization

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

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!

1. Pre-requisites

  • Confluence instance: Make sure you have the "Export Space" permissions in your Confluence instance in order to be able to perform the export. 
  • XWiki instance: You will need an XWiki server with server access.
    • Self-installation on your premises: If you would like to learn more about the best installation methods, you can check out our guide here.
    • Installation performed by XWiki specialists, on your premises: If you do not wish to handle the setup, you can also have the XWiki SAS specialists perform the installation and configuration of your new instance, on your premises. 
    • Cloud installation: If your XWiki instance is already hosted in our Cloud, you will just need to reach out to our support team and they will add the export file on the server. 

2. Prepare your files

  • Export the Confluence content that you wish to import into your XWiki instance in XML format.
  • Upload the zip file on the XWiki server. Make sure that the file is accessible to the user running your java process. If your XWiki instance is hosted in our Cloud, please contact the support team and they will handle it for you. 
  • Install Confluence XML module and Filter Streams Converter Application on your XWiki instance through the Extension Manager
    • For the Filter Streams Converter Application, make sure you select the version equivalent to your XWiki version. 
  • If you have Spaces in your Confluence instance, create their equivalents in sub-wikis in your XWiki instance. 

3. Run the migration

After you have installed the two extensions, click on the Filter Stream Converter entry from the Applications panel.

Follow these instructions as shown in the screenshot below:

  • Choose the "Confluence XML input stream (confluence+xml)" input type
  • Fill in the source field which contains "file:" followed by the path of the Confluence zip file, located on the machine where XWiki is running
  • Choose the "XWiki instance output stream (xwiki+instance)" output type to import the Confluence pages in your wiki


After you have completed these steps, click the "Convert" button. After that, you will see the conversion progress. It will look like this: 


After a refresh, you will see your new pages in the navigation panel on the left. 

4. Organize your new content

  • This is the perfect moment to consider the architecture of your new XWiki instance. A good content organization is one of the pre-requisites to an excellent platform, where users can create, find, and share information easily. You can draft the main sections of your wiki, decide if you will use sub wikis or only spaces, create AppWithinMinutes and think about content linking using page links, tags, or page relations. Moreover, you can delete or archive documents that have not been used for a long period of time. 
  • After you have drafted the structure of your pages on the XWiki instance, use the Nested Pages Migrator in order to create the hierarchical organization of your pages. Some pages will, therefore, become "parent pages" (spaces) that will have "children pages".
  • Lastly, do a final evaluation and move around the pages where they fit best. 

5. Solve potential compatibility issues

Both in XWiki and Confluence, you have the option to use macros. XWiki offers more than 170 macros that you can use to style content, display information in a special way, create dashboards, and many others. While some of the Confluence macros have an equivalent in the XWiki ones, some do not. Therefore, for the macros that are not mapped in XWiki, you will need to either create bridge macros and map them or re-create them in XWiki.

You can also run a quick Database Search to check how many times are the macros used in the pages that you have imported from Confluence. This could help you decide if you want to re-create them or not. 

6. Users and rights management

Map the users and recreate the permissions scheme, using our powerful, fine-grained Rights Management System.  You will be able to define view, comment, edit, script, delete, admin, and program rights per user or per group, at global, sub wiki, space, or even page level.

Moreover, you can set up another Authentication method such as Active Directory, Social Login, SSO, or Custom authenticators. 

7. Need some extra help?

XWiki SAS's architects can help you migrate and organize your Confluence content in your new instance. 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: