It’s time to dogfood your apps with the new approach to Confluence Cloud macros!

TL;DR

As previously announced in December 2020, the Atlassian Editor team is rolling out a number of sizeable changes to the way macros exist in Confluence Cloud. We’re shipping a new:

  • Configuration experience to help users stay in context when editing macros
  • Browser to help users find both native features/content types and macros (in a prettier way, too)
  • Top toolbar + dropdown to help users insert features/content types into the editor in a more consistent way

We need you to:

  • Read this blog and understand the impact to you.
  • Dogfood your apps and provide feedback through this blog (i.e. add a comment), directly to jkatahanas@atlassian.com, or set up a meeting with me. Note, dogfooding will only be available for partners who have signed up to be part of the dogfooding group for this feature; this already includes all instances signed up to the Confluence Cloud: Developer-First Rollouts for Ecosystem App Developers Group. Please complete dogfooding by Mar 12, 2021.
  • If you haven’t already, complete this 1 minute survey re; new browser categories to help us understand if our new proposed categories make sense. Please do so by Feb 26, 2021.
  • Update any of your marketing material, app store listings, etc, with any changes that your app will have from a UX POV. This is up to you when you do this, if at all. Our recommendation is to do so as soon as possible.
  • Leave any questions or comments on this blog

Note: As with any rollout of a big new change, unplanned things can arise. This timeline is our best guess with current information at hand. It’s subject to change if we encounter any issues we weren’t expecting.

Background

Extensibility in the Confluence Cloud Editor is critical for a number of reasons. For:

  1. Our mutual customers , it’s how they truly unleash the power of products to service their specific needs. Macros provide users the ability to supercharge their Confluence documents with all manner of wonderful experiences and features.
  2. You as partners , it’s how you create value for our mutual customers, and inherently, how you create a thriving business for yourselves.
  3. Atlassian , it’s how we scale our ability to deliver value to our mutual customers by having more external teams building on the editor.

For all the value the historical extensibility model in the editor provided, it had a number of downsides. For:

  1. Our mutual customers , the UX was at times unintuitive, disruptive, and out of date. For example, when editing a macro, the configuration would appear over the macro itself, making it impossible for the user to see what content they were editing without opening a second tab. Our macro browser also didn’t align to our current design guidelines.
  2. You as partners , could only build macros/apps for a single product, Confluence. There was no opportunity to surface and sell your app in other products’ editors (e.g. Jira’s editor).

What is changing?

With an understanding of the challenges mentioned above, we’ve reimagined and rebuilt our extensibility experience.

A new content discovery experience

We’ve overhauled the old school macro browser, giving it a lick of paint (i.e. aligning it to current design guidelines) and bringing native features/content types into the browsing experience. We now not only surface existing macros, like the Table of Contents macro, but also surface all other native features/content types that can be inserted into the editor, like panels and expands. This creates consistency with what is available in our other insert menus such as the slash command. Furthermore, it’ll work in all products, not just Confluence (in the future - more on that later).

Our + menu in the top toolbar dropdown has also been overhauled to look and feel the same as the / command Browser. A search field has been added to the top to enable quick search of macros and native features/content types.

Before

After

As part of this new browsing experience, we’ve done research to update the categories in the left sidebar of the browser. We had a belief that the categories didn’t map intuitively to all the apps. We validated this with user testing and have come up with a better performing list of categories. As a final test of these categories before we implement them, we’d love to get your thoughts on what category you think your app would make sense to map to. Can you please fill out this 1 minute survey to help us make this experience as awesome and intuitive as possible - follow this link to Google Forms.

Contextual configuration

To solve the problem of taking users out of context when configuring their macros, we’ve built extension configuration into the new side panel in Confluence. This aims to provide a far greater WYSIWYG experience for users, enabling them to see the extension they’re configuring whilst configuring it.

As partners, you don’t need to do anything for this. We’ve migrated all your configuration experiences to the sidebar.

