Experiences with Migrations to Atlassian Confluence

For some time past Communardo offers a migra­tion ser­vice to migrate data from exis­ting legacy sys­tems into Atlassian Confluence. During this pro­cess the Communardo pro­duct Content Import Plugin (CIP) is used. This plugin is avail­able with a free eva­lua­tion license and can be down­loa­ded from the Atlassian Plugin Exchange. You can order a full license in the online shop. So cus­to­mers can per­form migra­ti­ons on their own without using the migra­tion service.

This arti­cle descri­bes some of our expe­ri­en­ces with actual migra­ti­ons. It is tar­ge­ted to cus­to­mers who want to per­form a migra­tion on their own and to cus­to­mers who want to use our migra­tion service.

How Migrations are Performed

Migrations with the CIP are per­for­med in two steps. First, the data is expor­ted from the source sys­tem to an XML trans­port for­mat. As a second step this XML is impor­ted into Confluence with the CIP.

The trans­port for­mat con­tains all types of con­tents (spaces, pages, blog posts, attach­ments) with their meta data (aut­hor, crea­tion date, modi­fi­ca­tion date). Additionally the page hier­ar­chy and inter­nal links are supported.

The Customer's Expectations vs. Feasibility

Our pre­vious expe­ri­en­ces showed that cus­to­mers usually have high expec­ta­ti­ons of the migra­tion. These are often

• com­ple­teness of migra­ted data
• same lay­out after the migration
• kee­ping functionality

The com­ple­teness of the migra­ted data is pro­vi­ded from by the trans­port for­mat. All pages and their con­tents are cove­red by that and hence can be migra­ted into Confluence.

What is not always pos­si­ble is kee­ping the same lay­out and pos­si­ble func­tio­n­a­lity by JavaScript. This figure illus­tra­tes the under­ly­ing problem:

The cir­cles are stan­ding for the fea­ture set and lay­out abi­li­ties of dif­fe­rent markup for­mats. HTML has the big­gest fea­ture set and the most pos­si­ble vari­ants. With Confluence wiki code it is pos­si­ble to for­mu­late many of HTML's fea­tures. But there are some func­tio­n­a­li­ties that are not pos­si­ble with HTML (e.g. macros). The same app­lies for MediaWiki code.

Looking at this dia­gram it beco­mes clear that it is not pos­si­ble to migrate MediaWiki code lossless to Confluence wiki code. They do not share the exact same fea­ture set. MediaWiki knows some con­cepts that are not pos­si­ble with Confluence wiki code (e.g. mer­ged table cells). When migra­ting from plain HTML to Confluence there are also some fea­tures that are not pos­si­ble in Confluence (e.g. defi­ni­tion lists).

In some cases it is pos­si­ble to find alter­na­tive markup vari­ants that pro­vide a simi­lar result in Confluence. So defi­ni­tion lists could be repla­ced with nes­ted unor­dere lists. However, for nes­ted tables there is cur­r­ently no pos­si­ble coun­ter­part in Confluence.

Another pro­blem is the style of cer­tain ele­ments. A hea­ding could look a lot other after a migra­tion from MediaWiki to Confluence. The con­tent of the hea­ding was indeed migra­ted com­ple­tely but the hea­ding looks com­ple­tely dif­fe­rent after­wards. Formatting rules descri­bed in CSS can­not be migra­ted. To get a similar-looking result one has to define new Styles for Confluence or deve­lop a Theme Plugin.

Examples for other Migration Challenges

The next para­graphs describe some pro­blems we came across in our last migra­tion pro­jects. So you can get a feel of tech­ni­cal limi­ta­ti­ons in migra­tion projects.

Layout Tables

Until some years ago it was quite usual to use tables for web­site lay­outs. These are tables that have no visi­ble bor­ders. For an aut­hor of a web­site it was an easy way to build nice lay­outs with ele­ments posi­tio­ned side by side. So a navi­ga­tion bar could be near the content.

