convert jira ADF formatted description in HTML format

[faisalamdani]

I am working on jira V3. When we get the jira issue from api we get the issue desciption in ADF format (I think) how to convert that format into HTML to show in our UI or there is any specific editor is given.

Thank You!

[Dario B]

Hello @faisalamdani ,

If I understand correctly you are calling the  /rest/api/3/issue/{issueIdOrKey} REST API endpoint and you are looking for a way to get the issue description in HTML.

Now, if my understanding is correct (provide more details otherwise), then all you have to do is to append the argument to expand the rendered fields to your REST API call, like in below example:

https://NAME.atlassian.net/rest/api/3/issue/{ISSUE-KEY_OR_ID}?expand=renderedFields

This way you will get the HTML for the text in the issue description.

For more details on expansion and for known issues, you may want to review the below links:

• Jira Cloud REST API: Expansion, pagination, and ordering 
• Atlassian Document Format to HTML 
• Known issues:
  • JRACLOUD-71136 - The /rest/api/3/search endpoint does not return comments and worklog comments as HTML even if we pass parameter expand=renderedFields. Everything works fine using the v2 endpoint

  • JRACLOUD-75825 - renderedFields HTML returned in v3 REST API does not match the HTML in the new issue view

I hope this helps. 

Cheers,
Dario

[Aravindh Dorai]

Hey @Dario B - this endpoint (https://api.atlassian.com/pf-editor-service) seems to be down. We're getting back a 404 not found. 

Is this a known issue? Hope it comes back online - we found it super valuable and were using it in prod 

[Dario B]

@Aravindh Dorai , 

That's not an official endpoint and indeed it is not documented anywhere. Therefore it should not be used since it could change or stop working from one day to another without previous notice. 

[Aravindh Dorai]

Got it. Would it be possible to open source the code for the convertor? It was super helpful to our team and users 

[Don Dorian]

Hi @Dario B , 

Thanks you for your answer.

I would like to join @Aravindh Dorai 's request - even though `pf-editor-service` wasn't an official service, it is very useful to developers to integrate with, and write services on top of the great Jira platform. Do you think you will be able to provide an open source library for the convertor?

Cheers

[Dario B]

@Don Dorian @Aravindh Dorai ,

I am trying to get in touch with the team in charge of this endpoint and until that time I cannot say much.

However, our internal team did a little investigation and they noticed that the service name changed and the endpoint still works internally. However, it cannot be accessed via api.atlassian.com anymore. Not sure if this is intended or not. I will provide an update as soon as I will manage to get more information on this.

Cheers,
Dario

[Aravindh Dorai]

Sounds great, thank you @Dario B

[Dario B]

@Aravindh Dorai @faisalamdani  

I have created a Feature Request to have a public REST API endpoint to convert among formats:

• JRACLOUD-77436 - Provide a public REST API endpoint to convert between ADF, HTML, Markup and Markdown now that pf-editor-service has been decommissioned

You may want to vote and watch the above feature request so that you will get notified in case of any update. The  feature will be addressed according to the Implementation of New Features Policy

Cheers,
Dario

[Maxime de Roucy]

@Dario B 

> That's not an official endpoint and indeed it is not documented anywhere. 

It's used at least in one of the apps in the bitbucket atlassian repository :

https://bitbucket.org/atlassian/stride-markdown-to-adf-app/src/65d8c19a76a33e3d5a79cfad7e1754cc3214cb29/routes/markdown.js#lines-42

(that's what convince me to use it in the first place some times ago).

[Dario B]

Hello @Maxime de Roucy ,

Welcome to the Atlassian Community.

Please notice that:

• Stride has been discontinued since February 2019 (see https://en.wikipedia.org/wiki/Stride_(software) for details)
• Therefore, not being publicly documented, that was an internal endpoint used by a product that does not exist anymore.

Once this has been said, I am happy to let you know that a slightly outdated version of the code is available in the public atlaskit repo:

• https://bitbucket.org/atlassian/atlaskit-mk-2/src/master/packages/editor/editor-markdown-transformer/

You can give it a try since, for now, it is not granted that an official endpoint will be released.

Cheers,
Dario

[Aravindh Dorai]

@Dario B it seems like the link you provided to the public atlaskit repo converts to the Prosemirror document format vs what we need, which is the Atlassian document format. Maybe I'm missing something? Is there any documentation on how to convert markdown to ADF using that code?

[Dario B]

@Aravindh Dorai  I might not be the best person to answer here since I have never done this myself. However, I forwarded your question to DEV and I got the below example in return:

import { defaultSchema } from '@atlaskit/adf-schema';
import { JSONTransformer } from '@atlaskit/editor-json-transformer';
import { MarkdownTransformer } from '@atlaskit/editor-markdown-transformer';

const jsonTransformer = new JSONTransformer();
const markdownTransformer = new MarkdownTransformer(defaultSchema);

const markdownDocument = '';
const adfDocument = jsonTransformer.encode(markdownTransformer.parse(markdownDocument));

Can you kindly test this and let me know if this is what you are looking for? 

[Aravindh Dorai]

Thanks @Dario B ! This works going from markdown -> ADF. When I try to do the reverse, I get a "This is not implemented yet" error. 

This is the code I'm using 

markdownTransformer.encode(jsonTransformer.parse(adfDocument))

[Dario B]

@Aravindh Dorai 

That library is old and not maintained and it can pretty much be that the method was not implemented at that time.

As an alternative, you can try to have a look at the below one:

• https://bitbucket.org/atlassian/atlaskit-mk-2/src/master/packages/editor/editor-bitbucket-transformer/

[haji abdul]

@Dario B Is there is any end point so we can add out HTML to jira using Jira API. At this time it's show as <h1>heading 1</h1> on jira after posting commit using API.

thanks 

Abdul. 

[David Bakkers]

Hello @faisalamdani 

As an alternative to @Dario B's method, read this recent post Is there documentation for api.atlassian.com/pf-editor-service/convert? that describes an undocumented Atlassian REST API endpoint that converts ADF to HTML, markdown and a few others, and vice-versa. It means double processing of the issue description, but it works.

Apart from that, there are a few other open source Java and C# libraries that apparently do a reasonable job of converting ADF to HTML, but I've not tried any of them.

[Tomer Ben Arye]

For Python, see my recommendation HERE 

for comment in jira.comments(issue.id, expand='renderedBody'):  # this is the main trick 

 print(comment.renderedBody)

The whole process:

from jira import JIRA

jira = JIRA(
    basic_auth=("<email>", "<API_KEY>"),  # a username/password_or_API_KEY
    server="https://YOUR_ATLASSIAN_SERVER.atlassian.net",
    options={"rest_api_version": 3}
)

# Get an issue.
issue = jira.issue("ALL-1234")  # A project 'ALL' as example with issue number 1234.

avoiding_types = ['app', 'atlassian']
for comment in jira.comments(issue.id, expand='renderedBody'):  # this is the main trick

    print(comment.author.accountType)
    print(comment.author.displayName)
    if comment.author.accountType not in avoiding_types:
        print(comment.author.emailAddress)
    print(comment.renderedBody)
    print(comment.created)