Come for the products,
stay for the community

The Atlassian Community can help you and your team get more value out of Atlassian products and practices.

Atlassian Community about banner
4,323,843
Community Members
 
Community Events
168
Community Groups

convert jira ADF formatted description in HTML format

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!

3 answers

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.

1 vote
Dario B Atlassian Team Jul 16, 2021

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:

 

I hope this helps. 

 

Cheers,
Dario

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 Atlassian Team Sep 17, 2021

@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. 

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

Like Don Dorian likes this

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 Atlassian Team Sep 23, 2021

@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

Sounds great, thank you @Dario B

Dario B Atlassian Team Sep 23, 2021

@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

@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 Atlassian Team Sep 24, 2021

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:

 

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

 

 

Cheers,
Dario

 

@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 Atlassian Team Sep 24, 2021

@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? 

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 Atlassian Team Sep 29, 2021

@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:

0 votes

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)

Suggest an answer

Log in or Sign up to answer
DEPLOYMENT TYPE
CLOUD
PRODUCT PLAN
FREE
PERMISSIONS LEVEL
Site Admin
TAGS

Atlassian Community Events