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!

💻 You can also check out our webinar article which will provide you with insights on all the new 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 8th of March, 2023.

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!

Dedicated Migrator method:

Prerequisites

  • an XWiki instance with administrator rights
  • access to your XWiki instance's configuration files

Access to XWiki configuration files is necessary only if you are executing the migration on an instance installed on your premise. 

Migration Profile

Click on the Confluence Migration application installed on your instance to begin the process. Create a migration profile for each space that you wish to migrate:

migrator-1.png

Fill in the following information: 

  • Title of your profile 
  • Username of your Confluence user
  • Confluence token
  • URL of your Confluence instance
  • The key of the space that you wish to migrate

migrator-2.png

In order to generate a token, click on the "Api Token link". This will redirect you to the security administration section of your Confluence instance. Click on "Create API token":

token-1.png

Fill in the token name and click on create:

token-2.png

Copy the API token and make sure you store it somewhere safe. You won't be able to view the token again in your Confluence instance: 

token-3.png

Go back to your XWiki instance, fill in the token and save the migration profile. This will redirect you to an intermediate step, where the connection with your Confluence instance can be tested.

migrator-3.png

If the connection is successful, start the migration. Otherwise, check again the information filled in the migration profile and verify if you are still logged into your Confluence instance. 

If you are running an XWiki installation newer than 14.x, the connection to the Confluence instance is not necessary as the long hierarchy conversion is automatically done through a new core feature. 

migrator-4.png

Step 1

The first step of the migration is dedicated to preparing the XWiki instance from an infrastructure and performance point of view. 

migrator-new-prerequisistes.png

The first part of this process is only necessary if you are executing the migration on an instance installed on your premise. 

1. Processes that require XWiki configuration file access

  • increase the memory allocated to your XWiki instance
  • find the xwiki.properties file of your XWiki instance and set notifications.enabled and notifications.emails.enabled  to "false"

migrator-5.2.png

Restart your XWiki instance.

2. Processes done inside the XWiki instance

  • go to your Profile, in the Notifications section and choose "Never" for automatic page watching. Also, deactivate any application notification that you may have set

notifications-1.png

notifications-1.2.png

  • manually deactivate notification filters or click on "Clean Notification Preferences" to automatically erase the notification filters set. 

notifications-2.png

Please reactivate configure the notifications as you prefer once the migration is done. 

  •  deactivate Notifications listners by clicking on each of the 4 links in this section and switching the listner from on to off. 

Please reactivate the Notifications listners once the migration is done. 

Step 2

This step will perform an analysis on your Confluence instance to check for hierarchies that are too long and pages that were already imported in your XWiki instance.

To run the analysis, tick the boxes and click on "Start analysis".

migrator-6.png

The hierarchies that are too long may not be properly imported. If this script finds too long hierarchies, we suggest shortening the name of the pages in those hierarchies in the Confluence instance before importing.

If you are running an XWiki installation newer than 14.x, please skip this step as the long hierarchy conversion is automatically done through a new core feature. 

Step 3

This step will guide you through the Confluence export.

migrator-7.png

After the checks in step 2 are performed, go to the Confluence Space that you wish to migrate and click on "Space Settings" in the left panel.

space-export-11.png

Click on "Export space" and then choose the "XML" format.

space-export-2.png

space-export-3.png

Choose the pages that you wish to export, download the zip file and go back to the XWiki instance. 

Step 4

This is the step where your Confluence content is imported into the XWiki instance. 

Click on "Choose files", and select your Confluence zip export.

migrator-8.png

If you are migrating on an instance installed on your premise, you can do the following alternative step: Do not upload the Confluence export archive, but click on "Advanced setup", find "The source" field and fill in the path of the file on your machine:

migrator-9-1.png

Click on "Import" and check the logs. 

migrator-10.png

Step 5

In this step, the imported documents will be verified to check if all the parent pages are valid. 

Run the tests and click on "Fix invalid parents" if you find pages with errors.

migrator-11-1.png

If you are running an XWiki installation newer than 14.x, please skip this step as the long hierarchy conversion is automatically done through a new core feature. 

Step 6

At this point in the migration, your pages will be imported under one parent. This step will organize your documents in the same hierarchies that they were in Confluence. 

First, click on "Compute Plan" and look at the proposed hierarchy. You can choose to unselect certain documents so that they are not moved under parent pages. 

migrator-12.png

Once the plan is in order, click on "Execute plan". Your pages will be moved under the correct parents. 

migrator-13.png

After the nested pages migration is done, click on "Finish" to end this migration profile. You will be redirected to the profile page and you will see the newly imported and organized document in the navigation tree on the left. 

Other notes:

  • You can see all the migration profiles that were created in <yourxwiki>/xwiki/bin/view/Confluence/Migrator/Profiles/.
  • A full report on all the analyses performed is available in your migration profile. 
  • If you would like to restart a migration click on the "Restart migration" button, above the steps arrow. This will delete any pages that were imported through the current migration profile. 

Best practices:

1. When migrating, create a sheet with all the spaces that you wish to import and the state for each one of them. Here is an example: 

migration-execution-best-practice.png

2. If a space has pages that were not properly imported (usually if there are special, unsupported characters in the content or if the page is created through an unsupported editor) please fix the pages in Confluence and create a custom export (with the fixed pages) and then import them through a second profile in XWiki. For example, let us say that we do a first import for space "DOC", through the profile "Documents 1" and we have 120 total pages, but 3 pages were skipped because they contained unsupported characters. After fixing the pages in Confluence, export space "DOC", via custom export, select only the 3 fixed pages, and name your export "DOC2". Then, on the XWiki side, create profile "Documents 2" and import the "DOC2" export, containing the 3 fixed pages. 

3. If you are running an XWiki version from 14.x upwards, please skip the connection to the Conflunce and Steps 2 and 5

4. After starting the Import (Step 4) and Nested Pages Migration (Step 6) make sure that the jobs were finished before triggering another one. In order to verify if the import or nested pages migration jobs were done, please make sure the following conditions are met: 

  • you received the "Current conversion - Done." and respectively "The plan have been executed!" messages;
  • you do not see any new processes appearing in the browser Network.

migrator-process.png

Manual Method:

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. 

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. 

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

filterconverter.png

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

file-streams-conversion-done.png

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

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. 

After the migration:

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 to the XWiki ones, some do not. Therefore, for the macros that are not mapped in XWiki (identical macro does not exist in XWiki), you will need to either create bridge macros or use the equivalent macros that exist 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. 

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. 

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: