RFC-36: Live-Edit Pages in Confluence Cloud

General Request for Comments (RFC)
, ,
1

RFCs are a way for Atlassian to share what we’re working on with our valued developer community.

It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.

Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!

RFC dates:

  • Publish: February 13, 2024
  • Discuss: March 6, 2024
  • Resolve: April 24, 2024

Summary of the project

To make page creation & collaborative editing easier, we are in the early stages of testing Live-Edit Pages in Confluence Cloud. Live-Edit Pages will not have a separate editor and view interface. Users will be able to see all changes in real-time, without the need for the page to be published. Publish will be optional.

image
image4096×1260 218 KB

We are launching an Early Access Program, where apps will have some limitations, that we will expand on below. We want to be clear: this is very early testing, and is not representative of the final state of Live-Edit pages.

We plan to make many changes along the way that incorporate feedback and what we’ve learned over time. We are particularly keen to incorporate your feedback on any impacts Live-Edit Pages will have on apps that we may have missed, as well as how we can best support your apps in Live-Edit Pages.

Problem

Page creation & collaborative editing in Confluence today requires many clicks and page loads (edit, publish, update, etc). Solving this problem will help customers save time, collaborate more seamlessly, and help expand the adoption of Confluence (and its apps) throughout organizations.

Proposed Solution

To make page creation & collaborative editing easier, we are in the early stages of testing Live-Edit Pages with customers.

Live-Edit Pages are continuously editable for users with editing permissions, without any additional clicks to enter or exit the editing mode.

  • When visited, Live-Edit Pages are editable without any extra clicks, displaying edits in realtime. Users with view-only permissions cannot edit, but can still see others’ realtime edits. Live-Edit Pages will not have separate editing and viewing interfaces.
  • When created, Live-Edit Pages do not start as drafts. They are immediately created as pages with a default title (“Untitled page X”) that can be updated.
  • When created, Live-Edit Pages are “open by default.” In other words, other teammates in the space will be able to view and edit the page, as well as search for it & see it in the sidebar, without it ever being published. Users can, of course, update permissions for the page after creating it.
  • “Publish” is still available for Live-Edit Pages for pages that require more formality or version control, but is optional and one click removed in the ... menu. This means that it’s likely that many Live-Edit Pages are only ever accessed in editing mode. Users will also be able to convert a published page back to Live-Edit.
  • Once published, published pages work the same as today. They are viewed in a rendered state, require a click to edit, and are updated via additional publishes.
  • Live-Edit Pages will still maintain version history in “Page history,” but each version will be the result of automatic “snapshots” taken after each unique edit session.
  • Given the above, “Share” becomes the primary call-to-action for a Live-Edit page.

image
image2606×1442 289 KB

Given this is a large change to page creation in Confluence, we are holding an Early Access Program with ~20 customers to test our assumptions.

  • Customers in the EAP will be able to create “Collaboration” spaces within Confluence, where all newly created pages will be Live-Edit. In the future, other types of spaces will likely be able to have Live-Edit Pages created in them as well.
  • Customers can also create “Knowledge base” spaces, which behave the same as normal spaces today, with all newly created pages being standard published pages. Pre-existing spaces will be unaffected and continue to behave the same as normal spaces today, treated as “Knowledge base” spaces. Live-Edit Pages can be moved into “Knowledge base” spaces.
  • During this EAP, apps will have significant limitations with Live-Edit pages (listed out below).

Again, this is very early testing, and not representative of the final state of Live-Edit pages. We want your feedback on how apps and Live-Edit pages should work together in the future. To that end, we will:

  1. List the EAP limitations that we know exist and how we’re thinking of handling them in the future, open to your comments.
  2. In parallel, open up a Partner Early Access Program, so you can directly test and understand the impacts of Live-Edit Pages on your apps. Sign up for the Live-Edit Pages Partner Early Access Program here.

EAP Implementation details:

