Love it or hate it, there’s often of a lot of value to your organisation in the content of your existing Wiki. The effort that went into creating it shouldn’t be forgotten. Your options might be to park it up and switch the lights off (and hope nobody notices), leave it running in background, or, bight the bullet and commit to taking the invaluable mine of information forward to your new wiki. If like me, the mere thought of manually migrating content invokes suicidal tendencies, then here’s a great approach. UWC – the Universal Wiki Converter…
What is Universal Wiki Converter (UWC)?
You may (or may not) have seen this in your Confluence Admin page somewhere and thought, “Maybe I will use it one day” or “What is this?” or, “Meh, don’t really care!” I had those thoughts too until I was thrown in at the deep-end to use it. Long story short, this is a tool that helps convert quite a lot of Wiki’s into Confluence compatible pages. Developed by Atlassian and then by AppFusions for Confluence 4+, it is very useful for transferring Wiki content to Confluence taking away much of the pain in the process. Most of the automation is done through the scripts that are already built-in.
What follows is a short explanation of how to convert a MediaWiki into Confluence pages using Mac OS. It can also be used in Linux and Windows.
The MediaWiki that I encountered was written in PHP, but that’s not our concern for now – thanks to the tool! However. you need to know what type of Wiki you are converting as with UWC, it doesn’t support them all. Here’s as list of Wiki’s currently supported by UWC:
The above list can also be found on the following link
Step 1: Download UWC
Click here to download a zipped version of UWC.
Run either uwc.jar by double clicking on the file OR open the terminal and run run_uwc_on_mac.sh
Step 2: Edit the exporter file
First, we need to export all the data from the wiki. This can be done by editing the exporter file that sits under conf folder. Only some wikis require this file to be edited for it to connect to the database etc. Other wikis have a tool that allows you to export it from the UI itself.
In this scenario, we will edit exporter.mediawiki.properties
In this file there are a few parameters that need to be defined. These determine the extent of the detail in your export. A list of all these parameters and how to define them can be found from the following link
Once the parameters have been defined, you then have to click on Export. This will export it to the location that you have defined in the properties file.
Step 3: Edit the converter file
Once the pages have been exported, you will have to edit the converter file which can be found under conf folder and here define all the parameters in terms of what needs converting and how. Click here for guidance.
The file in this case is going to be converter.mediawiki.properties.
If you would like to keep the date and usernames intact as it was in the MediaWiki, I suggest you take a back up of your current Confluence (assuming same username and passwords are used), and restore it to your local Confluence instance first. After that, add a plugin called UDMF Plugin.
To have the table formatting converted and kept the same way as the MediaWiki, you will have to add Content Formatting plugin to your local Confluence which depends on the output that you require.
Step 4: Test the connection to your Confluence instance
After all that is done, all there is left to do is to define the Confluence details. These include the URL which is localhost:8080 in this case, username and password with a Space Key of where all the data from MediaWiki will be added.
Once all the details have been defined, you can simply drag and drop the pages from the export to Pages section in UWC. If you had attachments as well, then you can define the path to it.
Test the connection to Confluence instance is working by going into Other Tools.
Now you are ready to convert it. Simply click on Convert and let the magic happen.
You might notice in the guide provided by AppFusions that it supported Confluence version is 4.3.7. Don’t worry about it too much as for this example, Confluence version 5.5.7 was used.
If your Confluence is SSL configured, then you will have to install the certificate key to your Java keystore that is used to run UWC tool. More details of that can be found in the following link. A simple way to avoid this overhead is to install a local Confluence instance and later transfer the whole space.
If your instance is hosted by Atlassian i.e. OnDemand, then you will have to either install the SSL certificate to your Java keystore or install a local instance of Confluence and later export the space.
All in all, this is a great tool to convert complex wikis to Confluence pages. Although it may look like it’s a complicated task, once you crack on with it, you will find it is not as bad as it may look. Good luck!