UWC F.A.Q.

What is the license for the UWC?

The Apache License, Version 2

What wikis are currently supported?

DokuWiki, Jotspot, Mediawiki, MoinMoin, PmWiki, Tikiwiki, and TWiki.

Where do I submit enhancements or bugs?

Please add them to the JIRA project
Also, see UWC Bug Reporting

Does the UWC support SSL?

No the UWC does not currently support sending content to a Confluence server using SSL.

One way to move content to such a server is to create a local stand alone instance of Confluence, use the UWC to send content there, then export content from that server and import content to the target Confluence server.

Why do I see the {html} tag as part of the conversion?

In many cases there is no Confluence syntax which matches the original wiki's syntax. When this is of key importance the syntax is converted to html which in Confluence can be surrounded by the {html} macro. However this macro is disabled by default. To enable it in your Confluence you must go to Administration -> Plugins and enableit.

What can I do if the wiki I'm using isn't yet supported for Conversion?

Please vote for your wiki on this page:
http://confluence.atlassian.com/display/CONFEXT/UWC+Converter+Vote

The code base is very open so you can develop a wiki converter

Also you can engage our Custom Plugin Pack Team to develop one.

How accurate are the conversions?

Realistically there is always a bit more to do with a converter as there are dozens of syntax statements for most wikis and people typically extend their base wiki syntax with plugins, but the ones listed above are currently very usable. Your mileage may very, but much work has been put into the above three to make them as accurate as possible. In some cases too there is no exact translation to Confluence syntax in which cases things will look a little different.

Why use this instead of one of the other converters?

Media Wiki users do have another good option explore - the MediaWiki to Confluence converter from Intient.

Some of the other content converters may work, but many have quickly become out dated and as far as I know this is the only tool that handles attachments. A fair amount of effort has gone into making this tool both user friendly and a solid framework upon which to add new converters too. It's also likely the most well documented and only supported tool.

Why sometimes when I send a page to Confluence does it not show up as 'updated' in the Dashboard?

If you send a page to Confluence it sometimes takes the Dashboard a few seconds to update. Also if you've already sent the exact same page it won't show up as changed. However if you change a single character of the page and send it again it should show as updated.

There is no converter for the wiki I'm using. What should I do?

You can either develop it yourself or have one of Atlassian's development partners create it for you. Send a note to cpteam@atlassian.com for more info.

How technical do I need to be to use this tool?

To convert a supported wiki in most cases you'll need the ability to install Java, do some Confluence administration tasks via the UI, and understand a bit about where your internal wiki stores it's pages and attachments. But the goal is that you don't need to be a programmer.

Is this tool free to use?

Yes

What other wikis have people asked about converting?

Here are a few inquiries that have been made recently:

• SharePoint
• JotSpot (Update: Now supported!)
• SocialText
• TikiWiki
• MoinMoin
• SnipSnap
• JSPWiki (Update: Now supported!)
• VQWiki

I have a website I'd like to pull into Confluence. Is this possible?

Not currently. The best approximation that occurs to me offhand is to write some converters that actually strip out much of the html and perhaps convert some basic well formed syntax. Then at the very least the UWC could get the pages' content into Confluence where you'd likely want to go in and format it. This conversion would be far from totally automated, but it would perhaps be a jumpstart.

Alternatively, the Jotspot Converter has to handle a lot of HTML, so you could try starting with that.

How can I add a question to this F.A.Q.?

Either feel free to edit this page with the question or add a comment to the bottom of the page.

Where is the output from the conversion?

The output basically gets sent to uwc/output/output, starting with wherever you run the uwc from. The UWC actually reads everything into memory and holds it there but outputs these files so you can see what the converted sytax looks like if you wish. Changing the files on the file system will not affect what gets sent to the UWC. Although

I see the converted files in the output director, can I change them before sending to Confluence?

Yes, but it takes two steps. When you run the converter everything is held in memory. So changing the converted output files on the file system half way through the process will not have any affect. However you can

1. run the converter
2. say 'no' when prompted 'do you want to send the files to confluence?'
3. change the files on disk
4. run the UWC again, but delete all the 'converters'/regular expressions
   (then you're basically using the UWC to just send all the files to Confluence on this second step through)

How tricky is it to convert a wiki?

With our current approach a set of regular expressions are authored which convert the origin wiki syntax to Confluence. This can be (in some cases) a little harder than it sounds.

For one thing people use syntax in the original wiki that is not meaningful there, but it is in Confluence. So forinstance if someone writes

-here is a phrase-

One helpful strategy for particularly challenging conversion problems is tokenization. So for instance when you have some text which is ultimately between {code} tags you don't want to touch it in terms of escaping or anything else....but how can this be avoided? One strategy is to Base64 encode it near the beginning of the conversion and then decode it towards the end. In practice unfortunately Base64 encoding and decoding is pretty slow and even more so when run against thousands of pages.

A strategy which works better in the case of {code} blocks is to swap out all the text between what becomes {code} tags into memory, replace with some kind of token which will not be touched, then at the end swap the text back in.

Links are another challenge area where it's best to tokenize since there are typically such a large variety of ways to express both internal and external links.

An example here is something like

[this is not a link in TWiki]

\[this is not a link in TWiki\]

Regression testing is very important to make sure you don't backslide accidently in such cases. One strategy here is maintaining a file of syntax examples both pre conversion and post successful conversion. When you add something to your converter you can compare the results against the post successful conversion with a good quality diff program (I use JEdit's excellent JDiff Plugin).

