Configure Macro Security

Once you have installed the Macro Security for Confluence add-on, it must be configured with a property file that identifies who can run each security-enabled macro. Each macro security enabled macro accepts specific parameters to controls its use. This safeguards your Confluence instance and data from misuse or performance issues caused by inexperienced users or inappropriate use.

Follow these steps to configure it:

1. Download the sample macro-security.properties file that is configured for moderate restrictions. This restricts most security-enabled macros so that only Administrators can execute them, but allows some others to be used by any user.

2. Review the file and ensure that the lines beginning with "sql-query.datasource.*", "run" and "run-now" are restricted to the confluence-administrators group as shown in the example configuration file to the right.

3. Save the file.

4. Create a Confluence page entitled Macro Security Configuration in a space accessible only to Administrators (or apply page-level restrictions so the page is accessible only to Administrators) and attach the file to it. Take note of the space key of the space. The space key appears in the URL of the page after you've saved, immediately after "display/". For instance, in the URL http://wiki.examplegear.com/display/admin/Macro Security Configuration, the space key is admin.

5. Go to Manage Add-ons administration screen, locate the Macro Security add-on and click its Configure button. This will take you to the Macro Security configuration screen.

6. In the Load Security Configuration section, supply the location of your macro-security.properties file, in the form of spacekey:pagetitle^filename such as admin:Macro Security Configuration^macro-security.properties and click Load.

1. Select the Enable button and click Save.

# See the documentation space - https://bobswiftappfire.atlassian.net/wiki/display/CMSP
# More specifically:
# - managed macros: https://bobswiftappfire.atlassian.net/wiki/display/CMSP/Macro+Security+Managed+Macros
#
# Macro security is enabled/disabled from the UPM configure link for Macro Security for Confluence
# Property setting are loaded from the same configuration screen.
#
# Property settings here can restrict use of some powerful macro capabilities to trusted users
#   while still allowing non-trusted users to view content created by using these macros
# - this is accomplished by requiring those pages using the restricted macros
#   are controlled by trusted users
#   - a page is controlled by having edit capabilities restricted to a group
#     that is identified as being trusted in the properties file
#   - a page is also considered to be controlled if it is in a permitted space
#
# Property file
# - The property file can be loaded from any file location on the Confluence server or from an attachment
#
# No specific configuration
# - Add-ons can implement their own rules if there is no specific configuration found
#   depending on what they are restricting
# - Standard/default is
#   - Configuration entry must be specified if the macro is restricted
#     - *ANY can be used to allow all use (run is an example where *ANY is a likely use)
#   - Some macros have additional, finer grained (parameter level) restrictions
#     - these MUST also have something specified, otherwise macro use is not authorized
#   - Some macros only restrict a specific parameter
#     - these generally do not have to be specifically configured for use
#
# Property keys and values are case sensitive
#
# Property values are a comma separated list of groups or space names
# - the page edit restriction must match one of the groups listed
# - no other users or groups can be permitted to edit the page
# - use *ANY to indicate no restriction
#
 
# SQL - https://bobswiftappfire.atlassian.net/wiki/display/SQL
sql = confluence-administrators
sql.datasource.* = confluence-administrators
sql.datasource.testDS = *ANY
sql.limit = confluence-administrators
sql.disableAntiXss = confluence-administrators
sql.querytimeout = confluence-administrators
 
sql-query = confluence-administrators
sql-query.datasource.* = confluence-administrators
sql-query.datasource.testDS = *ANY
sql-query.limit = confluence-administrators
sql-query.disableAntiXss = confluence-administrators
sql-query.querytimeout = confluence-administrators
 
# Live template support - https://bobswiftappfire.atlassian.net/wiki/display/CMSP/Live+Template+Support
sql-query&live-template.datasource.* = *global
 
# Script - https://bobswiftappfire.atlassian.net/wiki/display/SCRP
beanshell = confluence-administrators
groovy = confluence-administrators
gant = confluence-administrators
jython = confluence-administrators
 
# HTML - https://bobswiftappfire.atlassian.net/wiki/display/HTML
html = confluence-administrators
xslt = confluence-administrators
 
