Installing and Pre-requisites

This document details Installation and pre-requisite information for the UWC

• Prerequisites
• Installation Steps

Prerequisites

1. Java 5 (a.k.a. JDK 1.5) or higher
2. The Confluence you want to send pages to must be running and accessible.
3. A Confluence user/login id and password which has write permission to the space(s) you wish to add converted content to
4. The Remote API must be turned on. See Adminstration -> General Configuration -> Remote API (XML-RPC & SOAP)
   Turn the Remote API on

   

backup We recommend that you back up Confluence before running the UWC. (In theory this process involves no data loss, no deletions, but back up to be safe and easily revert to an earlier state.)

Installation Steps

1. Download the uwc zip
2. unzip it in a folder of your choice
3. You may need to give execute permissions to the script you will be using.
   • run_uwc.bat (Windows)
   • run_uwc.sh (*nix)
   • run_uwc_on_mac.sh (Mac)
   • run_cmdline_devel.sh (UWC Command Line Interface)
     Example steps to give execute permissions to all shell scripts

     In a Mac Terminal:
     $shell$ cd uwc
     $shell$ chmod a+x *sh
     In a *nix Terminal:
     $shell$ cd uwc
     $shell$ chmod +x *sh
     

Installation Alternatives The UWC has download links in a bunch of different locations now, including the Confluence Plugin Repository, and (as of Confluence 2.10) via the Administration Console. Note: If you're attempting to install the UWC via the Confluence Plugin Repository, the Install link will not work as the UWC is a standalone app. Instead, expand the description, and click the download link to download the uwc.zip, then follow the above instructions.

This document details How the GUI works.

In order to have a successful conversion, there are a number of steps that need to be accomplished. For an overview of the general tasks, see the sidebar.

Once you have the UWC installed, the next thing you need to do is get all of the data that you're trying to move to Confluence into a format that the UWC can process. Generally speaking, things you will need are:

• A local directory of files, where each file represents a page in your wiki
• A local directory of attachment data, if desired
• Your connection settings to Confluence

To get the local directory of files and the location of your attachment directory, you will need to read the export and attachment sections in the notes for your particular wiki. See UWC Supported Wikis to get a link to those notes.

Your connection settings to Confluence include the Confluence url, your login information, and the spacekey for the space you wish to import pages to. To test that your settings are correct you can use the Test Connection tool in the UWC.

Now that you have all your data ready, and you've successfully tested your Connection to Confluence, just choose your wiki from the drop-down menu, set your attachment directory setting, and add your pages, either with the Add button or by dragging and dropping them into the application. Once all of the necessary settings have been set, and you've added at least one page, the Convert button should become enabled. Click Convert. A popup window will appear to provide status updates regarding your conversion.

Wiki Specific Remember, many of the preparation steps (like export or getting the correct attachment directory setting) are specific to your wiki. You'll need to check the notes on your specific wiki. See UWC Supported Wikis for a list.

This indicates the wikitype you are converting from.
Examples: Mediawiki, Tikiwiki, etc.
If the wikitype you are interested in is not displayed in the drop-down menu, then the UWC is not prepared to handle that wiki's conversion.

Note: As many wiki's share certain syntaxes, it's possible for a clever user to take advantage of existing converters in a particular converter.XXX.properties file, and simply comment out the ones you don't want. If nothing else, unconverted pages can be uploaded to Confluence using the choice NoSyntaxConversions.

This is a wiki specific setting that is used to determine where attachments and other info not contained within the wiki syntax is located. You will need to read your wiki's UWC specific notes (Example: UWC Mediawiki Notes) to find info on which directory should populate this setting.

Choose files or directories using the Add and Remove buttons, or by dragging and dropping files. Each file chosen will represent a page in Confluence. If you choose a directory, all pages below that directory will be converted. The contents of each file will be wiki specific, but in most cases will be the wiki syntax for that page.

The address of the Confluence you will be uploading the converted pages to. It should look something like one of the following:

* localhost:8080
* something.com/confluence
* https://localhost:8443

SSL and https If you are trying to connect to an SSL protected Confluence, you will need to: include the protocol (https://) in the address setting turn on SSL settings as detailed here: UWC SSL Support

Your username for the Confluence you are uploading these pages to. This username will need to have write permissions to the space you indicate.

The password for the above login.

The Confluence spacekey you are going to upload the pages to. Remember that the login you use must have write permissions to this space.

Once you have set all the required settings, the Convert button will become available. Choose it to start your conversion.

The UWC is prepared to handle the export of certain wikis (jotspot, mediawiki, etc.), to prepare them for conversion by the UWC. The exporter will only become available, if the Type setting is for a wiki the UWC can export.

You will need to edit the exporter.XXX.properties file. See your wiki's UWC specific documentation for more info on that. At the very least, you'll need to set where the UWC will export the wiki to.

When you're properties file is edited, and you're ready, choose Export to export your wiki. As you'll have set the output directory in your exporter properties, once the export is complete, you should be able to find your exported pages in the directory you indicated.

These are optional settings and tools that can be used but don't have to be.

By default, the UWC will send your converted pages to the Confluence you have indicated. But certain users, in particular developers, may not need this. They may just need a file representing the converted Confluence syntax, so they can improve their conversion, but not lose a lot of time uploading files.

The UWC always creates a version of the page in it's output/output directory. The file representing this Confluence syntax will be the same as the name it's going to get in Confluence if it was to be uploaded.

Unchecking the Pages will be sent... option simply means that the conversion completes after the files are saved, but before they would be uploaded.

By default, the UWC will launch the Feedback Window after every convert or export. If the user doesn't want this, just uncheck the Launch Feedback ... option.

The user may want to restrict the size of attachments that could be uploaded to Confluence. Check the Restrict Uploaded Attachment Size... option, and set it in the associated text field. See UWC Restrict Attachment Size Feature for more info on what to put in that setting.

Click the Test Connection button to get feedback on your Confluence connection settings. If there are problems with the settings, you'll receive an Error message in the Feedback Window. If there aren't any problems, you'll get the message:

Testing Connection Settings... SUCCESS.

Auto Detect Spacekeys Interferes If your particular wiki converter uses the UWC Auto Detect Spacekeys Framework, then the Test Connection setting will return a BAD_SPACE error instead of SUCCESS. Other connection settings errors will be reported first, so if you get a BAD_SPACE error in this case, then you do know that your other settings are ok. See Jira issue: UWC-304