Note: Some macros that have custom configuration won’t initially work in the new configuration panel. For these they will continue to use the old configuration. We have a flag that will recognize when custom configuration is used and will automatically fallback to the old configuration experience. Over time, we will work to define a path forward for these macros as well. Please let us know if this is you and what your requirements are.

A more extensible editor

One of the big advantages of this new approach, beyond the UX, is the fact that configuration and browsing of macros can happen in any Atlassian cloud product that has the new editor. This theoretically means that you can build a macro once, and sell it to a lot more users across Jira, etc. Unfortunately, we won’t be able to ship this in the short-term as products like Jira still have some issue views that use the markdown editor. If a user were to insert an extension in an issue’s new editor, then someone else were to view/edit it in the old editor, we’d corrupt their content. We’re currently looking at ways around this. We’ll let you know when we’re getting close to launch!

Our rollout plans

As this is a sizeable UX change, we’re going to do a conservative rollout. Stages of rollout are outlined below. Exact dates will be announced shortly on the dev community. We’re just finalising some dev work and testing on our side:

  1. Rollout new experience internally at Atlassian and on your testing instances through the dogfooding group for dogfooding. We’ll take feedback and make appropriate fixes over the course of ~4 weeks. We’ve recently started internal dogfooding at Atlassian. Partner dogfooding will run from the date this blog is published (Feb 11, 2021) and go until ~Mar 11, 2021.
  2. Finalise any remaining changes we need to make pre-rollout and go through our internal rollout process. This will finish on ~Apr 2, 2021.
  3. Start progressive rollout to customers on ~Apr 19, 2021. We’ll incrementally rollout over ~4+ weeks. We will start rollout to 10% of customers. Every week after (assuming no issues occur), we will progressively rollout to 25%, 50%, then 100% of non-enterprise customers. From ~May 14, 2021 we will rollout to the remaining enterprise customers.

During this rollout time, we’ll also be sending out communications to our customers about the upcoming changes.

Note: As with any rollout of a big new change, unplanned things can arise. This timeline is our best guess with current information at hand. It’s subject to change if we encounter any issues we weren’t expecting.

What do you need to do?

#1 Dogfood and give feedback: Please dogfood and give us feedback! When we rollout to the partner dogfooding instance, please spend time testing your app and giving us feedback.

If you find bugs, please let us know:

  • Current behaviour
  • Expected behaviour
  • What you were doing when it occurred
  • What browser you were using
  • How to reproduce, if possible

If you have suggestions, please let us know:

  • Current behaviour (or what doesn’t exist)
  • What you want to exist
  • Why / user problem it solves / use case

When giving feedback, the more information you can provide, the better.

#2 Complete survey re; browser categories for your apps: Can you please complete this 1 minute survey re; new browser categories to help us understand if our new proposed categories make sense. Please do so by Feb 26, 2021.

#3 Design and build future apps with the new experience in mind: As you’re building new apps in the future, please consider the new UX, ensuring that your configuration makes sense in the new model. If we have any gaps with what we’re providing, please also let us know so we can make things better!

If you have the question - “How do I build new apps using this new config?” There’s a simple answer:

  • If you’re building a Forge app, this is the only configuration that is possible to use. You don’t need to do anything new. Just follow the Forge docs.
  • If you’re building a Connect app, you’ll need to follow these docs.

Some other things to note about the current experience in dogfooding

We’ve already been dogfooding this for about a week internally and have found a number of bugs and UX issues. There is a team working through them to get them fixed before going to customers. If you find any issues with your macros, check this list of known issues and see if it’s related.

Thanks for all your input on this new experience. We hope you’re as excited about this as we are!

Jonno Katahanas | Product Manager for the Atlassian Cloud Editor

7 Likes

Whoa, thanks for all the details and explanations @JonnoKatahanas!

I just wanted to test the new experience on my main dev instance which I’m 99.99% sure is in the EAP program already. Unfortunately I seem to still be getting the old experience there.

