Migration to Version 8

How to migrate

Important:

1. The update/migration is one-way - If you update to Page Tree Creator version 8.0.0, there is no going back

2. Be sure to have a backup or snapshot or your Confluence instance before attempting the update and migration

Overview:

• Can be run multiple times

• Can be run for single spaces and pages

• Consists of two phases: Scan and Migration

• Legacy elements that need to be migrated are:

  • Template Configurations

  • Tag Configurations

  • Consecutive Tags

  • Instantiation Records, Placeholder Records

  • STC Tag Description Macros

• Deprecated elements with no replacement are

  • STC Jira Macro

• If there are any legacy elements on a template, the instantiation might fail. Also the user will be presented a warning in view mode

Prerequisites

1. Installation of the new version of the Page Tree Creator

2. Make sure you have administrator permission and are in the confluence-administrators group

Steps

1. Hit the Scan or Re-Scan button to find all legacy Page Tree Creator and Space Tree Creator content in your Confluence instance
   -> Depending on your Confluence size, this might take some time.

2. When scanning is completed, you see an overview of all spaces and pages which contain legacy elements.
   Typically legacy elements are your PTC Templates, STC Tag Description Macros, Consecutive Tags. Since we need to migrate most of the old Page Tree Creator data, any page that is related to a template will need some form of migration.

3. Select the content that should be migrated

4. Hit the Migrate button.
   -> As with the scan procedure, this can take a little while

5. Success → Your content has been migrated.

Errors and Warnings during Migration

If you encounter any errors during the migration, the content that has failed during the migration is still displayed in the migration wizard. Expanding the content in the wizard will show the corresponding error message(s). You can attempt another migration. Be aware, that in this case, the migration strategy* is changed from Rollback on Error to Continue on Error:

1. During the first migration attempt, if any error occurs on a specific piece of content, all changes for this single content are reverted.

2. If you attempt a migration for a previously failed piece of content, the migration is executed nonetheless, in the worst case, the legacy element is deleted but no new element is created**

3. If you have a previously failed piece of content and do a Re-Scan, the mode will be changed again for the next migration.

*The migration strategy is executed on a per piece of content basis, e.g. a single page
** For some elements you can inspect the legacy element via the page history and manually create the new representation, e.g. the new Placeholder Macro for the STC Tag Description Macro

Troubleshooting

In case the migration is not yet performed (or only partially applied), the user might see some warnings when viewing a template page with legacy content.

Unknown Macro: spactreecreator-button

Description

Unknown macro ‘spacetreecreator-button’

Cause

This can happen if you installed the new Page Tree Creator Pro while the Space Tree Creator was also installed

Solution

Uninstall the Page Tree Creator Pro and the Space Tree Creator and then reinstall the new Page Tree Creator Pro again

Note: Uninstalling the app won’t affect any app data

Deprecated Macro: Jira Macro

Description

Deprecated Page Tree Creator Macro: Please replace this macro with the new PTC Jira Macro

Cause

We deprecated the STC Jira Macro

Solution

Edit the page and replace the STC Jira Macro with the PTC Jira Macro

Deprecated Macro: STC Tag Description Macro

Description

Deprecated Page Tree Creator Macro: Please use the PTC Migration Wizard in the General Configuration or contact your Confluence Administrator

Cause

The STC Tag Description Macro was deprecated with version 8.0 and is replaced by the PTC Placeholder Macro

Solution

Open the Migration Wizard in the General Configuration of Confluence and select the corresponding page and run a migration. If the page is missing, attempt a re-scan.

Note: If, for any reasons, this should not be possible, you can also manually migrate the macro. Simply create a PTC Placeholder Macro and fill in the same parameter values as for the STC Tag Description Macro

Support

If you encounter Problems that you can’t fix

1. Set the log level in the Logging and Profiling configuration (under General Configuration) for the eps.focuspro package to DEBUG

2. Attempt another Scan and Migration in the Migration Wizard

3. Export a support.zip with the application-logs from the Support Tools of your General Configuration

4. Contact us via our Service Desk