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.

About Synchrony

Collaborative editing is powered by Synchrony which synchronises data in real time. Synchrony is executed as a separate process by Confluence and managed by Confluence automatically. Under normal circumstances it should not need to be managed manually by an administrator. 

To check if Synchrony is running, go to  > General Configuration > Collaborative editing

Here you can check your Synchrony status and current configuration, including current port, database driver and maximum heap size allocated to Synchrony. This information can be useful if you need to troubleshoot Synchrony problems.  

Synchrony runs on port 8091 by default, and an internal Synchrony proxy means that you shouldn't need to open this additional port.

On this page:

Related pages:


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:

  1. Go to  > General Configuration > Collaborative editing
  2. Choose Change mode.
  3. Select a mode and choose Change

Changing the editing mode is not trivial, and some changes can result in the loss of your users' drafts, so it is good to understand the implications of each mode. 

The following modes are available:

Mode Implications
On

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 the recommended editing mode.

Limited

This mode protects your users' shared drafts if you need to troubleshoot Synchrony. You would only switch to this mode if your users are experiencing problems editing and publishing.

The editing experience will be very limited for your users:

  • Only one person can edit a shared draft at one time.
  • You can't revert to an earlier version of the page in the page history.
  • You can't move pages.
  • You can't make inline comments on pages.

As soon as Synchrony is running again, we recommend turning collaborative editing back on.

Off

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. This mode replicates the Confluence 5 editing 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).

All existing shared drafts are lost when you switch to this mode, so make sure your users have published any work they want to keep before you make the change.

Auditing considerations

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 the only unpublished changes on the page were made by anonymous users.  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. 

Unpublished drafts are not included in space or site exports

The content of any unpublished shared drafts are not included when you export a space or site to XML.  This is particularly important to know if you use an XML site backup as part of your backup strategy. See Production Backup Strategy for our recommendations, which do not rely on the XML export. 

If you do need to do a space or site export, you should ask your users to publish any work they want to keep before you begin the export. 

Change your Synchrony configuration

You can't change your Synchrony configuration through the Confluence UI. Configuration changes are made via system properties. In most cases you will not need to make changes to the default configuration.  

 

  Change the port Synchrony runs on...

Synchrony runs on port 8091 by default. If this port is already in use by another application on your server you can use the the synchrony.port system property to change it to an available port.  

If you're Confluence 6.0.3 or earlier you'll need to use reza.port instead of synchrony.port.

See Configuring System Properties to find out how to change this. 

For Confluence Data Center the way you run Synchrony is a little different. See Configuring Synchrony for Data Center for more information.

  To change the maximum heap for Synchrony

Synchrony has a maximum heap size of 1 GB by default.

If you experience out of memory errors related to Synchrony, you can change the heap size allocated to Synchrony using the synchrony.memory.max system property.

If you're Confluence 6.0.3 or earlier you'll need to use reza.memory.max instead of synchrony.memory.max.

See Configuring System Properties to find out how to change this.  

For Confluence Data Center the way you run Synchrony is a little different. See Configuring Synchrony for Data Center for more information.

 
See Recognized System Properties for the full list of Synchrony system properties. 

If you need to pass additional arguments to Synchrony's JVM directly, create a file called synchrony-args.properties in the Confluence home directory and include the arguments you want to pass to Synchrony, one per line, as follows.

property1=value1
property2=value2

This will add -Dproperty1=value1 -Dproperty2=value2  to the Synchrony command.  This is only available in Confluence 6.0.2 and later. 

You can't use this method for passing any value that is already handled by a system property, such port, Xmx or Xss etc. See Configuring System Properties for a full list of system properties. 

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. 

SSL

Synchrony runs in a seperate 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. 

Proxies

In the diagrams below we've used a common implementation where Confluence is running under the /confluence context path (e.g. www.mysite.com/confluence). The concepts are the same if you use Confluence without a context path (e.g. www.myconfluence.com). 

No reverse proxy 

If you don't run Confluence behind a reverse proxy, you'll connect to Synchrony via Confluence's internal Synchrony proxy. SSL, if used, is terminated at Tomcat.  This is the default configuration, and you shouldn't need to make any additional changes to use collaborative editing. 

With a reverse proxy 

If you run Confluence behind a reverse proxy, you will connect to Synchrony via Confluence's internal Synchrony proxy. This is the default configuration with a reverse proxy, and a good choice if you do not want to open port 8091. SSL should be terminated at your reverse proxy.

You do not need to make any additional changes to your reverse proxy configuration for Synchrony, but for best results your reverse proxy must support WebSocket connections (you may need to manually enable this in your proxy).   

To tell Confluence that you want to use the internal proxy, set the synchrony.proxy.enabled system property to true. (This is optional, but will prevent Confluence from trying to reach Synchrony via /synchrony first, before retrying via the internal proxy). 

 

If Synchrony can't be reached via /synchrony-proxy we'll automatically try /confluence/synchrony-proxy (where /confluence is your Confluence context path). 

Direct to Synchrony with a reverse proxy 

If you run Confluence behind a reverse proxy, and experience latency or other issues connecting to Synchrony via Confluence's internal Synchrony proxy, you can choose to connect direct to Synchrony. This is the optimal setup, but does require some changes to your environment. You will need to open port 8091 and add /synchrony to your reverse proxy configuration. SSL will still be terminated at your reverse proxy, as Synchrony does not accept direct HTTPS connections. 

If Synchrony can't be reached via /synchrony we'll automatically try the internal Synchrony proxy via /confluence/synchrony-proxy (where /confluence is your Confluence context path). 

See the following guides for example reverse proxy configurations. The order of directives is important, so check our examples.  

XHR fallback

When a user cannot connect to Confluence via a WebSocket, we'll fall back to a XML HTTP Request (XHR), allowing them to edit pages successfully. For the best editing experience, we strongly recommend that your environment allows WebSocket connections however. 

XHR fallback is enabled by default, but can be disabled using a system property if necessary. You shouldn't need to change this. 

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport