Universal Wiki Converter User Documentation

We've recently noticed that the Java 6 regular expression engine seems to occasionally throw some exceptions when running a UWC conversion while the Java 5 engine does not. So at this time we advise running with Java 5.

• Overview
• What you need
• Usage
• Specific Wiki Notes - TWiki, PmWiki, DokuWiki, MoinMoin, Mediawiki, Jotspot, Tikiwiki
• Screenshots
• Demo videos
• Scope of the UWC
• Out of Scope
• Getting Help

Overview

The Universal Wiki Converter was written to support the conversion of other wikis to Confluence. It is both a GUI tool to make the conversion process as easy as possible and a framework which is meant to make it as easy as possible for developers (and even sophisticated users) to create and modify conversions.

What you need - prerequisites

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 the Confluence server must be accessible from where the UWC is running. If you can bring up a web page with Confluence that should be verification enough of network connectivity.

Usage

See the UWC Quick Start Guide

Additional notes:

• You must locate or export from the origin wikis the files which the UWC uses to convert. The UWC converts files (which represent pages in the wiki) containing the origin wiki's syntax. Some wikis store their pages as files in this format already. For some wikis you must export the content as files.
  See UWC - Wiki Specific Conversion Notes
• Once you've completed a successful conversion you can check the Confluence Dashboard to see pages which have recently been added or modified. However in some cases it takes the Dashboard a minute or two to reflect the updates even though the pages themselves have been updated. In other cases if you convert a page multiple times (which is fine) but the content has not changed then the page does not actually get updated because nothing has actually changed. In such cases no new version is generated.
• Attachments are uploaded to the pages with which they are associated. Each wiki's attachment conversion is specific to that wiki. The UWC might have trouble uploading too many large attachments (10Meg+) in one shot. In these cases you might have to run the UWC multiple times. Numerous large attachment uploads haven't been extensively tested, but the Confluence documentation notes some inefficiencies with large attachment uploads via the method the UWC is using (XML-RPC). For information on how to restrict the size of attachments to be uploaded, see UWC Restrict Attachment Size Feature

Specific Wiki Notes

These pages contain notes relevant to the specific wiki converters

• TWiki Specific Notes
• PmWiki Specific Notes
• DokuWiki Specific Notes
• Mediawiki Specific Notes
• MoinMoin Specific Notes
• Jotspot Specific Notes
• Tikiwiki Specific Notes
• Jspwiki Specific Notes

Demo videos

• UWC Usage Video - version 3

Older Gui These demo videos do not reflect the current GUI, released with version 46 of the UWC.

• UWC Usage Video - 4 min.
• UWC Developer Video - 11 min.
• JotSpot Conversion Video - 11 min.
• Test Connection demo - ~ 1 min.

Tips

• If you have more than a thousand pages and run into a slow down during the conversion process, 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 it will likely be most efficient to run it against about 1000 files at a time. If you convert the same page multiple times it doesn't matter because, in this case the page will only get added to Confluence once (that is if you send it to Confluence twice with the identical content).

Screenshots:

See the UWC Quick Start Guide for the latest screenshots

Goals and scope of the product:

• To provide a GUI tool which makes converting a wiki to Confluence as easy as possible.
• To provide a framework which handles common tasks such as sending pages and attachments to Confluence.
• To provide a framework which makes it easy to re-use regular expressions others have written for convertering other wikis to Confluence.
• To provide a solid foundation for continued open source development on this project through sufficient documentation and version control.

Things that are currently beyond the scope of this product:

1. Converting users or user profiles is beyond the scope of this product. There is a 'bulk user upload' plugin for Confluence worth checking out if you're interested in pursuing user conversion.
2. Converting the page groups, hierarchies, categories or other page metadata - though in some cases these things could be added by writing additional 'converters' if there is an appropriate mapping in Confluence.
3. wiki syntax/markup for which there is no Confluence equivalent translation, for instance TWiki tables allow column spans while Confluence does not currently. Though no data should be lost the conversion is imperfect in such cases.
4. Forums
5. Image galleries that are housed outside of standard wiki pages
6. user profiles (unless they are wiki pages)
7. page histories - all wikis keep page histories, but they all store them very differently. Now supported to some extent. See UWC Page History Framework

Getting Help

Having trouble using the UWC? There are a couple of different things you can do:

1. If you're noticing that a particular conversion isn't working quite the way you'd like, consider reporting a bug to the UWC's jira. Info on that here: UWC Bug Reporting
2. Want to ask someone a question? Try out the UWC Forum.