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

Could someone kindly explain - or link to documentation explaining - what the “macro-id” parameter in XML source is used for?

To test, I created 3 instances of the same macro on a Confluence page. Then, when I look at the source storage format, the ac:macro-id="…" for each instance have different ids, even though the macro is the same.

Also, when I use the XML in a User Macro, without the macro-id parameter, the resulting pages using the User Macro appear to execute the macro just fine. In other words, the User Macros execute the same regardless of whether the macro-id parameter is present or not.

If this is the case, what is the purpose of the “macro-id” parameter?

Thanks in advance.
M

Another way to frame my inquiry:
What negative effect could occur if the macro-id is incorrect, or absent altogether in a User Macro XML source?

For example, if I create a User Macro that just calls the “cheese” macro twice.
It could be written as:

<p><ac:structured-macro ac:name="cheese" ac:schema-version="1" ac:macro-id="6f58a3b3-35a8-4988-9b6b-0ace97bf6478" /></p>
<p><ac:structured-macro ac:name="cheese" ac:schema-version="1" ac:macro-id="1b7a26f0-73be-4d4c-a46f-6fd2f3463a51" /></p>

or, as:

<p><ac:structured-macro ac:name="cheese" ac:schema-version="1" /></p>
<p><ac:structured-macro ac:name="cheese" ac:schema-version="1" /></p>

Is there any danger in coding the latter (without the macro-id specified) versus the former?

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: https://developer.atlassian.com/server/confluence/preparing-for-confluence-5-8/

Source: https://developer.atlassian.com/cloud/confluence/rest/#api-content-id-history-version-macro-id-macroId-get

From my experience macros do not have an ID if they are generated prior to Confluence 5.8 (that is they do not automatically get one until they are saved with a later version) or if the page has been generated by a space blueprint. But I have no references for this.

2 Likes