Issue description style format for Status and Expand by REST API

[Maksym Shtatskyi]

Hi.

I use REST API to update issues in Jira.

I want to support some format of data in issue description. There are Status and Expand:

When I create description by Jira with such styles like this:

and get issue by rest api: /rest/api/2/issue/SP-295?expand=renderedFields

I have rendered value of description like:

<p><font color="#6554C0"><b>[ STATUS VALUE ]</b></font> </p>

<p><b>Expand title</b></p>

<p>Expand description</p>

And not rendered:

{color:#6554C0}*[ STATUS VALUE ]*{color} 

*Expand title*

Expand description

But when I send same value for description by request:

PUT /rest/api/2/issue/SP-295

{"fields":{"summary":"JF234","issuetype":{"id":10001,"name":"STORY"},"description":"\n{color:#6554C0}*[ STATUS VALUE ]*{color} \n\n*Expand title*\n\nExpand description\n","priority":{"name":"Medium"}]}}}

I will get same value in rendered and not rendered description field, but it looks different:

How can I achieve same visualization value for description after update it by REST?

[David Bakkers · Accepted solution]

Helllo @Maksym Shtatskyi 

Those things called 'Status' and 'Expand' are macros. The output of those macros is rendered within the Description field and it is that rendered output that you can retrieve via GET /rest/api/2/issue/SP-295?expand=renderedFields, not the macros themselves. As you have found, you can retrieve that rendered output in either HTML or wiki markdown format.

What you PUT into that Description field was just some wiki markdown content, so what you see via the GUI as a result is exactly what you put there.... some content, using wiki markdown format, being rendered correctly.

There are no v2 REST API endpoints for Jira Cloud that will place macros within a rich text field and also set the values for those macros.

[Maksym Shtatskyi]

Hello, @David Bakkers . Thank you for answer!

What about v3 of REST API? Is there something to work with description macros?

[David Bakkers]

Yes, because the v3 endpoints use ADF for the formatting of the content of rich text fields, which allows you to define and reference the macros via their type and IDs.

Here is an example of what the ADF content of your Description field would look like:

"description": {
 "version": 1,
 "type": "doc",
 "content": [
  {
   "type": "paragraph",
   "content": [
    {
     "type": "status",
     "attrs": {
      "text": "status value",
      "color": "purple",
      "localId": "a0f64507-fda5-48c9-8b9c-2b28ac16406e",
      "style": ""
     }
    },
    {
     "type": "text",
     "text": " "
    }
   ]
  },
  {
   "type": "expand",
   "attrs": {
    "title": "Expand title"
   },
   "content": [
    {
     "type": "paragraph",
     "content": [
      {
       "type": "text",
       "text": "Expand description"
      }
     ]
    }
   ]
  }
 ]
}

Yes, ADF is more verbose than wiki markdown or HTML because it is the underlying, un-rendered storage format of the field's content, but it is the only way to deal with embedded objects like macros.

@Jehan Bhathenahas provided an example of how to do it via the v3 endpoints.

[Maksym Shtatskyi]

Thank you, @David Bakkers !

[Jehan Bhathena]

Hi @Maksym Shtatskyi ,

I tested the Rest API and it works with the expected formatting. 

I used the below work around to formatting the issue Description though, please find the steps below and see if they work for you:

1. Fetch the Issue's content using the rest API :  https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-get. Did not use any query parameters in this, so the JSON content was shown as it is.
2. Fetch the Description from the above JSON, and use it as input in the "fields" for the PUT REST API : https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-put
3. Fire the PUT API from the second step to verify if the content is show as it is

[Maksym Shtatskyi]

Thank you, @Jehan Bhathena !