This page last changed on Sep 12, 2011 by pwatson.

If you are upgrading to Confluence 4.0 from an older version, then as part of the upgrade an automatic migration of your site will take place. This is a non-destructive process. Your existing content is not overwritten: instead a new XHTML version of each Wiki Markup page will be created. In saying that, you must still be sure to perform a backup of your database and home directory prior to starting the new version of Confluence. Of course, that is our standard recommendation for any Confluence upgrade.

Migration Process

Depending on the size of your Confluence install, the Wiki Markup to XHTML migration could prove time consuming. The duration of the migration is difficult to estimate; this is due to a number of site specific factors. As a rough guide, a test dataset we migrated was 130,000 pages, totalling approximately 700Mb, which took six minutes.

There are certain properties that can be modified to allow finer control over the migration process.

Property

Purpose

Default

confluence.wiki.migration.threads

The number of concurrent worker threads migrating content

4

confluence.wiki.migration.batch.size

The number of items migrated in each batch of work

500

confluence.wiki.migration.versioncomment

The comment associated with the newly migrated version of each piece of content

"Migrated to Confluence 4.0"

(For instructions on setting Confluence system properties see this document.)

Again, due to the large variability in Confluence installations it is hard to give specific recommendations for the above settings. One point to note though that both increasing batch size and the number of threads (or both) will increase the peak memory required for migration. If memory is an issue then as you increase one of these settings consider decreasing the other.

Another factor to be aware of if modifying these defaults is that of the cache settings employed in your site. The migration will quickly populate certain Confluence caches so be sure that if you have customised caches as described here that there is enough memory on the server for these caches should they reach maximum capacity.

To monitor the progress of a site migration you should watch the output in the application log.

Migration Logging

Typical logging progress will be shown by multiple log entries at the INFO level of the format -

WikiToXhtmlMigrationThread-n - Migrated 2500 of 158432 pages, this batch migrated 500/500 without error

There may be a wide array of messages logged from each individual page but any errors are also collected for display in a single migration report once all content has been processed. A typical example of such a report is -

Wiki to XHTML Exception Report:
Summary:
	0 settings values failed.
	0 PageTemplates failed.
	2 ContentEntityObjects failed.
Content Exceptions:
	1) Type: page, Id: 332, Title: Release Notes 1.0b3, Space: DOC - Confluence 4.0 Beta. Cause: com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro link is unknown.. Message: The macro link is unknown.
	2) Type: comment, Id: 6919, Title: null, Global Scope. Cause: com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro mymacro is unknown.. Message: The macro mymacro is unknown.

Each entry in the report will identify the content that caused migration exceptions as well as displaying the exceptions themselves.

In almost all cases any content reported as errored will have been migrated to XHTML but actually consisting of Wiki Markup content wrapped within an XHTML specific 'unmigrated-wiki-markup' macro. This content will still be viewable in Confluence and editable within the new Confluence Editor.

However, in some cases a batch of content may actually have completely failed to migrated. This is most typically due to an unhandled exception causing a database transcation rollback. This would be reported in the log with a message like -

Unable to start up Confluence. Fatal error during startup sequence: confluence.lifecycle.core:pluginframeworkdependentupgrades (Run all the upgrades that require the plugin framework to be available) - com.atlassian.confluence.content.render.xhtml.migration.exceptions.MigrationException: java.util.concurrent.ExecutionException: org.springframework.transaction.UnexpectedRollbackException: Transaction rolled back because it has been marked as rollback-only

The current version of Confluence 4.0 provides no further report about this scenario and will also allow Confluence to restart as normal without retrying a migration. Should a user try to view any such unmigrated content they would see an exception similar to -

java.lang.UnsupportedOperationException: The body of this ContentEntityObject ('Page Title') was 'WIKI' but was expected to be 'XHTML'

The solution here is to ensure you manually re-run the site migration after the restart.

Re-running Migration

A Confluence Administrator can restart the site migration should there have been any content found to have failed migration (see previous section). Only the content that is still found to be Wiki Markup formatted will be migrated so typically a re-migration will take less time than the original migration.

To manually re-run migration:

  1. Open <site>/admin/force-upgrade.action
  2. From the 'Upgrade task to run' list select wikiToXhtmlMigrationUpgradeTask
  3. Click 'Force Upgrade'.

Re-attempt Migration

The previous section was about dealing with the exceptional circumstance where certain content was left completely unmigrated. The most common migration problem is that the content was migrated but remains Wiki Markup within the body of an 'unmigrated-wiki-markup' macro. This is the state any content which is references in the migration report will be found in. This content is still viewable and editable but since it is Wiki Markup it cannot be edited using the full feature set of the new Editor.

The most common reason for content to be in this state is that a non 4.0 compatible macro (or unknown macro) was found on the page.

There are two possible fixes for this situation -

  1. Install a 4.0 compatible version of the macro. See Plugin Development Upgrade FAQ for 4.0.
  2. Edit the page to no longer use the problematic macro.

Regardless of the solution you choose, you can then force a re-migrated of all the content that was left wrapped in an 'unmigrated-wiki-markup' macro. This feature is found at <site>/admin/unmigratedwikicontent.action


force-upgrade.png (image/png)
remigration.png (image/png)
Document generated by Confluence on Sep 19, 2011 02:29