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.

5

Hi Mihai,

Thanks for the detailed clarification and guidance. This is very helpful for our migration planning.

To help confirm the remaining macros, here is a brief description of their current DC usage:

Data Center pages:

  • eui-button – Used to create clickable buttons on a page, mainly for navigation to other Confluence pages/sections or external links, with a specific button-style presentation.
  • ep-rollover-image-link – Used to display an image which changes/rolls over when the user moves the mouse over it, and the image acts as a clickable link.
  • getactiveusers – Used to retrieve/display the currently active Confluence users on the page.
  • imagehover – Used to provide a hover effect on images, where the image/content changes or displays additional information when the user moves the mouse over it.
  • jira-collector – Used to provide a Jira feedback/issue collection option directly from a Confluence page, allowing users to submit feedback or raise/collect Jira-related requests.
  • personal-space-buttons – Used to provide buttons/actions related to a user’s personal space, mainly for quick navigation or actions within the personal space.
  • epmhandle – This is a custom macro used on some of our DC pages. We need to check its exact Cloud/Forge feasibility based on its current implementation.
  • genspace-administrators – Used to retrieve and display the administrators of the current Confluence space.
  • space-administrators-with-mail – Similar to the above, but additionally displays the email address of the space administrators.

Regarding your question: the main purpose of these macros is to render their own functionality/content on the page. However, some of them may need to retrieve information from Confluence/Jira (such as users, space administrators, or page context) through APIs. They are not intended to modify or control arbitrary content outside their own macro.

Could you please confirm whether these can be rebuilt in Confluence Cloud using Forge with the same or similar end-user functionality, and mention any API/permission/security limitations?

As I understand, get-page-id, page-version, and update-date are feasible to rebuild using Forge.

We also understand that hideElements, expand-collapse-all, alle-aufklappen-oder-zuklappen, and pagebreak are not possible to rebuild using Forge and currently have no suitable alternative.

Thanks again for your support and clarification. This will help us finalize our migration approach.

6

Hi @GodlaKesavaPrasad,

Per macro.

get-page-id, page-version, update-date stay settled.

macro doable how catch
eui-button yes a link none.
ep-rollover-image-link yes Custom UI UI Kit has no raw HTML or DOM access; its :hover only styles Box/Pressable with token values, so an image swap isn’t reachable there.
getactiveusers depends on “active” licensed accounts, v1 search/user with cql type=user, scope read:content-details:confluence if it means who is on the page right now, no presence endpoint exists in v1 or v2.
imagehover yes same same.
jira-collector caveat script domain under permissions.external.scripts unlisted, it doesn’t load.
personal-space-buttons should be user endpoint with expand=personalSpace untested.
epmhandle no verdict undescribed tell me.
genspace-administrators caveat v2 space permissions, scope read:space:confluence filter for operation.key = administer.
space-administrators-with-mail caveat same, plus email needs profile visibility Anyone, or read:email-address:confluence plus the email endpoint.

I’d start both in Custom UI.

Two limits cut across everything: no arbitrary script injection, and external scripts only run through the manifest allow-list, which means a new major version plus admin consent for every domain you add later.

Must the admin lists include admins granted through a group rather than directly?

And what does epmhandle do?