Post HTML Issue Description with JIRA REST API v3

Hey,

I was able to implement/use the JIRA REST v3 api, it’s pretty straightforward to create Issues through the API: https://developer.atlassian.com/cloud/jira/platform/rest/v3/#api-rest-api-3-issue-post

The problem is that by default we can create only text based descriptions.
I noticed JIRA has it’s own rich text / mark down structured text format (ADF = Atlassian Document Format).
Since we’re using HTML in our client, we need to find a way convert HTML to JIRA “rich text” (ADF). Is there an API or a library to make this happen?

OR can JIRA api interpret standard Markdown as description?

What is the best way to do such a conversion?
Please advise.

4 Likes

Hi @TamasKalman I found this question while running into the same problem myself. I edited a Jira ticket manually and then used the Get issue endpoint: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-get to look at the format of the description object, which for me (I needed a link and a code snippet) looked like this:

        "description": {
            "version": 1,
            "type": "doc",
            "content": [
                {
                    "type": "paragraph",
                    "content": [
                        {
                            "type": "text",
                            "text": "My text "
                        },
                        {
                            "type": "text",
                            "text": "PART-OF-MY-LINK",
                            "marks": [
                                {
                                    "type": "link",
                                    "attrs": {
                                        "href": "https://website.com"
                                    }
                                }
                            ]
                        }
                    ]
                },
                {
                    "type": "paragraph",
                    "content": []
                },
                {
                    "type": "codeBlock",
                    "attrs": {},
                    "content": [
                        {
                            "type": "text",
                            "text": "global name 'test' is not defined"
                        }
                    ]
                }
            ]
        },

copying that worked for me, hope this helps others.

2 Likes

@TamasKalman I have automated the Jira ticket creation with Jenkins, Nodejs & Axios using Jira Rest API v3 & I also have the same issue. I have tried many ways of formatting the ticket’s description to add bold styles & h1 tags but with no luck. Did you find a solution to this issue?

When using the REST API to create / edit an issue, the description field must be text formatted using markdown codes. You can’t use HTML formatting.

There is no generic ‘library’ that does this, so you need to do some form of iterative text search and replace in the programming language you are using. Use Google to search for ‘convert HTML to JIRA markdown’ for all the different approaches people have used.

Note, there is a ‘workaround’, but it’s only possible for Jira SERVER, not cloud. Read this article.

What kind of markup format is used?

I am using this JSON to create an issue in Jira (using v2 of the REST APIs).

{
    "fields": {
       "project":
       {
          "key": "MyProjectId"
       },
       "summary": "REST ye merry gentlemen.",
       "description": "An elevator pitch (value statement) that describes the epic in a clear and concise way.",
       "issuetype": {
          "name": "Epic"
       }
   }
}

How can I include the markup here to create an Epic with rich text as description?

Well … after a bit of digging I noticed that the response when requesting an issue through the REST API’s (v2) also included the markup format.

I modified my JSON to include the ‘description’ like this

"description": "epic test\n*dssdf*\n{color:#ff5630}dfa{color}",

It works … now I just need to figure out how to convert HTML to this format :slight_smile:

Yep, that’s where to put the markdown. Converting HTML to markdown is fairly straight forward task of searching and replacing, but you need to do a few passes to convert all the formatting combinations.
Do a Google search for ‘convert HTML to markdown’ and you’ll find lots of examples.

Atlassian has a public JavaScript npm packages for building ADF easily:

And also exists community library to convert Markdown do ADF: GitHub - b-yond-infinite-network/md-to-adf: Markdown to Atlassian Document Format translation/traduction

Note: I would also need some HTML to ADF convertor.

Note: Since npm is a public package, too, so it should be possible to instantiate ADF editor in a web page (I have not tried.) Check @atlaskit/editor-core - npm

1 Like

Thank you for this! I was having the same problem and this was exactly what I needed to do to get the formatting right

@jlundstocholm Have you find any solution to convert html to this format?

Try this transformer to covert markdown to JSON or JSON format to markdown

https://atlaskit.atlassian.com/packages/editor/editor-markdown-transformer
https://atlaskit.atlassian.com/packages/editor/editor-json-transformer
https://atlaskit.atlassian.com/packages/editor/editor-wikimarkup-transformer/example/adf-to-wikimarkup

3 Likes

I think this exmple is in react and I am working on angular.
How can I use it in angular?

Thank You!