RFC-83: Live Docs & Pages in Confluence Cloud

[DavidMichelson]

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!

Project Summary

Live Docs & Pages

What we have long been calling “live pages” now have a new name: Live Docs. Furthermore, we will be rolling out Live Docs as a new content type in addition to the existing Page content type. Pages will continue to start as drafts and need to be published, with subsequent edits needing to be published. Users will have the option to create Live Docs OR Pages. That way, they can create Live Docs when they want to quickly collaborate and Pages when they want to create more authoritative knowledge base content. We are eager to get your feedback on this direction.

NB: To end users, Live Docs & Pages will appear as two different content types. But, in their underlying API representation, Live Docs & Pages are both still Pages, differentiated by a subtype - more details below.

• Publish: Feb 4 2025
• Discuss: Feb 18 2025
• Resolve: Mar 4 2025

Problem

Customers want to be able to create Live Docs OR Pages. That way, customers can create Live Docs when they want to quickly collaborate and Pages when they want to create more authoritative knowledge base content.

Proposed Solution

Here are some highlights of how the experience of Live Docs differs from Pages. We will also provide more technical details under “Impact to apps” below.

• When visited, Live Docs are editable without any extra clicks, displaying edits in realtime. Users with view-only permissions cannot edit, but can still see others’ realtime edits.
• When created, Live Docs do not start as drafts. They 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.
• Users can toggle from “Editing” and “Viewing” a Live Doc, if they want to view a Doc in a view-only state to review it and avoid accidental edits.
• Live Docs will still maintain version history, but each version will be the result of automatic “snapshots” taken after each unique edit session.
• Live Docs can be converted into Pages (then, further edits will need to be published), and Pages (both unpublished drafts and published Pages) can be converted into Live Docs.
• Just like Whiteboards or Databases can be turned off in a space (making it so no new Whiteboards or Databases can be created in that space), Live Docs can also be turned off in a space (making it so no new Live Docs can be created in that space).

Timelines / Rollout Plan

• Late February 2025 - We’ll be rolling out Live Docs as a new content type to customers that are already enrolled in our EAP as well as sites in the Developer Canary Program for developers to test. All EAP customers are aware that some apps may not be fully functional yet in Live Docs.
• Early April 2025 - We’ll allow 100% of customers to opt in to a Live Docs Open Beta. These customers will also be aware that some apps may not be fully functional yet in Live Docs.
• Later in 2025 - We’ll start gradually rolling out Live Docs to all customers (GA / General Availability).

Dates are estimates and are subject to change.

Impact to apps

API’s

Live Docs will be available through REST API V2. Developers will be able to Create or Filter Live Docs using the existing Pages API itself. This will enable developers to leverage the existing infrastructure and their learning to work Page APIs to develop Live Docs .

In order to get the REST API V2 support for Live Docs ensure Live Doc feature is enabled for your tenant.

Create Live Doc with API

• To create a Live Doc, use the field "subtype" : "live" in the request body for Page Create endpoint.
• The existing behavior for creating a Page will stay as it is i.e for creating a Page no subtype field is necessary.

Identify a Live Doc from response

• The Page API response for Live Docs will contain an exclusive field called subtype with value live.
• This subtype field will not be present for pages.

Filter Live Docs on bulk fetch

• Bulk Get pages by default will return both Pages and Live Docs. The endpoint will support an additional query parameter subtype which can be specified as page for Pages and live for Live Docs.

/pages?subtype=live -> Get Live Docs Only
/pages?subtype=page -> Get Pages only
/pages               -> Get both(Live Docs and Pages)

Timing: The above API changes are now available for all tenants in the EAP & the Developer Canary Program. They will continue to be made available to all tenants in future rollout phases (Open Beta, GA).

Under consideration: We would love to hear your feedback around some other API-related changes we are considering making.

• Making subtype available in the Forge context, allowing Forge apps to determine whether a document is a Page or Live Doc without a REST call.
• Adding a client-side API to get the latest editor content & update it, to allow apps to make instant changes to Live Doc content.

