Data migration

To move data from one environment to another, you export it from the source environment and import it into the destination environment using the Documents API.

The same approach applies to any pair of environments, for example:

• between two environments within the same organization,
• between environments belonging to two different organizations,
• between two On-Premises instances,
• between the EU and US cloud regions (region migration).

Migrating data between environments is a combination of two operations:

1. Export the data from the source environment using the GET /documents/{source_document_id} endpoint.
2. Import the exported data into the destination environment using the POST /documents endpoint.

Migrating data in the opposite direction only requires swapping the source and destination configuration.

Before migrating any data, make sure that:

• Editor bundle – the editor bundle used by your documents is present in the destination environment. It is not migrated automatically, but you can copy it over the REST API (see Migrating the editor bundle).
• API secret – you have the API secret of each environment. Every request must be signed with the secret of the environment it is sent to, using a request signature.
• Users – migrate the users first, so that the authors of comments and suggestions can be found in the destination environment (see Migrating users).
• Region domains – when migrating between cloud regions, use the correct endpoint domain: EU environments use *.cke-cs-eu.com, US environments use *.cke-cs.com. For On-Premises, use your own application endpoint.

Migration is performed document by document – there is no endpoint that migrates all documents at once. For every document, you export it from the source environment and import it into the destination environment.

To build the list of documents to migrate when the source environment uses the document storage, use the GET /storage endpoint, which returns the documents saved in the storage. The endpoint is paginated, so follow the next_cursor value to collect all documents. Because the documents are persisted, they can be migrated at any time, even when no collaboration session is active.

If the environment does not use the document storage, documents are not persisted – a document exists only while its collaboration session is active. In this case, you cannot rely on GET /storage. Instead, list the documents that currently have an active collaboration session with the GET /collaborations endpoint and migrate them while their sessions are still active.

The Documents API migrates the entire document as a single resource, including:

• the document content (the active collaboration session or the stored content),
• comment threads and comments,
• suggestions,
• revision history.

Comments and suggestions reference their authors by user ID. To keep this information consistent after the migration, migrate the users to the destination environment before importing the documents, using the POST /users endpoint of the Users API.

Users are stored per environment, so you only need to migrate them once per destination environment – not for every document. When migrating many documents, migrate all their authors first and then import the documents.

Ready-to-use Node.js snippets for the whole process are available in the Migrating data between environments example. They cover:

• exporting and importing a single document together with its comments, suggestions, and revisions,
• migrating the editor bundle and its configuration,
• migrating users,
• migrating all documents from an environment in batches.

The snippets work in both directions and can be used for any of the use cases listed above, including migrating data between the EU and US cloud regions.