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 https://www.npmjs.com/package/@atlaskit/editor-core

2 Likes

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!

2022-04-11: I’ve updated the post below as the adf-schema package was changed just after I posted.

I hope somebody finds this helpful.

The @atlaskit documentation can be found here.

Below is the code to do the Wiki Markup <-> HTML conversions. I’m pretty sure that you can just stap out the WikiMarkupTransformer for the JSON transformer.

// (Markdown / Jira Markdown) <-> HTML
import { defaultSchema } from '@atlaskit/adf-schema/schema-default';
import { WikiMarkupTransformer } from '@atlaskit/editor-wikimarkup-transformer';
import { DOMParser, DOMSerializer } from 'prosemirror-model';

/**
 * Convert Jira "Wiki Markup" -> ProseMirror -> HTML
 * @param {string} md The Jira "Markdown" string
 * @returns {string} The generated HTML
 */
const toHTML = md => {
  // Convert the Wiki Markup from Jira to a ProseMirror node
  const transformer = new WikiMarkupTransformer(defaultSchema);
  const pmNode = transformer.parse(md);

  // Serialize Prose Mirror Node to a DocumentFragment
  const dom = DOMSerializer.fromSchema(defaultSchema).serializeFragment(pmNode);

  // Get the HTML
  const div = document.createElement('div');
  div.appendChild(dom);
  const html = div.innerHTML;

  return html;
};

/**
 * Convert HTML -> DOM -> ParseMirror -> Jira "Wiki Markup"
 * @param {string} html The HTML
 * @returns {string} The generated Jira ADF
 */
const toMD = html => {
  // Create a new document and set the body
  const dom = document.implementation.createHTMLDocument();
  dom.body.innerHTML = html;
  console.debug('toMD', { dom });

  // Parse the DOM into ProseMirror and export to Wiki Markup
  const pmNode = DOMParser.fromSchema(defaultSchema).parse(dom);
  const transformer = new WikiMarkupTransformer(defaultSchema);
  const md = transformer.encode(pmNode);
  
  return md;
};

export { toHTML, toMD };
3 Likes

Thanks @PaulTaggart - this was very useful
In my case I could not find/use the default schema so I ended up using the confluenceschema ( getting jira or any other schema should be the same)

import { confluenceSchema  } from '@atlaskit/adf-schema/schema-confluence'

For the serializeFragment to work I had to change use get the fragment from the node (pmNode.content)

Lastly and the most tricky bit… I did not have the window object, because I am not running the code in
the context of a browser, so I had to use the window package . window - npm (npmjs.com) and pass it as an option to the serializeFragment method . …

serializeFragment(pmNode.content, {document: window.document});

Thanks again, your code was incredibly useful.

@kazidevelop I’m pleased it was helpful.

Is there a place where I can get information on the schemas (under @atlaskit/adf-schema) like ‘@atlaskit/adf-schema/schema-confluence’ e.g. what other schemas are there
confluenceSchema works but it does not translate come codes like {panel} and the formatting is a bit off
e.g. it marks new lines are
instead of
, and the code macros are not formatted correctly, among other things

Hi, @kazidevelop.
You can browse all the packages for @atlaskit here. Although there isn’t a lot of documentation.

The details for the schemas are here.

Since my post, @atlaskit/adf-schema was updated from 22.1.0 to 23.0.0 and the entry points were updated. So it looks like you’ll need to import as:

import { defaultSchema } from '@atlaskit/adf-schema/schema-default';

I’ve updated the import in my code above.

Paul

@PaulTaggart the only downside to this is if you use your own prosemirror dependency (for a custom editor) in tandem with the one Atlaskit is dependent on for these html->markup conversions.

It seems any introduction of additional prosemirror versions results in: Error: Looks like multiple versions of prosemirror-model were loaded

Interested to know if anyone has figured out a workaround. For me I just had to abandon pulling in my own prosemirror dependency, which means I’m locked into Atlaskit’s…

@evbo, thank you for the details.
I didn’t encounter this issue as I just needed to convert from Wiki Markup to HTML and back.

Thanks @PaulTaggart, I created a new issue for this. Unfortunately I had to monkey patch prose-mirror in order to interoperate with Atlaskit, so it’s a very fragile work around as discussed in that github issue.

My hope is Atlaskit will consider writing a unit test reproducing this error, so that they avoid it in the future: