Summary
Live docs are coming to Confluence Cloud as new content type alongside existing Pages. Live docs can be updated instantly without having to publish, allowing teams to quickly collaborate on content. All sites in the Developer Canary Program have access to Live docs (as of November 2024).
We are asking developers to test their apps in Live docs and make sure that they are functioning as expected by May 30, 2025. See More details to learn more about relevant technical details.
Thank you to so much all of the developers who participated in our many RFC’s for Live docs!
More details
Note that we are also working on including all of the following details in official documentation on developer.atlassian.com where relevant, but wanted to share with developers ahead of time.
Live docs & pages
Live docs are coming to Confluence Cloud as new content type alongside existing Pages. 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.
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.
Key behavior differences between Live docs & pages
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
- Now - We rolled 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). We are giving developers a deadline of May 30, 2025 ahead of GA.
Dates are estimates and are subject to change.
Technical details on supporting Live docs
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).
IN PROGRESS: We are working on the following, and will make sure to update the Changelog as soon as we have updates.
- We will make sure that subtype is supplied via Forge context as well as AP.context.getContext().
- We will also move forward with a Forge 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 |
|---|---|---|
| page_initialized | avi:confluence:initialized:page | Emitted when a new blank Live Doc is created |
| page_started | avi:confluence:started:page | Emitted at the end of the first editing session of a page. The page will have a user generated title and 1 version. |
| page_snapshotted | avi:confluence:snapshotted:page | Emitted at the end of every subsequent editing session. |
| page_published | avi:confluence:published:page | 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.
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)
Your app’s macros will continue to function as expected on Pages, as well.
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. All apps using extension point modules supported in Live docs will automatically appear in Live docs when they are rolled out for general availability (GA), so please make sure to test and (if necessary) update your apps if they are using the below extension points.
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).
CQL
Developers will be able to use CQL to filter for Live docs, using the subtype field which we are indexing.
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 (achieved either by toggling “Editing” off OR by having view-only permissions for 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).
