Krosoft Wiki
Krosoft Wiki
Breadcrumbs

Legacy Assets Macro Converter for Confluence - User Manual

Use this manual to configure and operate Legacy Assets Macro Converter for Confluence after a Confluence Server or Data Center migration to Confluence Cloud.

Last reviewed from the product repository: May 31, 2026.

Overview

Legacy Assets Macro Converter for Confluence helps administrators find and clean up old Insight/Assets macros left behind after migration to Cloud.

The app can:

  • Scan Confluence Cloud pages for legacy assets-objects-macro and insight-objects-macro storage macros.

  • Show affected spaces and pages.

  • Convert selected pages to native Confluence Cloud Assets table blocks.

  • Repair native Assets tables that were placed inside unsupported scroll-ignore content.

  • Map legacy Assets schema IDs, object type IDs, object keys, and display columns to Cloud equivalents.

  • Resume long-running scans and conversions from saved state.

The app does not migrate Assets data. The relevant Jira Service Management Assets schemas, object types, objects, and attributes must already exist in Cloud.

Before You Start

Confirm the following before running a production cleanup:

  • Jira Service Management Assets is available in Cloud.

  • The Cloud Assets data has already been migrated.

  • The user or app can read the target Confluence spaces and pages.

  • The user or app can edit pages that will be converted.

  • The user or app can read the relevant Cloud Assets workspace, schemas, object types, attributes, and objects.

  • You have tested conversion on a small sample page before running larger batches.

The app is available from Confluence global settings as Legacy Assets Macro Converter.

Run Modes

Select a run mode before checking permissions, scanning, or converting.

Mode

Use when

Behavior

Run as User

Content is restricted and should follow the current user's permissions.

Confluence and Assets calls run as the user opening the app.

Run as App

You want a consistent app-level permission set for bulk cleanup.

Confluence and Assets calls run as the Forge app.

Use the same mode for the environment check, scan, and conversion unless you intentionally want separate results.

Conversion Settings

Open Mapping settings before converting pages.

Manual Mappings

Use Manual mappings when you know the Cloud equivalents for legacy IDs.

  • Schema ID map: legacy schema ID to Cloud schema ID.

  • Object type ID map: legacy object type ID to Cloud object type ID.

  • Legacy key attribute: Cloud Assets attribute that stores old object keys. Default: ORIGINAL_KEY.

Use Refresh schemas to list visible Cloud schemas for the selected run mode.

Data Center Auto-Lookup

Use Data Center auto-lookup when the original Jira Data Center Assets/Insight metadata is available.

First open Source settings and configure:

  • Data Center URL, for example https://jira.example.com.

  • Authentication method: username/password or personal access token.

  • Username when using username/password.

  • Password or token, stored as a Forge secret.

Click Test connection before saving. A successful test confirms Jira authentication and Data Center Assets schema access. Auto-lookup can then resolve legacy schemas, object types, numeric attribute IDs, and object keys by reading Data Center metadata and matching it to Cloud data.

Because Data Center lookup uses backend egress to the configured URL, the app does not qualify for the Runs on Atlassian badge while wildcard backend egress is present.

Test Mapping

Use Test mapping before production conversion. Test with a known legacy schema, object type, object key, or display attribute. Treat failures as blockers and warnings as items to review before converting many pages.

Scan Workflow

  1. Select Run as User or Run as App.

  2. Click Check space permissions.

  3. Wait until the app reports accessible spaces.

  4. Click Start Scan.

  5. Review the space results table.

  6. Click View Pages for a space to inspect affected pages.

The scan reads Confluence page storage and detects:

Content type

Meaning

Legacy macros

Pages containing assets-objects-macro or insight-objects-macro.

Embedded Assets tables

Native Assets tables inside unsupported scroll-ignore content that need repair.

Scans are batched and resumable. If you reload or leave the page, the app can restore scan state and cached results. Use Clear cached results to remove stored scan data while keeping conversion settings.

Convert Pages

Conversions start from the View Pages modal.

  1. Select one or more pages.

  2. Click Convert selected pages.

  3. Watch batch progress, warnings, and failures.

  4. Review converted pages in Confluence.

  5. Rerun the scan to confirm cleanup.

For each page, the app prepares replacements first and updates the page once. It also checks the page version before writing. If someone edits the page during conversion, the app stops and asks you to restart that page's conversion.

The conversion uses:

  • The original iql or aql macro parameter.

  • Resolved Cloud Assets workspace and schema IDs.

  • Rewritten object keys when old keys can be mapped to Cloud keys.

  • Resolved display columns. The Key column is always included if missing.

If a column or mapping is ambiguous, the app records a warning instead of guessing.

Unsupported scroll-ignore Content

Cloud Assets tables cannot remain inside unsupported scroll-ignore content. When this is detected, conversion pauses and asks what to do.

Choice

Result

Place outside

Move the converted or repaired Assets table outside the unsupported block. This is the default.

Convert to inline URL

Replace a simple single-object legacy macro with an inline Assets object link, when available.

Skip page and continue

Leave the page unchanged and continue the batch.

Inline URL fallback is available only for a block with exactly one legacy Assets macro using a simple query such as Key = ... or Key IN (...), and only when the app can resolve it to one Cloud Assets object.

Data Storage

The app stores operational state so work can resume safely.

Stored in Forge app storage:

  • Environment check result.

  • Scan state and results.

  • Conversion settings, excluding secrets.

  • Page conversion job status, warnings, and errors.

Stored as a Forge secret:

  • Data Center password or personal access token.

Stored in browser local storage:

  • Last run mode.

  • Client-side cached scan and batch conversion state.

Rollback

The app updates pages by creating a new Confluence page version. If a result is not acceptable, restore the previous page version from Confluence page history.

Troubleshooting

Symptom

What to check

Start Scan is disabled

Select a run mode and run Check space permissions.

No spaces found

Check Confluence permissions for the selected user/app.

Assets workspace error

Check Jira Service Management Assets access for the selected run mode.

Schema cannot be loaded

Add a manual schema mapping or configure Data Center auto-lookup.

Object type or columns fail

Check object type mappings, Data Center metadata, and Cloud Assets attribute access.

Page update fails

Check page edit restrictions and space/page permissions.

Page changed during conversion

Restart conversion for that page.

Batch pauses

Choose how to handle unsupported scroll-ignore content, or skip the page.

Data Center connection fails

Verify URL, credentials/token, REST access, and Assets schema permissions.

For support, include the Cloud site URL, space key, page URL, run mode, mapping mode, relevant schema/object type/object key values, and the exact error or warning shown by the app.

Contact support@krosoft.nl.