Atlassian Confluence is a popular collaboration platform used by many organizations around the world. Users are accustomed to relying on Confluence for meetings, memos, wikis, and project management; however, Atlassian recently announced that they are discontinuing the server edition in favor of a cloud-only configuration.

Many customers with sensitive information, such as research companies in the high-tech industry, lawyers, financial service providers, and journalists, are concerned about moving all their collaboration data to the web. Others, even if they aren't in particularly sensitive industries, might not want to give their data to the cloud for any number of policy or practical reasons.

Even as some Confluence admins grapple with the challenge of moving to the Atlassian cloud, others are looking for alternatives that will let them keep their data local and avoid the vendor lock-in of proprietary tools like Atlassian Confluence, but migrating data is often time-consuming, although it is possible. The transfer of Atlassian data to a new system is typically the most complex task during migration.

Users who want to leave will usually not receive any help from Atlassian, and Confluence support service providers expect good money for their help. To make matters worse, Confluence is different from most wikis. Unlike its open source competitors, Confluence manages individual pages in "workspaces," has its own access rights, and handles subordinate pages, as well as numerous macros. Some of these features might not correspond directly to equivalent features in the alternative tools.

Confluence administrators are happy to see that export functions are available, at to least export the content to, for example, XML, so those who know how to use scripts will achieve quick and good results manually.

A pair of leading open source wiki tools advertise migration assistants to help you migrate your Confluence data. One of those tools, XWiki, is fully open source once everything is moved over, but their supported migration assistant costs EUR1,900 after 30 days (see the "XWiki" box). Another enterprise alternative that offers a less restrictive migration path is BlueSpice.

XWiki

French company XWiki produces the Java-based open source software of the same name and has been successful in many setups, including as a part of the digitally sovereign openDesk [1] web desktop from the German and French governments. Although anything else in XWiki is free, the company has not made the supported version of its migration tool available as open source software.

For EUR1,900, the customer receives the Confluence Migration Toolkit [2], which interested parties are allowed to test for 30 days free of charge after entering a test key [3]. A free license (trial) for the Migration Toolkit is available on request at any time. The XWiki customer must send their instance ID to the manufacturer and enter it in the Global Administration | Licenses section under Add License (Figure 1).

Figure 1: The XWiki migration wizard is available for a fee. Users need a registration key for the 10-day test and a number of other XWiki extensions. © XWiki [2]

XWiki offers a number of resources, including a blog with numerous articles about migration and 60 supported Confluence macros [4]. The XWiki Migration Toolkit also has a guided migration process that the manufacturer has integrated directly into the XWiki web interface.

BlueSpice

BlueSpice, which is developed by the company Hallo Welt! [5], is available as open source on GitHub, including the scripts tested in the example in this article. The company advises its customers to seek support during the migration process, perhaps because of the business model or the complexity of the tasks. In many cases, migrating everything on your own might seem unrealistic, but with BlueSpice, the attempt is possible, even without the manufacturer's help, thanks to open source migration scripts. Some American universities and institutions have done so without support from the vendor, even from Atlassian's products to BlueSpice's upstream project, MediaWiki, with the use of Hallo Welt! tools.

Migration with BlueSpice takes five steps: provide infrastructure (server, storage, network, installation), extract content, check data homogeneity, correct language and media, and integrate [6]. The initial macro check is followed by the XML export from Confluence and then migration with data import and checking. Many Confluence installations use macros (built-in or programmed by third parties) to prepare, link, and display content. So many of these macros exist that not all of them can be supported by BlueSpice or XWiki.

Hallo Welt! offers a test on its website that you can use to find out which macros are supported during migration: Macro management is also found in the data management settings in Confluence, where you can select all macros and copy them to the clipboard (Ctrl+C). On the BlueSpice website [6] you will then find the live macro check, where you can paste the macros found (Ctrl+V) and click Check (Figure 2).

Figure 2: The BlueSpice macro wizard has found an unknown macro – manual work is necessary.

Exporting a Space to XML

Once all macro problems have been resolved, the next step is to transfer an entire space from Confluence to BlueSpice (Figure 3). Confluence can export data to CSV, HTML, XML, and PDF (Figure 4). XML is the best choice when it comes to structured data migration (and as in the following example, neatly packaged in an archive).

Figure 3: In the Space settings of Confluence …

Figure 4: … you will also find the settings for data export.

During migration, the data is extracted from Confluence and the archive is stored on the BlueSpice server or the administrator's working machine. The subdirectories input and workspace must be created, and the Confluence archive is unpacked to input. Now it is time to get the migration tools from GitHub [7] and test their functionality; you will need the well-known universal documentation tool pandoc and more (all documented in the README.md file).

The scripts prepare the data for import, which ends up in the workspace/result subdirectory. Now the migrate-confluence migration script (from GitHub) can be started.

Starting the Migration

The migrate-confluence.phar file is called four times in succession: once to analyze the data (analyze, Figure  5), then to extract (extract), convert (convert), and finally compose in the new format (compose).

The following illustrations show the syntax in examples and the feedback from the system for a simple Confluence space, as well as the result in the directory tree. The parameter --config=config.yaml in the analysis is only necessary if you have defined special configuration options in a YAML file. If you use it, you must specify it in the first three steps.

The command

php migrate-confluence.phar analyze --src=input -dest=workspace

analyzes the data and stores files with this information in the workspace directory. The analyze parameter prepares the export. The -config= parameter (as used in Figure 5) is only necessary if the optional configuration mentioned earlier is used; otherwise, it can be omitted. The output provides information about the exported content.

Figure 5: The BlueSpice migration assistant analyzes the data.

In the second step, the command,

php migrate-confluence.phar extract --src=input --dest=workspace --config=config.yml

takes the exported and analyzed data from Confluence and stores it in the destination – in this case the workspace directory (Figure 6). Now, the command

php migrate-confluence.phar convert --src=workspace --dest=workspace --config=config.yml

Figure 6: The content is being converted.

takes the data from workspace and converts it into a format that can be imported by BlueSpice (Figure  7). The workspace directory now usually contains numerous raw files with the prepared Confluence export. The last step (if everything went well) is to use the compose option,

php migrate-confluence.phar compose --src=workspace --dest=workspace

Figure 7: The compose command compiles the raw data extracted from Confluence and stores it as XML files.

to assemble the various elements. The successfully converted export can now be found under workspace/result.