Migrating Legacy Data Center User Macros to Confluence Cloud via Forge: Feasibility & Workaround Check

Forge
1

Hi Community,

We are currently migrating from Confluence Data Center to Confluence Cloud. Our instance actively uses 20 custom User Macros across 3,495 pages.

We have already set up our local environment and started code research. We found that a few macros (html5-video, videojs, and conditional-formatting) can be replaced by native Confluence Cloud built-in features, so we do not need to rebuild them.

However, we plan to rebuild the remaining active macros as a private app using Atlassian Forge.

Forge Feasibility Check: Based on our macro list below, can ALL of them be successfully rebuilt using Atlassian Forge? Are there any that are completely impossible to build due to Cloud architecture?

  1. auibutton
  2. ep-rollover-image-link
  3. expand-collapse-all
  4. get-page-id
  5. getactiveusers
  6. hideelements
  7. imagehover
  8. jira-collector
  9. page-version
  10. pagebreak
  11. personal-space-buttons
  12. apmehandle
  13. genspace-administrators
  14. space-administrators-with-mail
  15. update-date
  16. alle-aufklappen-oder-zuklappen

We would highly appreciate any additional suggestions, warnings, or best practices for our custom macro migration approach.

Thank you for your guidance!
Kesava

2

Hi @GodlaKesavaPrasad,

The limit that will bite you is that a Forge macro only controls what it renders itself, and what it renders is whatever the author wrapped in its own body. Fetching outside data is fine, so get-page-id, page-version and update-date are a resolver call each. Changing how content it doesn’t own is displayed has no route.

That lands on your expand/collapse-all pair (expand-collapse-all and alle-aufklappen-oder-zuklappen look like the same macro listed twice). A button that toggles Expand macros already on the page has nothing to grab. Built as a bodied macro wrapping the sections it collapses it’s fine, but that means re-wrapping content across 3,495 pages.

I’d ask what hideelements actually does first: does it wrap the content it hides, or target elements elsewhere on the page by selector? The first is a bodied macro with a group check. The second has nowhere to stand.

3

Hi Mihai,

Thanks for the clarification.
For “hideElements”, we use it in DC to hide specific page elements/content based on the configured target.

Regarding “expand-collapse-all” and “alle-aufklappen-oder-zuklappen”, both macros provide the same/similar functionality to expand or collapse sections on a page.

For reference, below is the brief usage of each macro. Could you please confirm the Cloud/Forge feasibility for each one?

1. “eui-button” – Creates buttons/actions on a page.

2. “ep-rollover-image-link” – Provides rollover image and link functionality.

3. “expand-collapse-all” – Expands/collapses multiple sections on a page.

4. “get-page-id” – Retrieves the current Confluence page ID.

5. “getactiveusers” – Displays/retrieves active users.

6. “hideElements” – Hides specific page elements/content.

7. “imagehover” – Provides hover functionality for images.

8. “jira-collector” – Provides Jira feedback/issue collection functionality.

9. “page-version” – Displays the page version.

10. “pagebreak” – Controls page-break formatting.

11. “personal-space-buttons” – Provides actions/buttons for personal spaces.

12. “epmhandle” – Provides specific custom functionality used in our DC pages.

13. “genspace-administrators” – Displays space administrators.

14. “space-administrators-with-mail” – Displays space administrators with email details.

15. “update-date” – Displays/updates date information.

16. “alle-aufklappen-oder-zuklappen” – Expands/collapses page sections.

For each macro, could you please confirm whether it is:

- Available as a native Confluence Cloud feature,

- Possible to rebuild using Forge, or

- Not supported, with the recommended alternative if available.

Also, please let us know if there are any Cloud/API, permission, security, or migration limitations we should consider, and whether the existing macro content on migrated pages will continue to work as expected.

If we need assistance with rebuilding any of these macros, could you also let us know what support is available from your side? For example, guidance/documentation, technical assistance, or a call/session with the relevant team to help us with the Forge implementation.

This will help us finalize the migration approach for these macros.

Thanks for your guidance.

4

Hi @GodlaKesavaPrasad,

That settles hideElements and both expand/collapse macros. If a macro targets content by config rather than wrapping it in its own body, there is no Forge equivalent: a macro only controls the output it renders itself, and nothing in the API reaches the rest of the page, so anything that hides or restyles content it does not own has nowhere to stand at render time.

pagebreak fails for a different reason. A macro’s output is ADF, and I pulled @atlaskit/adf-schema 57.1.0 off npm to check the node type enum in its full.json: 66 node types, no page break in any spelling. A macro cannot emit one.

The rest read as self-contained, so I’d expect them to rebuild. For space-administrators-with-mail you want the read:email-address:confluence scope, otherwise addresses come back only where the user has made them visible. I wouldn’t sign off on epmhandle, ep-rollover-image-link or eui-button from a one-line description though. I think the question for each is the same one: does it render its own content, or reach for the page’s?

I’m not Atlassian, by the way, only another dev in this forum, but happy to keep going here.