Confluence Migrator

Last modified by Administrator on 2024/12/05 00:08

Confluence Migrator

Migrates content from Confluence to XWiki

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

This application is not supported anymore by our team. We recommend using the Confluence Migration Toolkit.

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

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. 

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 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 Notifications listners by clicking on each of the 3 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 from 14.x upwards, 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 from 14.x upwards, 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 and 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

Installation Steps

This paid extensions requires XWiki 14.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

v1.1

Tasks done:

#100 Upgrade parent to 13.10.3

Upgrades:

  • Pro Macros to 1.9.2

v1.0.14

Upgrades:

  • Confluence XML to 9.20.1
  • Nested Pages Migrator to 0.7.6

v1.0.13

Bugs fixed:

  • #97 Spaces with dots are not converted on step 6 (Nested Pages)

v1.0.12

Upgrades:

  • Confluence XML to 9.20.0
  • Nested Pages Migrator to 0.7.5

v1.0.11

Bugs fixed:

  • #89 Links to pages with forward slash "/" break during import

Upgrades:

  • #95 Upgrade nested pages migrator to 0.7.4

v1.0.10

Improvements:

  • #87 Permanently delete archives after import

Upgrades:

  • #93 Upgrade Confluence XML dependency to 9.18.0

v1.0.9

Bugs fixed:

  • Fixed bug #88 (Parents with "/" in the name are duplicated by the nested pages migrator)

Upgrades:

  • Pro Macros to 1.5
  • Confluence XML to 9.15.3

v1.0.8

Bugs fixed:

  • #74 Confluence migration fails from subwikis
  • #82 Nested pages migration cache issue
  • #84 Style is lost from time to time on the migrator
  • #85 Upgrade pro macros and confluence dependencies

v1.0.7

Bugs fixed:

  • #76 Nested pages migrator step 6 not working on XWiki 14+

v1.0.6

Tasks done:

  • #68 Provide a XIP package for offline installation

v1.0.5

Bugs fixed:

  • #66 Import fails if the file has a space in its name

Tasks done:

  • #67 Warn users that nested pages migrator 0.8.x is incompatible

v1.0.4

The following fixes are provided in this version::

  • 642: Support URLs of Confluence instance without the /wiki/ path: Fix export link as well

v1.0.3

The following fixes are provided in this version:

  • 60: Issue with loading of smartwizard css on 13.10.x
  • 61: Support URLs of Confluence instance without the /wiki/ path

 

v1.0.2

Initial version of Confluence Migrator

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.1
  • org.xwiki.contrib.confluence:confluence-xml 9.20.1
  • org.xwiki.platform:xwiki-platform-filter-ui 13.10
  • org.xwiki.contrib:application-nestedpagesmigrator-ui 0.7.6
  • com.xwiki.pro:xwiki-pro-macros 1.9.2
  • org.webjars.npm:smartwizard 5.1.1
  • org.xwiki.contrib:macro-job 2.0
  • org.xwiki.platform:xwiki-platform-office-ui 13.10
  • org.xwiki.contrib.listeneradmin:application-listener-admin-ui 1.0.2