Migration Path

We recommend you migrate your spaces containing Scroll ImageMaps using Confluence's Cloud Migration Assistant

Migration Steps

Step 1: Update Scroll ImageMap to the latest Server/Data Center version

Updating to the latest version of the app is required to ensure that all Scroll ImageMap macros are updated to a cloud-compatible format. A background task for migrating incompatible Scroll ImageMap macros will run globally in the instance when Scroll ImageMap v2.4 (or later) is installed.

Step 2: Migrate all spaces that contain Scroll ImageMaps

Use Confluence's Cloud Migration Assistant to confirm the space(s) that you are wanting to migrate from Confluence Server/Data Center to Confluence Cloud. You can learn more about using Atlassian's Cloud Migration Assistant for Confluence here.

Step 3: Check that there are no incompatible Legacy Scroll ImageMap macros used in your content

During the migration steps with Confluence's Cloud Migration Assistant you will be notified via the App specific checks if there are any incompatible Scroll ImageMap macros present in the content you are trying to migrate.

Step 4: When incompatible Legacy Scroll ImageMap macros are detected

If the App checks section of Confluence's Cloud Migration Assistant reveal incompatible Scroll ImageMap macros during the migration, these affected macros will need to be converted to a Cloud compatible format before proceeding further with the migration.

When using the latest version of Scroll ImageMap in Confluence Server/Data Center a background task for migrating incompatible Scroll ImageMap macros will run globally (ie. within all the space). To check the success of this automatic task it remains possible to search for the following line in the confluence.log file → ImageMap migration task completed with status:

However, if for the some reason the migration task does not successfully complete it could be that some cloud incompatible Scroll ImageMap macros remain in your content and these will be detected during the App check.

Step 4a: Use the Download report option to reveal which Scroll ImageMap macros are affected

Using the Download report button will provide a CSV file which can be opened to view the space(s) and specific page(s) where the legacy incompatible Scroll ImageMap macros are present.

Step 4b: Convert the incompatible Scroll ImageMap macros to a cloud compatible format

To fix and convert any detected incompatible Scroll ImageMap macros you can either;

navigate to the page where the macro is present, edit the page and open the Scroll ImageMap macro and then save it again. This action will refresh the macro and convert it to a Cloud compatible version
OR
use the REST API to trigger the macro migration tool for a specific space or for all spaces

Using the REST API to trigger the macro migration

Running the Tool

The command to start the tool is formed as follows:

CODE

# Convert all macros in all spaces:
curl -u {userName}:{password} -X POST -H 'X-Atlassian-Token: no-check' {baseUrl}/rest/k15t-scroll-imagemap/1.0/admin/migration/start

# Convert all macros in a specific space:
curl -u {userName}:{password} -X POST -H 'X-Atlassian-Token: no-check' {baseUrl}/rest/k15t-scroll-imagemap/1.0/admin/migration/start/space/{spaceKey}

# Convert all macros on a specific page:
curl -u {userName}:{password} -X POST -H 'X-Atlassian-Token: no-check' {baseUrl}/rest/k15t-scroll-imagemap/1.0/admin/migration/migrate/page/{pageId}

Example

CODE

 curl -u admin:admin -X POST -H 'X-Atlassian-Token: no-check' http://localhost:1991/rest/k15t-scroll-imagemap/1.0/admin/migration/start/space/TEST

The command should be executed in the terminal (with preinstalled curl) or with another similar tool. The API returns the ID of the task that was started. For example: d944acee-8f2c-4298-be3c-8c3e367ffed7

Checking the Success of the Tool

The result of the fixing tool can be called up in the browser with the following command:

CODE

{baseUrl}/rest/k15t-scroll-imagemap/1.0/admin/migration/task

The resulting JSON structure will contain an object with the ID returned when starting the migration and this object contains the status of the migration task.

Step 5: Complete the Migration

When no legacy Scroll ImageMap macros are detected and/or any legacy Scroll ImageMap macros have been converted, the migration with the Confluence Cloud Migration Assistant can continue and the related content will then be available in your cloud instance.

Still Unclear? Reach Out to Us

If you need help with any of these migration steps, reach out to us via help@k15t.com.