The Ultimate ScriptRunner for Confluence Macros Cheat Sheet

Macros are widgets you can easily add to your Confluence pages while in edit mode. They each offer unique functionality that we’ll look at further in this blog, but their overall aim is to improve the process of managing your content or improving the appearance of your pages. They make information easier to digest, easier to find, and easier to keep up-to-date.

Confluence offers some macros out-of-the-box, such as Galleries, Pivot Tables, and Forms. But ScriptRunner for Confluence is an app which offers additional macros that cover many of the common needs of Confluence users.

ScriptRunner offers two types of macros: built-in and custom. Built-in macros are ready to use, so you can start improving your Confluence pages—fast!

Custom macros are available to Confluence admins only, allowing organisations to create their own macros to meet their unique needs. Custom macros have unlimited potential, allowing you to display information and format your Confluence space exactly how you want it.

Confluence is only as valuable as the information it contains. If your space becomes outdated or the page structure becomes too complex and time-consuming to navigate, you risk finding it frustrating to use and potentially give up on it altogether. Thankfully, macros are here to help the entire team make your Confluence space a success!

Using the macros provided by ScriptRunner, you can enhance your Confluence experience. Macros take existing functionality in Confluence and make it more accessible, often automating processes to relieve manual work. You can use them to edit the appearance and structure of your pages to suit the needs of your team better.

For those looking to improve their Confluence content experience quickly, ScriptRunner offers a range of out-of-the-box macros ready for use straight from the Confluence macros menu. Read on for a complete list of ScriptRunner macros and their functionality.

You can easily access ScriptRunner's built-in macros from any Confluence page.

Don’t see ScriptRunner macros? Talk to your Confluence admin to install ScriptRunner using this free trial today.

If you're looking to get more from Confluence—without having to request help from your administrator—read on to discover the functionality you can add to your Confluence pages using ScriptRunner's macros. We've included links to the training and videos you need to get started, plus a cheat sheet that you can save for later.

Users familiar with labelling on Confluence will be happy to hear you can also add variable labels to your pages thanks to the 'Add Label' macro. Variable labels automatically pull information into the label based on your query, such as '$year' to add a label of the current year, '$month' to add a label of the current month, or '$username' to insert the username of the person who created or last edited the page.

You can use this macro when running a clean-up project on your Confluence space. Use the 'Add Label' macro to add labels for the year created by using $year, then conduct a search to display pages with a particular year to identify outdated pages. You can then decide whether to delete these pages or refresh the content.

Bonus tip: Combine this macro with the CQL search macro (number 3 on our list!) to display the pages as a list on a Confluence page for easier scanning.

Variable labels are also helpful for tagging template pages. For example, you can automatically populate labels for the current year or month every time a new page is created from that template, eliminating manual work.

Similar to the 'Add Label' macro, this macro adds new labels to your pages; however, the 'Choose Label' macro gives you additional control over label naming conventions to help keep your labels accurate, useful, and tidy.

An example use case for this macro is storing recurring meeting notes in Confluence. You can create a parent page called 'Monthly Department Meetings' then create a template child page that uses the 'Choose Label' macro. Set up labels for each department, deciding on naming conventions for each label. When this template is selected, the user chooses the correct department from the list, ensuring labels are accurate and consistent every time. For example, the user selects 'HR' from the list instead of incorrectly entering 'Human Resources' manually.

This macro is helpful when performing a clean-up of outdated pages on your Confluence instance. First, search for a label, such as a specific year, to create a list of pages created that year, and bingo—you have a list of pages to work from to help you decide which pages to delete, archive, or refresh.

You can also use this macro to create a list of Confluence pages you would like all new team members to read to help familiarise themselves with your business. Tag the pages with an 'Onboarding' label and include it in your search. Voila! Enjoy an automatic reading list for new starters, which will keep itself up-to-date in line with tagged content.

The 'Create Page' macro allows you and others to create templated pages lightning-fast. Use this macro to insert a 'Create Page' link on a Confluence page to create a child page when clicked. The new page can be a blank page, a template page, or a copy of an existing page. Use a template page to automate the page formatting of your child pages, ensuring the correct labels and page style are used across all child pages. If you’ve been craving consistency across your space, this is a great, hands-off way to get it.

One way to use this macro is to create a '2022 Monthly Sales Meeting' parent page containing the 'Create Page' link. When clicked, the link automatically generates a child page from a pre-set template. The template can include headers for an agenda, notes, outcomes sections, and a '$month' variable label to help with indexing.

Screenshot of the markdown macro before publishing

Markdown is a plain text formatting language designed to make editing text for the internet easier to read than HTML. Some of the most common options include:

When you use the 'Markdown' macro on Confluence, you’ll see formatting characters, such as _italics_ and *bold*, when you edit your page. After you've published the page, your text will transform to show the formatted text, such as italics and bold.

Bonus: if you are importing from Gist or a repository in GitHub or Bitbucket, you can automatically include any existing Markdown data by inserting the raw content URL. This means the text you already have stored will not need to be re-typed and manually formatted. You can continue to format plain text using Markdown, then use the 'Markdown' macro to display the formatting in Confluence.

That's a job for your Confluence admin! Talk to your Confluence admin to set up new groups.

The macro can help track how recently the page was updated and by whom, so you can see at a glance whether the information is up-to-date.

This macro is ideal for use on pages displaying technical documentation, where the user may wish to refer back to previous versions, and for auditing purposes if you are in a regulated industry.

This macro is ideal for sharing useful information on multiple pages without having to copy the same information onto each page. For example, you can create individual pages for important information, such as employee remuneration, sick leave policies, and how to request annual leave. You can then use this macro to insert this information in multiple places within your space, for example, a new starter portal, an HR space, and departmental spaces. When this information needs a refresh, you can easily update the source page, and the target pages will automatically update.

You can opt to display the page contents of any previous version of the page, or you can opt to include the most recent version. Choose to display a prior page version, which will not update as you publish new versions of the source page, to create a static page that is correct at a specific time. Alternatively, you can ensure your page information is always up to date by displaying the latest version.

The 'Include Report' macro is used in conjunction with the 'Include Version' macro to show which pages (and which versions of these pages) are featured in the 'Include Version' macro. This macro displays links to these pages, as well as an 'Update all' button to force-update all listed pages to the most current versions.

Use this macro to see where key content appears and if the page displays the most appropriate version of that content.