Bundled Macros
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.
-
Select Insert, and then select Other Macros.
-
Select the Add Label macro from the provided list.
-
Complete the Labels field.
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.
-
Click Save and the labels you added appear on the page.
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.
-
Select Insert, and then select Other Macros.
-
Select the Choose Label macro from the provided list.
-
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.
-
| Mixing languages on a Confluence page results in undefined label suggestion behaviour. |
-
Click Save, and the macro appears on the page.
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
-
Tick the Show Suggested Labels on the Macro checkbox on the Edit 'Choose Label' Macro dialog.
-
Choose the suggestions that you want.
-
Click Save, and the rendered macro appears on the page.
Macro Configuration: Choose Suggested Generated Labels
-
Tick the Show Suggested Labels on Label Dialog checkbox on the Edit 'Choose Label' Macro dialog.
-
Click Save.
-
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).
-
When you are on the page not in edit mode, by press "L" on the keyboard.
-
-
When the Labels dialog box appears, choose generated labels here.
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:
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:
| 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.
-
Click Insert > Other Macros.
-
Select the Create Page Macro from the provided 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. If you select a template with variables, you are redirected to a Page Template Wizard when you use the macro to create a 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.
-
Save the Confluence page
-
To create the new page, select the link.
This is when the Page Template Wizard appears if you selected a template with variables. The wizard gives you the option to fill in variables before the page is created. When you’re ready for the finished page, select Next to see the created page.
If you select Open in a New Tab when you create your macro, the Back button on the Page Template Wizard does not work.
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:
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:
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:
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:
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.
| 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 |
|
|
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:
| 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:
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:
-
Add the macro to a page.
-
Provide the group name.
-
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:
| This macro shows first 200 members of a group returned by Confluence API. |
| Users which have disabled accounts will not be shown by the macro. |
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.
-
Select the Page Info macro from the provided 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 you want displayed. If no name is given, then the current page is assumed.
Options $self and $parent can be used to refer to the current page and the parent page respectively.
string
$self
No
Date Format
Set the display format for the date and time displayed. When no date is to be displayed this parameter has no effect.
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 a
Show list information in different formats.
Options are Flat to display a comma separated list or List to display a bullet list.
enum
Flat
Yes
Prefix
Inserts a prefix before the version number. This field has no effect on display types without a version number.
string
None
No
Reverse Order
Reverse the list item when the option is selected.
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.
NOTE: If you select this option, the comments refer to the page version comments (entered in the What Did You Change? field) which can be added before saving the page.
Checkbox
Unchecked
No
Show Versions
Display the version numbers.
Checkbox
Checked
No
Supported values for the Information Type field follow:
Information Type Description Created By
The user who created the page.
Commenters
A comma-separated list of the users who have commented on the page.
Create Date
The date the page was created.
Current Version
The most recent version number of the page.
Diffs
A comma-separated list of version number links. These are clickable to view the differences between versions.
Labels
A comma-separated list of labels. These are clickable to view other pages that possess the same label.
Modified By
The user who last modified the page.
Modified Date
The date the page was last modified.
Modified Users
A comma-separated list of all the users who have modified the page.
Page ID
The ID of the current page.
Participants
A comma-separated list of the users who have modified or commented on the page.
Title
The title of the page.
Tiny URL
A tiny url link to the specified page.
Versions
A comma separated list of version numbers. These are clickable to view the selected version.
The following image is an example of a selected field:
The following image shows the output when Created By is selected for the Information Type field. In this example, the page was created by the admin.
Example
The following two images show how the Page Info macro can be used to populate information.
The input:
The output:
Tips for the Page Info Macro
-
Formatting Dates: The Page Info 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.
Examples of formatted dates follow:
Page Edit Mode Page Output 
-
Displaying Versions and Diffs: The versions and differences ("Diffs") are clickable to view a particular version and difference.
-
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.
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.
-
Select the Version History macro from the provided 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 |
-
The following screenshot shows what the macro results in with default parameters. It shows that the current page has three different versions.
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.
