This server will be upgraded at 3pm Sydney time on December 3rd (December 2nd, 8pm PST) and will be down for up to 30 minutes.

UWC Documentation

Added by Brendan Patterson, last edited by Brendan Patterson on Apr 26, 2007  (view change) show comment

'Original' Universal Wiki Converter

This is the original documentation preserved because it contains some possibly still relevant comments and details. However this page is now dated and you should refer to either the UWC User Documentation page or possibly the UWC Developer Documentation.

Why this exists

Every week there are usually two or more requests to convert other wikis to Confluence. There are several existing converters in various states, but none of those reused the efforts of others.

Status

Currently DokuWiki and PmWiki converters are in active development and mostly working. The core framework is still being refined, but largely working reliably. Alpha? Beta? It's pretty much someting you'll use once for a few hours. It feels like it's nearing the point where it's working reliably.

What you need

The Universal Wiki Converter is a client side application with a rich GUI.

  1. The UWC requires Java 5 (Java 1.4 or earlier will not work since we took advantage of new Java 5 constructs)
  2. The instance of Confluence where you want to send convertered pages must be up and running.
    1. Adminstration -> General Configuration -> Remote API (XML-RPC & SOAP): must be turned on
    2. You must have a login/password for a user that has write permission for the target space to where you will write pages.
    3. You can run the UWC on a different computer than where Confluence is running, but obviously they must be networked. If you can bring up a web page with Confluence that should be verification enough of network connectivity.


Basic Usage

  • Always back up everything before doing anything major like this....back up Confluence, backup your original wiki, back up your mother-in-law's birthday on your calendar. (in theory this process involves no data loss, no deletions, but back it all up).
  1. Make sure your original wiki pages are exported to files in a format usable by the UWC. In many cases this is 'out of the box' functionality for these wikis. In other cases the process requires a little massaging. See [UWC - Wiki Specific Conversion Notes]
  2. Start the Universal Wiki Converter GUI by running run_uwc.bat or run_uwc.bat
  3. Make sure the configuration settings are correct by checking 'Confluence Export Settings'
    • You'll want to be sure that the "Attachment Directory" is pointing to where your file attachments are stored.
  4. Select the pages you wish to convert by clicking on 'Include Wiki Pages'
    • These converters are loaded from the 'converter.properties' file. So you'll want to first make sure to go in and copy conf/confluence.pmwiki.properties to conf/confluence.properties depending on the wiki you're converting. This is something we'll handle in the GUI soon.
  5. Select the converters to run by clicking on 'Include Converter'. In most cases this will be all so hit ctrl-a in the dialog and then 'Add to Engine',
  6. Hit Send to Confluence
    • The pages will initially be put into a new directory under 'output'. You can verify how they look there
    1. "Send to Confluence?" - Click on Yes
  7. Go look at your Confluence Dashboard (refresh it) to see what happened.



Demo videos

Demo video (~ 4 min.)

How to add a set of converters to convert another wiki.

Grab the source code

Check in your changes

Architecture

How it works:

The Universal Wiki Converter is a client side application with a rich GUI. It converts files containing wiki markup from the first wiki and then sends those files directly to Confluence via XMLRPC

What the framework provides:
  1. A GUI interface
    1. GUI allows user to select pages to convert
    2. GUI allows user to dynamically specify Confluence settings
    3. GUI provides a regular expression test tool for rapid development of regular expressions which these specific regex engines (all regular expression engine implementations seem to be slightly different)
    4. GUI allows the user to add, edit, or disable converters (which include regular expressions) dynamically
    5. GUI provides a %completetion bar while files are both being converted and sent to Confluence
  2. Currently one regular expression engine. The regular expression engines are pluggable. You need only exted 'BaseConverter' have a look at the PERLConverter to see how (~5 lines of code).
  3. The BaseConverter can be extended to implement 'Java converter' classes to handle the trickier cases where a regular expression isn't quit up to the task.
  4. All the XMLRPC code necessary to send pages to Confluence, and upload attachments to their pages
  5. The ability to dynamically massage page names.
  6. Several of the systems have unit tests both to verify functionality and provide sample code
  7. lots of sample regular expressions.

Tips

  • If you have a lot of pages, try converting just around 1000 at a time. For some reason the UWC runs very fast against about six hundred files and then pauses. Each pause gets a little longer. If you have several thousand files to convert for now just run it against about 1000 files at a time. If you convert the same page multiple times it doesn't matter because that page will just end up with multiple versions at worst.

Other Notes

Things that are out of scope:

Several wiki systems have other services they provide including forums, user account management, comments. Pretty much everything beyond page contents and their attachments is currently out of scope of the UWC targets. Though some things like page comments could be added very easily and might be if anyone really wants them. Here are some things that are out of scope:

  • Forums
  • Image galleries that are housed outside of standard wiki pages
  • user profiles (unless they are wiki pages)
  • users lists (there is bulk user upload macro which could handle these...though it needs to be updated)
  • page histories - all wikis keep page histories, but they all store them very differently.
  • markup which doesn't match anything in Confluence - you can add html to a Confluence page and in some cases there are converters (regular expressions) which do this to convert markup for which Confluence has no construct. But in some cases it won't really be possible without a considerable extra amount of effort.

Screenshots:





Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.