Macros are small code generators that perform a task. The following documentation explains bundled macros, which are macros that are included in ScriptRunner for Confluence. Customization is not required for bundled macros. This documentation is sorted by macro in alphabetical order.

The library of bundled macros is expanding. New macros are added based on need. If there is a macro that would be useful to you, let us know by filling out this form.

Eventually, you’ll be building these macros yourself. For more information on building macros yourself, visit Custom Macros.

Add Label Macro

The Add Label macro adds specified labels to a page if they are not already present. Some predefined variables are allowed, and you can overwrite these variables or add specified custom variables.

When you are editing or creating a page in Confluence, you can use ScriptRunner for Confluence to add a label to the page.

  1. Select Insert, and then select Other Macros.

    macro browser

  1. Select the Add Label macro from the provided list.

    add label macro list

  1. Complete the Labels field.

    add label macro config example

    Labels must obey naming restrictions imposed by Atlassian. Certain characters (:, ;, ., ,, ?, &, [, ], (, ), #, ^, *, @, !, ', `, spaces) are not allowed.

    Some restricted characters are modified when possible to allow successful application of labels.

  1. Click Save and the labels you added appear on the page.

    add label macro pic

When the page where the macro is located is refreshed, the labels are applied. If some of the labels are already present, only the missing labels are applied. If all the labels are already present, no action is taken.

Use Provided Variables as Labels: ScriptRunner provides several variables that you can use to add specific labels. To use them, add the variables to the Labels field as you would any standard label.

  • $username - Username of the person who created and/or edited the page.

  • $fullname - The full name of the person who created and/or edited the page.

  • $year - The year when the page was created and/or edited.

  • $month - The month when the page was created and/or edited.

  • $day - The day when the page was created and/or edited.

  • $parent - The parent title of the current page.

Once you save the macro and the page loads, variable labels load with the correct data. The added labels can be seen on the bottom right of the page.

Choose Label Macro

The Choose Label macro provides you with predefined options for adding labels and generating suggested labels to a page if they are not present. You can use some predefined variables, overwrite variables, or add user-specified custom variables.

When you are editing or creating a page in Confluence, you can use ScriptRunner for Confluence to choose labels for a page.

  1. Select Insert, and then select Other Macros.

    macro browser

  1. Select the Choose Label macro from the provided list.

    choose label macro list

  1. Complete the following fields as needed:

    Field Description Type Default Required Tip

    Title

    Specify a title for the macro which will be displayed above the macro.

    string

    none

    no

    N/A

    Labels

    Specify the labels using a comma separated list.

    string

    none

    yes

    • Labels must obey naming restrictions imposed by Atlassian. Certain characters (:, ;, ., ,, ?, &, [, ], (, ), #, ^, *, @, !, ', `, spaces) are not allowed.

    • Some restricted characters are modified when possible to allow successful application of labels.

    Descriptions

    Specify label descriptions using a comma separated list. If this field is left empty, the description of each label is the same as the label. If populated, the length of the description and label field must match.

    string

    none

    no

    None

    Button Text

    Specify custom text for the Add Label button.

    string

    Add Label

    no

    N/A

    Multiselect

    Allow multiple labels to be added at the same time.

    boolean

    false

    no

    • Without Multiselect enabled, the macro is hidden after the first label is added.

    • With Multiselect enabled, the macro is hidden once all the labels are added. Several labels can be added at one time. Generated suggested labels are not taken into consideration when hiding the macro.

    Show Suggested Labels on the Macro

    Allow the system to suggest labels on the macro based on the content of the page.

    boolean

    false

    no

    Label suggestions only start working once at least 100 words are added to the page. Label suggestions become more accurate as more words are added, with good suggestions arising at over 500 words. Supported languages are English, German, Dutch, and Danish.

    Show Suggested Labels on Label Dialog

    Shows the suggested labels on the label dialog.

    boolean

    false

    no

    Label suggestions only start working once at least 100 words are added to the page. Label suggestions become more accurate as more words are added, with good suggestions arising at over 500 words. Supported languages are English, German, Dutch, and Danish.
    choose label macro config example
Mixing languages on a Confluence page results in undefined label suggestion behaviour.

  1. Click Save, and the macro appears on the page.

    choose label macro pic

    When the page where the macro is located is opened, the Choose Label macro is shown and only the applicable labels are shown. If all the provided labels are already present on the page, the macro is not shown.

Macro Configuration: Use Provided Variables as Labels

ScriptRunner provides several variables that you can use to add specific labels. To use them, add the variables to the Labels field as you would any standard label.

  • $username - Username of the person who created and/or edited the page.

  • $fullname - The full name of the person who created and/or edited the page.

  • $year - The year when the page was created and/or edited.

  • $month - The month when the page was created and/or edited.

  • $day - The day when the page was created and/or edited.

  • $parent - The parent title of the current page.

Once you save the macro and the page loads, variable labels load with the correct data. The added labels can be seen on the bottom right of the page.

Macro Configuration: Use the Generated Label Suggestions Feature

  1. Tick the Show Suggested Labels on the Macro checkbox on the Edit 'Choose Label' Macro dialog.

    choose label macro config example2

  1. Choose the suggestions that you want.

    choose label macro render example2

  1. Click Save, and the rendered macro appears on the page.

Macro Configuration: Choose Suggested Generated Labels

  1. Tick the Show Suggested Labels on Label Dialog checkbox on the Edit 'Choose Label' Macro dialog.

    choose label macro config example2

  2. Click Save.

  1. Open the Labels dialog by doing one of the following:

    • When you are in edit mode on the page, select the Label icon (the tag by the file path, pictured below).

      label icon

    • When you are on the page not in edit mode, by press "L" on the keyboard.

  1. When the Labels dialog box appears, choose generated labels here.

    choose label macro render example3

Converting Pages Macro

If you have multiple Include Page macros on a page, it it is difficult to manually update them. A Representational State Transfer (REST) endpoint is included in the Converting Pages macro, which converts all instances of Include Page to Include Version. The version number is specified to be the current latest version, so the page contents should be identical in all instances. The page contents remain identical until one of the includes is modified.

You can easily hook up this REST endpoint using a web item. You can see the fields that you fill out to create a web item in the following image:

convert includes web item

The link address of the condition code is:

/rest/scriptrunner-confluence/latest/content-info/convert-includes?pageId=${page.id}&#url_xsrfToken()

The following image is the result of the Converting Page macro being configured:

convert includes disp
This result only appears on the pages that contain the Include Page macro.

CQL Search Macro

If you provide the CQL query, the CQL Search Macro macro executes the search and returns the results as links to pages. This macro is useful to show the results of complex queries on pages, labels, etc.

Create Page Macro

The Create Page macro helps users to create pages in the right place, with the right template and correctly formatted page title.

Usage

  • Click Insert > Other Macros.

macro browser

  • Select the Create Page macro from the provided list.

create page macro list

  • Complete the desired fields.

Parameter Description Type Default Required

Parent

By default, the created page will use the current page as its parent. However, you can specify a different parent page by supplying the page title. This field also accepts the variables: $self, $parent, $username, $fullname, $year, $month and $day.

string

$self

no

Title

Specifies the title of the new page. This field also accepts the following variables: $parenttitle, $ident, $username, $fullname, $year, $month and $day.

string

none

no

From Page

Specifies an existing page from which the new page will copy content

string

none

no

Labels

Add labels to the newly created page. Accepts several labels in a comma separated list. The following variables can be used: $parenttitle, $pagetitle, $username, $fullname, $year, $month and $day.

string

none

no

Title Prefix

Prefix to be applied to the page title given by the user.

string

none

no

Title Suffix

Suffix to be applied to the name given by the user.

string

none

no

Target Mode

Options are 'view' or 'edit'. Whether to go to view or edit mode when creating the page.

enum

view mode

yes

Template

The name of the template that will be used when creating the new page.

string

none

no

AUI Class

Optional AUI Class to help with styling. Use "aui-button" to represent a button or "aui-message" for an alert style message. More information can be found at https://docs.atlassian.com/aui/

string

none

no

CSS

Optional basic CSS to help with styling. Please provide css in a comma separated list, for example: "font-size: 20px, background-color: red". More information can be found at https://www.w3schools.com/css/default.asp

string (csv)

none

no

Ident Index

Allow the $ident parameter to start from a specific number.

int

none

no

Add Space

Add a space in between prefix and postfix variables.

boolean

true

no

Prompt Title

Customise the title used in the prompt dialog. If left empty then the title will be Please enter the new page title

string

none

no

Suppress Notification

Suppress notification while creating page.

boolean

false

no

Open in a new tab

Open the created page in a new tab

boolean

false

no

Variable descriptions

Variable Description

$parenttitle

the title of the parent page.

$ident

a number which increments each time a new page is created if the title exists.

$increment

a number which increments each time a new page is created.

$username

the username of the user that created the page.

$fullname

the full name of the user that created the page.

$year

the current year.

$month

the current month.

$day

the current day.

$self

the current page.

Labels must obey naming restrictions imposed by Atlassian. The following characters will be removed (:, ;, ,, ., , ?, &, [, ], (, ), #, ^, *, @, !, ' ' spaces ).

  • Supply the text that is going to be used to display the Create page link.

createPageMacroEdit

  • Save the Confluence page

createPageMacroView

Currency Converter Macro

The Currency Converter macro converts an amount of money to multiple target currencies based on the last close of day exchange rate. The reference rates are usually updated around 16:00 CET on every working day, except on target closing days. They are based on a regular daily concertation procedure between central banks across Europe, which normally takes place at 14:15 CET.

It uses European Central Bank exchange rates.

Previously (v5.2.10 and earlier), Yahoo was used before their service was retired.

To get the last daily exchange rate just provide a valid Amount, and then select the From and To currencies. You can see those three fields in the following image:

currency converter

Include Version Macro

Use the Include Version macro to choose a specific version of the page to display. This macro is similar to the Include Page macro.

Using Include Version, you can create a space that consists only of boilerplates that can be great for proposals and reports. The boilerplates can be as long or short as you want it to be; some may only be a combination of include macros.

When including a page using this macro, the page defaults to the number of the latest version. There is an additional macro Latest, which simply tracks the latest version. When Latest is used, it becomes identical to the standard Include Page macro.

The following image shows the Include Version macro selection screen:

include version macro config

You can use the macro browser preview functionality to view the results of including the different versions.

A common problem associated with this macro is making edits to a page that will show up in multiple places. If someone is not aware of all the places the page shows up, the changes could be inaccurate in some places. Using the Includes Report macro lets you control this. See more information in the Includes Report Macro section.

Includes Report Macro

Use the Includes Report macro with the Include Version macro to keep track of versioning and links to the different places the pages are used, also called diffs. This macro includes which pages have later versions with links to the different places they are used.

This macro provides a button to Update All, which updates all included pages to the latest version number. Make sure to check the diffs first to make sure this is the needed version number. When this macro is used, it will create and save a new version of the current page. You can roll the page back to a previous version if it wasn’t the result you wanted.

The following image is the result of the Includes Report macro:

includes report view

To display this macro best you could put it in a Panel macro.

If you are writing reports for customers, you may not want them to see this information. Using a No Print macro hides this information.

The following image is an example source of the Includes Report macro:

includes report source

Lock Content Macro

Use the Lock Content macro to restrict users or groups from editing or viewing certain content. For example, if you want to add a page status or page information and do not want that information to be removed by a specific group, you could use a Lock Content macro to restrict that specific group.

You cannot restrict Confluence administrators and space administrators from editing content using the Lock Content macro.

To use this macro, add the user name to Restricted Users or the group to Restricted Groups. Additionally, if you want to hide the content of the macro from the restricted users, check the Hide Content box.

In the following image, all the users in the painters group and the user dali won’t be able to modify the content of the Lock Content Macro.

lock content
There are cases when the macro cannot restrict users from updating contents. For example, when using API, you cannot restrict editing page content.

Markdown Macro

You can insert your own Markdown inline tags or render them from a URL using the Markdown macro.

Usually you would want to include Markdown from a Gist or a repository in Github or Bitbucket. In GitHub and Bitbucket, use the raw content URL, which links to the original Markdown file.

Github

Bitbucket
github raw
bitbucket raw

If you want to display Markdown from another Atlassian product (like Bitbucket Server) the macro automatically detects if you have an application link setup for the URL you have entered and uses it to retrieve the content.

You may also place Markdown directly into the body of the Markdown macro:

markdownBody
markdownBody2
If you place Markdown in the body of the macro and you provide a URL, the Markdown in the body of the macro will be ignored.

The Markdown macro only supports the CommonMark specification of Markdown, which means that different versions of the Markdown specification may not render correctly.

For information about using external links in the Markdown macro, see the Whitelisting URLS section.

Whitelisting URLs

Using external URLs in a Markdown macro requires you to add them to the whitelist for outgoing requests.

If the Confluence whitelist is disabled, you cannot use URLs with the Markdown macro at all, but inline Markdown still works. This is necessary in order to prevent Server Side Request Forgery (SSRF) vulnerabilities.

Linked Atlassian applications are whitelisted by default, but you’ll likely want to whitelist common Markdown sources such as these:

You may want to be more restrictive and, for example, only allow data from your company’s Bitbucket project. For that, you could use a wildcard expression rule like https://bitbucket.org/MyCompany/*.

Confluence’s whitelist tester may still display a red mark for the incoming URLs depending on your company’s firewall settings. The Markdown macro does not require incoming whitelisting, so this should not become a problem.

The following image is an example of the red mark that could display on an incoming link based on firewall settings:

url whitelist test incoming red okay

Files, FTP, and other data

You may have Markdown files in places that can’t be accessed over HTTP that you still want to render in Confluence. For example, you may have a network file share on your Confluence server where permitted users add Markdown documents.

In the past, ScriptRunner for Confluence automatically allowed specifying file & FTP URLs for the Markdown macro. In order to support the added security of the URL whitelist, this is no longer automatic. Fortunately, you can still use a Scripted REST Endpoint to use those documents.

Files

To use a file in the whitelist URL, create a REST endpoint with code similar to the following example, with appropriate changes for your environment.

Use the following features (match the number of the list item to the number in the above image) to read the Markdown files from a directory in your Confluence server’s home directory:

import com.onresolve.scriptrunner.runner.ScriptRunnerImpl
import com.onresolve.scriptrunner.runner.diag.ClusterHomeLocatorService
import com.onresolve.scriptrunner.runner.rest.common.CustomEndpointDelegate
import groovy.transform.BaseScript

import javax.ws.rs.core.MediaType
import javax.ws.rs.core.MultivaluedMap
import javax.ws.rs.core.Response

@BaseScript CustomEndpointDelegate delegate

getMarkdownFile( (1)
    httpMethod: "GET", (2)
    groups: ["confluence-users"] (3)
) { MultivaluedMap queryParams ->
    def fileName = queryParams.getFirst("filename") as String (4)

    if (!fileName) {
        return Response.status(Response.Status.BAD_REQUEST)
            .type(MediaType.TEXT_PLAIN_TYPE)
            .entity("Must specify a markdown file.").build()
    }

    def homeDirectory = ScriptRunnerImpl.getOsgiService(ClusterHomeLocatorService).sharedHomeDir
    def markdownFiles = new File(homeDirectory, "markdown-files/") (5)
    def file = new File(markdownFiles, fileName) (6)

    boolean pathIsCanonical = file.path == file.canonicalPath (7)
    boolean fileIsMarkdown = [".md", ".markdown", ".mdx"].any { extension -> fileName.endsWith(extension) }

    if (!pathIsCanonical || !fileIsMarkdown || !file.exists()) {
        return Response.status(Response.Status.BAD_REQUEST)
            .type(MediaType.TEXT_PLAIN_TYPE)
            .entity("You may only specify markdown files in the appropriate directory.").build()
    }

    String fileContents = file.getText()
    return Response.status(Response.Status.ACCEPTED)
        .type(MediaType.TEXT_PLAIN_TYPE)
        .entity(fileContents).build()
}
1 This is the name of the REST endpoint; the name forms part of the URL. In this example, the name is getMarkdownFile.
2 This is the httpMethod, which must be GET in order for the endpoint to work with the Markdown macro.
3 This line should be used to restrict use of the REST endpoint to specific groups of authenticated users. Don’t allow access unless it is needed.
4 This line retrieves the filename from the URL’s query parameters.
5 On this line, we assume that the directory where the Markdown files live is inside your Confluence home directory. If it is somewhere else on the server, you can specify a path as a string (e.g. new File("/opt/path/to/markdown-files/").
6 This variable points to the individual Markdown file.
7 These are basic checks against directory traversal attacks. This checks the path against the canonical path.
Be extremely careful that your endpoint doesn’t allow users to read the arbitrary files from the Confluence server.

Once you have configured the REST endpoint for your environment, your users can configure the Markdown macro to point to a URL like https://confluence.mycompany.com/rest/scriptrunner/latest/custom/getmarkdownFile?filename=somefile.md. Replace confluence.mycompany.com with your Confluence instance’s base URL.

FTP, SFTP, or FTPS

Alternately, you may want to set up a REST endpoint that can read files from an FTP, SFTP, or FTPS server.

import com.onresolve.scriptrunner.runner.rest.common.CustomEndpointDelegate
import groovy.transform.BaseScript

import javax.ws.rs.core.MediaType
import javax.ws.rs.core.MultivaluedMap
import javax.ws.rs.core.Response

@BaseScript CustomEndpointDelegate delegate

markdownSftp( (1)
    httpMethod: "GET", (2)
    groups: ["confluence-users"] (3)
) { MultivaluedMap queryParams ->
    def fileName = queryParams.getFirst("filename") as String (4)

    if (!fileName) {
        return Response.status(Response.Status.BAD_REQUEST)
            .type(MediaType.TEXT_PLAIN_TYPE)
            .entity("Must specify a markdown file.").build()
    }

    def sftpRootUrl = "ftp://myftp.host.com/root/allowed" (5)
    def pathToFile = "$sftpRootUrl/$fileName" (6)

    boolean pathIsPermissible = ['../', '$', '*'].every { !pathToFile.contains(it) } (7)
    boolean fileIsMarkdown = [".md", ".markdown", ".mdx"].any {
        extension -> fileName.endsWith(extension) (8)
    }

    if (!pathIsPermissible || !fileIsMarkdown) {
        return Response.status(Response.Status.BAD_REQUEST)
            .type(MediaType.TEXT_PLAIN_TYPE)
            .entity("You may only specify markdown files in the appropriate directory.").build()
    }

    def url = new URL(pathToFile) (9)
    String fileContents
    try {
        fileContents = url.text
    } catch (Exception e) {
        return Response.status(Response.Status.BAD_REQUEST)
            .type(MediaType.TEXT_PLAIN_TYPE)
            .entity("File $fileName does not exist or is unreadable.".toString()).build()
    }
    return Response.status(Response.Status.ACCEPTED)
        .type(MediaType.TEXT_PLAIN_TYPE)
        .entity(fileContents).build()
}
1 This is the name of the REST endpoint; the name forms part of the URL. In this example, the name is getMarkdownFile.
2 This is the httpMethod, which must be GET in order for the endpoint to work with the Markdown macro.
3 This line should be used to restrict use of the REST endpoint to specific groups of authenticated users. Don’t allow access unless it is needed.
4 This line retrieves the filename from the URL’s query parameters.
5 This FTP URL points to both the server and subdirectory that you want to access. Change this as appropriate for your environment.
6 On this line, the root path is combined to the FTP site with the file name.
7 These are basic checks against directory traversal attacks. This checks that the path doesn’t contain characters which could permit users to add malicious attempts to access the FTP server or other URLs.
8 This line validates the file type acessed by extension. Only Markdown files are accepted.
9 Note that the URL is only created once all validation is passed. This differs from java.net.URL instances, which perform a DNS lookup on creation.

Once you have configured the REST endpoint for your environment, your users can configure the Markdown macro to point to a URL like https://confluence.mycompany.com/rest/scriptrunner/latest/custom/markdownSftp?filename=somefile.md. Replace confluence.mycompany.com with your Confluence instance’s base URL.

Mugshot Gallery Macro

The Mugshot Gallery macro shows profile photos of group members in tabular format for a group. For example, you can show the photos of group members on a page.

Follow these steps to use the Mugshot Gallery macro:

  1. Add the macro to a page.

  2. Provide the group name.

  3. Specify the number of profile pictures you want to see in a row.

The following image shows the fields to set up a Mugshot Gallery macro:

mugshot gallery
This macro shows first 200 members of a group returned by Confluence API.

Page Info Macro

The Page Info macro makes it easy to display information about the page it is used on. This could include information such as page versions, differences in versions, contributors and many other options listed below.

Usage

  • Click Insert > Other Macros.

macro browser

  • Select the Page Info macro from the provided list.

macro browser list

  • Complete the desired fields.

Parameter Description Type Default Required

Information Type

See the Supported Information Types table below

enum

commenters

yes

Page

The name of the page whose information will be displayed, if none is given then the current page is assumed. Option "$self" and "$parent" can be used to refer to the current page and the parent page respectively.

string

current page

no

Date Format

Allows setting the display format for the date and time displayed. When no date is to be displayed this parameter has no effect. Under the hood, this uses Confluence’s DateFormatter API, which in turn uses a java.text.SimpleDateFormatter. See the Oracle Documentation on how to create your own custom date format string.

string

MMM dd, yyyy - hh:mm

no

Type

Different options to show information, Can be:

  • Flat - display a comma separated list (default) or

  • List - display a bullet list.

enum

flat

yes

Prefix

This parameter insert a prefix before the version number when used. Has no effect with those display types which do not display a version number.

string

none

no

Reverse Order

Reverse the list item when the option is selected with "List" option.

checkbox

unchecked

no

Count

Limit the number of items shown in a list (eg. versions and diffs).

int

none

no

Show Comments

Display the comments that accompany an update.

checkbox

unchecked

no

Show Versions

Display the version numbers.

checkbox

checked

no

Supported Information Types

Information Type Description

Created by

Displays the user who created the page.

Commenters

Displays a comma separated list of the users who have commented on the page.

Create date

Shows the date the page was created.

Current version

Most recent version number of the page.

Diffs

Displays a comma separated list of version number links. These are clickable to view the differences between versions.

Labels

Displays a comma separated list of labels. These are clickable to view other pages that possess the same label.

Modified by

Shows the user who last modified the page.

Modified date

Displays the date the page was last modified.

Modified users

Displays a comma separated list of all the users who have modified the page.

Page id

Shows the Id of the current page.

Participants

Displays a comma separated list of the users who have modified or commented on the page.

Title

Displays the title of the page.

Tiny url

Displays a tiny url link to the specified page.

Versions

Displays a comma separated list of version numbers. These are clickable to view the selected version.
pageInfoPlugin

  • The following screenshot shows the output when "Created by" is selected as the "Information Type". In this case the page has been created by the admin.

example 1

Example

The following two screenshots show how the Page Info macro can be used effectively to populate information. For example the input:

shortExampleOut

The output:

shortExampleIn

Formatting Dates

  • The macro supports standard date formats which allows the user to format the date with various combinations. For example the following screenshot shows how to use "dd-MMM-yyyy" as the date format.

dateFormat1

  • More examples of the Page Info macro are added in a table below.

Page Edit Mode Page Output
Diagram
Diagram

Displaying Versions and Diffs

Here is an example of "Versions" and "Diffs". The versions and differences ("Diffs") are clickable to view a particular version and difference.

diffsOut

View Page Information for a Different Page

Provide the name of the page for which information will be displayed. The following example shows the page creator for page P2. It is also possible to use "$parent" [without double quote] to refer to the parent page of the page that contains the macro.

differentPage

Version History Macro

Formerly part of the separate Page Info plugin, the Version History macro is now a native feature of ScriptRunner for Confluence.

The Version History macro makes it easy to display versioning information about any page in listed form.

Usage

  • Click Insert > Other Macros.

macro browser

  • Select the Version History macro from the provided list.

version macro browser list

  • Complete the desired fields.

Parameter Description Type Default Required

Page

Specify the page name for which version history information will be displayed. The variables $self(default) and $parent is also accepted.

string

$self

no

Date Format

Specify the format in which the date is displayed, eg: dd MMMM yyyy - hh:mm aa

string

MMM dd, yyyy hh:mm

no

Reverse Order

Display the version history list in reverse order.

checkbox

unchecked

no

First

Specify how many results are displayed. Display only the first x entries

int

none

no
pageInfoPlugin

  • The following screenshot shows what the macro results in with default parameters. It shows that the current page has three different versions.

version history result

Have questions? Visit the Atlassian Community to connect, share, and learn with other Atlassian users and experts, including Adaptavist staff.

Ask a question about ScriptRunner for JIRA, Bitbucket Server, or Confluence.

Want to learn more? Check out courses on Adaptavist Learn, an online platform to onboard and train new users for Atlassian solutions.