Versions Compared

Old Version 8

changes.mady.by.user Betsy Walker

Saved on

compared with

New Version 9

changes.mady.by.user Betsy Walker

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Overview

Excerpt

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.

Basic Use

Normally

Macro Security macro

The Macro Security macro is generally not used directly on a page unless for testing. It is purposely hidden in the Macro browser, but you can type . 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

Panel
bgColor#efefef

 On This Page:

Table of Contents
maxLevel32

Parameters

(info) Click a column heading to toggle the sorting of that columnThe Macro Security macro accepts 3 parameters.

Table plus
highlightColor#ffffec
rowStylesbackground:#f0f0f0;color:#222;font-size:14px;border-bottom:black 2px solid;border-top:black 2px solid;,
stylebackground-color:white;
autoNumbertrue
Parameter
Default
Macro Browser Label
Description
name<required>Macro nameThe 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

The primary use is in a user macro or private macro.

Here is a simple user macro example. This macro will only continue to process and render content if the security configuration and context allow it to do so.

Image Removed

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:

  1. 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:

    Code Block
    restricted = confluence-administrators
  2. Coding 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.

Image Added

In the example above:

Table plus
columnStyleswidth:70%,width:30%
columnTypesS,S
styletable-layout: fixed; width: 100%;
These line(s):Mean...

## Macro title: Restricted
## Body processing: No macro bodyo
##
## Developed by: Bob Swift Atlassian Add-ons
## Date created: 11/23/2015
## Installed by: <your name>

## This is a user macro the demonstrates how to incorporate
## Macro Security into a user macro.

These are comments (as denoted by the "## " at the start of the line) that document the purpose and configuration of the user macro.

## Check for authorized use
#set ($securityMessage = $action.getHelper().renderConfluenceMacro("{macro-security:restricted}"))

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 $securityMessage. This will reflect an empty string if the security configuration and "edit" page restriction conditions are met; otherwise it will return an error string that indicates the reason for the error.

#if ($securityMessage =="")
    ## There are no security issues, so do whatever the macro's normal
    ## processing would be here
    This is the result of the macro
#else
    ## Just send out the security error message as is.
    $securityMessage
#end

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.
HTML Comment
hiddentrue

Example 2 - Advanced Use

This example demonstrates how to add support for a user macro that uses both Use Restrictions and Parameter 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:

  1. 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:

    Code Block
    restricted = confluence-administrators
  2. Coding 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.