Hi team,
I’m evaluation the cost of upgrading our addon to start using Jira API rest v3 instead of v2. Just to be prepared before any depreciation happens.
As far as I know, the main (and only?) difference is the use of the Atlassian Document Format (ADF). Rich Text Fields like description, environment, comment’s body, etc would use Atlassian Documents instead of wiki markup.
I have encountered several problems. I believe some of them are bugs and I couldn’t find the corresponding ACJIRA tickets. If they have been reported, could you provide a public issue key/link?
1) Single-line custom field inconsistency
Issue create operation fails if the value sent in a single line custom field is a plain string. For example, an issue input with a field like:
"customfield_11536": "singleLine"
.
fails with “Operation value must be an object”
After changing the value to
"customfield_11536" : {
"type" : "doc",
"content" : [ {
"type" : "paragraph",
"content" : [ {
"text" : "singleLine",
"type" : "text"
} ]
} ],
"version" : 1
},
The issue is created but field is broken:
and also the rest response when getting the issue is broken:
Should single-line custom fields be just plain text strings? not rich at all? Should the rest work with ADF objects or strings? If the UI is not rich, v3 rest should work with plain strings
2) Multi-line custom field inconsistency
Multi-line custom fields work better than single-line fields. They accept, stores and returns ADF document objects consistently.
The problem I have found is in the UI. For some reason, the UI doesn’t show the “richness” of the field and the UI editor is not rich either.
Some screenshots of the multiline custom field next to the similar environment field that does accept rich text in the UI:
Are multiline fields going to be rich? Or just plain texts that allow new lines? Should the rest work with ADF objects or strings? Again, If the UI is not rich, v3 rest should work with plain strings
I haven’t tested single and multi-line issue fields (the ones declared in the addon descriptors) yet. But when fixing this please consider those fields.
3) JSD Rest Api
Create a comment through the JSD rest API currently only accepts wiki strings instead of ADF objects. Are you going to provide a new version of JSD rest API?
4) Issue webhook data uses old issue/field model
Issue data in webhooks uses the old format.
"description": "some wiki markup *description*"
Is there any way to tell Connect to start sending the in issues in webhooks using the new v3 format? Some kind of apiMigrations flag like the gdpr one.
5) ADF <-> HTML <–> WIKI Convertors
It will be nice to have bidirectional mappers between all 3 formats.
Similar to the unofficial, not upgraded “/rest/api/1.0/render”
https://jira.atlassian.com/browse/JRACLOUD-38731
I’m aware of the ?expand=renderedFields. It currently doesn’t work with comment bodies, multiline custom fields and not all the values we would like to map are coming from Jira.
Long shot but I had to ask. I guess some of us are going to implement ADF to HTML/WIKI mappers.
What’s the future of v2 and v3?
Is there any deadline or deprecation date of v2? What should we expect? What’s the future of ADF? is it propagated to Confluence Cloud too?
Thanks!!
Fernando