Confluence Migrator

Last modified by Alex Cotiugă on 2021/12/24 00:00

Confluence Migrator

Migrates content from Confluence to XWiki

migrator-13.png
CategoryApplication
Active Installs31
Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
SourcesIssues

The Confluence Migrator is an all-in-one toolkit that allows you to quickly migrate and reorganize your content in only a few minutes, without any cost!

The toolkit is available for any deployment method, whether it is on your premise or in the XWiki Cloud. 

To migrate from Confluence to XWiki you will need: 

  • an XWiki instance with administrator access
  • access to your XWiki instance's configuration files, if you are running XWiki on your premise
  • a Confluence instance with administrator access

The wizard will take you through 6 steps that are needed to complete the migration of a Confluence space. Please follow the instructions in the "Documentation" tab for a full breakdown of each step. 

External Resources

 

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. 

  • Confluence Migrator and the Pro Macros installed on your XWiki instance
  • administrator access to the Confluence instance that you wish to migrate content from

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. 

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. 

migrationn-5.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.cfg file of your XWiki instance and set xwiki.store.cache.capacity to 5000

migrator-5.1.png

  • find the xwiki.properties file of your XWiki instance set notifications.enabled to "false" 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 SOLR and Notifications listners by clicking on each of the 4 links in this section and switching the listner from on to off. 

Please reactivate the SOLR and 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.

The pages that were already imported will not be imported again.

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

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. 

Installation Steps

This paid extensions requires XWiki 11.10 or above. In order to install the extension, follow the next steps inside your XWiki instance (on cloud or on premise).

Navigate to the Extension Manager

In the Applications Panel click on "More Applications..." and then "Install new applications...". Alternatively navigate directly to the Administration and select the "Extensions" section.

step1.png

Install the Extension

Search for the extension you wish to install and use the Install button to install it.

step2.png

Get a License

Navigate to the "Licenses" section of the Administration, fill your details, look for the extension you just installed in the live table and click the buttons to get a trial license or to buy a license.

step3.png

Install the License

If you have selected a trial license then you're good and there's nothing else to do. Your trial license is automatically installed.

However if you've selected to buy a license you'll be redirected to a page to perform the payment. At the end you need to come back to the "Licenses" administration section and click on the "Check for Updates" button. This will download and apply the license you bought.

Use the Extension

Start using the Extension! Refer to the extension's documentation to know how to use it.

Installing Paid Apps on Subwikis

If you want to install an application on the whole farm (main wiki + subwikis), you can do so directly from the main wiki’s Extension Manager, as seen below:

step4.png

Extensions can also be installed only on a particular subwiki by global admins. Subwiki admins will not be able to install these extensions due to their limited rights.

Options

The price is per year and varies depending on the support level and the number of users.

Support / Users

Benefits

What do you get when you purchase an XWiki extension?

1 year license

By purchasing an XWiki extension license, you'll benefit from it during one year.

Free updates

You benefit from all the extension updates during one year. You are always up to date.

Support included

If you are facing an issue, you can reach the XWiki support. Our team is always available to help.

How to Buy

To buy, install this extension from inside your XWiki instance and follow the instructions.

Release notes

Extension details

This information is only displayed to Administrators. Your users can't see this tab.

License

  • GNU Lesser General Public License 2.1

Sources

Issues

Type

  • xar

Developed by

Compatibility

  • Requires XWiki 8.4 or above.

Installable with the Extension Manager

Dependencies

  • com.xwiki.confluence:application-confluence-migrator-api 1.0.2
  • org.xwiki.contrib.confluence:confluence-xml 9.14.2
  • org.xwiki.platform:xwiki-platform-filter-ui 12.10
  • org.xwiki.contrib:application-nestedpagesmigrator-ui 0.7.3
  • com.xwiki.pro:xwiki-pro-macros 1.2.1
  • org.webjars.npm:smartwizard 5.1.1
  • org.xwiki.contrib:macro-job 2.0
  • org.xwiki.platform:xwiki-platform-office-ui 12.10
  • org.xwiki.contrib.listeneradmin:application-listener-admin-ui 1.0.2
Tags:
XWiki SAS Copyright © 2021