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?

Hi @ademoss, we have updated the documentation (https://developer.atlassian.com/server/jira/platform/extending-the-rich-text-editor-in-jira/) so that this particular incident doesn’t happen again. However, in the grand scheme of things, this is not something we can guarantee will never happen again. Our tools were used in a way we did not expect nor anticipate. We see now why you were under the impression that this use case was supported, and we are sorry for that, but it’s not reasonable to ask us to come up with every unsupported use case and write it down in the documentation. I know that’s not the answer you want to hear, but it’s the truth.

Is that what we’re asking though? I mean, this sounds a bit like a reductio ad absurdum, which is a logical fallacy.

What we’re asking for is very basic stakeholder management: replacing a rich text editor is kind of a thing that you might want to pro-actively tell your power users. I mean, we’re even getting a months notice for a UI only naming change.

It’s completely reasonable for us to ask you take into consideration that you’re not the only one building on top of this product, given that Atlassian actually created an ecosystem of app developers to do so. I know it’s not something you want to hear, but it’s the truth.


@ChrisMorgan BTW, I know this great company that wrote a guide on stakeholder management if you’re interested.

Unless obviously you want to make a point about how Atlassian Marketplace Partners are not stakeholders… I mean, I get it, but I think @msuntinger would disagree

1 Like

Hi @remie

I understand you are frustrated. Your comment above shows why it was so important that we update the documentation. We have not replaced the rich text editor with this change. If we had done so we would definitely have notified partners and power users as early as possible.

We replaced the customer portal editor which is not the same editor as the RTE used elsewhere. The CP editor is just a textbox, which was retrofitted with some support for styles only. The team analysed all the supported use cases for this text box looking for cases where upgrading this to Atlaskit would cause a functional regression. The team did not identify any such supported use cases, and hence it did not trigger the extra comms tasks.

Had we known of this use case - we would’ve advised that it was not supported - but we also could’ve started the discussions for what it would take to officially support this, by adding in appropriate tests and procedure automations (including the above comms).

We make large numbers of changes every release and it is always a tradeoff about what to communicate (as overcommunicating can be equally bad for signal to noise), which is why we think long and hard about procedures to strike the right balance.

I am sorry this use case is one that we did not take into account, and the resulting undercommunication has affected you so greatly. We can only plan to analyse our known supported use cases, and we will continue to work through all our channels to discover and refine our set of use cases to avoid situations like this.


@ChrisMorgan is this really about documentation, or rather fulfilling the contract between Atlassian, customers, and vendors? You should not introduce any breaking changes in a minor release.

1 Like

Hey folks,

So after catching up on this thread, I was equally as upset as the sentiment here and spent much of the day digging into it.

What became apparent to me is that Developer Experience doesn’t call out significant UI changes as a critical notice/communication trigger for the developer community. In retrospect, that’s clearly a miss, and we’ll work to resolve that right away.

@ChrisMorgan and I also discussed in-depth the change process on the product side that led to this, and I do believe Chris made the best decisions given the information available. I also believe the feedback from this thread will help prevent this type of issue from happening again.

I’m very sorry this caused so much frustration and distraction. We’ll continue to work with our R&D teams to factor in these types of scenarios and ensure our stakeholder management is improving.

Thank you for your patience.