CKEditor Ecosystem Documentation
Search
Home/Cloud Services/Getting started

Migrating to Real-time Collaboration

# Overview

This article aims to explain the prerequisites and process of migrating Non Real-time Collaboration Features to the Real-time version. Thanks to this, your documents will be able to be edited simultaneously by many users. Your application will also be excluded from the responsibility of processing and synchronizing the data.

# Differences between Real-time and non Real-time Collaboration

In non Real-time Collaboration you have to implement adapters for each object that would process the data from the editor. A server application has to be implemented as well to store and synchronize the data:

In Real-time Collaboration all the logic required for synchronising and saving the data is handled by the CKEditor5 Real-time Collaborative plugins and the CKEditor Cloud Services.

To learn more about the difference between asynchronous and Real-time collaboration see here.

# Prerequisites

In order to take full advantage of Real-time Collaboration Features you will need:

  1. Active CKEditor Cloud Services subscription.
  2. A Real-time Collaboration editor build integrated with CKEditor Cloud Services
  3. A token endpoint prepared. It is required to authenticate users connected to the Real-time Collaborative Editing Sessions.

# Migrating your data to the Real-time Collaboration

The migration process can be summarized in these steps:

  1. For each separate editor build you were using prepare a separate editor bundle with RTC features.
  2. Get data for each document and each user you want to migrate to the Real-time Collaboration from your server
  3. Map the data according to the CKEditor Cloud Services requirements and upload it using the REST API. Please note that all requests to the CKEditor Cloud Services REST API require authentication.

# Uploading editor bundle

To take full advantage of the Real-time Collaboration an editor bundle has to be uploaded to the server. For each editor build you were using in the asynchronous collaboration a respective bundle would have to be created.
Since in Real-time Collaboration your server is excluded from the responsibility of synchronizing the data, the build does not have to include adapters for each resource (comments, track changes, etc.). To ensure data consistency, the bundled editor should include every other plugin that was used in the non-RTC editor.

You can learn more about preparing and uploading an editor bundle in our dedicated guideline

# Migrating user data

The real-time collaborative editing plugin will define user data and permissions automatically based on your token data. If you want to migrate the user data manually your server would also have to store the user data and it would also have to be prepared at this step.
For each user you want to migrate call the REST API endpoint POST /users

# Migrating document data

To be able to collaborate in real-time on a given document its data would have to be migrated to the CKEditor Cloud Services. In order to do so, you need to get the data from your server application for each resource present on the document and map each field according to the requirements specified in the REST API endpoint POST /documents and call it. After a successful response from the server, you can start collaborating on the document in Real-time and let the CKEditor Cloud Services handle the rest.

For Real-time Collaboration to work properly some fields not present in the non-RTC collaboration are required:

  1. suggestion.author_id – Each suggestion in Real-time Collaboration should be linked with a user that requested it. In Real-time Collaboration this value is set automatically. If you don’t save information about who posted the suggestion on your server, you can either set some anonymous user as the suggestion author or create a user using Users REST API and then assign it as the author of every suggestion from the non-RTC collaboration.
  2. content.version – Each document has its version set based on the operations performed. This value is required to import revisions to the Real-time Collaboration. If you want to migrate document with revisions you can set this value as the highest toVersion value from migrated revisions.
  3. comment.type – This field is used by the CKEditor Cloud Services to determine whether a given comment is placed under the suggestion or another comment. The type for a regular comment is 1 and for the suggestion comments it’s 2
    If you don’t store such information you can determine it by trying to find a matching suggestion by comparing its ID with the ID of a given comment thread. If for a given comment thread a matching suggestion would be found, you can set type = 2 for each comment under that comment thread. Otherwise, it should be set to 1. A simplified example can look as follows:
function getCommentThreadsData( commentThreadsForDocument, suggestionsForDocument ) {
    const threads = [];
    const comments = [];

    commentThreadsForDocument.forEach( commentThread => {
        const hasMatchingSuggestion = suggestionsForDocument.some( suggestion => suggestion.id === commentThread.id );

        threads.push( {
            // map your comment thread here
        } );

        comments.push(
            ...commentThread.comments.map( comment => ( {
                // map other comment fields here
                // set comment type depending if a comment thread it belongs to has a matching suggestion 
               type: hasMatchingSuggestion ? 2 : 1
            } ) )
        );
    } );

    return {
        threads,
        comments
    }
}

# Example

Check an example of an application that migrates documents to Real-time Collaboration in Node.js and Express.js.

# Next steps