Collaboration data

# Overview

The collaboration session starts when the first user connects to the document. The content is stored for as long as there is at least one user connected to the document. When the last user disconnects, the server will wait for 24 hours and then delete the temporary collaboration data.

One of the steps of integrating CKEditor 5 and Real-Time Collaboration with your application is providing saving the capabilities of the collaboration data to some permanent storage location and initializing the editor with new or saved content. There are several solutions to this. This guide will cover the available scenarios for getting and setting the collaboration data.

# Temporary and permanent data

CKEditor Cloud Services remove the collaboration session data 24 hours after the last user disconnects. This includes any content in the editor that was created by the users. To preserve your content between collaboration sessions, you need to save it on your server or use our Document storage feature.
Only operations performed on the document are stored during collaboration session lifetime. Operation is every update (document history) made during the editing session stored as an object model.

Some of the data is stored permanently. This includes comments, suggestions, revisions, and user data. Thanks to this, comment content, timestamps, suggestion metadata, and user details will be stored between collaboration sessions and the users are not able to modify other users’ data.

When it comes to data removal, document content is permanently removed, while comments and suggestions are only marked as removed (e.g. when removing a comment or accepting a suggestion). The REST API for comments and suggestions also provides two types of removal - soft (the default one) and permanent (requires an explicit flag).

Deleting the environment permanently removes all the data associated with this environment.

# Comments and suggestions

When a user adds a new comment or suggestion, in the editor’s content you will only find a reference to it – two HTML elements marking the start and the end of the suggestion or comment with an additional ID attribute. The rest of the data (the creation time, the user name, the content of the comment, etc.) is not visible in the editor data. In the case of Real-Time Collaboration plugins, the comments or suggestions metadata is sent to the Cloud Services server, where it can be securely stored and shared only with authorized users. Thanks to this approach, users cannot modify other users’ comments and suggestions.

Any comment or suggestion created during the collaboration session is assigned to the document ID, where it was created. You cannot access its data with a different document ID. Similarly, you cannot access comments or suggestions created in a different environment, even if they are from the same organization or are on the same Collaboration Server On-Premises instance.

If you open a document containing comments or suggestions created in a collaboration session with a different documentId or in a different environment, it can result in an editor crash with one of the following errors:

track-changes-user-not-found
Cannot find suggestion abc
Comment thread abc not found

The accepted or rejected suggestions and deleted comments are only marked as removed. This means that they can be restored via the REST API even after the collaboration session ends (24 hours after the last user disconnects). All restored metadata will be kept in the database as well. It is also possible to delete the comments and suggestions permanently using the REST API.

# Comment archive

The comment archive feature requires storing additional data (context, attributes, etc.) of comment threads. Additional comment thread properties can be synchronized via comments REST-API, documents REST-API, or webhooks.

Starting with the v37.0.0 release of CKEditor 5 the comment thread data handling was slightly changed. Accepted comment threads are now treated as resolved and moved to the comment archive. Therefore, instead of commentthread.removed a new webhook called commentthread.resolved is triggered when a comment is moved to the archive.

When residing in an archive, a comment thread can be either:

reopened – in such a case the commentthread.reopened webhook is triggered
removed – in such a case the old commentthread.removed webhook is triggered

Moreover, 2 new webhooks were added:

commentthread.added – triggered when comment thread is added, can contain added comments
commentthread.updated – triggered when the comment thread is updated

# Rest API

You can use Cloud Services REST API for CRUD operations on suggestions and comments. Example use cases of the suggestions and comments CRUD operations:

transferring your existing content into Cloud Services databases,
moving the suggestions or comments data between environments,
moving the suggestions or comments data from one document to another,
adding attributes to the suggestions or comments.
… and more.

Refer to the REST API documentation for more details.

# Webhooks

CKEditor Cloud Services sends an HTTP POST request to a configured URL when specified events are triggered.

You can use comments and suggestions webhooks to:

sync data from CKEditor Cloud Services servers with your databases,
notify users when their comment is removed or gets an answer,
notify users when the state of their suggestions changes,
… and more.

Refer to the Webhooks documentation for more details.

# Data safety

The data stored permanently by CKEditor Cloud Services is encrypted with a key that differs for each environment. Additionally, in most cases, the system uses identifiers instead of the data that originates from the users. CKEditor Cloud Services uses encryption to protect the communication between the user and the server and provides all communication interfaces using HTTPS or WSS protocols.

Refer to the system security section for more details.