Connect Webhooks / Forge Events

Connect Webhooks & Forge Events for Live Docs

Connect Webhook Key	Forge Event	Description
avi:confluence:initialized:page	page_initialized	Emitted when a new blank Live Doc is created
avi:confluence:started:page	page_started	Emitted at the end of the first editing session of a page. The page will have a user generated title and 1 version.
avi:confluence:snapshotted:page	page_snapshotted	Emitted at the end of every subsequent editing session.
avi:confluence:published:page	page_published	Emitted when a Live Doc is converted to a Page (and is therefore published).

Connect Webhooks & Forge Events common to both Pages and Live Docs

Events such as avi:confluence:moved:page or page_moved, which apply to both pages and live docs, will have a subtype=live field added in their payload if emitted by a Live Doc. Developers can use this if they need to filter for only Live Docs or only Pages. At this time, only Live Docs events are guaranteed to have a subtype field in the events. Page events are not guaranteed have a subtype.

Timing: We plan to make the above webhook & event changes available by late February 2025.

Under consideration: We are also considering adding an event for when a Page is converted back into a Live Doc. We would love to hear your feedback whether an event like that would be needed.

Macros

Since macros live within the editing experience that is shared across Pages and Live Docs, your app’s macros will automatically be available in Live Docs. Over the past few months, we’ve rolled out changes that make macros fully supported in Live Docs:

• Macros can both be interacted and configured in Live Docs (Changelog)
• Users can access both the “display” and “editing” state of bodied macros in Live Docs (Changelog)
• Apps will be able to detect whether they’re on a live page via REST API (above)

Your app’s macros will continue to function as expected on Pages, as well.

Timing: Macros will automatically be available in Live Docs for all customer cohorts (EAP, Open Beta, GA).

We understand that some macros display “placeholder” content while editing, as they are not primarily used to display content but to mark parts of a page to behave a certain way when published or exported. For example, Atlassian’s native Anchor macro used to display placeholder content when inserted while editing that did not appear when published.

Since Live Docs are most often consumed in the editing state, we recommend that you update your macro UX to always display a consumable state while editing. For example, we made the Anchor macro UX more consumable and feel like “it belongs”

Extension Point Modules

Live Docs already support the below extension points (shared with Pages). We do not have plans to support other extension points at this time. Sites in today’s customer EAP & the Developer Canary Program have these extension points in Live Docs today, and future Open Beta sites will as well, so developers can more easily test & update their apps as needed for Live Docs. Customers in these cohorts are made aware that apps may not be fully functional yet in Live Docs.

Extension points supported in Live Docs:

• Forge
  • confluence:contentBylineItem
  • confluence:contentAction
  • confluence:contextMenu
• Connect
  • contentBylineItem
  • system.content.action
  • system.content.action/primary
  • system.content.action/secondary
  • system.content.action/modify
  • system.content.action/marker
  • page.view.selection/action-panel
  • atl.general
  • atl.footer (for running background scripts).

However, when we start gradually rolling out Live Docs to General Availability (GA), apps using these extension points will not automatically appear in Live Docs. That way, developers can have control over testing & updating their apps as needed in Live Docs before they GA to all customers. Note that this does not apply to atl.general or atl.footer as they are designed to persist throughout Confluence.

To make your apps using any of these extension points appear in Live Docs, our proposal is that developers will have to proactively opt in by adding a new optional showsInLiveDocs (or some similar name) property to its corresponding Connect module or Forge module and set it to true. Note that, if your app previously had a major version on Forge or Connect, the update to opt in to Live Docs will only reflect for customers on the latest version. By default, showsInLiveDocs will be set to false for all modules, unless developers proactively set it to true.

6 months after GA’ing Live Docs, we plan to change the default value of the showsInLiveDocs property to true, meaning if the property showsInLiveDocs is not explicitly set, it will update to true, making those modules appear in Live Docs. So, we recommend that developers of affected apps ensure their apps function well in Live Docs by then to avoid having their customers run into issues.