The following definitions will be used to describe the implementation.

  • View page / renderer: the static rendered mode that users land on once a page is published. Uses Atlaskit Renderer.
  • Editor: a separate component that enables building page structure and collaborative editing. Uses Atlaskit Editor core.

Instead of a separate content renderer, Confluence will use the Editor for an always-live combined view and edit mode. This means that by default there will not be a static view mode, rather, the Editor component will be re-used and extended. Even users with view-only permissions will be able to see the document updates in real-time.

Confluence will continue using the same underlying page content type. Upon creation, we will immediately create both the current and draft versions; rather than starting with an unpublished draft. The draft status version of the content object will be the source of content loaded into the editor. Background “snapshots” will be created after a period of inactivity on the document, which copy across changes from the draft object to a new current version. This snapshotting allows version history, notifications, indexing and retrieval of the content by macros. Unlike unpublished drafts, Live-Edit Pages will be open by default upon creation and visible across the product. Again, these behaviours are what we have for the EAP and are subject to change in the future.

An explicit publish action will not be required for Live-Edit Pages, therefore, we expect a change in user behaviour, whereby a subset of pages are never published. However, we don’t yet know what the ultimate proportion of always live-edit pages versus published pages will be. Note that the intention will be for publishing Live-Edit Pages to closely match previous behaviour, including for apps (e.g. macros, publish conditions, webhooks, events).

Impacts to Apps in EAP

Connect Webhooks / Forge Events

For EAP, Live-Edit Pages will send a page created event immediately upon creation (Forge & Connect Webhook). This behaves differently than non-Live-Edit pages, where the create event is sent upon first publish.

Background snapshots will trigger a page updated event (Forge & Connect webhook).

Under consideration: We are considering having Confluence emit a new event when background snapshots are created in Live-Edit Pages, and reserving the pre-existing update event to fire only when a user explicitly triggers a publish/update.

Extension Points

Live-Edit Pages EAP will not roll out with the various web item integration points that are available on the view page. Specifically, web items & panels: System Content Metadata, System Content Button, Secondary Content Action, Page Metadata Banner and atl.page.metadata.banner. Only the previous editor integration points will be supported for the Live-Edit Pages EAP - System Editor Precursor Buttons and atl.editor.savebar.

Under consideration: We are planning on adding support for a subset of the existing view page web items and panels in Live-Edit Pages.

Macros

Currently, all macros (built by Atlassian, vendors, and customers) only have full usability & interactivity on the view page as they only show a preview in the editor. This means a large number of macros will not be fully supported within the Live-Edit pages EAP.

For the EAP, we are making a subset of simple Atlassian-built macros functional in the editor by allowing their contents to be clicked in the editor (for example, making links in the Children display macro clickable while editing). For the EAP, when a macro that is not fully supported in Live-Edit pages is inserted into a Live-Edit Page, we will show a flag to the user that informs them so, and that they can publish their page in order to display the macro properly.

Screenshot 2024-02-26 at 11.53.06 AM

Certain macros have additional complexity due to Javascript event conflicts with the Editor - for example, input fields, like in the Atlassian-built Live Search macro. Bodied extensions currently only show their nested content in the editor, and the “rendered” view cannot be displayed in the editor. We are aware that many app macros use bodied extension content as a configuration for their display.

Under consideration: We are considering allowing Connect/Forge macros to have a setting that allows their contents to be clicked in the editor. The ideal end-state is that all macros (Atlassian-built, vendor-built, and customer-built) in Live-Edit will be WYSIWYG and fully interactive, without a need to publish to see the final macro content.

Additionally, we are planning to improve the UI for macros in the editor to make them appear more seamless with the rest of the content. These enhancements will apply for vendor macros as well, and we are collecting feedback separately here: RFC-33: Modernized macro styling while editing in Confluence Cloud.

Changes to the publish workflow

Since Publish is removed as a necessary action for users to share and distribute Live-Edit Pages, this means that publish conditions are no longer a prerequisite before pages are distributed. This changes the use-case for publish conditions.

