Come for the products,
stay for the community

The Atlassian Community can help you and your team get more value out of Atlassian products and practices.

Atlassian Community about banner
Community Members
Community Events
Community Groups

update roadmap planner macro via REST API


I want to realize a non-standard view on one of my created Confluence pages, using the `roadmap planner` macro. the macro looks nice and on the GUI level it can be adjusted with ease. I already successfully read the Confluence page using the provided REST API. And I already wrote back page content, so that Confluence rendered it properly.

Now, when trying to update page content in the format of a `roadmap planner` macro, I was not successful so far. Confluence seems to refuse the roadmap planner portion of the transferred page so that changes made externally are discarded.

Looking at the identified XML, I see the intended structure:


<ac:parameter ac:name="maplinks" />
<ac:parameter ac:name="timeline">true</ac:parameter>
<ac:parameter ac:name="pagelinks" />
<ac:parameter ac:name="source">


<ac:parameter ac:name="title">Roadmap%20Planner</ac:parameter>
<ac:parameter ac:name="hash">4a0a5db3725b7993ffa53e0ad0ffa858</ac:parameter>


Here is my analysis of the XML elements which seem relevant form updating the page:

this seems to be a reference to a Confluence-internal macro location. I would leave it as is, in order to not invalidate any internals. hoping that this values does not change over time but stays stable during lifetime of the chosen confluence page.

this parameter seems to hold all the user data necessary to display the roadmap planner diagram within the Confluence page. The values look like a JSON structure encoded for usage in HTML pages.

this parameter might be calculated from the contents of this XML structure. but I don't see over which part it is calculated or after which further transformations (e.g. JSON pre- or post-encoded, SHA algorithm, ...). I guess, within Confluence this hash value is used to check for correct syntax of the user data before rendering on the Confluence page?


I guess, I had no success so far because I didn't set the "hash" correctly. searching the provided help pages (especially the `storage format`) didn't get me any further.


So, is there a way to use the supported REST API for updating (not just reading) the `roadmap planner` macro contents? What am I missing?


Thank you.

1 answer

It's possible. If you use urldecode function to decode the "source" string. You'll get a compact json. The one you provided is like below(prettified).

"title": "Roadmap Planner",
"timeline": {
"startDate": "2021-04-24 00:00:00",
"endDate": "2022-03-24 00:00:00",
"displayOption": "MONTH"
"lanes": [
"title": "SPUR_01",
"color": {
"lane": "#f6c342",
"bar": "#fadb8e",
"text": "#594300",
"count": 1
"bars": [
"title": "SPUR_01__AKTIVITAET_01 äöü",
"description": "ein kurzer Kommentar für AKTIVITAET_01",
"startDate": "2021-04-30 19:21:58",
"duration": 3.0198019801498406,
"rowIndex": 0,
"id": "a4d328d1-46af-47f5-b95e-0198f171fc55",
"pageLink": {}
"title": "SPUR_01__AKTIVITAET_02",
"description": "ein kurzer Kommentar für AKTIVITAET_02",
"startDate": "2021-06-01 00:00:00",
"duration": 3.009900989969136,
"rowIndex": 1,
"id": "dcca8a98-cd2b-4c33-aae4-8692490aa584",
"pageLink": {}
"title": "SPUR_02",
"color": {
"lane": "#3b7fc4",
"bar": "#6c9fd3",
"text": "#ffffff",
"count": 1
"bars": [
"title": "Leiste 3",
"description": "dies ist ein extrem kurzer Kommentar für AKTIVITAET_03",
"startDate": "2021-04-01 07:57:37",
"duration": 2.5,
"rowIndex": 0,
"id": "638a8b73-aa22-4b8d-9a13-bf7f25d57c63",
"pageLink": {}
"markers": [
"title": "MARKIERUNG_01",
"markerDate": "2021-04-15 00:00:00"

 So You can populate the json dynamically and urlencode it back to the hash.

Hi @Jason Chueh , thanks for your answer. Unfortunately, this solves only part of my problem. I decoded the "source" string by hand (you used an `urlencode` functionality, which is by far a better approach). But the problem comes thereafter: there is still a "hash" string within the macro structure:

<ac:parameter ac:name="hash">4a0a5db3725b7993ffa53e0ad0ffa858</ac:parameter>

Is there a process to calculate it from the "source" string or the decoded JSON structure? I've heard, there are many different ways to calculate "hash" values. SHA-1, SHA-256, ... 

Which way / type of hash calculation is expected here?

That value represents the thumbnail of the macro in edit mode, and it is required so the macro would work. I also have no idea how it is populated, so I simply copy a valid hash from another roadmap planner macro manually created in the edit mode. It won't give the custom one the correct thumbnail, but it doesn't matter.

BTW, I'm not sure if my approach would work in your use case. I have not yet tried to update the page through rest API. Instead, I use a plugin ScriptRunner for Confluence, and use its custom macro feature to construct raw data in storage view of roadmap planner from Jira issues. Of course, if you don't have this plugin, you can still write a custom plugin to do the same thing. 

I just found out: its the md5 hash of the encoded string

Suggest an answer

Log in or Sign up to answer
Community showcase
Published in Confluence

Confluence: Where work and wellness meet

Feeling overwhelmed by the demands of work and life? With a 25% increase in the prevalence of anxiety and depression worldwide during the pandemic, for most of us, it’s a resounding yes . 🙋‍♀️ ...

767 views 5 21
Read article

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you