Universal Wiki Converter: how to transfer your wiki content to Confluence


Posted by
Anand UNADKAT

March 25, 2015

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:

  • TWiki
  • PmWiki
  • DokuWiki
  • Mediawiki
  • MoinMoin
  • Jotspot
  • Tikiwiki
  • Jspwiki
  • Sharepoint
  • SWiki
  • Vqwiki
  • XWiki
  • Trac
  • SMF
  • Socialtext
  • Mindtouch
  • upload a directory of documents
  • Jive

The above list can also be found on the following link

Step 1: Download UWC

Click here to download a zipped version of UWC.

Your local machine will need to be able to connect to MediaWiki database, so using it in your Company network is recommended.

Run either uwc.jar by double clicking on the file OR open the terminal and run run_uwc_on_mac.sh

./run_uwc_on_mac.sh

 

Screen Shot 2015-03-02 at 15.43.18

You will need Java installed on your local machine to be able to open the UI for UWC.

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.

Screen Shot 2015-03-02 at 16.07.20

Test the connection to Confluence instance is working by going into Other Tools.

Screen Shot 2015-03-02 at 16.05.26

Now you are ready to convert it. Simply click on Convert and let the magic happen.

Few notes

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.

Conclusion

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!

  • Br. Bill
  • Anand,
    Thanks for this summary write up. I need to merge a few wikis into our new Confluence system but the link to the UWC plugin file on Atlassian’s site is dead. By chance do you have the UWC zip file? If so, could you please post a working download link or can you email it directly to me.

    Thanks

  • Anand Unadkat

    Hi Mathieu,

    Thanks for your comment. Just trying to understand. Are you having trouble opening the jar file?

    Thanks
    Anand

  • Atlassian no longer supports the UWC, so it is no longer possible to convert other wikis into Confluence.

  • Hi,

    I agree with Sven. This add-on doesn’t work with the lastest versions of confluence…..

    I didn’t manage to install it :
    – Could not find a handler capable of installing the add-on at C:\Users\pellegrinoma\Desktop\uwc-4.0\uwc\uwc.jar. Check that the file is a valid add-on
    Or
    – Could not find a handler capable of installing the add-on at C:\Users\pellegrinoma\Desktop\uwc-4.0.zip. Check that the file is a valid add-on.

    Is there an alternative ?

    Thanks

  • Anand Unadkat

    Hi Sven,

    Apologies for a very late reply – yes you are right, all over the web it says it doesn’t but I have done it for 5.x and I had no issues.

    Regards
    Anand

  • Hi,

    Does this really work with confluence 5.x? I hear it doesn’t all over the web…

    thanks,
    sven