Rest API’s

Existing page REST APIs will still function, given that Confluence is still representing Live-Edit Pages with the same page content type. A new “unpublish” API will be introduced and it will be made public post-EAP.

Live-Edit Pages and draft/published pages will be differentiable via the content API by the subtype field. Currently the subtype is not available on the v2 API. This is not considered a stable API and the representation of Live-Edit Pages may change. Apps should not be querying the subtype at this time.

Asks

  • What do you think about the early proposals to handle app limitations in Live-Edit Pages listed in this RFC?
  • Are there any other areas, use cases, etc that we are missing?
  • What other feedback do you have to make apps and Live-Edit Pages work best together in the future?
  • Sign up for the Partner Early Access Program if you are interested in directly testing your apps in the early EAP environment.
2 Likes
2

I’d suggest careful consideration of how the current content/page version number is incremented. If it’s going to be incremented with each live edit, that will break any Marketplace apps using it as a reference.

There are multiple conflicting RFCs in play across multiple independent internal teams. What really needs to happen is for Atlassian to completely finish all the work (v2 API, live editing, macro changes etc) and then deploy that into a staging EAP environment. Then give us Marketplace developers 12 months to test and fix all the inevitable breaking changes.

12 Likes
3

Hi @DavidMichelson ,

Thank you for the advance RFC and thoughts about implementation and impact.

We work with many Atlassian customers in regulated industries. These customers rely on page versioning to make sure that a specific page and page version correspond to some specific document state.

Live editing seems to break this correspondence between document version and (viewable) document state. I believe the impact for these customers will be large.

How will live editing o.a. impact on content state: Introducing Content State API ?

How will connect static content macros be handled?

5 Likes
4

Hi @DavidMichelson ,

Thanks for the RFC and for asking our input. I believe the impact of this will be huge, because – like @marc just pointed out – it changes a fundamental principle of how page updates work. Let me elaborate a bit on that.

Before, we had defined versions for pages: whenever someone publishes a page, a new version is created. This relationship between a page version and changes on the page weakens with live edits, especially when users adapt their behavior and no longer publish pages.

To give a more tangible example: Say you have an app that listens to a page updated event, scans the updated page and then potentially performs an action on that page. With the change proposed here, the app will receive a lot more events for what is now a background snapshot. Since there’s no way to determine if that background snapshot is just intermediary or whether the user is finished editing, the app would need to react to every single one of these events. Especially for Forge apps, I can see that becoming hard to manage.

From a user perspective, the background snapshots would become visible with apps that work like I mentioned above. Pages they are still actively working on might be changed by an app that before would just make an updated after editing was finished. So, not only would users need to learn new editing behaviors, they would also need to get used to new app behaviors.

There are also a lot of Confluence Automation Rules, created by various of our shared customers that rely on the “Page Published” or “Page Edited” events. A lot of those will need to be rewritten or at least adapted to work with live-edit pages.

What do you think about the early proposals to handle app limitations in Live-Edit Pages listed in this RFC?

Just speaking from our perspective: We’ll have potentially more events to handle, but should be mostly fine. Our users will very likely experience a difference in behavior and it will be interesting to see how they will react.

Are there any other areas, use cases, etc that we are missing?

Never-publish pages definitely break a basic assumption of how Confluence works, which will not just affect Marketplace Apps, but also Automations for Confluence. Users and Admins who work with Automations might not read this RFC or even this community.

11 Likes
5

Hi @DavidMichelson , thanks for the RFC.

At Requirement Yogi, we index part of the content of confluence pages when receiving a page updated/created event, run validations on the content, and create links between pages.
This will massively change things for us, and depending on the frequency of updates, we might have to implement our own debounce for events, and risk showing inaccurate or outdated information compared to the information shown on the page.

  • How will Confluence automation be integrated with this proposed change?
  • Could we restrict the use of macros to a published page, and how do you propose this restriction be communicated with the users?

We will follow very closely.

11 Likes
6