Under consideration: Alternatively, we are also considering making showsInLiveDocs a new top-level field in the Forge manifest or Connect app descriptor, making it a setting at the overall app level instead of at the module level. We are eager to get your feedback on which direction to take, and feedback in general on our proposed approach!

Timing: As mentioned above, once we GA Live Docs (timing still TBD, later in 2025), apps using Live Doc supported extension points will no longer automatically appear in Live Docs, giving developers time to make sure their apps are supported & opt in when ready. 6 months after GA begins, all apps using Live Doc supported extension points will again appear in Live Docs, meaning developers should make sure their apps are well supported in Live Docs by then.

CQL

Developers will be able to use CQL to filter for Live Docs, using the subtype field which we are indexing.

Timing: We plan to support Live Docs in CQL by late February 2025.

Version Changes in Live Docs

A new version is created immediately once a user makes changes. As the user makes changes, the latest version itself will continually be updated, until the editing session ends and the version is finalized (15 minutes after the editing session ends).

Live Doc & Page States

We recommend ensuring that your app functions well across all states that Live Docs and Pages can be experienced in:

• Editing a Live Doc
• Viewing a Live Doc
• Editing a Page
• Viewing a rendered Page

Also continue to consider permissions scenarios around who can edit / view Live Docs, these continue to exist in Live Docs (e.g. a user may have view-only permission of a Live Doc).

Asks

• We are eager to hear your feedback on all outlined above!
• Once we release Live Docs in late February to EAP customers & sites in the Developer Canary Program, please start testing and updating your apps, and continue to give us feedback.
  • Note that Live Docs are already available in an “older” version (than what we’ll release in late February) on sites in the Developer Canary Program today (see details here Live pages are available for testing on sites in the Developer Canary Program). Feel free to play with Live Docs on those sites to get a feel for them, but keep in mind that the above changes are on the way.

[marc]

Hi @DavidMichelson ,
Thank you for using the feedback and writing a new RFC!
I think the differentiation between Live Docs and Pages is very important. This reduces confusion for users.

One thing I thin is missing: When a static content macro is used, it seems no new renders are triggered when editing Live Docs. Are you planning to add this? Static content macros are rendered by Confluence, and we as app developer can’t have any js in a static content macro and so can’t listen to any change event.

[shushen]

How about the content search endpoint? Does CQL get the support to differentiate Live Docs from Pages by the subtype?

[Corentin]

Adding a client-side API to get the latest editor content & update it, to allow apps to make instant changes to Live Doc content.

That’s very interesting to hear. However for our plugin (managing requirements in Confluence), the nature of the live-edit document will probably clash with the fact that requirement documents are usually intended to be pretty static. We would love to have something similar to help users create content in regular pages as well !

Since Live Docs are most often consumed in the editing state, we recommend that you update your macro UX to always display a consumable state while editing. For example, we made the Anchor macro UX more consumable and feel like “it belongs”

Would it be possible to add an indication when rendering a static macro that the page is displayed in “live mode”.
We already have the output.type parameter configured in our Connect app:
"url": "/macro/requirements-configuration?render={output.type}", and having a way to distinguish between modes would be helpful.

[MattiaLomazzo]

Hello David, Thank you for sharing this announcement.
Regarding the webhooks key/Forge event. It is currently possible to convert a page to live editing. Will there also be a webhook key and forge event for this case?

[JackGraves]

I feel like the distinction between Live Docs and Pages will be lost on users. At the end of the day, under-the-hood it’s just a page that auto-publishes after a period of inactivity instead of requiring a manual publish and shows the current draft . The functional difference is tiny, yet now we have another “page” type - with all the added complexity that brings.

Creating a separate content type seems like it will add more confusion than clarity, especially since both are fundamentally the same under the hood. It’s a wiki - why on earth do we need two different types of pages? Does any piece of wiki software you know have two types of pages? No, because it’s confusing!

Instead of enhancing the existing page experience, you’re planning introducing two separate options, each with its own webhooks, APIs, and other overhead. Now users have to decide which one to use, admins have more settings to manage, and, of course, developers get another API headache.