Unfortunately Confluence does not know the con­cept of bor­der­less tables. So it is not pos­si­ble to migrate such a lay­out table without dif­fe­ren­ces in lay­out. The lack of sup­port for nes­ted tables boost this pro­blem even more.

Tables with Merged Cells

With HTML it is sim­ply pos­si­ble to merge some cells of a table in hori­zon­tal (col­span) or ver­ti­cal (row­span) direc­tion. This is often used for table hea­dings that span more than one table row.

Since Confluence has no pos­si­bi­lity to markup span­ned table cells these can­not be migra­ted without los­ses in lay­out or even content.

Hand-Crafted HTML

If you try to migrate hand-crafted HTML you run into real trou­ble. Many con­tent manage­ment sys­tems use WYSIWYG (what you see is what you get) edi­tors for crea­ting or edi­t­ing con­tents. These edi­tors do not show the source HTML directly but the for­mat­ted result as it will appear on the web­site later. The big advan­tage is that these edi­tors gene­rate uni­form HTML.

For such con­tent it is pos­si­ble to reco­gnize pat­terns of same markup and to trans­form them into Confluence code. If the page markup was hand-crafted no such pat­terns exist. So it is extre­mely hard to find pat­terns for trans­for­ma­tion. As a result you have to accept severe for­mat­ting losses.

Internal Links

Often it is quite hard to migrate inter­nal links. Sometimes the links of the source sys­tem are bro­ken, so it is not pos­si­ble to find the cor­rect link tar­get. Sometimes it is necessary to choose from mul­ti­ple pos­si­bi­li­ties and take the "best-fitting link target".

Sometimes it is pos­si­ble to change the the struc­ture of the data or add some gene­ra­ted con­tent. This is the case when the migra­tion should gene­rate some over­view pages that didn't exist in the source sys­tem or that were gene­ra­ted by the sys­tem. The com­ple­xity for fin­ding the tar­gets of inter­nal links is incre­a­sed extre­mely by this.

Structural Mapping

Confluence offers the fol­lowing pos­si­bi­li­ties to struc­ture information:

• Spaces with pages and blog posts
• Child pages of pages (tree structure)
• Attachments on pages or blog posts

If there are struc­tures in the source sys­tem that go bey­ond Confluence struc­tu­ral abi­li­ties (e.g. mul­ti­lin­gual con­tents) there is no way to migrate these infor­ma­tion directly into Confluence. Only by using third-party plugins (e.g. the Communardo SubSpace Plugin for space hier­ar­chies) the migra­tion is possible.

Unpredictable Behavior of the inter­nal Wiki-Code Converter of Confluence

The trans­for­ma­tion of HTML to Confluence wiki code is per­for­med by Confluence's inter­nal wiki code con­ver­tert. This com­po­nent has some issues with the trans­for­ma­tion of any HTML (that was not gene­ra­ted by Confluence its­elf) into wiki code. Even the smal­lest dif­fe­ren­ces in the input (like line breaks or dif­fer­ently nes­ted HTML ele­ments) may result in com­ple­tely dif­fe­rent wiki code. Especially when migra­ting hand-crafted HTML migra­tion los­ses are not avoidable.

Conclusion

The migra­tion of con­tents into Atlassian Confluence is nearly lossless pos­si­ble with the Content Import Plugin. The for­mat­ting of this infor­ma­tion howe­ver has to be adjus­ted to Confluence and dif­fers in the most cases from the for­mat­ting that was shown by the source sys­tem. Furthermore it is not pos­si­ble to migrate con­cepts or func­tio­n­a­lity that exis­ted in the source sys­tem but that does not exist in a simi­lar form in Confluence (e.g. defi­ni­tion lists, nes­ted tables, …)

Related Links

• Description of the Migration Service (PDF, german)
• Product Description of the Content Import Plugin
• Description of the XML Transport Format (PDF)
• SubSpace Plugin