guideDocument storage

# Overview

The document storage feature allows you to permanently save the document 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, they are saved permanently in the CKEditor Cloud Services server.

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.

There are two steps that 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”.

If you are interested in using the document storage feature with Collaboration Server On-Premises, you need to login into the Cloud Services Management Panel and you can skip the next step.

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

Your products view in CKEditor Ecosystem customer dashboard.

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

Select the environment that you want to manage.

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

Navigate to the Feature configuration tab and switch on the Document storage feature

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.

Switching this feature off will remove all stored documents for a given environment.

# Usage

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

CKEditor Cloud Services do not keep multiple versions of the document. Only the most recent document version is available.

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

# Document management

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

  • 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.

You can use the above methods if you would like to also have some backups of the documents on your side.

# Example

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

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

# Debugging

If needed, it is possible to store all collaboration data for the 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.