TL;DR: Splitting them into two options seems like unnecessary complexity without enough added value.

[marc]

This is a great idea, we’d like to see support for output.type also.

[scott.dudley]

Hi Atlassian,

Will the subtype be supplied via AP.context.getContext() (or is it already)?

The idea of this transitory showsInLiveDocs parameter is weird. I understand the intent of not breaking things for existing software, but at least in two cases (atl.general and atl.footer), these plugin points were explicitly created with the intent that they work across all types of pages of a site. Changing this definition now to “these plugin points show across all pages of a site, except this one specific type, but only for six months” is odd.

Requiring descriptor updates for a short-term transition period is also not ideal. Vendors have existing customers who are blocked on old descriptor versions (with no realistic possibility of upgrade), so in some cases, updating the descriptor is impossible and the app will be broken for this six month period.

I suggest that “default-off followed by default-on” is not ideal behavior: this feature has been in beta and available to vendors in EAP for months, so we have already effectively had a deprecation period, and those who need to make changes to make their app compatible have presumably had time to do so.

The number of apps that are not compatible are probably in the minority, so changing this policy to “default-on” seems like it would impose the least burden on vendors, and also impact a smaller number of customers, including those who are blocked on version upgrades.

[DavidMichelson]

Thanks your your feedback Scott! Good clarification re: atl.general and atl.footer. Within the paradigm of having a showsInLiveDocs parameter, those should appear no matter what the state of showsInLiveDocs is, with the rationale that you provided (they’re expicitly created to work across all pages).

[DavidMichelson]

Hi @marc - To clarify, are you saying that today a static content macro will only render on page load (then, it will not re-render while a user is editing a Live Doc), and you would like a way to re-render while editing a Live Doc (w/o a refresh)?

Could you tell us more about the use case you’d like to enable?

[DavidMichelson]

@Corentin Thank you for your feedback! Could you tell us more about the use case you’re thinking about here?

Would it be possible to add an indication when rendering a static macro that the page is displayed in “live mode”.
We already have the output.type parameter configured in our Connect app:
"url": "/macro/requirements-configuration?render={output.type}", and having a way to distinguish between modes would be helpful.

@marc as well!

[DavidMichelson]

@MattiaLomazzo In the RFC we mentioned that we are considering a webhook key / event for when a Page is converted into a Live Doc. At the moment we haven’t yet identified critical use cases for it though.

Could you tell us more about why that would be interesting to you?

[marc]

Hi @DavidMichelson

@DavidMichelson

To clarify, are you saying that today a static content macro will only render on page load (then, it will not re-render while a user is editing a Live Doc), and you would like a way to re-render while editing a Live Doc (w/o a refresh)?

Could you tell us more about the use case you’d like to enable?

For example we have a static content macro which displays the last edit time. In normal pages, on page render we fetch the last edit time from the api, and render the time as a string into the page.
In live edit pages, a user would expect that the last edit time changes after an edit. That means we must re-render our macro, and for that to happen there must be a “page /macro” reload.
We also have other static content macros, which allows you to sign a page. Obviously the signature is only valid if the page is not edited afterwards. So if a signed page is a live doc, we need to detect if there were changes made after adding the signature, and we need to say something like “older version signed”
Hope this helps to explain our use cases.

[marc]

Hi @DavidMichelson ,

@DavidMichelson

Would it be possible to add an indication when rendering a static macro that the page is displayed in “live mode”.
We already have the output.type parameter configured in our Connect app:
"url": "/macro/requirements-configuration?render={output.type}", and having a way to distinguish between modes would be helpful.

I believe for a static content macro, the output.type is the only real way to determine it is on a live doc. If we can determine we are on a live doc, we can e.g. show a visual element to our users making it clear to them that the status our macro shows is not the same as the status of a published page.
For example for our signature macro, we would like recommend people to publish the page before signing. Otherwise subsequent edits of the automatic live doc version increment will change the validity of the signatures.

[MattiaLomazzo]

