Using the Macro Security Macro to Control User Macros
Overview
The macro-security macro is primarily a tool for administrators to enable usage control of user macros. When included in the logic of a user macro, it can be used to control who can edit content containing the user macro in a manner very similar to how other macro security controlled macros work.
Macro Security macro
The Macro Security macro is generally not used directly on a page. Instead, it is used within a user macro to enforce any restrictions coded for that user macro within the Macro Security properties file configured by a Confluence Administrator.
For testing purposes, you may wish to temporarily add the Macro Security macro to a page. To do this, you will need to type the entire markup shortcut in the editor to insert it, as the Macro Security macro is deliberately not visible in the Macro Browser.
Markup Shortcut | {macro-security} |
|---|
Screenshot
Parameters
The Macro Security macro accepts 3 parameters.
Parameter | Default | Macro Browser Label | Description |
|---|---|---|---|
name | <required> | Macro name | The name to use as the primary lookup in the macro security configuration to see if this particular use is allowed. |
parameter |
| Parameter name | Used to further qualify the security lookup when a Parameter Restriction is defined. Leave blank if not needed. Normally represents a macro parameter name. |
parameterValue |
| Parameter value | Used to further qualify the security lookup when a Parameter Restriction is defined. Leave blank if not needed. Only valid if a parameter name is provided. Normally represents a macro parameter value when specific values need to have secured use. |
Example 1 - Basic Use
This example demonstrates how to add support for a user macro named "restricted" that uses only Use Restrictions. A trusted user or group will be able to add this user macro to a page; other (non-trusted) users and groups will be able to view the page but not edit it. Learn more about Use Restrictions on the Understanding How Macro Security Works page.
There are two steps:
Editing and reloading the Macro Security properties file so it contains a Use Restriction entry for the user macro. This entry might look like this:
restricted = confluence-administratorsCoding the user macro so that it invokes the Macro Security macro and then directs its processing based on what is returned from the Macro Security macro.
In the example above:
These line(s): | Mean... |
|---|---|
| These are comments (as denoted by the "## " at the start of the line) that document the purpose and configuration of the user macro. |
| The #set line indicates to invoke (execute) the Macro Security macro, sending it its required name parameter which is the name of the user macro (restricted, in this example). This looks up the configuration of the "restricted" user macro in the Macro Security properties file and compares it to the "edit" page restrictions on the Confluence page on which the user macro is being used. The value returned by the Macro Security macro is placed into a variable named |
| The first line (#if...) determines if the Macro Security macro returned an error string. If it did not, then the "normal" processing statements will be executed. If it did return an error string, the "else" condition is executed to display the error message itself. |