update roadmap planner macro via REST API

[nnako]

Hi,

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:structured-macro
    ac:name="roadmap"
    ac:schema-version="1"
    ac:macro-id="7163f205-1b64-4f99-8a02-2ca8e502fe3f">

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

%7B%22title%22%3A%22Roadmap%20Planner%22%2C%22timeline%22%3A%7B%22startDate%22%3A%222021-04-24%2000%3A00%3A00
%22%2C%22endDate%22%3A%222022-03-24%2000%3A00%3A00%22%2C%22displayOption%22%3A%22MONTH%22%7D%2C%22lanes%22%3A
%5B%7B%22title%22%3A%22SPUR_01%22%2C%22color%22%3A%7B%22lane%22%3A%22%23f6c342%22%2C%22bar%22%3A%22%23fadb8e%
22%2C%22text%22%3A%22%23594300%22%2C%22count%22%3A1%7D%2C%22bars%22%3A%5B%7B%22title%22%3A%22SPUR_01__AKTIVIT
AET_01%20%C3%A4%C3%B6%C3%BC%22%2C%22description%22%3A%22ein%20kurzer%20Kommentar%20f%C3%BCr%20AKTIVITAET_01%2
2%2C%22startDate%22%3A%222021-04-30%2019%3A21%3A58%22%2C%22duration%22%3A3.0198019801498406%2C%22rowIndex%22%
3A0%2C%22id%22%3A%22a4d328d1-46af-47f5-b95e-0198f171fc55%22%2C%22pageLink%22%3A%7B%7D%7D%2C%7B%22title%22%3A%
22SPUR_01__AKTIVITAET_02%22%2C%22description%22%3A%22ein%20kurzer%20Kommentar%20f%C3%BCr%20AKTIVITAET_02%22%2
C%22startDate%22%3A%222021-06-01%2000%3A00%3A00%22%2C%22duration%22%3A3.009900989969136%2C%22rowIndex%22%3A1%
2C%22id%22%3A%22dcca8a98-cd2b-4c33-aae4-8692490aa584%22%2C%22pageLink%22%3A%7B%7D%7D%5D%7D%2C%7B%22title%22%3
A%22SPUR_02%22%2C%22color%22%3A%7B%22lane%22%3A%22%233b7fc4%22%2C%22bar%22%3A%22%236c9fd3%22%2C%22text%22%3A%
22%23ffffff%22%2C%22count%22%3A1%7D%2C%22bars%22%3A%5B%7B%22title%22%3A%22Leiste%203%22%2C%22description%22%3
A%22dies%20ist%20ein%20extrem%20kurzer%20Kommentar%20f%C3%BCr%20AKTIVITAET_03%22%2C%22startDate%22%3A%222021-
04-01%2007%3A57%3A37%22%2C%22duration%22%3A2.5%2C%22rowIndex%22%3A0%2C%22id%22%3A%22638a8b73-aa22-4b8d-9a13-b
f7f25d57c63%22%2C%22pageLink%22%3A%7B%7D%7D%5D%7D%5D%2C%22markers%22%3A%5B%7B%22title%22%3A%22MARKIERUNG_01%2
2%2C%22markerDate%22%3A%222021-04-15%2000%3A00%3A00%22%7D%5D%7D

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

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

`ac-macro-id`
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.

`ac:name="source"`
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.

`ac-name="hash"`
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.

[Jason Chueh]

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.

[nnako]

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>
</ac:structured-macro>

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?

[Jason Chueh]

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.

[Jason Chueh]

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. 

[Daniel Breneis]

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