I am using the Jira Cloud rest API v3, and I need to know if it’s posible to get rendered fields such as comments and description in plain text.
Endpoint: /rest/api/3/issue/DEMO-1
Cheers, Francisco Santos.
2 Likes
Not that I’m aware of. I kept going back to the v2 API call where I was using the Description field. Recently I set some time aside to understand and write some code to convert Jira’s ADF text into plain text - it’s not comprehensive but works for me and has allowed me to start using the v3 API calls again.
Hi @dmorrow,
Our team is trying to upgrade to the REST API version 3. However, the description field is now giving the adf instead of wiki.
We were thinking about using some Editor dependency from atlaskit. However, there is this note:
“This component is designed for internal Atlassian development.”
Do you know if there is anyone at Atlassian that could help us?
Thank you.
1 Like
Hi @paulo.alves,
Are you needing to render the description field or parse it? There is some documentation of ADF at Client libraries which references a library to help build ADF, but not parse or display it unfortunately.
Regards,
Dugald
Hi Dugald,
Thank you for your response.
We need to parse the adf to get the description in raw/plain text as we can get in version 2 of the REST API. After upgrading to version 3, we got an adf instead the raw text and we are trying to find a way to transform the adf.
Kind regards,
Paulo Alves.
Generally, we won’t be able to switch to the v3 API until we get a bi-directional text representation of content, like wiki markup is in v2. It doesn’t have to be wiki markup (although for compatibility reason we’ll need to continue supporting it for a long time), but it needs to be text-based instead of object-based, and it needs to be simple to understand and manipulate. The reason is simple: we offer scripting and templating functionality, which is naturally based on a textual representation of data, just like any other scripting /templating technology out there.
What would you do if you could only write web pages using the DOM instead of HTML?
2 Likes
Hi @paulo.alves, Hi @Francisco.Santos
Getting the plain text of a comment (or the description) is pretty easy with Jira Expressions. You can just use the REST API endpoint for Jira Expression, send the issue you are looking for as context and use an expression like this one:
issue.comments.map(c => c.body.plainText)
Jira Expressions have the additional benefit of allowing you to select only the data you need, ie you can keep the payload small and have Jira perform aggregations for you.
While Jira Expression are said to at some time support ADF, the way I understand the documentation is that the plainText attribute is here to stay.
Hope that helps,
Oliver
P.S. The Expression Tester in the screenshot is a free app of ours. I find it easier than using curl or postman.
3 Likes
Hi Oliver,
Thank you for your response.
We tried to use Jira Expressions before, but we didn’t find a way to get rendered fields from it. In our case, we need both description and custom fields in plain text and html.
Were you able to get rendered fields from jira expressions? Calling two different services for this doesn’t look like a solution for our use case.
Thank you,
Paulo Alves.
I totally agree with David, we need to continue supporting this and it’s hard to upgrade to API version 3. It would help if Atlassian could provide some utilities for converting from plain text to html or adf to plain text for example.
1 Like
I believe what we need is utilities (or APIs) to do bi-directional conversion between ADF and:
- plain text (removing any formatting)
- HTML
- some sort of markup language that describes the formatting
With the v2 API, we have:
- no conversion between wiki markup and plain text (that I know of)
- conversion from wiki markup to HTML (but not the reverse)
- bi-directional conversion between ADF and wiki markup (when the content was created with the new issue view)
@paulo.alves FYI, Jira expressions don’t return plain text, they return wiki markup. So if you have a word in bold, you’ll see the wiki markup for it: “a bold word” returns "a *bold* word"
2 Likes
Hi David,
I got confused about these sentences: “1. no conversion between wiki markup and plain text (that I know of)” and “Jira expressions don’t return plain text”.
Maybe I’m wrong about it, but I think Jira expressions return plain text for the description and other fields - the only difference is the renderer type that could be default text or wiki-style renderer. Won’t you agree?
Thank you.
Hi @paulo.alves,
what I meant by “plain text” is text without any markup. In my example, that would be "a bold word" (without the * around the bold text). Sometimes, it can be useful to get real plain text from a “rich” text field such as description or comment, for example to send it to a chat system or in a raw text email body.
Of course, Jira doesn’t make any difference between plain text and wiki text until it renders a field and interprets the wiki markup using the wiki renderer if one is associated with the field for the issue’s issue type and project (because it depends on the issue field scheme).
However, things are a little different in the new issue view, which totally ignores the “renderer” and considers fields as “rich” and stores the content as ADF. This creates some nice inconsistencies between the old and new issue views, where, for example, some tables built with the new issue view will be “broken” in the old issue view.
Hope this clarifies my earlier comment.
David
1 Like
FYI: I found this page Handle wiki markup and HTML a while ago and was wondering how it could be beneficial to my problem of getting good quality HTML from ADF or wiki markup. I never quite figured out how I would use it and just ended up relying on the renderedField from the API. However, I had completely overlooked (or more just that I didn’t think about it) to use the Jira Expressions API! D’oh! I’m testing this now and will respond soon if I have any good results.
Hi,
@dmorrow I’ve seen the library the helps us to build the ADF but currently it seems there is none to help with the conversion from ADF format to HTML or wiki. This doesn’t allow us to upgrade to the v3 of the Rest API.
Do you know if something like that will be available in the future?
Best Regards,
Mário Ferreira
1 Like
For an issue on v3 API, use ?expand=renderedFields. For comments, use ?expand=renderedBody. This will give you HTML.
You can also try using the Confluence converter to convert between various formats.
Unfortunate there is no way to get plain text that doesn’t include markup (e.g. [~accountid:1234abcd]). Very annoying when integrating with plain-text systems. Why can’t we easily get it as @Display Name?
“Rendered plain-text” is what we want for integrating with external systems that do not support HTML - essentially, identical to the HTML rendered view, but with the HTML tags stripped. Hell, give us a .stripHtml in Jira Expressions, Smart Values, and any other expression systems you decide to create instead of re-using existing systems (WTH are SVs different than JEs?!?!) and we can do it ourselves.
1 Like
I wrote a Javascript example script that parses the Atlassian Document Format (ADF) JSON and extracts the plain text from the “text” property of all the document nodes. It recursively iterates through all content and extracts the “text” property if it exists, and concatenates it to a string. If the content has a “content” property, it will recurse through it to extract the “text” property. Text that belongs under a common node such as paragraph are concatenated inline. Each collection of text from a node is put on a new line:
Script:
// Sample JSON
const json = {
"version": 1,
"type": "doc",
"content": [
// ...
]
};
// Function to extract text from JSON
function extractTextFromJSON(json) {
let text = "";
// Keep track of the previous node type
let previousNodeType = null;
// Iterate through all content
json.content.forEach((content) => {
// If the content has "text" property, append it to the string with or without a newline character
if (content.hasOwnProperty("text")) {
// Check if the current node type is the same as the previous node type
if (content.type === previousNodeType) {
text += content.text;
} else {
text += "\n" + content.text;
}
// Update the previous node type
previousNodeType = content.type;
}
// If the content has "content" property, recurse through it
if (content.hasOwnProperty("content")) {
text += extractTextFromJSON(content);
}
});
return text;
}
// Call the function with the sample JSON
const result = extractTextFromJSON(json);
console.log(result); // Output the concatenated string with each "text" field on a new line
Example Rendered Text:
This is a rendered rich text area that I created using the Atlassian Document Builder Tool
JSON Object in Atlassian Document Format:
{
"version": 1,
"type": "doc",
"content": [
{
"type": "heading",
"attrs": {
"level": 1
},
"content": [
{
"type": "text",
"text": "Lorem"
}
]
},
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Lorem "
},
{
"type": "text",
"text": "ipsum",
"marks": [
{
"type": "strong"
}
]
},
{
"type": "text",
"text": " dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris "
},
{
"type": "text",
"text": "nisi ut aliquip ex ea commodo",
"marks": [
{
"type": "em"
},
{
"type": "underline"
}
]
},
{
"type": "text",
"text": " consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. "
}
]
},
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Excepteur sint occaecat cupidatat non proident, "
},
{
"type": "text",
"text": "sunt in culpa qui officia",
"marks": [
{
"type": "em"
}
]
},
{
"type": "text",
"text": " deserunt mollit anim id est laborum."
}
]
},
{
"type": "bulletList",
"content": [
{
"type": "listItem",
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Sed "
}
]
}
]
},
{
"type": "listItem",
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "ut "
},
{
"type": "text",
"text": "unde",
"marks": [
{
"type": "strong"
},
{
"type": "textColor",
"attrs": {
"color": "#bf2600"
}
}
]
}
]
}
]
},
{
"type": "listItem",
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "perspiciatis "
}
]
}
]
}
]
},
{
"type": "paragraph",
"content": []
},
{
"type": "paragraph",
"content": []
}
]
}
Script Output:
Lorem
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Sed
ut unde
perspiciatis
JSFiddle Link: Atlassian Document Format Textarea JSON to Plain Text - JSFiddle - Code Playground
2 Likes