Addon migration from Jira Cloud rest v2 to v3

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:

image

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:

image

image

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

2 Likes

To complement Fernando’s excellent analysis, I would like to insist on the importance of being able to continue using a text-based input method (such as wiki markup). Our app, JMWE, offers post-functions that can set the value of a field, and the value is provided as text. Currently, if you are setting a wiki-rendered field such as Description, you can pass wiki markup to create rich text (e.g. “This is bold text”). I don’t see how the same could be passed using ADF.
Of course, we could offer the ADF editor instead of a plain text editor. But that won’t work with templated text. Our app uses the Nunjucks templating system to allow you to insert dynamic data into a field’s value. For example, you could pass this as the value:
Issue key is {{ issue.key }}
This, I guess could still work in an ADF editor. But what about:

Issues:
{% foreach linkedIssue in issue | linkedIssues("blocks) %}
* *{{linkedIssue.key}}*
{% endfor %}

which iterates over linked issues and outputs something like:
Issues:

  • TEST-1
  • TEST-2

As you can imagine, there’s no way the ADF editor could include repeating text sections. So we definitely need to keep a text-based format.

David

Thank @david2,

We are also in the same situation. User can provide a script that generates wiki markup. I reckon we would need to process the script, generate the wiki markup and then parse/convert the wiki markup into an ADF document. That’s why I’m asking for a wiki to/from ADF converter if possible.

We are going to code wiki markup parsers probably…

Same here. We allow users to put YAML into text fields and I cannot imagine asking them for creating ADF containing YAML.

Hi team, this topic is getting hot.

The editor in the new issue view uses markdown rather than wiki markup. Right now, if you’ve added wiki markup in the old editor, we’ll render it correctly in the new issue view. As we continue to roll out the new issue view and new editor, wiki markup support will be phased out and eventually removed in favor of markdown.

We are seeing how wiki markup is fading away. If you edit a description that was written in wiki markup and you save it the final text will be broken (showing the wiki markup instead of the formatted text)

Has Atlassian solved the issues? Should we start migrating our addon to start generating ADF asap?

An additional note on using renderedFields: the rendered HTML output provided via this interface is not even close to the HTML that is used on the actual new issue view. This becomes apparent for things like the “status” block, which is not rendered anything like it looks on the new issue view itself. I would’ve expected that the v3 API would render it the same as it does on the new issue view! I get that the v2 API would render it like it does when converting to it for the old issue view.

Note: I’ve created the following issue regarding that particular nuance:
https://jira.atlassian.com/browse/JRACLOUD-75825

At this point, it’s just a suggestion and needs votes…

I have left a comment in ACJIRA-2171 requesting a plan be outlined for solving these issues.

Thanks for the extensive analysis @fboucquez! I just retestet single- and multi-line custom fields, and it seems that at least single-line custom fields behave correctly now (accepting only string values, without ADF).

For the multi-line custom fields, I’m wondering if this is an issue at all, since it doesn’t seem to be possible to insert rich text in the Jira UI. As long as only the supported subset of ADF is used with these fields (e.g. type = paragraph/hardBreak/text), it should be fine?