Moving your content from Zen Foundation to Theme Press.

Successfully transitioning your content requires migration of all of your Zen pages, brands, macros, and other settings. To facilitate this process, we have created the Zen Migrator add-on, available by request via our normal support process.

If using:

  1. Replace me with something to note about this how-to entry that falls outside the scope of all other sections; and
  2. Add the tight-bottom class to the Steps block above to narrow the gap between the two blocks.

If using:

  1. Replace me with something to note about this how-to entry that falls outside the scope of all other sections; and
  2. Add the tight-bottom class to the next visible/non-collapsed block above this one to narrow the gap between the two blocks.

If using:

  1. Replace me with something to note about this how-to entry that falls outside the scope of all other sections; and
  2. Add the tight-bottom class to the next visible/non-collapsed block above this one to narrow the gap between the two blocks.

Version Requirements

Zen Foundation 5.2.16 (or higher) and Theme Press 1.1.7 (or higher) are required to complete the migration.

Caution

Looking to upgrade to Confluence 7.x? Due to compatibility issues, it is important to migrate from Zen to Theme Press BEFORE upgrading Confluence.

The Basics

Before beginning migration, we recommend familiarizing yourself with the concepts below.

As you move through the process, the migrator takes note of:

  • Zen's application on a site-wide and space-by-space basis
  • Any spaces using themes other than the default
  • Any spaces using layouts other than the master

When you migrate, your Zen pages become Theme Press architect pages. The migrator creates an architect page for each header, layout (page or blog), menu and footer page in your site. For each admin-notice page, the migrator creates a banner page.

Layouts Overriding Master Layouts

The migrator also creates a Theme Press layout page for any Zen layout overriding the master.

What were called brands in Zen Foundation are now called themes in Theme Press. Migrating involves creating a Theme Press theme for each Zen brand that is not a built-in brand.

Both Zen and Theme Press allow you to set a default theme (brand). Likewise, you have defaults for Zen and architect pages. You do not need to map your defaults from Zen to Theme Press. The migrator sets them for you.

The migrator also looks for any spaces using a brand or Zen page other than the default, including layouts overriding the master. The migrator applies these overrides accordingly in Theme Press.

Macros available through Zen differ from those in Theme Press. In some cases, Theme Press offers equivalent macros. When available, you can use the migrator to convert Zen macros into Theme Press macros. When not available, you must manually change or remove Zen macros. See our Zen Macro Migration for more information.

After migrating, manually add your custom CSS and/or JavaScript to Theme Press. You may need to update this code.

Theme Press does not support cascading menus. Therefore, Theme Press ignores any second level items in migrated menus. Try panel menus or secondary menus instead.

Getting Started

Accessing the Migration Page

Once you install the Zen Migrator App, complete the following:

  1. Navigate to General Configuration under the Confluence Administration Menu.
  2. Locate the Zen Migrator section on the left.
  3. Click the Migrate Zen Foundation to Theme Press link.

Monitoring Your Progress

As you move through the migration process, a log appears to the right of the screen. Use this section to monitor your progress and any issues that may arise. You can download these logs if necessary.

Running the Migration

Select Scope

Before initiating any steps, you should set the scope of the migration. First, determine if you want to migrate all spaces or Zen-only spaces. Select all spaces if:

  • all spaces in your site use Zen
  • some spaces use Zen and other spaces formerly used Zen
  • some spaces use Zen and other spaces contain pages using Zen macros

Next, select a processing mode: migration vs. audit.

  • Migration mode completes the conversion during each step.
  • Audit mode simulates the conversion and generates an audit log.

Migrate Zen Pages

During this step, the migrator replicates each Zen page as a Theme Press architect page. Afterward, the migrator assigns a site default for each type of architect page (banner, header, menu, layout, footer). Additionally, the migrator looks for any space overrides and applies those pages accordingly. (Admin-notice pages are converted to banner architect pages.)

Migrate Overriding Layouts

For each unique Zen layout that overrides the master, the migrator generates a Theme Press layout page. In other words, if two or more Zen pages use the same type of layout, the migrator creates only one layout page in Theme Press. The migrator also applies these layouts to the appropriate pages. (In Theme Press, layouts are found in the Theme Press Default Space.)

Migrate Brands

You have the option of migrating Zen brands to Theme Press themes. Just select the appropriate brands. Note, you cannot migrate built-in brands. (In Theme Press, themes are located in the theme tab of the Theme Press Designer.

Migrate Zen Macros

During this step, the migrator finds all pages using Zen macros. Upon building the list, you'll see a blue action circle ( ) next to each macro that is ready for conversion. Click this icon to replace the Zen macro with a Theme Press equivalent. You must manually convert or remove all other macros.

You can find a full list of Zen Macros and their Theme Press equivalents here.

When in audit mode, be sure to click the blue action circle for the following macros:

  • include-section
  • simple-space-list
  • zen-section

This step adds helpful information to the audit logs.

How do I find pages using these Zen macros?

Click the blue arrow next to the name of each Zen macro that shows results.

Apply Theme Press

Now that you've migrated your brands and Zen pages, you should apply Theme Press and the resulting themes. For each space, migration involves:

  • applying Theme Press as the site or space theme
  • assigning a site default theme
  • assigning any themes that override the site default

Built-in Brands

If using a built-in brand as the default, the migrator sets the Theme Press default theme to Splash. This step is necessary because you cannot migrate built-in brands.

Create and View Punch List

As you complete this conversion, the migrator builds a list of items you should review and fix.

Manual Changes

Once you generate the punch list, you'll see several items that require manual changes, involving migrated brands, as well as pages and layouts.

Migrated Brands

When migrating a brand, the punch list shows tasks for brand settings that (1) need review or (2) cannot be migrated. Each item shows a brand setting reference that begins with a dollar sign ($).

Pages and Layouts

When viewing the punch list, review the following tasks related to pages and layouts:

  • check layout format
  • review layout (floating sections)

The punch list provides a link for each page that may need adjustment. Most likely, these pages previously contained floating or tabbed sections.

In Zen, columned sections are referred to as floating sections. Each floating section migrates into its own layer/column/block when migrating to Theme Press. If a Zen page contains two floating sections (section 1 and section 2), the migrated Theme Press page will then contain the following:

  • one layer/column/block for section 1
  • another layer/column/block for section 2

Each tabbed section migrates into its own layer/column/block. Note: In Theme Press, while tabbed blocks on 'normal' content pages work much like Zen, you cannot create tabbed blocks on Theme Press layout pages.

Adding Columns and Layers

You may need to adjust affected pages so that content appears in columns, either by adding additional columns to a layer or creating a new layer (with desired number of columns). Once you create new columns, drag and drop your content into the appropriate areas.


Need help with your punch list?

Before migrating your production server, be sure to:

  • Verify your results in a test environment
  • Backup your site and verify the validity of the backup

Disabling Zen

We recommend you disable Zen Foundation upon completing the migration steps and checklist. Once you determine the migration is successful, uninstall the add-on.