Do I need to resubmit my instance for the EAP program (well, already did that) to get the new experience, or is it simply not rolled out to my instance yet and I just need to be a little more patient? :smiley:

Cheers,
Sven

Hey Sven, sorry for the inconvenience. Can you please check again if it’s working for you now or not?

Hmmmm… Also tried in Incognito in case this might be caching issue, but am still getting the old experience as far as I can tell.

Hey @sven.schatter, it should work now :crossed_fingers:

1 Like

Thanks for looking into it @rifat, it does work now - and slick it is! :slight_smile:

2 Likes

Hey @rifat,

I’m getting the same issue as @sven.schatter on the instances that I enrolled in the EAP. Could you roll them out to our instances again too please (I’ll DM you with them).

Cheers,
Dylan

Hey @dlindsay,

I will have a look if your instances are included or not. I didn’t manually add @sven.schatter to any list. There was a feature flag dependency issue which was preventing it from working. Now it should work for anyone who is included in the EAP segment.

Cheers,
Rifat

2 Likes

Many thanks and looking forward to working with it!

Hi @JonnoKatahanas,

I found an issue with some of our inline macros having plain text bodies. It’s not possible to change the body currently because the respective field in the macro editor is not displayed anymore.

I’ve seen that you have a related item on your known issues list:

Plain text macro content is not editable

Just wanted to let you know that there actually is a demand for macros with these settings :slight_smile:

"outputType": "INLINE",
"bodyType": "PLAIN-TEXT",

Is there some sort of timeline for a fix yet?

Cheers,
Jens

5 Likes

@JonnoKatahanas Full screen macro configuration modal is the case I would like to mention here. It could stay intact. :slight_smile:

2 Likes

Hey @jens! Thanks for that. We’re working through potential solutions for inline and block plain text macros as we speak. We won’t have a solution for initial launch to customers, so for some period of time we’ll fallback to the old config experience. As soon as we have something, we’ll let you know.

Cheers,
Jonno

3 Likes

@Grzegorz.Tanczyk the full screen macro config will remain as is for the forseeable future.

3 Likes

In our instance, the edit button has vanished for our fullscreen macros since upgrading to the new configuration. Macros can therefore no longer be edited. It seems that the “fallback” to the old version does not work out of the box.

2 Likes

We are also experiencing this issue which means we can no longer develop on that instance.

@JonnoKatahanas is there a workaround for this issue?

3 Likes

@JonnoKatahanas We are testing this on one of our EAP instances with a plain-text macro presently. We are not seeing that macro fall back to the old editing experience. As a result, the right hand side bar offers no ability to insert plain text macro body text at all, rendering the macro completely useless (unless it had content inserted prior to the new UI being released).

This issue has broken our ability to run integration tests on any EAP site. Please tell me the fallback is going to be fixed before it reaches any customers. If you need a demonstration of the problem, please reach out to us directly.

4 Likes

We are seeing the same behavior that @BobBergman has reported across all our plain text macros. Hopefully, we are a ways away from shipping any of these changes. This is not the first time plain text macros have been neglected and left behind by Atlassian. Any chance you guys can beef up your testing efforts to include a variety of macro types especially since this is a large change to the macro experience?
Thanks

3 Likes

Hello Atlassian,
I opened DEVHELP-5737 to track this for my team. This affects multiple macros/apps that we publish and it would be a big problem for a lot of customers if this bug makes it beyond EAP. It’s an emergency for us.

Thanks!

3 Likes

We’re seeing problems now with non-plain-text macros now as well. We will post more details here shortly, but I would like some formal Atlassian response that issues reported here will actually be individually collected and tracked. In the meantime we will cross post details as we find them to a DEVHELP that we opened with the same information.

There are a lot of issues with the current build and think that even a reasonable amount of pre-testing with popular macros on the marketplace would have revealed a lack of readiness for this EAP release.

4 Likes