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: 9.x: |
|---|---|
Not supported yet | Confluence 10.x |
Who can use it | Confluence administrators |
App version | 1.1.0 |
How to use
Download User Macro Exporter from Google Drive. Choose the file that matches your Confluence version (see the table above).
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.Press the Configure button of the app, or open Administration → User Macros.
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:
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).
(Recommended) Fix the issues before you export. See Fix Cloud compatibility issues.
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.
Warning:The app fixes macro and parameter names. Because of Atlassian limitations, templates that rely on Server/Data Center-only features (for example$req,$actionor$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.comOpen User Macro for Confluence Cloud and press Import.
Choose the macros you want to import.
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-panelinstead ofinfo_panel).Your Server/Data Center macros are now available in Confluence Cloud! 🎉
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 |
|
|
A parameter name can't start with a digit |
|
|
A parameter name can't be fully uppercase |
|
|
A parameter name can't be a reserved name: |
|
|
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.
- 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.
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.
Press Fix issues. The macros are fixed one at a time:
A corrected copy of the macro is saved. The old macro still works, so your pages keep rendering during the fix.
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.
When nothing uses the old name any more, the old macro is removed.
You can press Stop at any time and Continue later. Steps that are already done are not repeated.
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.
When all macros are fixed, press Export to download the JSON file, or Close and reload.
Manual fix needed
Some macros can't be fixed automatically. They are marked Manual fix needed with the reason, and are skipped:
Reason | What to do |
|---|---|
A different macro already uses the new name (e.g. | Rename or remove one of the macros, then run the fix again. |
Two parameters would get the same name (e.g. | 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 | Add the |
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 |
"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.