Hello @DavidMichelson, thank you for getting back to me.
Our Connect app for the usage analysis for Confluence offers, among other things, the possibility to filter the reports based on content type. For various reasons, we currently store the content type of the tracked content with us. It would therefore be important that we are notified of all the contents’ type changes.

[GaborDicsoMidori]

Hi All,

I played around a bit with the Live Docs feature to see how Forge events are sent to the webhook defined in our app. Here’s what I don’t understand:

#1
This is the list of the event types in this RFC, which I added to the app manifest:

avi:confluence:initialized:page
avi:confluence:started:page
avi:confluence:snapshotted:page
avi:confluence:published:page

However, I was only able to actually see the below ones in the app log (these are the same 2 event types listed at https://developer.atlassian.com/cloud/confluence/changelog/#CHANGE-2122 in the changelog):

avi:confluence:started:page
avi:confluence:snapshotted:page

#2
I find the below series of events slightly confusing (sent over a period of about an hour while creating and updating a live doc, then converting it to a page, back to a live doc, and again to a page):

avi:confluence:viewed:page (arrived instantly)
avi:confluence:started:page (arrived with 10m delay)
avi:confluence:snapshotted:page (arrived with 10m delay)
avi:confluence:created:page (arrived instantly)
avi:confluence:snapshotted:page (arrived with 10m delay)
avi:confluence:updated:page (arrived instantly)

As you can see, there is no initialized event, the first event in the series is a viewed event, before started arrives with a 10-minute delay. Furthermore, when the page is published, we receive no published event, only a created event, even though the page has been created and updated much earlier as a Live Doc, with events sent for those updates. (Subsequently converting the page back to Live Doc and then publishing it again results in an updated event being sent, which makes more sense, though it is not really an update.)

I would expect the initialized event to be sent immediately upon creating the doc (or at least the started event should not be delayed), and then a published event and no created (or even updated) event when publishing it.

#3
When creating a new page in my test instance, I did not see the separate “Live Doc” option when selecting the content type. I turned Live Docs off and on again in my instance, but it did not change anything.

I find #2 most confusing, with created sent more than 30 minutes after creating and updating the page.

Is this the expected behaviour?

[lwonnacott]

Hey all!

Thanks for letting us test this! I’ve noticed a couple of issues with bodied macros that are blocking us from fully supporting Live Docs

The first is that there is a slight delay between editing content within the bodied macro, selecting “Done Editing,” and the content of the page updating. This leads to our bodied macros rendering before the content of the page is fully saved.

We use a multi-macro model for our tabs, meaning the first tab in the group collects the content of the other tabs and renders them all together. The other tabs then resize to be as small as possible on the page.

In a scenario where a user adds multiple tabs to a page, selects “Done Editing” on the first tab (which triggers the rendering of the entire tab group), then edits the content of the second tab and clicks “Done Editing” there, the first tab has no way of detecting the change and updating its content accordingly.

From this, I have a couple of requests:

• Would it be possible for us to listen for the “Done Editing” event?
• Would it be possible to minimise the size of the container once the user has finished editing the content of the bodied macro? (This would be useful for our multi-macro model, where only the first macro of the group renders the content, and the other macros remain hidden)

Thanks again

[DavidMichelson]

@shushen

Yes! Developers will be able to use CQL to filter for Live Docs, using the subType field which we are indexing. We also estimate this to be ready by late February rollout. Will add to the body of the RFC.

[DavidMichelson]

@GaborDicsoMidori Thank you so much for diving deep and testing already!

What you are experiencing is expected - for now. We have not yet made the events or the separate “Live Doc” option listed in the RFC available - we are working on them now (gathering feedback from developers in parallel) and are targeting late February to make them available.

When things are ready, we will make sure to communicate again that they are!

In the RFC, you can see these estimated rollout timings wherever it says " Timing :"

[DavidMichelson]

Hi @lwonnacott Thank you so much for your bodied macro feedback. I have sent you a message separately to try and better understand how you would utilize these feature requests to fulfill your use cases!