Document storage

# Overview

The document storage feature allows you to permanently save the collaboration data in the CKEditor Cloud Services. When enabled, the documents are no longer stored temporarily just for the duration of the document session lifetime. Instead, the collaboration session data is saved permanently in the CKEditor Cloud Services server.

Data saved in the document storage consists of the following:

• content - it is the full content of the edited document. It’s the equivalent of the results of calling editor.getData()
• operations - it is every document update (document history) made during the editing session stored as an object model. The operations are stored in the compressed state.
• version - the current version of the document. The version is determined based on the number of distinct operations performed.

When a user connects to a previously existing document for which the collaboration session has already expired, a new collaboration session will be initialized using the content stored in the document storage.

Your server is completely excluded from the responsibility of saving the document. You do not have to write any additional logic for getting the collaboration data, saving it in your database, and initializing the document with the previously saved data. These actions will be handled automatically by CKEditor Cloud Services.

# Prerequisites

To use the document storage feature, an editor with its configuration needs to be uploaded to the CKEditor Cloud Services server. Cloud Services is using your editor to generate the correct output data before saving and to initialize the collaboration session with previously stored data. Thanks to this approach, your custom plugins that could generate some custom data will also work correctly.

Two steps need to be taken before you can start using the feature:

1. Upload your editor bundle with the editor configuration to the CKEditor Cloud Services server. Refer to the Editor bundle guide for more information.
2. Set the required bundleVersion property in the editor configuration. Refer to the Editor configuration section of the editor bundle documentation for more details.

# Enabling the document storage feature

Follow the steps below to set up the document storage feature.

1. Log in to the CKEditor Ecosystem dashboard and navigate to “Your products > Cloud Services”.

2. From the list of available subscriptions in the dashboard choose the subscription that you want to manage and click the “Manage” link.

3. Select the environment where you want to enable the document storage feature. Create one if needed with the “Create new environment” button.

4. Navigate to the “Feature configuration” tab and switch on the feature in the “Storage > Document storage” section.

Remember that the document storage feature only works in the environment it was turned on for. If you use many environments, you need to enable the feature separately for each of these.

# Usage

# Initiating the collaboration session

With the document storage enabled the sessions will be automatically created using the data stored in the CKEditor Collaboration Server databases. There are no additional actions required and initializing the editor with a channelId value will load the stored content.

The process for initializing the collaboration session is as follows:

1. A user wants to open a document with a given channelId and the editor starts to initialize.
2. The CKEditor Collaboration Server checks if the content was already stored in the document storage.
3. Editor initializes with the data of the stored document.

# Saving the document

After uploading the editor bundle and enabling the feature, the encrypted collaboration data will be saved automatically to the CKEditor Cloud Services database. There are several cases triggering the document save action:

• an operation in the document made by any of the users (once every 5 minutes),
• 1000 operations to the document made by the users,
• the last user disconnects from the collaboration session,
• a new document is created (either by the user or when a document is imported using the REST API),
• a collaboration session is flushed using the REST API.

It is possible to trigger the document save action manually by using REST API.

You can also import the document synchronously to the storage through REST API for as long as there is no active collaboration session with the same ID.

# Document storage webhooks

You can receive information about the processing of your document in the document storage in the form of webhook events. Refer to the document storage events section for more details.

The document storage webhooks can be very useful when setting up the document storage. You can quickly verify that the documents are properly saved and there are no issues during this process.

Some use cases could require having a copy of the content in your application. To sync the content between the CKEditor Collaboration server and your application, you can use the storage.document.saved webhook to receive a signal that a newer version of the document is available. This can trigger a REST API request to fetch the content from the CKEditor Collaboration Server and then store it in your database.

The recommended flow for keeping the documents in sync is as follows:

1. A user action or a REST API request triggers document storage saving.
2. The document content is saved in the CKEditor Collaboration Server databases.
3. The CKEditor Collaboration Server emits the storage.document.saved webhook, which includes the channelId property.
4. Once you receive the webhook, send a GET /storage/{document_id} request.
5. Store the content of the document in your database.

# Document management

You can manage stored documents using the methods available from the REST API. The document storage methods available are:

• POST /storage – imports the content of a document to the storage. It can be either HTML content or a stringified JSON structure for documents created by a multi-root editor. In the latter case, the keys are the root names and the values are the HTML content for a particular root.
• GET /storage/{document_id} – gets the content of a single document saved in the storage. It can be either HTML content or a stringified JSON structure for documents created by a multi-root editor. In the latter case, the keys are the root names and the values are the HTML content for a particular root.
• GET /storage – gets the list of the document IDs that are saved in the storage.
• DELETE /storage/{document_id} – deletes a single document from the storage.

# Example

Check an example of an application that uses the document storage feature in Node.js and Express.js.

Also, you can check the CKEditor Cloud Services samples repository, where you can find more examples.

# Debugging

If needed, it is possible to store all collaboration data for debugging purposes. Thanks to this, our customer support team will be able to check the errors related to the document storage feature. Please enable this option only when you are asked to do so by our customer support team.