Cannot add macro parameters programmatically in Confluence version gt 5.2

From Confluence 5.3 onwards it's not possible any more to add macro parameters when calling MacroDefinition.setParameters inside a MacroDefinitionUpdater, when the xhtml-macro definition declares any parameters.

MacroDefinitionUpdaters are used from:

    String body = xhtmlContent.updateMacroDefinitions(ceo.getBodyAsString(), conversionContext, new MacroDefinitionUpdater(){

This problem appears as soon as the macro has a parameter defined like

    <xhtml-macro name="macro-test" class="test.TestMacro" key="macroTest">
        <parameters>
            <parameter name="name" type="string" required="true"/>
....

Even if I add a placeholder in the macro definition for parameter I want updated, it is not added. Works in Confluence 4.3 - 5.2.

Cause

Confluence 5.3 now tries to maintain some structured values for macro params inside a new ac:structured-macro element. The storage macro marshaller for this element treats the MacroDefinition.typedParameters property as canonical in this case, and it only consults the (untyped) parameters property if the typedParameters property is null or empty.

As of Confluence 5.8, the types of typedParameters values can be one of:

• for xhtml-macro declared parameter type "username": UserResourceIdentifier
• for "spacekey": SpaceResourceIdentifier
• for "confluence-content": Link to a ResourceIdentifier
• for "url": UrlResourceIdentifier
• for "attachment": AttachmentResourceIdentifier
• for "full_attachment" (new in 5.6.5 and 5.7): AttachmentResourceIdentifier, fully qualified with the containing page/blog post and spacekey
• otherwise: String

Right now, too many property types are still treated as strings for the typedParameters map to be a permanent replacement. Longer term, the parameters property will be deprecated, and callers will need to migrate to using the typedParameters API.

Note also that handling for the default parameter is now also different: it is stored keyed by the empty string (""), rather than as a separate property. This applies to both the typedParameters and parameters properties.

Workarounds

For all of the workarounds below, you will need to define the macro parameter correctly in your xhtml-macro definition. You cannot rely on your parameter being parsed and stored safely without this. You can mark this parameter as hidden if you do not want it to show up in the macro editor.

1. Update the MacroDefinition.typedParameters property to hold the value you want to add/update, using the types as described above. This is the safest and most forwards compatible option. OR
2. Build a fresh MacroDefinition with the MacroDefinitionBuilder containing just the properties you want stored. This option risks shearing off additional attributes the Confluence internals want to store. OR
3. Null the typedParameters, to force the persistence code to fall back to using the old parameters property instead. Note that this option may cause page, blog and attachment links to break again, due to the problems with wikimarkup special characters.

Fix

We could add a way of tracking if the MacroDefinition.parameters property was modified while invoking any of the XhtmlContent macro methods, and if so use it to persist the macro params instead of the typed parameters. Note that this may cause page, blog and attachment links to break again, due to the problems with wikimarkup special characters