🐙 How to Programmatically Get The Current Page ID in a Custom Cloud Macro (And Why You Should Care)

[#1]

Is there a macro you had on-prem that you wish you could re-create on Cloud?

Or maybe you have a special use case that you can’t find a Marketplace solution for.

ScriptRunner for Confluence Cloud allows you to create your own custom macros on Cloud, much like the User Macros feature on Server.

You can script any static macro you like using Groovy. However one of the key pieces to unlocking the full power of what you can create is being able to identify the current page the macro is used on.

Why being able to identify the current Page ID is so powerful

When you can identify the current page on which your custom macro is used, it opens a lot of doors.

For example, you would be able to create macros that automatically display metadata related to the current page for reporting or project documentation purposes - saving tonnes of time in manual input.

You could use the current Page ID to make REST API calls and return a lot of useful information, including:

• The current version of the page

• The space the current page is in

• Children, descendants and ancestors of the current page, or related pages

• Attachments, comments and labels for the current page or related content

And, with a bit more work, you can modify content, e.g. to automatically add or delete a label on a page based on some criteria.

How to use ScriptRunner to get the current Page ID

ScriptRunner for Confluence Cloud makes identifying the current Page ID easy by providing a Map called ‘parameters' containing the current Page ID.

The 'parameters’ Map allows users to access any user-created parameters in the current macro and to access parameters like Page ID or Macro ID.

Whenever you create a custom macro using ScriptRunner, this Map will be available by default for you to use.

It will look something like this:

[pageId:234651756]

So you can access it simply by writing something like: 

def currentPageId = parameters.pageId

which assigns the Map value for key ‘pageId’ to a (String) variable.

How to make REST API calls with the current Page ID

Since Unirest is also available for free in ScriptRunner Custom Macros, you can use this to make a REST API call to get information on the current page as follows (the page will need to have a parent page for this script to work):

def currentPageId = parameters.pageId
def currentPageInfo = get("/wiki/api/v2/pages/${currentPageId}")
.header("Accept", "application/json")
.asObject(Map).body

This will return a Map of information on the current page, something like this:

[parentType:page, createdAt:2024-02-29T17:31:38.347Z, authorId:55405973741f03-9fc6-4eab-98ce-0838267ae921, id:234651756,

version:[number:23, message:, minorEdit:false, authorId:55405973741f03-9fc6-4eab-98ce-0838267ae921, createdAt:2024-03-07T17:42:14.276Z
],

position:50326921, title:REST API Test Macro, status:current, body:[:], parentId:730778040, spaceId:143811, ownerId:55405973741f03-9fc6-4eab-98ce-0838267ae921, lastOwnerId:null,

_links:[editui:/pages/resumedraft.action?draftId=234651756, webui:/spaces/TEST/pages/234651756, tinyui:/x/EoDRM, base:https://acme.atlassian.net/wiki]

]

So now you can either use this information directly in the output of the macro, e.g to display a link to the parent page:

return """
<p><strong>Parent Page:</strong> 
<ac:link>
<ri:content-entity ri:content-id='${currentPageInfo.parentId}'/>
</ac:link>
</p>
"""

or show the current version number of the page:

return "<p>Current version: ${currentPageInfo.version.number}</p>"

or make further REST API calls.

To get information on the current Space, for example, you could use:

def currentSpaceId = currentPageInfo.spaceId
def currentSpaceInfo = get("/wiki/api/v2/spaces/${currentSpaceId}")
.header("Accept", "application/json")
.asObject(Map).body

Hope this helps and happy custom macro scripting!

Notes

• As mentioned above, the 'parameters' map will also be used to store any parameters that you create for the macro in the form [pageId:234651756,{parameter name}:{parameter value},...]

• The information returned by the REST call will vary depending on the content type: Overview Pages, for example, do not have Owners or Parents, so these values will be null. It's good practice to handle null values in your macro code, although I've not added any validation in the examples above.

Where to learn more about creating your own custom macros

🐙 [Webinar] How to create custom Cloud macros with ScriptRunner

We recently hosted a webinar on how you can build your own custom macros using ScriptRunner.

The webinar recording and macros scripts used are available free here.

The webinar covered:

• What the Custom Macro feature on ScriptRunner is and how you can use it

• How to script macros using Groovy, including a live tutorial building 2-3 macros from real use cases

• Where you can access the macro scripts to try it yourself

There was also a live Q&A at the end.

Watch the webinar recording and access the free macro scripts here: How to create your own custom cloud macros

ScriptRunner custom macros documentation is available here