Filter stream extension to parse a Confluence XML package

Description

Filter module used to read a Confluence XML package. Allow for example to import it into an XWiki instance.

In an XWiki instance it's generally used through Filter Streams Converter Application which needs to be installed separately. Select it as input module and select the output module you want (the instance module to import the confluence package in the current instance for example).

Warning

Importing a Confluence instance is a multi-step process. This tool allows to import an export from Confluence into XWiki pages, but additional specific actions need to be handled, including Nested Pages migration, supporting standard or custom Confluence macros. Also for large instances, some specific issues might occur, such as too long page names or hierarchies that cannot be imported or unsupported macros.

In order to help with this migration, you have the option of contacting a sponsoring company offering software and services to help with it.

Tutorial

To get started with the Confluence Import, you will need to install the Filter Streams Converter Application and this Confluence XML module. You can install these apps using the Extension Manager.

You then need to export your confluence data from the Confluence administration and upload the zip file to the XWiki server. Make sure you make it accessible to the user running your java process.

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

Follow these steps on 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

Note: in some cases, the Java Application server cannot access all the directories from your computer or server. You can try storing the file in a directory used by the application server (root directory of the application server or log directory). Alternatively it is also possible to make your file accessible on a web server and indicate the URL of that file.

After you have completed these steps, click the "Convert" button. After that, you will see the conversion progress. For example:

For example with the following initial page from Confluence:

You'll get the following page in XWiki after you've made the import:

You're all set!

Where is my Confluence hierarchy ?

Confluence has a parent/child relationship based hierarchy which is what XWiki used to have too and what this extension is producing. But in recent versions of XWiki this parent/child relationship is hidden and visually replaced by a path based hierarchy. The extension would need to be improved to automatically convert to this new system by default.

In the meantime the possible workarounds are:

• using Nested Pages Migrator Application after the import to convert the hierarchy
• switch back to the old parent/child hierarchy but it's not recommended since you might break more and more things which expect the new hierarchy system by default

Macro Conversion

The following macros are converted automatically:

• anchor : converted to an id macro

XWiki SAS, a sponsoring company of XWiki, has released the paying "Pro Macros" package which supports a set of Confluence Macros. See the "Warning" section in this document. In particular if you see a "layout macro" error you will need this package.

In addition the importer converts the Confluence macro syntax to the macro syntax for the default syntax defined in your XWiki instance. To avoid collisions with existing XWiki macros which have very little chance to behave as expected macro unknown macros coming from the confluence package are prefixed by default with "confluence_" (it's possible to change the prefix in the filter properties) and an error message will appear saying that the macro cannot be found. You then have several choices:

• Edit the page and manually select an existing XWiki macro to use.
• Create a macro of the same name.

Macro Equivalents

This section is meant to help user pick the closest existing macro in XWiki to match Confluence ones.

• <add here>

Extending Macro Conversion

You can implement a MacroConverter XWiki Component that will we used by this Confluence importer when performing the macro conversions. For that you need to write a component which implements the org.xwiki.contrib.confluence.filter.MacroConverter with a component hint named after the confluence macro id you wish to convert automatically.

Release notes

Release notes can be found on Confluence project page.

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Dependencies

Dependencies for this extension (org.xwiki.contrib.confluence:confluence-xml 9.15.0):

• org.apache.commons:commons-compress 1.20
• org.apache.commons:commons-configuration2 2.6
• org.xwiki.commons:xwiki-commons-filter-xml 12.1
• org.xwiki.platform:xwiki-platform-filter-event-model 12.1
• org.xwiki.platform:xwiki-platform-filter-event-user 12.1
• org.xwiki.platform:xwiki-platform-model-api 12.1
• org.xwiki.contrib.confluence:confluence-syntax-xhtml 9.15.0
• org.xwiki.contrib.confluence:confluence-syntax-confluence 9.15.0
• org.xwiki.platform:xwiki-platform-oldcore 12.1
• org.xwiki.rendering:xwiki-rendering-syntax-xwiki21 12.1