Confluence XML
 | Filter stream extension to parse a Confluence XML package |
| Type | JAR |
| Category | |
| Developed by | |
| Active Installs | 176 |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
Table of contents
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.
XWiki SAS, a sponsoring company of the XWiki Open Source software, is providing software and services to help with the migration:
- The paying macro package has been released and is available on the XWiki SAS store: https://store.xwiki.com/xwiki/bin/view/Extension/ProMacros/
- XWiki SAS is working on a migration package to handle all steps of the migration in one application. This package is currently in development.
- XWiki SAS can provide services to analyse a Confluence instance and study what is needed to migrate it (which package, which process, what macros are needed).
You can contact XWiki SAS on the XWiki SAS web site: https://xwiki.com
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
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.
Events
As of version 9.21.0, two events are emitted ConfluenceFilteringEvent and ConfluenceFilteredEvent. ConfluenceFilteringEvent is sent after the package has been read, but before the actual filtering has begun. ConfluenceFilteredEvent is sent after the filtering is done but before closing the package. Both the events carry the confluence package as data.
Reusable tool to parse and analyse a Confluence package
The main job of this extension is to provide an input filter to convert a Confluence package into something else, but it's also exposing its parsing and analyzing tooling as an API.
To parse a Confluence package, you can inject and use the component org.xwiki.contrib.confluence.filter.input.ConfluenceXMLPackage:
private Provider<ConfluenceXMLPackage> confluencePackageProvider;
public void analyze()
{
// Create a new instance of ConfluenceXMLPackage component
ConfluenceXMLPackage confluencePackage = this.confluencePackageProvider.get();
// Parse the packaged located on the file system (but support any org.xwiki.filter.input.InputSource which lead to a zip content or a directory)
confluencePackage.read(new DefaultFileInputSource(new File("path/to/the/confluencepackage.xml.zip")));
// Call the various getters of ConfluenceXMLPackage
}
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.29.0):
- org.apache.commons:commons-compress 1.22
- org.apache.commons:commons-configuration2 2.8.0
- org.xwiki.commons:xwiki-commons-filter-xml 14.10
- org.xwiki.platform:xwiki-platform-filter-event-model 14.10
- org.xwiki.platform:xwiki-platform-filter-event-user 14.10
- org.xwiki.platform:xwiki-platform-model-api 14.10
- org.xwiki.contrib.confluence:confluence-syntax-xhtml 9.29.0
- org.xwiki.contrib.confluence:confluence-syntax-confluence 9.29.0
- org.xwiki.platform:xwiki-platform-oldcore 14.10
- org.xwiki.rendering:xwiki-rendering-syntax-xwiki21 14.10
