Stand with Ukraine 🇺🇦
Products
Services
Blog
About Us

User Macro Exporter

This documentation covers the User Macro Exporter app. To learn more about User Macro migration, please refer to our documentation.

User Macro Exporter helps you move User Macros from Confluence Server / Data Center to User Macro for Confluence Cloud:

  • it exports all your User Macros to a JSON file that the Cloud app can import;

  • it checks every macro against the Cloud naming rules and shows which ones won't work in Cloud;

  • it can fix those macros for you, together with every page, blog post and comment that uses them, before you export.

Before you start

Supported Confluence versions

7.x and 8.x: user-macro-exporter-7.x.x-8.x.x.jar

9.x: user-macro-exporter-9.x.x.jar

Not supported yet

Confluence 10.x

Who can use it

Confluence administrators

App version

1.1.0

How to use

  1. Download User Macro Exporter from Google Drive. Choose the file that matches your Confluence version (see the table above).

  2. Install the JAR file on your Confluence instance: Administration → Manage apps → Upload app.

    Note:
    If your Confluence does not have the Upload app button in Manage apps, refer to this Atlassian ticket.
  3. Press the Configure button of the app, or open Administration → User Macros.

  4. The app checks all your User Macros. If they are all compatible with Confluence Cloud, nothing changes: go straight to step 6. If some macros are not compatible, a yellow banner appears above the list of macros:

    User Macros page with the compatibility banner
    • Show details lists every macro, its problem and the suggested fix.

    • Show usages under a macro opens a Confluence search with every page, blog post and comment that uses it.

    • Fix issues opens the fix window (see Fix Cloud compatibility issues).

    Banner with Show details openedConfluence search opened by Show usages
  5. (Recommended) Fix the issues before you export. See Fix Cloud compatibility issues.

  6. Press Export all macros (next to Create a User Macro).

    • If there are no issues, a JSON file with all your User Macros is downloaded automatically.

    • If some macros are not compatible, the window Some macros may not work in Confluence Cloud opens first. You can Fix issues or Export anyway.

    The Export all macros link
    Warning:
    The app fixes macro and parameter names. Because of Atlassian limitations, templates that rely on Server/Data Center-only features (for example $req, $action or $content.getCreator()) may still not work in Cloud. Do not worry: we are happy to help align your macros with Cloud. Send us the JSON file with your User Macros before you continue, and we will do everything we can: info@wombatscorp.com
  7. Open User Macro for Confluence Cloud and press Import.

    image-20250326-171324.png
  8. Choose the macros you want to import.

    image-20250423-090051.png

    You can keep the original macro key from Server/Data Center by selecting the corresponding checkbox. If you fixed a macro first, the key it keeps is the new one (for example info-panel instead of info_panel).

  9. Your Server/Data Center macros are now available in Confluence Cloud! 🎉

    image-20250326-171710.png

Cloud naming rules

User Macro for Confluence Cloud doesn't accept some names that Confluence Server/Data Center allows. A macro that breaks one of these rules will not work after the import.

Rule

Example

Suggested fix

The macro name can't contain _

info_panel

info-panel

A parameter name can't start with a digit

2nd

p2nd

A parameter name can't be fully uppercase

TITLE

title

A parameter name can't be a reserved name: macroId, pageId, pageVersion, spaceId, spaceKey, renderMode, outputType (in any letter case)

pageId

pageIdParam

Fix Cloud compatibility issues

Fix issues renames the incompatible macros and parameters and updates all content that uses them, so your pages keep working in Server/Data Center and are ready for Cloud.

Before you fix:
  • Back up your Confluence, or try the fix on a staging copy first.
  • Your account must be able to edit every page, blog post and comment that uses a macro. Page restrictions apply to administrators too. A macro used on content you can not edit is not fixed; it is marked Manual fix needed.
  • Run the fix at a quiet time. Drafts that are open in the editor during the fix keep the old names.
  • Every fixed macro adds one new version to each page that uses it. No notifications are sent.
  1. Press Fix issues in the banner, or Fix issues in the export window. The window lists every incompatible macro with its problem, the suggested fix, where it is used, and its status. Show usages opens the list of content that uses the macro.

    The fix window before fixing
  2. Press Fix issues. The macros are fixed one at a time:

    1. A corrected copy of the macro is saved. The old macro still works, so your pages keep rendering during the fix.

    2. Every page, blog post and comment that uses the macro is updated one at a time. Only the macro name and its parameter names change; nothing else on the page is touched. Each update is saved as a new page version, so you can restore it from Page history.

    3. When nothing uses the old name any more, the old macro is removed.

    The fix window while fixing
  3. You can press Stop at any time and Continue later. Steps that are already done are not repeated.

  4. If some content still uses the old name (for example content you can't see, or content created during the fix), the macro shows Old name still used with the list of that content. Update the content and press Continue, or press Finish anyway to remove the old macro regardless.

    A macro whose old name is still used, with Finish anyway
  5. When all macros are fixed, press Export to download the JSON file, or Close and reload.

    The fix window after fixing, with the Export button

Manual fix needed

Some macros can't be fixed automatically. They are marked Manual fix needed with the reason, and are skipped:

A macro marked Manual fix needed

Reason

What to do

A different macro already uses the new name (e.g. notice-box exists when fixing notice_box)

Rename or remove one of the macros, then run the fix again.

Two parameters would get the same name (e.g. ID and id)

Rename one of the parameters in the macro template and on the pages that use it.

A parameter is used in the template without a ## @param line

Add the ## @param line to the template, then run the fix again.

You can't edit some content that uses the macro

Ask someone who can edit that content to run the fix, or give your account edit permission.

To fix a macro manually, press Edit next to it on the User Macros page, rename it or its parameters, and update the pages that use it. Show usages helps you find them. If you need help, contact us at info@wombatscorp.com.

What is not updated

The fix updates the current version of pages, blog posts and comments. It does not change:

  • earlier page versions in Page history,

  • unpublished drafts,

  • page templates, space templates and global templates,

  • Custom HTML and other site-wide customisations.

After the old macro is removed, these places show an "Unknown macro" error for the old name.

Troubleshooting

Problem

Solution

"Export failed" message

Check the Confluence log for details. Older versions of the app downloaded an empty file on recent Confluence releases (8.5.x, 9.2.x); update to the latest version.

No Export all macros link

Older versions didn't show the link when Confluence runs under a context path such as /wiki. Update to the latest version.

"Your administrator session has expired"

Reload the User Macros page and confirm your password.

A macro is Manual fix needed although the name looks fine

Open Show details: the reason is shown under the macro. See Manual fix needed.

If you need any help, write to info@wombatscorp.com and attach the JSON file with your User Macros.