# Run CLI Actions - https://bobswiftappfire.atlassian.net/wiki/display/CCLI
cli = confluence-administrators
cli.profile.* = confluence-administrators
cli.product.* = confluence-administrators
cli.directory.* = confluence-administrators
cli.datasource.* = confluence-administrators
 
include-remote = confluence-administrators
include-remote.profile.* = confluence-administrators
 
# Cache - https://bobswiftappfire.atlassian.net/wiki/display/CACHE
cache = *ANY
future = *ANY
future.timeout = confluence-administrators
 
# Run - https://bobswiftappfire.atlassian.net/wiki/display/RUN
run = confluence-administrators
run-now = confluence-administrators
run.disableAntiXss = confluence-administrators
 
# Advanced Tables - https://bobswiftappfire.atlassian.net/wiki/display/TBL
csv.url.* = *ANY
csv.disableAntiXss = confluence-administrators
json-table.url.* = *ANY
json-table.disableAntiXss = confluence-administrators
 
# Excel - https://bobswiftappfire.atlassian.net/wiki/display/XL
excel.url.* = *ANY
excel.disableAntiXss = confluence-administrators
 
# Flash - https://bobswiftappfire.atlassian.net/wiki/display/FLASH
flash.url.* = confluence-administrators
 
# Markdown - https://bobswiftappfire.atlassian.net/wiki/display/MARKDOWN
markdown.allowHtml = confluence-administrators
markdown-attachment.allowHtml = confluence-administrators
markdown-url.allowHtml = confluence-administrators
 
# Code Pro - https://bobswiftappfire.atlassian.net/wiki/display/CODE
code-pro.url = *ANY
code-pro.profile.* = confluence-administrators

Macro Security Configuration page, after loading the macro-security.properties file:

Create Confluence page

Create a Confluence page that will eventually contain the macros needed to run the self-service report.

1. Create a page named For Management Review in a space accessible to the desired audience.
2. Click the Unrestricted button to open the Page Restrictions screen.
3. Click the Restrict editing radio button.
4. Start typing confluence-administrators in the text box and select that group name from the list of suggestions to apply an edit restriction to that group. This restriction is being added so that Macro Security managed macros can be used.
5. Click Save to close the Page Restrictions screen.
6. Click Save to save the new page.

Configure the Run macro

Edit the For Management Review page and do the following:

1. Insert the Run with a user form and parameters macro, which is part of the Run Self-Service Reports for Confluence add-on.
2. Click the Run macro container and click Edit so you can adjust its parameters as shown on the right.
   • The Replace field list parameter indicates to show a single field in the self-service form, with its default value set to "acquisition." The field will be labeled as "Search HipChat for this word" and will be referenced by a variable name of "word1."
   • The Hide export button indicates to suppress the display of the Export button. This is unnecessary as the output will be shown on this page.
   • The Field name to receive focus parameter indicates to display the page with the cursor positioned in the "word1" field.

The page is not yet fully operational, so you can remain in Edit mode for the next step.

Configure the CLI macro

This step uses the CLI macro, which is part of the Run CLI Actions in Confluence add-on, to retrieve the HipChat chat history that references the selected word. To configure the CLI macro, do the following:

1. With the cursor positioned inside the Run macro container, insert the CLI macro.
2. Click the CLI macro container and click Edit so you can adjust its parameters as shown on the right.
   • The Profile parameter provides the name of the profile you set up for accessing your HipChat instance.
   • The Product parameter indicates the name of the Atlassian product whose CLI you will be using.
   • TheHide the output parameter indicates to suppress the display of the messages generated when the CLI command runs.
