Administering Collaborative Editing
Collaborative editing takes teamwork to the next level. This page covers everything you need to know about administering collaborative editing.
Head to Collaborative editing to find out how your team can work together in real time on software requirements, meeting notes, retros, and any other Confluence page you can think of.
Collaborative editing is powered by Synchrony which synchronizes data in real time. Confluence manages Synchrony, so administrators should rarely need to interact with it directly.
Synchrony runs on port 8091 by default, and an internal Synchrony proxy means that you shouldn't need to open this additional port.
How you connect to Synchrony will depend on your environment, and your Confluence license. See Possible Confluence and Synchrony Configurations.
To see your collaborative editing and Synchrony setup, head to Administration > General Configuration > Collaborative editing.
Change the editing mode
The editing mode determines the editing experience for all users in your site. This is how you turn collaborative editing on or off.
To change the editing mode:
- Go to Administration > General Configuration > Collaborative editing.
- Choose Change mode.
- Select either On or Off and choose Change.
Changing the editing mode is not trivial, so it is good to understand the implications of each mode.
This mode allows your team to edit a shared draft of a page at the same time, and see each others' changes in real time.
This is the recommended editing mode.
This mode means that your team can only edit their own personal draft of a page. Confluence will attempt to merge any conflicts on save. Consider turning collaborative editing on for the full experience
This mode is useful if you are unable to run Synchrony successfully in your environment, or if you have decided that collaborative editing is not for you (for example if you have auditing requirements that would prohibit using collaborative editing just yet).
It's a good idea to prompt your users to publish any shared drafts before you turn collaborative editing off, as they will not be able to resume editing existing shared drafts or unpublished changes.
What happens to existing drafts when the mode changes?
Users can always access any existing personal drafts and shared drafts from the Drafts page in their profile. Whether they can resume editing the draft depends on the editing mode.
When collaborative editing is ON, users will be able to discard or resume editing any personal or shared drafts. A personal draft will be converted to a shared draft when a user resumes editing.
When collaborative editing is OFF, users will be able to discard or resume editing any personal drafts. They can't resume editing existing shared drafts, but can view and copy the contents of those drafts.
Shared drafts will only appear in a user's Drafts page if, when collaborative editing was on, they:
- created a draft, and never published it
- edited a published page, and did not publish their changes.
Maximum editor limit
A maximum of 12 people can edit a page at the same time. This means that people can't enter the editor if there are already 12 other people editing the page, and will need to wait until someone leaves.
Administrators can increase or decrease this limit using a system property. If you experience performance issues when many people are editing, you might want to decrease this limit.
We know that auditing is a major consideration for some customers. We don't yet have very granular auditing capabilities with collaborative editing. All page changes are currently attributed to the person that publishes the page, rather than the people who made each specific change.
If this is going to be a problem in your site, we recommend turning collaborative editing off in your site for now.
No version history in unpublished drafts
We're saving all the time in collaborative editing, but we don't save versions of unpublished changes. When restoring an earlier page version, you can only roll back to an existing published version. Any unpublished changes will be lost when you restore a previous version.
Visibility of edits made by anonymous users
There are some additional things to be aware of if you have granted the Add page permission (and Can use global permission) to anonymous users.
You won't be alerted, when closing the editor or publishing a page, if anonymous users made the only unpublished changes on the page. This means a logged in user may inadvertently publish changes they were not aware had been made to the page.
The changes themselves are visible in the page, but the usual warning dialog will not appear if the only people to have made changes were not logged in.
If there are unpublished changes from both logged in users and anonymous users, the warning dialog will appear, but only the logged in users will be listed in the dialog. Changes made by all users (including anonymous) will be included if you view the changes from that dialog.
Proxy and SSL considerations
How you connect to Synchrony will depend on your environment. We know that most Confluence sites run behind a reverse proxy, often with SSL. Here's some information to help you identify the right configuration for your environment, and any changes you might need to make to your environment to use collaborative editing in your site.
Synchrony runs in a separate JVM, and does not support direct HTTPS connections. If you are not using a reverse proxy, SSL should be terminated at Tomcat. If you are using a reverse proxy or load balancer, SSL should be terminated at your reverse proxy or load balancer.
See Possible Confluence and Synchrony Configurations for detailed diagrams and examples.
If you run Confluence behind a reverse proxy, you should take a look at the Possible Confluence and Synchrony configurations for guidance on how your Confluence and Synchrony setup may impact your proxy.
See Possible Confluence and Synchrony Configurations for detailed diagrams and examples, plus links to example proxy configuration files.
For best results, your load balancer and proxies should allow WebSocket connections. If your users cannot get a WebSocket connection, Confluence will fall back to an XML HTTP Request (XHR), allowing them to edit pages successfully.
XHR fallback is enabled by default, but can be disabled using a system property (passed to Confluence) if necessary. You shouldn't need to change this.
Change your Synchrony configuration
You can't change your Synchrony configuration through the Confluence UI. In most cases you shouldn't need to make changes to the default configuration.
If you need to change the port Synchrony runs on or the maximum memory available, for example, you can do this using a system property, or in your start-synchrony script (if you're running your own Synchrony cluster).
See Configuring Synchrony for more information.
Start and stop Synchrony
If Synchrony is managed by Confluence (recommended), Confluence will automatically start Synchrony for you when it starts up. You can also restart Synchrony from the collaborative editing admin screen in Confluence.
If you're running Synchrony standalone in a cluster, you'll use the
start-synchrony.bat. scripts on each Synchrony node. A process ID (PID) file will be created in your synchrony directory.
Stop Synchrony the same way, using
stop-synchrony.bat. This will destroy the PID file that the start script created in your Synchrony directory. If you've customized the location for storing the PID file in the
start-synchrony script, you'll need to also update this in the
If you're unable to start Synchrony, check that there isn't an existing PID file in your Synchrony directory.
To check if Synchrony is running, go to Administration > General Configuration > Collaborative editing.
If you're running Confluence in a cluster, you can check the status of Synchrony on each node from the clustering screen.
Go to Administration > General Configuration > Clustering, then on each node choose Collaborative editing. You can access all nodes in this way, you don't need to hit a specific node in your browser.
From here you can see the Synchrony status, mode, and URL Confluence is using to connect to it. Here's what it looks like when Synchrony is managed by Confluence.
All Confluence nodes must use the same Synchrony mode. For example, you can't have one node using managed Synchrony, and another node connecting to a standalone Synchrony cluster.
You can track the connection state between Confluence and Synchrony by using a health check that comes with the ATST plugin 1.53.2 and later. To have the Synchrony connectivity health check available, upgrade the ATST plugin to at least version 1.53.2. Learn more about the health check
Accessing Synchrony logs
If Synchrony is managed by Confluence (recommended), Synchrony logs will be stored in your
<local-home>/logs directory, with the Confluence application logs.
If you're running Synchrony standalone in a cluster, your Synchrony logs will be stored in the Synchrony directory on each Synchrony node (wherever you run the start and stop scripts from).
To learn how to change the logging level, see Configuring Synchrony.
Managing Synchrony data
Each page and blog post has its own Synchrony change log, which contains a graph of all edits to that page or blog post. In busy Confluence sites the database tables that store the Synchrony change logs can grow very quickly. Because the change logs store all changes as they happen, they may retain personally identifiable information, even after the page they relate to has been deleted.
We provide two scheduled jobs for removing Synchrony data:
- Synchrony data eviction (soft)
- Synchrony data eviction (hard).
The soft eviction job runs regularly in the background. The hard eviction job is available for when you need to remove Synchrony data more aggressively, and is disabled by default.
See How to remove Synchrony data for more information on how these jobs work.