Hi @DavidMichelson:

  1. Can we assume that web-panels associated with atl.general will still work?
  2. Content bylines (contentBylineItems modules) are not mentioned above, although they exist on the view page but not edit. What is the plan for EAP and for GA?

Can I ask why this new work is being implemented on the deprecated V.1 API and not implemented for the V.2 API? The latter has already been in production for a year.

Atlassian has been asking all developers to move to V.2 for a long time (via a series of pushed-back deadlines), yet it seems like Atlassian itself is not moving to V.2 internally.

This seems now like a trend rather than an isolated incident (we’ve seen the same issue with the launch of whiteboards, databases, and now this), so I ask: is there some sort of culture shift or internal messaging that needs to happen within Atlassian to put V.2 first?

8 Likes
7

Hey @DavidMichelson ,

Thanks for bringing this to RFC and for the team evolving Confluence to meet the needs of our mutual customers.

Like everyone else here, I have to flag that this is a massive, breaking change for us/the app vendor community. One that will take both strategic and implementation time to resolve. While I understand and am grateful that you’ve brought this to RFC early, I’m imploring you not to treat the resolve date as the date as a green-light to ship (as is the case with other RFCs). This represents weeks or months of work for us and if shipped will negatively impact customers with our apps from day one (leading to a sub-optimal roll out from Atlassian’s side). Once this gets a little further, we’d really appreciate a roadmap for its roll out so that we can plan accordingly.

I also want to flag that this is not packaged currently as an opportunity for the ecosystem, it’s overhead. This would be a fantastic candidate for a fireside conversation or larger discussion about extensibility (given it fundamentally changes Confluence). I believe that there are ways of us building new extensibility off the back of this that individual comments on this thread will struggle to capture as it will be too focussed on use cases.

Here are a few direct feedback points:

Access to the edit screen is very limited for app vendors pre-change (largely via siloed macros). This puts app vendors who used any of the integration points at a further disadvantage. It would be good to consider how we could extend the new edit/single experience to incorporate some of these. Happy to chat through how we use them (eg for App awareness and onboarding).

WYSIWYG on edit view is not perfect for all scenarios. An example, we have an alert macro in Content Formatting Macros that allows users to flag if content is being worked on or out of date. That macro is a placeholder in edit mode and is triggered in view mode.

I’ll also mention that the side-bar macro editor (which powers the WYSIWYG macro experience) is very restrictive. We extensively use a custom macro editor (as do a lot of app vendors) as it allows us to better present our content experiences (and allows for far better onboarding). This missing from Forge is one of the main reasons we don’t consider it viable.

Custom macro dialogs are anti-WYSIWYG (aligned with convos I’ve had with Atlassian’s previously), if the goal is to get us all to WYSIWYG some work around what is possible with the sidebar editor would be very welcome.

Last point, I worry that this change will further alienate your more technical audience who rely on strict editing and publishing controls (often extended with an app to help reinforce it). How does this work for those that are using their Confluence instance as an external facing documentation side for example?

Always happy to discuss further.

Cheers,
Dylan

6 Likes
8

Hello,
I think this is a good idea, but once more as a vendor I’d really stress that this is a fundamental change and albeit it might not impact our Apps directly it may break a lot of other Apps used by our customers.
In particular Atlassian should make sure this does not affect the permission management, i.e. the current permissions can also lock down the creation and editing of these “drafts”.

Thanks for sharing.

2 Likes
9

Hello @DavidMichelson ,

Just want to strongly second the concerns about this raised by other marketplace partners here in that thread, especially for partners being on Forge. The side panel just does not give enough possibilities, and you cannot edit things in the frame in edit mode, or have a custom configuration editor. So we are providing that possibility on view mode now. I’d personally ask you to not make this general available before you have provided a viable path for this and gathered enough feedback.

Thanks,
Eckhard

2 Likes
10

@Corentin

“Could we restrict the use of macros to a published page, and how do you propose this restriction be communicated with the users?”

