UWC Jotspot Notes

Overview

This is the documentation page for the Jotspot Conversion module of the Universal Wiki Converter.

Unlike other wikis, there were two possible conversion sources for Jotspot:

• it has it's own markup (which is usually what we convert)
• it's saves it's data as XML.

Since there's an 'Export Wiki as XML' feature in Jotspot's admin console, we opted to focus on converting the XML.

UWC converts Jotspot XML The UWC does not convert Jotspot markup. It converts Jotspot XML.

Status

The Jotspot Converter module is an alpha release. If you find problems, please help us improve it by submitting a Bug Report.

Supported Conversions

• Basic Syntax
  • bold
  • italics
  • strikethrough
  • fixed font
  • color
  • underline
• Lists
• Links
• Tables
• Attachments
• Headers

Limitations

Nesting

The converter does not handle nested span and font tags. For example:

<font color="#ff0000">Red <font color="#00ff00">Green</font> Red?</font>

would be translated to:

{color:#ff0000}Red Green{color} Red?

If you want to maintain that type of data, just don't nest those structures. You can use Jotspot's 'as XML' editor to check how these structures are going to be exported. For example, the following would work to maintain those different colors:

<font color="#ff0000">Red </font><font color="#00ff00">Green</font><font color="#ff0000"> Red?</font>

Row and Colspans

As Confluence does not provide a way to handle incoming tables with row or colspan structures, the converter will make a best effort attempt to convert those tables.

Table styles

styles will not be maintained for tables.

Jotspot extras

The converter only handles wiki pages at this time. It does not convert many of the Jotspot extras, including:

• comments
• revision history
• events and calendar pages
• spreadsheets
• photo or filegalleries

Usage

Steps:

1. Get the wiki data from Jotspot
2. Launch the UWC
3. Prepare your jotspot data
4. Convert to Confluence pages

Get the wiki data from Jotspot

1. Login to your Jotspot wiki as an administrator
2. Look for the 'Export Wiki As XML' link. (In my Jotspot, this was at the bottom of the page)
3. Click that link, and save the zip file.

Launch the UWC

UWC Quick Start

Prepare your jotspot data

At this point you have two choices, you can

• use the Jotspot Exporter to prepare this zip for use with the converter,
• unzip it yourself, and start converting directly.

The main difference is that the exporter will clear out files that the converter can't use, so there's fewer directories to slog through.

Exporting

Exporter Properties

To use the Jotspot exporter to clean up your jotspot.zip data, you'll need to modify a properties file.
You must configure the exporter.jotspot.properties file, in order for the exporter to work.
It is located in the conf directory of the UWC.

The available properties are as such:

Property	Required	Example	Description
exporter.class		com.atlassian.uwc.exporters.JotspotExporter	Leave this alone, unless you want a different class to run the exporter
exported.zipfile.location		/Me/Desktop/jotspotdata.zip	This is the location of Jotspot export zip file.
exported.output.dir		/Me/Desktop/jotspot/	This is the directory that the exported files should be placed in
exported.protected.directories		PhotoGallery, PhotoGallery.xml	files to explicitly save. See below

Protected Directories

The main point of the exporter is to clean out the (many) unnecessary files from the zip file. So, most everything in the zip is going to be deleted. (The zip itself won't be deleted.) If you know that there's a particular file or directory that you definitely do not want deleted, you can protect that file/directory with the exported.protected.directories property. This is an optional comma delimited list of directories (from within the zip) that should be explicitly saved.

Suggested Possibilities: Calendar, FileCabinet, PhotoGallery, GroupManagement, Spreadsheet, TodoList.

Running the exporter.

1. Define your Exporter Properties.
2. Click the Export Your Wiki tab in the UWC.
3. Click Jotspot
4. Click Run Exporter

Converting

Confluence Settings

Attachment Directory

Make sure you set the attachment directory setting to the location of your jotspot data.

Example: If you unzipped your zip file to /Me/Desktop/jotspot/, then set that directory as the attachment directory.

File name pattern

If you have exported your files from Jotspot, they will most likely be .xml files.
Make sure that the file name pattern does not exclude .xml files.
(I would recommend having leaving the file name pattern blank)

Choose pages to convert

Choose XML files from within the exported data directory.

What's it called?

The xml filenames will match the titles of your pages in the following way.
If the page you wish to convert was

My Wiki Page

then it will be titled

My+Wiki+Page.xml

Where is it?

It will be in a directory by the same name as it's parent page (minus the extension).
So, if it's parent page was WikiHome, and the data directory is /Me/Desktop/jotspot, then it will be located in:

/Me/Desktop/jotspot/WikiHome/My+Wiki+Page.xml

See UWC Gui v2 Documentation for more info on converting.

Bug/Feature Reports

If you run into a syntax that doesn't convert the way you wish it would:

Submit a bug report/feature request to UWC JIRA.
Set the Component to 'Jotspot'. (This will ensure faster response.)

Please provide the following information, so that we can best respond to your request:

• Before: An example of the jotspot XML that did not convert as you wished. (You can get this by clicking the As XML editor from the drop-down editor box)
• Current: An example of the Confluence syntax that is currently being created. (The undesired behavior). This helps us create a test case.
• Desired: An example of the Confluence syntax that would be ideal.

Thank you!