Lisa Murray
27 October 2022
The Ultimate ScriptRunner for Confluence Macros Cheat Sheet
The only cheat sheet you need on ScriptRunner for Confluence Macros. Find everything you need to get started with our built-in macros today.
Confluence is an excellent tool for bringing your corporate information into one place. With pages created by various departments across your organisation, every member of your team knows where to turn to find the information they need.
But for those creating and managing the content, so much information gathered in one place can be tough to keep in check. Those new to Confluence have considerable functionality to get to grips with, particularly if they have access to apps like ScriptRunner for Confluence! To help, we've compiled a complete guide to ScriptRunner for Confluence macros, containing everything a Confluence user needs to know to get up and running using ScriptRunner macros.
Read on to discover:
- What macros are
- Why you should use ScriptRunner macros
- Where you can access ScripRunner macros
- How to use macros
- 12 ScriptRunner macros (plus training links and a cheat sheet!)
What are macros?
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.
Find out more about macros
Why should I use ScriptRunner macros?
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.
Where can I access macros for Confluence?
You can easily access ScriptRunner's built-in macros from any Confluence page.
From the top menu bar, click '+' then 'other macros' to view a list of available macros. This comprehensive list displays all the available macros, including Confluence's built-in macros and ScriptRunner's built-in macros.
Don’t see ScriptRunner macros? Talk to your Confluence admin to install ScriptRunner using this free trial today.
How do I use macros?
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.
ScriptRunner for Cloud built-in macros training
ScriptRunner for Server/Data Center built-in macros training
1. 'Add Label' macro for Confluence
Available on Cloud, Data Center, and Server.
Pages on Confluence can be tagged (or indexed) with labels, and users can click these labels to see other pages tagged with that same label.
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.
Watch the 'Add Label' video tutorial now
2. 'Choose Label' macro for Confluence
Available on Cloud, Data Center, and Server.
Using the 'Choose Label' macro, you can add a drop-down menu to your Confluence page containing a list of pre-approved labels.
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.
Watch the 'Choose Label' video tutorial now
3. 'CQL Search' macro for Confluence
Available on Data Center and Server.
Using the 'CQL Search' macro, you can use CQL (Confluence Query Language) to perform a targeted search of pages in your Confluence instance, and then display the resulting pages as clickable links in a table on a Confluence page.
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.
Watch the 'CQL Search' video tutorial now
4. "Create Page" macro for Confluence
Available on Data Center and Server.
You can easily create a new page on Confluence by clicking the 'Create' button in the menu bar—so why do you need this macro?
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.
Watch the 'Create Page' video tutorial now
5. 'Currency Converter' macro for Confluence
Available on Data Center and Server.
Using the 'Currency Converter' macro, you can convert a cash amount into multiple currencies to display on your Confluence page. The currency will convert at the previous end-of-day exchange rate from the European Central Bank.
To use this macro, choose the currency to convert from and the currency to convert to. For example, you can display 100 GBP and the conversions to Euro, USD, AUD, and more, all of which will automatically update every 24 hours. Farewell, manual checking and conversions!
Find out how to use the 'Currency Converter' macro here
6. 'Markdown' macro for Confluence
Available on Data Center and Server.
Screenshot of the markdown macro before publishing
Screenshot of the markdown macro after publishing
In Confluence, you can use Markdown syntax to format the appearance of your page using the 'Markdown' macro.
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:
- **bold**
- _italics_
- - Unordered lists
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.
Watch the 'Markdown' video tutorial now
Why choose ScriptRunner?
ScriptRunner for Confluence benefits everyone in the organisation who interacts with Confluence: with features available for administrators, space admins, and users alike. It gives everyone the tools they need to ensure that their Confluence spaces are up-to-date and easy to navigate.
7. 'Mugshot Gallery' macro for Confluence
Available on Data Center and Server.
Using the 'Mugshot Gallery' macro, you can automatically display profile photos of group members on your Confluence page. Just add the macro to the page, choose the group name, and select how many images you would like to show per row. The macro will automatically import and display the profile photos of up to 200 group members.
Find out how to use the 'Mugshot Gallery' macro here
Looking to set up a group for your team?
That's a job for your Confluence admin! Talk to your Confluence admin to set up new groups.
8. 'Page Info' macro for Confluence
Available on Cloud, Data Center, and Server.
The 'Page Info' macro displays a page's metadata on a page. Choose from a range of metadata to include, such as creation date, current version, and the user who last made modifications. The page information can be displayed anywhere on the page, even in tables. You can show information about the current page or a different page within your Confluence.
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.
Find out how to use the 'Page Info' macro here
9. 'Versions History' macro for Confluence
Available on Data Center and Server.
The 'Versions History' macro displays a list of historical page versions in a table on your Confluence page. Add this macro to a Confluence page and easily see who has modified the page. This is ideal for displaying version history information to users without advanced permissions. It also allows users with the appropriate permissions to revert pages to previous versions.
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.
Find out how to use the 'Versions History' macro here
10. 'Include Version' macro for Confluence
Available on Data Center and Server.
Using the 'Include Version' macro, you can include the contents of any previous or current version of another page from your Confluence instance (the source page) on your current page (the target page).
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.
Find out how to use the 'Include Version' macro here
11. 'Includes Report' macro for Confluence
Available on Data Center and Server.
As your Confluence instance grows, you may have multiple pages using 'Include Version' macros, and it can become challenging to keep track of which pages refer to which.
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.
Find out how to use the 'Include Report' macro here
ScriptRunner for Confluence Macros cheat sheet
Let's get started!
ScriptRunner offers a whole range of built-in macros for your Confluence pages. Some of these macros can automate manual tasks and put vital time back into your day, while others help maintain consistency using templates to alleviate stress around information accuracy. Ultimately, these tools can help you get more from Confluence, encouraging uptake within your teams to help you communicate more effectively as an organisation.
We hope this guide has helped you identify which ScriptRunner built-in macros you can use to take your Confluence pages to the next level, and that our training guides and videos have given you the confidence to get started.
If you would like more detailed information, head on over to our Documentation for step-by-step instructions and videos on using each of our macros.
New to ScriptRunner?
Talk to your Confluence admin to install ScriptRunner free for 30 days!