Mismatch in localId of Confluence macro

[NguyenLe]

Hi everyone,

I’m working on a feature where our app adds a macro to Confluence pages. The feature works as expected when the page has current status. However, when the page is switched to edit mode, or when the macro is added to a page that is still in draft status, the macro stops working and displays an error that we defined ourselves.

After investigating, I found that the issue is caused by the localId assigned to the macro being changed when the page switches between these states or when added to draft version of the page. Our macro relies on localId to fetch the data needed for rendering.

After some reseach, IIUC, localId is supposed to be handled by Confluence rather than explicitly assigned by the app. In the case the app assign the ID, Confluence won’t change the ID unless it is conflicted. This made me wonder why explicitly assigning a localId appears to work correctly for pages with current status, but then gets replaced when the page enters edit mode or is saved as a draft (please note that the ID I assigned to the macro is a UUID, which would be very hard to be conflicted with other IDs).

Has anyone encountered similar behavior or knows why Confluence handles localId differently between current and draft/edit-mode content?

[remie]

Ah yes, the macro ID conundrum!

Unfortunately, over the course of the years, the relevant documentation for this has disappeared from the official sources, but fortunately there is still some information left to be found here on the forums:

What is the purpose of macro-id in the source XML?

As this question is a couple of months old, this is probably no longer of interest for mike4. But since I searched for references myself and found this question first, the following may save some minutes for others having the same question. As far as I know the macro ID is only unique within a page. If the macro has no ID, one will be created. The purpose is to make a macro identifiable, but the ID may change at any time. Here are some sources for references: Source: Preparing for Confluence…

In short, the macro ID is replaced by an auto generated UUID with ever new version. This is not a reliable identifier!

[NguyenLe]

Hello @remie, thank you for answering.

As you mentioned, the macro ID (or localId in current time) will change after every new version of the document. This raised a concern regarding our previously created macros: Does this issue also apply to macros created by using command syntax (the / input)? If yes, it is interesting how our app hasn’t got any tickets regarding this problem yet.

[remie]

@NguyenLe

If yes, it is interesting how our app hasn’t got any tickets regarding this problem yet.

We solved it by not using localId. We create our own ID and add it to the macro properties. This has proved to be the most reliable method, although it creates a separate issue when users copy macros (as the ID property will also be copied)