JSM now uses Atlaskit editor for customer comments, which breaks some Jira functionality and my plugins


  • Jira Server/DC supports custom macros for the editor
  • JSM switched to Atlaskit editor, which breaks custom macros


Jira Server / DC supports the concept of custom macros, as documented here:

That is, plugins can bring their own macros, and also enhance the functionality of the Jira Rich Text Editor.

Sometime recently (I noticed it with JSM 4.15), JSM converted to using the Atlaskit editor for customer facing content (ticket descriptions, comments, etc). This change breaks custom macros, and in turn breaks functionality for multiple of my plugins.

This seems like a gross oversight from the JSM team to ship a breaking change like this, and dropping support for native functionality without telling anyone about it.


  • why is there a breaking change being shipped without announcements?
  • what can I do to fix my plugins now?

Hi @ademoss,

I’ve started investigating this. Either myself or someone from the JSM Server team will be back in touch with a response.


Thanks @dmorrow, much appreciated.

Thank you for drawing our attention to this.

The editor changes in JSM 4.15 address a number of long standing customer requests. Whilst making the changes, we overlooked the ability for apps to extend the editor and we apologise for not providing advanced warning about these changes via developer channels.

We would like to understand if the change impacts user experiences, workflow/processes, or other types of functionality. We would also like to understand the degree of impact of this change on your apps and if there is a suitable workaround for your apps. This information will be useful for planning how to proceed.

Chris Morgan
JSM Server/DC

Hi @ChrisMorgan

In order to address your questions, let me elaborate a bit on what one of our plugins does:

Our plugin provides the ability to creating tasks/checklists within issues. This functionality exists on the Jira side, and on the JSM side, and is done by exposing a {task} macro that can be inserted into any Jira Rich Text field. That macro is then parsed on our end, edited to inject an id (so we can track the task), and then rendered.

To make entering the {task} macro easier, we do crazy customizations to the Rich Text Editor. We expose extra actions, to insert a task and to convert selected bullet points to tasks. We also have a customizable shortcut, so if a customer types /t for example, a task is inserted. This works in Visual Mode, as well as Text Mode. Similarly, when editing a task, hitting enter key wraps to the next line and starts a new task, similar to how bullet points work.

Now, you want to know the impact on user experience…
well, your changes literally broke pretty much all of the above on the JSM side, so customers can no longer do this.

  • Our custom actions - gone
  • Our shortcuts - gone
  • Manually entering a {task} macro - broken
  • Rendering existing task macros - still work (yay? :slight_smile: )

The Atlaskit editor does not understand any macro that is not native to Jira. So if you try to enter one, it simply treats it as text, and in fact, escapes it, which means the Jira Markup renering engine can’t even kick in. {task} turns into \{task\}.

As for workarounds, unless you’re planning on one of the following, I don’t quite see how a workaround is possible here.

  • adding extension points to the Atlaskit editor
  • adding support for rendering 3rd party macros that do not natively ship with Jira
  • changing the behavior of the editor to no longer escape manually entered macros

Now that i’ve pointed out all the doom and gloom, let’s level a bit :slight_smile:

How big of a problem is this really?
To be completely honest, hard to tell, but probably not that big of a deal.
I’ve also only heard from 2 customers about this so far, and they have been pretty nice about it all. Similarly, no other vendor has spoken up so far, which makes it seem like I might be one of the few (only?) vendors that actually used that functionality.

I’m pretty realistic about the greater needs of JSM, and I actually know just how ‘interesting’ (yeah, let’s go with that) it can be to work with the Atlaskit editor or try to customize it. As such, I have no illusions that your team is going to roll back this functionality, or make a fundamental change to Atlaskit, just to accommodate a small vendor that brings in less than 7-figures.

If the official word needs to be that “this is how it is”, no problem. I will tell my customers, throw you guys under the bus a bit, everyone will grumble for a day or three, and then we all move on.

As this type of issue keeps happening more and more frequently in recent months/years across (many) Atlassian teams, I would appreciate some answers on more fundamental questions. Namely…

  1. Your team decided to make a fundamental change to JSM (replacing the editor is no small thing). Why was there no announcement of any kind for such a major change?

  2. (most important of all) what changes has your team made in response to this?
    What is being done to ensure such an oversight doesn’t happen going forward?
    What is being done to communicate fundamental changes more effectively?

  3. Why pecifically was this overlooked? And Why is it that I, as a Vendor, have to educate an Atlassian team on their own product?
    This is literally the business Atlassian is in. Tools to track these things. Jira, Confluence, a marketplace that is searchable. All sorts of reporting behind the scenes.
    I don’t mean this as a snarky question. I am genuinely curious: What went wrong here?



Hi Anthony

I can see that would be pretty hard for you.

We understand that sometimes our documentation isn’t optimal, however we will try to refine that as best we can going forward. While the customer portal did work with macros, it was never intended to formally support them (as the customer portal editor was not the same thing as the rich text editor used within Jira, even if they did end up sharing some parts - something our documentation could’ve pointed out more clearly), so we hadn’t planned on anyone relying on that slice of it. We hope that vendors can catch these misunderstandings in our EAP releases, but understand that is not always possible. I apologise that this has impacted you.

You are right in your summation that we are not in a position to promise to roll back or extend Atlaskit with this functionality at this time.

There is one workaround I can suggest, for those customers who are affected and who have upgraded to 4.15, and that is to turn off the feature flag in their instance(s) for using the new editor - allowing them to operate with the old CP editor:

feature flag: “sd.customer.portal.wysiwyg.editor”

Hope that can go some way to helping you in your current situation


Hi @ChrisMorgan - thanks for the follow up. I’ll let the affected customers know about options to disable the new editor if they care.

As for telling me that the documentation is at fault, or that a publicly documented feature was not intended to be used in some specific way, well… I don’t even know where to begin with that… so, let me put that aside and not dwell on it.

The simple fact however is this: your team kinda messed up here.
So, can you please revisit my very specific questions from above, and tell us what your your particular team has done/changed (in terms of processes, and so forth) to ensure something like this doesn’t happen in the future?

You have to realize that every time this kind of thing happens (and the frequency is increasing), we get some sort of bogus excuse, and empty promises of “we’ll do better” and “we’re looking into ways to improve things”.

So how about we try to break that cycle of empty platitudes, and try to come up with something a bit more constructive. Perhaps something more tangible that actually creates accountability?



Hi @ChrisMorgan, I’m following up on this, in case you missed the notifications.
Are you going to answer my questions?

Hey @ChrisMorgan - following up on this again.
Your team literally broke existing functionality. And while I’m pretty zen about, and don’t expect any fixes/changes, the least you could do is explain what your team has done to prevent this going forward. So, are you going to answer?