• Prerequisites
• Migration Profile
  • Step 1
  • Step 2
  • Step 3
  • Step 4
  • Step 5
  • Step 6
• Other notes:
• Best practices:

Prerequisites

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

• 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:

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

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":

Fill in the token name and click on create:

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: 

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.

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. 

Step 1

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

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"

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

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

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. 

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".

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.

Step 3

This step will guide you through the Confluence export.

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.

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

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.

Click on "Import" and check the logs. 

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.

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. 

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

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: 

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.

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.

Install the Extension

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

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.

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:

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.

Benefits

What do you get when you purchase an XWiki extension?

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

License

• GNU Lesser General Public License 2.1

Sources

• https://github.com/xwikisas/application-confluence-migrator/tree/master/application-confluence-migrator-ui

Issues

• GitHub

Type

• xar

Developed by

• XWiki SAS

Compatibility

• Requires XWiki 8.4 or above.

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