Introduction

# Saving the collaboration data

This guide covers four separate methods of reading the content of a collaboration session to save it to some permanent storage using:

The Cloud Services REST API – a server-side solution, where your server can send a request to Cloud Services Collaboration Server to receive the content of the edited document to store it in your database.
Saving data with Webhooks – a server-side solution, where your server receives requests (webhooks) with content of the documents when the collaboration sessions end.
Document Storage – a Cloud Services solution, where the document data is permanently saved in the CKEditor Cloud Services server.
The Autosave plugin – a client-side solution, through which the users periodically send the content of the collaboration session to your server.

# Export using the Cloud Services REST API

This mechanism, based on the REST API, was introduced as an alternative to the autosave plugin. It improves and simplifies the process of synchronizing the data of the document which is saved in your database.

Using this feature, the responsibility for saving the current document data will be transferred from collaborating users to your server. As a result, it is your server that gets the current content of the document from CKEditor Cloud Services.

Please compare the diagram showing the data workflow to notice the differences:

Data handling in the new solution.

The number of requests is largely reduced – there is just one connection present between the CKEditor Cloud Services server and the client’s server. The whole responsibility of serving and storing the content is handled by server-server connection. The collaborator’s only role is content editing.

# The benefits of using the Cloud Services REST API

The user is sure to use the latest version of the document. There is no risk of race condition, data inconsistency or other problems related to document synchronization.
Reduced number of requests to your server. Collaborating users no longer need to send the document data in time intervals.
Increased communication security. The synchronization process takes place only between your server and the CKEditor Cloud Services server using an encrypted SSL connection and request signatures.
The process of saving the document data is independent of the network conditions in which the users work.
The content in the collaboration session can be initialized by the client’s server.
One export operation means only one document content which allows you to save some storage and get rid of minor changes to the document versions.

There are two types of export:

Document export – exports current collaboration session content or document storage content (if present and no current collaboration session exist), and all document-related data like comments and suggestions. Check out the guide for the implementation details.
Collaboration export – exports only current collaboration session content. Check out the guide for the implementation details.

# Saving data with webhooks

This approach is similar to REST API usage, but the main difference is the direction of the requests. With REST API export endpoints you send a request to the Cloud Services server and the server responds with the content of the edited documents. When using webhooks, your server (or serverless functions) waits for the requests from the Cloud Services server instead.

To use the feature, you should enable webhooks in the Customer Portal or in the Cloud Services Management Panel, provide a URL to your server and enable the collaboration.document.exported event. When the collaboration session ends, the request with the document content will be sent to the provided URL. Refer to the webhooks section in the documenation for more details. Also, check other webhook events related to collaboration that can be useful when using webhooks to save document data.

The collaboration session ends 24 hours after the last user disconnects from it. If your application needs to access the document content before the collaboration session expires it is possible to manually remove the collaboration session using a flush method from Cloud Services REST API. This will also trigger a collaboration.document.exported webhook. You could also use the collaboration.user.disconnected webhook event to check if there are no users connected and then trigger the flush to get the data in the collaboration.document.exported webhook. Please, keep in mind that this could impact the UX, when users refresh a page or have some network issues. It is recommended to use debounce or timeout mechanism that will cover brief disconnects from the collaboration sessions.

# Document storage

Cloud Services also offer the document storage feature that allows you to permanently save the document data in CKEditor Cloud Services. In this case, the client-server handling used to store the document data is replaced with Cloud Services server. This is especially convenient for clients that value speed and security. When a user connects to a previously existing document for which a collaboration session has already expired, the document is automatically loaded into a new collaboration session.

# Benefits of the document storage feature

Reduced number of requests to your server. Collaborating users no longer need to send the document data in time intervals.
Your server is completely excluded from the responsibility of saving the document.
The process of saving the document data is independent of the users’ or your server’s network conditions.
No need to check whether a collaborative document session currently exists.
No need to load the current content of the document in case the collaboration session has expired.
No race condition problem when saving the document data.
Documents are saved in an encrypted form.
It is possible to get or delete documents from the storage or get the documents list via the REST API.

Check out the document storage guide for implementation details.

# The autosave plugin

While using the autosave plugin, user data is periodically sent to the client’s server, where it can be handled, validated and stored in the database. See the diagram below for the details of the process.

The workflow of the Autosave plugin.

This method, although the simplest to implement, has its drawbacks:

There is a race condition issue when many users are working on the same document and you need to ensure that you save the most recent version of the document.
The data is coming from an untrusted source (the end-user) and may be manipulated.
When opening previously edited documents, the user needs to fetch the content from the database to use it as the initial data.
It increases the number of requests and the traffic to your server.
It may be slow, especially when a large document is edited by a user with a poor internet connection.

# Ways of initializing the collaboration session with data

The users will not always start from an empty editor and finish the document in one collaboration session. There is hence the need to initialize the editor with the previously saved versions of content or with some generated templates. Similar to getting the collaboration data, there are few ways to start a new collaboration session with your content:

Use the initialData property in the editor configuration – the content passed to this property will be used when the user opens the editor. It will not overwrite the data if the collaboration session already exists.
Use document import from the Cloud Services REST API – your server can initialize the content in the collaboration session with all comments and suggestions with a single API call, and then the users will be able to connect to this collaboration session.
Use collaboration import from the Cloud Services REST API – your server can initialize the content in the collaboration session ( without comments and suggestions) with a single API call, and then the users will be able to connect to this collaboration session.
Use document storage – if you enabled this feature, then opening previously edited documents will be automatically initialized with the saved content.

Refer to the import and export and document storage guides for implementation details.