This documentation has moved. For the most recent documentation, check out https://docs.adaptavist.com. Please update your bookmarks and links.

Skip to end of metadata
Go to start of metadata

In ThemeBuilder the format of the skin data and backup files has changed so completely that it was not possible to make them backwards compatible. To reduce the work involved in porting the layout data to be compatible with the new skin format a layout exporter has been made available which generates a skin that replicates the original builder layout and converts much of the old menu markup to use ThemeBuilder compatible macros.

 

Menu 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
  • DOES NOT have ThemeBuilder or the Exporter installed

You should follow all steps as described in Instructions.

If your Confluence 5 server:

  • HAS been used for a ThemeBuilder migration
  • DOES have ThemeBuilder or the Exporter installed
  • You want to OVERWRITE THIS THEME

Please follow the instructions for clearing ThemeBuilder data from a server before continuing.

If your Confluence 5 server:

  • HAS been used for a ThemeBuilder migration
  • DOES have ThemeBuilder or the Exporter installed
  • You want to KEEP THIS THEME

Adaptavist do not recommend running multiple migrations on the same server but if you want to maintain the existing theme then be sure to check ‘Merge uploaded layout data with existing layouts' in steps 2 and 6.

Instructions for a Confluence 4 Server Upgraded to Confluence 5

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.

    • Select ‘Export All’ in the dropdown
    • Check 'Convert wiki-markup to storage-format'
    • Click ‘Export’ and save the zip file



  3. This will convert all of the layouts available into skin format

  4. Go to ThemeBuilder > Backup > Restore Backup > Upload the migrated ThemeBuilder backup you saved in step 2.

    • Check the relevant boxes if you have templates or user macros to import.
    • Do not check ‘Merge uploaded layout data with existing layouts.
    • Check ‘Select builder as the theme based on the data in the backup file’ if you want to carry over previous Confluence to ThemeBuilder relationships eg global theme.
    • Check ‘Set the skin selection based on the data in the backup file’ if you want to carry over previous Space to Skin relationships.
    • Click 'Upload'

Once the skin backup has been uploaded you may then 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 that replicates the old Theme Builder 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 contain the contents of the flaglogic.wiki resource.

You will 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.

Out of the box, an exported layout will not be immediately usable since ThemeBuilder now uses the internal confluence menu functionality to generate the drop-down menu areas. This adds some complexity to the process of re-using an exported layout since the Atlassian menu code is not capable of generating nested menus, as such a review of the menu usage will be required. 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 > Check all boxes > Download 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.



  2.  Stay on the ThemeBuilder Backup screen and go to the Reset Layout Data section.
    If this is greyed out run the backup action again – the lower areas on the Backup screen only become active when a backup has been saved.

    • Enter the Server Base Url (you can copy this from the General Configuration screen) and check the box for ‘Delete layout data before resetting’
    • Click 'Delete All'

      This will clear all ThemeBuilder layout data from your server so only do this if you have the backup from step 1.

  3. Go to ‘Manage Add-On's’ and delete the ThemeBuilder and Exporter plugins. Also delete the Hmenu plugin if this has been installed. This is to ensure that all ThemeBuilder data is reset and ready for a fresh migration.

  4. Install the latest ThemeBuilder and Exporter plugins.

  5. Return to the top of this page and follow the migration instructions.

Resources

 

 

 

 

 

  • No labels