3. Copy the example CLI command inside the CLI macro container. 
   
   1. The runFromRoomList action indicates to retrieve a list of public HipChat rooms and then, for each room, run the action indicated by the --common parameter. (Note that the value of the --common parameter extends up to the final double quote (") character.)
   2. The getRoomHistoryList action  that is executed for each room returned by the runFromRoomList action includes these parameters:
   • • --room indicates to access the current HipChat room

     • --file indicates to save the references to the words you're monitoring into a file named chatreferences.csv. Since you are running the CLI command within Confluence, this file will be saved by default to the /script/cli/<page_id> folder in your Confluence home folder, where <page_id> represents the page id of the page containing the CLI macro. Note that the script folder will be created, if it doesn't already exist, the first time a CLI command is invoked with a parameter that indicates to create an output file.

     • --append indicates to append the output to the chatreferences.csv file if it already exists. This is important since the references may be written from multiple HipChat rooms.

     • --regex provides a Regex expression that indicates to look for references to the word supplied on the self-service form ($word1 in this case). Note that this expression is inserted between \" and \" since it must be quoted but appears within the entire --common parameter which is also quoted.

The page is not yet fully operational, so you can remain in Edit mode for the next step.

Example CLI command:

--action runFromRoomList --common "--action getRoomHistoryList --file "chatreferences.csv" --append --room "@room@"  --regex ".*\b(?:$word1)\b.*" "

Configure the CSV macro

This step uses the CSV macro, which is part of the Advanced Tables for Confluence add-on to present the output generated from the preceding CLI macro in a Confluence table. To configure the CSV macro, do the following:

1. With the cursor positioned inside the Run macro container and after the CLI macro container, insert the CSV macro.
2. Click the CSV macro container and click Edit so you can adjust its parameters as shown on the right.
   • The Columns to show parameter indicates to show only the 4 named columns, which eliminates some columns that aren't likely to be of interest.
   • The CSV macro assumes the input file (chatreferences.csv) resides in the script folder within your Confluence installation's home folder. The Location of CSV data parameter is used to override this, indicating it can be found in the cli/$page_id subfolder within the script folder of your Confluence installation's home directory. $page_id is a pre-defined variable recognized by the Run and Run Now macros that represents the page id of the page containing the Run macro.
   • The Auto number on each row parameter indicates to number each table row in the output.
   • The Show sort icon parameter indicates to show an icon next to each column heading in the table so the user can easily understand that the output is sortable.
   • The Auto sort column parameter indicates to sort the output based on the first column, which is the Room column.
   • The Column Types parameter define the four columns as string, date, string and string. The default column type is string but since the second column shown is a date, specifying "M" ensures it will be sorted as a date.

The page should now appear as shown on the right. It is now operational, so click Save to save the page.

Page in Edit mode:

Run the report

You should now see a page that appears as shown in the first image on the right.

Once you click the Run button, you will see output similar to the second image shown on the right (assuming references to the specified word were found).

If you encounter any errors,  you may find it helpful to temporarily change some macro parameters to help you troubleshoot the error:

• Run macro
  • Set Automatically render body on display to true so that the report runs right away. This allows you to run it from the Preview pane while editing the macro in the Macro Browser.
• CLI macro
  • Set Show command in panel to true so that the full command you're executing is displayed.
  • Set Use panel for output to true so the output messages appear in No Format macro panel, which makes it easier to read and distinguish it from the remaining output.
  • Set Hide the output to false so the output message are shown.

Page in View mode (after clicking Run):

Bonus Tip

Div
class time
Status title Optional Estimated Time: 3 min

While not required, you may find it helpful to install the Wiki Markup for Confluence add-on. This add-on allows you to code macros using Wiki Markup notation that was available in Confluence prior to version 4.0 — even in Confluence 4.0 and later.

With this approach, the parameter settings may be more obvious and easier to understand, and it makes it easier to cut-and-paste them to another page.

The Run macro would be left as explained previously, but the CLI and CSV macros would be coded in Wiki Markup notation and be inserted within a Wiki Markup without Migration macro container, as shown on the right.

Wiki Markup to be inserted within the Wiki Markup without Migration macro container:

{cli:profile=hipchat|product=hipchat|hideOutput=true}
--action runFromRoomList --common "--action getRoomHistoryList --file "chatreferences.csv" --append --room "@room@"  --regex ".*\b(?:$word1)\b.*" "
{cli}
{csv:script=#cli/$page_id/chatreferences.csv|columns=Room,Date,Message,From Name|autoNumber=true|sortIcon=true|sortColumn=1|columnTypes=S,M,S,S}