For the Early Access Program, users will still be able to insert any macro into a Live-Edit Page. But, if the macro isn’t fully supported in the Editor, they will see a flag that tells them they have to Publish the page to get full functionality. Note as mentioned in the RFC, only a subset of simple Atlassian-built macros will be fully supported in the editor at the time of the EAP.

11

@dlindsay “I’m imploring you not to treat the resolve date as the date as a green-light to ship (as is the case with other RFCs)”

@EckhardMaass “I’d personally ask you to not make this general available before you have provided a viable path for this and gathered enough feedback.”

Completely agreed with both of you. Rest assured that the Resolve date on this RFC is NOT when we plan to make Live-Edit Pages generally available. We will be making sure to give more concrete timelines (i.e. future EAP expansions, closed betas, open betas, etc) alongside how we will be incorporating your feedback along the way.

2 Likes
12

Hey,
Reviewing the above comments and noticing how everyone emphasized the importance of not considering the resolve date as the release date of this feature. Well, it’s getting even worse for us :slight_smile:

We have begun receiving customer bug reports regarding a broken experience when they attempted to use the Live-Edit page in Confluence feature!!

Upon communicating with Atlassian support, here’s what the customer received. Please read it carefully:

Response from Atlassian support:
“The live-edit experience was not an opt-in feature. This improvement is being slowly rolled out to all Confluence users”

The response continues:
“Since the third-party app causes this, we must understand whether they are working on it.”

Since this RFC entails major breaking changes for numerous vendors,

  • Why has this already been released to customers?
  • Shouldn’t this very specific feature be withheld from early access to customers, particularly considering that most of them utilize vendor apps?

Please be mindful of the impact of this significant RFC on the app vendors and our/your customers regarding how and when to ship it.

Thanks,
Ziad Alharash
Refined

14 Likes
13

We are also experiencing issues with confluence cloud since early today in which the custom macro editor for connect apps no longer supports AP.dialog.disableCloseOnSubmit()

Macro editor dialogs are now closed before our .bind() click handler on the submit button is finished (and AP.confluence.saveMacro() is called, so the macro is not saved).

We’re currently not seeing this on all instances, but if this does get rolled out to customers it will have huge impact for end users

14

@ZiadAlharash1

“Why has this already been released to customers?”

To clarify, the live-edit experience is only available to a small set of customers enrolled in the EAP, as mentioned in the RFC. It is not being slowly rolled out to all Confluence users. We will make sure to clarify this with support.

Update: We have learned that some of the confusion around live-edit pages seeming to be released to customers is due to a similar looking feature that has been rolling out, where we make the content sidebar & top navigation available to Confluence users while they edit pages, to give them a better idea of where they are creating & reduce context switching. That feature is separate from this RFC, and is available for both standard published pages and live-edit pages - you can learn more about that separate feature in our community post about it.

“Shouldn’t this very specific feature be withheld from early access to customers, particularly considering that most of them utilize vendor apps?”

This is something we considered, so we definitely understand your concern. But, to test a large change like live-edit, we have to learn via early access to a small set of customers. Similar to the RFC, we have made sure to be very clear with customers that marketplace apps may not be fully supported in the EAP to make sure that those who enroll are fully aware.

2 Likes
15

Hi @DavidMichelson, thanks for the clarification. Was there an RFC for that change?

1 Like
16

I now have access to the Live Edit EAP on my instance.

  • The first thing that puzzled me was that Confluence now shows a warning about potentially unsaved changes when leaving a page, even though everything seems to be saved.
    image

  • The same goes for the warning after inserting a vendor macro. Rendering & saving macros seem to work well (at least for our draw.io and Aura macros), but the editor warns about an unsupported macro:
    image

I consider those warnings as temporary bugs. Still, this feature (and the confusion about what is a Live Edit page and what a Page-With-Navigation-In-Edit-Mode is) concerns me. A significant amount of the Confluence marketplace revenue is generated by providing third-party macros.