Where can I ask questions about the UWC?

Adding comments to this page is a good place for now.

During a conversion the UWC keeps getting stuck on the 1077th page (or some page). What is the problem?

I've seen something similar happen previously. Very occasionally the UWC gets stuck for some time on a single page which is either very very large or has a large number of some complex construct such as tables that it is trying to convert.

When I've seen this in the past the page is not a user created page but rather a system created page...perhaps something like a history of all the edits for that wiki and several megabytes in size.

When the UWC gets stuck on that page look at the DOS window or Unix shell you were running the UWC from. At the very bottom it should tell you what file it is currently working on trying to convert and stuck on.

Then kill the UWC (close the window or ctrl-break) and run it again.

Then go and either move or delete the problem file else where (you could also just not select it or deselect it in the UWC) and try things again.

Essentially you probably want to eliminate that page from the conversion or handle it some other way. It's very likely you won't want that page anyway.

Will bugs I submit be fixed?

Possibly. The source code is available and version control accessible. There is a working ANT build system. So anyone is free to submit fixes.

Can I convert HTML pages?

This wasn't a planned feature because HTML pages can be so vastly variable in their markup and layout. However it might be possible to use some sort of HTML to ASCII conversion tool to export the HTML pages to ASCII files. You'll want the titles of the pages to be reflected as the filenames. From there you can use the UWC to import the files to a Confluence instance. A quick Google search yielded this tool (among others) as potentially helping out http://www.jafsoft.com/detagger/remove-markup.html

Alternatively, the Jotspot Converter has to handle a lot of HTML, so you could start there.

How do I build the UWC from the subversion source?

1. Get the svn source
2. cd [universal-wiki-converter]/devel/
3. if necessary, chmod a+x run_build.*
4. run ant ( ant has to be installed )

To run the newly built uwc:

1. cd target/uwc
2. If you're going to use the exporter, configure it in conf/exporter.X.properties
3. if necessary, chmod a+x run_uwc.*
4. run the uwc.
   1. Mac? ./run_uwc_on_mac.sh
   2. Unix? ./run_uwc.sh
   3. Windows? ./run_uwc.bat

I'm getting a NoClassDefFoundError when I run the UWC from Windows, how can I fix this?

_{Referenced from UWC Problem from Confluence Dev Forum}

When I click the converter, it doesn't respond, but the following Stack Trace is found in the running terminal window:

Exception in thread "Thread-7" java.lang.NoClassDefFoundError: org/apache/commons/httpclient/URIException
at java.lang.Class.forName0(Native Method)
at java.lang.Class.forName(Unknown Source)
at com.atlassian.uwc.ui.ConverterEngine.getConverterClassFromCache(Conve rterEngine.java:215)
at com.atlassian.uwc.ui.ConverterEngine.getConverterFromString(ConverterEngine.java:157)

Solution:
You need to add one line to the run_uwc script. If you run it on
Windows, add the following line to run_uwc.bat:

Set UWCClasspath=%UWCClasspath%;%lib-loc%\commons-httpclient-2.0.2.jar

Credits Thanks to Yao for the above solution

How can I combine Confluence spaces and rearrange pages post conversion?

Have a look at this video

The wiki I'm converting uses tags, labels, keywords or a similar type of metadata. How can I import those to labels to Confluence labels?

Currently the UWC doesn't have a direct facility handy to add keywords as labels to Confluence. However several people have done the same thing using the {add-label} macro which you can find here: http://www.adaptavist.com/display/USERGUIDE/add-label+macro

That way you can just add them directly to page as markup and doing so in the format of this macro will send them to the right place. To do this, you'd probably want

1. to start by reading the UWC Developer Documentation, especially the section on the anatomy of a converter properties file.
2. You'd want to isolate how you determine what a label is in your wiki.
3. Add a converter to do this. Example: (if your wiki's label lived in the wiki syntax of a page and looked like 'Label: cookies', then you could, for example try something like:

   Mywiki.xxxx.labels.java-regex=(^|\n)Label:([^\n]*){replace-with}{add-label:$1}

   The above is untested, but that's the idea.

Another more involved option would be to create a new class extending BaseConverter plus add the relevant addLabel methods to the RemoteWikiBroker.

If the first approach works for you that will probably be a bit easier.