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.

# Recovery snapshots

When an editing session ends, a Collaboration snapshot is created. It includes all the necessary data for debugging and retrieval of the document when required. Snapshots data is encrypted. Snapshots and related data will be permanently removed after 30 days.

# Use cases

The collaboration snapshots feature can be helpful when solving hard to reproduce cases related to documents.
For example:

• When data is stored on the user’s side relying on webhooks. When issue occurs with webhook delivery the data might be potentially lost.
• Issues related to the use of erroneous editor bundle.
• Issues related to operation corrupting the document.
• Other cases introducing irreversible changes to the document.

# Recovery steps

In order to debug and/or retrieve document, the CKEditor team needs you to provide a zip containing these 3 files:

• The document snapshot .json
• The editorBundle
• The config

To retrieve your document’s snapshot follow these steps:

1. Get a list of snapshots existing for the selected document. Use REST API GET metadata endpoint.
2. Use selected snapshot’s metadata to retrieve it and save it as .json. Use REST API GET snapshots endpoint.
3. Send editorBundle, config and snapshot to our team.

When the CKEditor team retrieves operations from your document you will receive a file with your document’s content in HTML. Use the retrieved data to create new editing session by sending request to this REST API endpoint.

This feature is in Beta phase and it will be extended in the future. If you have any feedback feel free to contact us.

# 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 editing 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 editing 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 editing 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.