This page describes how Confluence Add-on developers can easily add code so that its macros implement Macro Security.

Adding the Code

The following code should be placed so that it is executed before each macro within the add-on returns rendered data. In general, it will be placed at the start of the macro logic. If there are any parameter restrictions that the macro will implement, the code for them should be placed just after any parameter handling logic. This snippet is unlikely to require changes to support new versions of Confluence. 

In the code below, the name of the add-on's macro is "restricted", which has one parameter ("myRestrictedParameterName") for which a Parameter Restriction is supported. You would substitute the name of your macro and its parameter, of course.

import com.atlassian.renderer.v2.SubRenderer;
...
String securityMessage = subRenderer.render("{macro-security:restricted}", pageContext, RenderMode.suppress(RenderMode.F_FIRST_PARA));
...
if (!securityMessage.equals("")) {  // Macro Security is reporting an error due to a Use Restriction
    throw MacroExecutionException(securityMessage);
}
...
if (!parameterValue.equals("")) { 
    securityMessage = subRenderer.render("{macro-security:restricted|parameter=myRestrictedParameterName}",
        pageContext, RenderMode.suppress(RenderMode.F_FIRST_PARA));

    if (!securityMessage.equals("")) {  // Macro Security is reporting an error due to a Parameter Restriction
        throw MacroExecutionException(securityMessage);
    }
}

 How your customers use Macro Security with your add-on

To use your add-on's new Macro Security capability, your customer's Confluence Administrators must:

1. Install your add-on
2. Install the Macro Security add-on
3. Configure and enable Macro Security, including adding a Use Restriction entry and (optionally) any number of Parameter Restriction entries for your add-on's macros.
4. Ensure the appropriate restrictions are in place, as described in Understanding How Macro Security Works:
   
   1. If using Trusted Users and Groups, the appropriate "edit" page restriction(s) are in place on content using your restricted macros.
   2. If using Trusted Spaces, the appropriate space-level permissions are in place to ensure that only trusted users and groups can edit content in the space.