The Adaptavist Group LogoDocumentation

Migrating from ThemeBuilder 4 to ThemeBuilder 5

In ThemeBuilder 5 onwards, the format of the skin data and backup files changed significantly from ThemeBuilder 4. These data and backup files from version 4 back are not compatible with the newer versions of ThemeBuilder.

We have made a layout exporter available to reduce the work involved in importing compatible layout data for ThemeBuilder 5. The layout exporter generates a skin that replicates the original and converts much of the old menu markup to ThemeBuilder compatible macros.

If you want to migrate a theme and retain all existing menu macros, please follow these instructions and use the free Hmenu Legacy Plugin. Make sure to note the important information on that page, as this is a free, unsupported plugin and is only supplied as an interim measure until your developers have migrated all menus over to the new Confluence 5 format.

Exporter Instructions for a Full Migration

Notes

If your Confluence 5 server:

  • HAS NOT been used for a ThemeBuilder migration

or

  • DOES NOT have ThemeBuilder or the Exporter installed

follow all steps as described in the instructions below.

If your Confluence 5 server:

  • HAS been used for a ThemeBuilder migration

or

  • DOES have ThemeBuilder or the Exporter installed

you need to overwrite this theme.

If your Confluence 5 server:

  • HAS been used for a ThemeBuilder migration

or

  • DOES have ThemeBuilder or the Exporter installed

you should keep this theme.

Adaptavist does not recommend running multiple migrations on the same server. If you want to maintain the existing theme, then be sure to select the Merge Uploaded Layout Data with Existing Layouts checkbox in steps 2 and 6.

Instructions for a Confluence 4 Server Upgraded to Confluence 5

Follow these instructions to export your existing layouts as a Skin Backup that can be uploaded into ThemeBuilder. On your Confluence 5 server that has been upgraded from Confluence 4:

  1. Install the latest ThemeBuilder and Exporter plugins.
  2. Go to ThemeBuilder > Export Layouts to Skins link in the Tab area.
    1. Select Export All in the drop-down menu.
    2. Select the Convert Wiki-Markup to Storage-Format checkbox.
  3. Click Export and save the zip file.

    This will convert all layouts available into skin format.

  4. Click ThemeBuilder Backup.
  5. In the Restore Backup area, select the migrated ThemeBuilder backup you saved in step 2.
  6. Click Upload.
    1. Select the relevant boxes if you have templates or user macros to import.
    2. Do not select the Merge Uploaded Layout Data with Existing Layouts checkbox.
    3. Select the Select Builder as the Theme Based on the Data in the Backup File checkbox if you want to carry over previous Confluence to ThemeBuilder relationships, like Global theme.
    4. Select the Set the Skin Selection Based on the Data in the Backup File checkbox if you want to carry over previous Space to Skin relationships.
  7. Click Upload.

Once the Skin Backup has been uploaded, you may use the Skin Editor to view the exported layout. If you are satisfied that your layouts have been migrated successfully to skins, you may uninstall the exporter.

Converted Skins

Exported layouts will consist of a Main panel replicating the old ThemeBuilder theme structure. You should not need to edit this panel since it only exists to provide the framework for your panel content. The Dashboard panel will contain the contents of your dashboard.wiki resource. Similarly, the Flaglogic panel will have the contents of the flaglogic.wiki resource.

Notice that the storage format panels inherited from the root skin are disabled. This is intentional because they are no longer used within an exported layout. Instead, panels have been created to match those used by the original layout, the wiki markup that they contained has been copied over, and the menu items translated into ThemeBuilder compatible macros where possible.

An exported layout will not be immediately usable since ThemeBuilder uses the internal Confluence menu functionality to generate the drop-down menu areas. This adds some complexity to re-using an exported layout since the Atlassian menu code is not capable of generating nested menus. We suggest reviewing menu usage for this task. See the section on ThemeBuilder Menus for more help with this.

How to Clear ThemeBuilder Data from a Confluence 5 Server

  1. Go to ThemeBuilder Backup > Create Backup > Backup All Layouts and select all checkboxes.
  2. Click Download and save the zip backup to a safe place.

    You will only need this backup if the new migration fails and you want to return to this state.

  3. Stay on the ThemeBuilder Backup screen and go to the Reset Layout Data section.
    Note:

    If this is greyed out, rerun the backup action. The Backup screen's lower areas only become active when a backup has been saved.

  4. Enter the Server Base URL (you can copy this from the General Configuration screen) and select the checkbox for Delete Layout Data Before Resetting.
  5. Click Delete All.
    Warning: This will permanently clear all ThemeBuilder layout data from your server. Only do this if you have the backup from step 1.
  6. Click Manage Add-Ons and delete the ThemeBuilder and Exporter plugins. Also, delete the Hmenu plugin if this has been installed.

    This ensures that all ThemeBuilder data is reset and ready for a new migration.

  7. Install the latest ThemeBuilder and Exporter plugins.
  8. Return to the top of this page and follow the migration instructions.

Search documentation

Start typing to search the docs.