I ask Atlassian to provide a clear migration path for vendor macros before such significant changes are rolled out to customers. Please note that more than a sidebar-only macro parameter configuration will be required for many use cases. Imho Atlassian’s new card macros usability already suffers from that sidebar experience.

Wd’d like to get more information on which alternative approaches related to macro editing Atlassian encourages in the long run as soon as they are available.

Will the modal editing be abandoned? We’d need some time to adapt to those significant changes. Is this the reason behind the missing Custom UI for Forge macro?

7 Likes
17

Thank you for starting this RFC in the early stages of testing!

Many concerns have already been pointed out in this thread and I really hope that they are going to be addressed before live-edit pages are leaving the EAP. In its current form, this feature is going to negatively impact lots of apps and users.

Extensibility

Most importantly, the current implementation is taking away all page integration points for Forge apps, making them pretty much unusable.

You mentioned in the original post that you are considering to support a subset of integration points. For us and many others, content byline items are the most important integration point, and we need them on live-edit pages as well.

Macros

Interactive macros on live-edit pages are absolutely necessary. Otherwise, our app is unusable on live-edit pages.

Comments

Some apps are posting footer comments on pages to notify users about certain events, but footer comments are not visible on live-edit pages.

Data loss

The current snapshot/versioning system can lead to data loss when apps are updating pages while they are edited by users because live-edits that haven’t been snapshotted yet are invisible to apps. There is a merge mechanism that attempts to merge updates from the REST API with live-edit content, i.e., the content is not simply overwritten, but I could easily create scenarios in which a content update was lost or merged incorrectly.

5 Likes
18

I agree with @klaussner (and as I mentioned earlier) that content bylines are important here.

The workflow with live-edit pages is weird. As soon as a page is created, it starts out as (and remains) a live-edit page. If someone inadvertently clicks the Publish button, the page suddenly becomes a legacy page where edits need to be saved with the Publish button. This creates two problems:

  1. There is seemingly no way to go back to a “live edit” page if you accidentally made it a published page, nor to convert an existing page to live-edit, and

  2. There are now two completely different workflows for editing pages, which creates significant usability issues. The two types of pages are largely visually indistinguishable. On one set of pages, I just navigate away from the page and the changes are automatically saved. On a separate set of pages, I have to save my changes manually by clicking a button first. (Confusingly, this button is in the same location and the same color as the “Share” button on the live-edit pages, which seems likely to create further confusion.)

And the browser modal saying “you may lose data if you navigate away from this page” is also effectively identical between the two types of pages, even though you can resolve the issue in one case by simply waiting a few seconds, versus clicking a separate button to manually save in the other case (versus trying to wait forever and being disappointed).

6 Likes
19

Hi @DavidMichelson ,
What is unclear to me is how the page status changes. If I understand the description correctly, I understand that the page status changes after reconciliation of the live edit. From a user perspective that seems to be asynchronous.
If so, that is a major usability issue. Many use cases of pages revolve around the page status.

20

Thanks for publishing your ideas on live-edit pages in Confluence Cloud.

  • What do you think about the early proposals to handle app limitations in Live-Edit Pages listed in this RFC?

We have concerns about two areas:

  1. Webhooks. The number of page updated webhooks may increase significantly if you trigger “background snapshot” for live-edit page. This may impact significantly and require changes in our current infrastructure as well as in our apps architecture, as there is a lot we do after page updates.

  2. Macros. Macros are a vital part of our apps, and the described limitations will impact significantly their functionality. With what is currently described, we would need to allocate time for important work to be done to support macros in live-edit page, and this would change our product roadmaps and cause delays in other significant features we want to release for our customer.

  • Are there any other areas, use cases, etc that we are missing?

None that we can think of.

  • What other feedback do you have to make apps and Live-Edit Pages work best together in the future?

We need Live-Edit Pages to support all the functionalities currently provided by “knowledge-based” pages.

Done, and we look forward to exploring Live-Edit Pages in more depth.

3 Likes