Synchronizing Spaces with contentful-space-sync

Overview

Many users of Contentful have developed custom workflows to work with their content, such as having a space for content testing, and a separate one for production content.

Given the need to keep multiple spaces in sync, some of our users have developed their own synchronization tools. Having learned from their common problems and needs, we have decided to develop our own flexible and maintainable tool to address this problem.

Getting the tool

This tool is a command line tool built with Node.js.

However, you don't need to write code or even know JavaScript, unless you want to check out and change the code (which is open source)

If you have Node.js in your system, and if you've installed it in one of the most common ways, you should also have the npm package manager, and then you can just do the following:

1
npm install -g contentful-space-sync

If you run the command contentful-space-sync without any arguments, it will show you all the parameters that can be specified.

Creating a configuration file

Because you will run this tool multiple times, you won't want to always type all those arguments, so you can also specify most of those parameters in a JSON configuration file:

1
2
3
4
5
6
{
  "sourceSpace": "zz23f5a5k4px",
  "destinationSpace": "51gdd42hhlg",
  "sourceDeliveryToken": "9d6a92ad34ea20kejr2083fugelsfe4d968c72a0885628cefa2",
  "managementToken": "0f3e4bb0f4e4c51lkhd2h3o8dslfdushfdf9c892c937ddbc1a6847d42"
}

Note that the example space IDs and tokens in this example are not real.

Getting API keys

In order to get the API key for the source space, open the space you wish to get your content from on the Contentful web app, go to the APIs section, and select API keys under Content Delivery API.

There you can create a delivery API key for your space. You can also get the space ID.

Management API keys are generated differently. You can get one and learn more about their differences on the authentication page.

Synchronizing across different organizations

The configuration above assumes both the source and destination spaces live under the same organization and you only need one management token.

If you want to synchronize spaces across different organizations, you can specify separate management tokens:

1
2
3
4
5
6
7
{
  "sourceSpace": "zz23f5a5k4px",
  "destinationSpace": "51gdd42hhlg",
  "sourceDeliveryToken": "9d6a92ad34ea20kejr2083fugelsfe4d968c72a0885628cefa2",
  "destinationManagementToken": "123rw340f4e4c51lkhd2h3o8ds1231231892c937ddbc1324j23fwef",
  "sourceManagementToken": "0f3e4bb0f4e4c51lkhd2h3o8dslfdushfdf9c892c937ddbc1a6847d42"
}

Running the tool

With your configuration file in place, you can now run your space synchronization. Let's assume you called your configuration file cf-sync-preview-to-production.json. You would run this as:

1
contentful-space-sync --config cf-sync-preview-to-production.json

The tool will then run, providing output about the content that is being synchronized.

In the end the tool will produce a file named contentful-space-sync-token-zz23f5a5k4px-51gdd42hhlg which contains a synchronization token, generated by the Contentful API.

This file, and the token contained in it, is used to determine the last state that was copied from the source space. This means that for entries and assets, only new and updated items will be copied. Deleted items on the source space will also be deleted on the destination space.

You need to ensure this file is present in the current directory or specify a path with --sync-token-dir.

If any errors occur, the tool will also generate a log file with information about those errors.

Some of these errors might be related to the current state of your content. After you fix them, you can run the tool again to synchronize the problematic content after it's been fixed.

More options

Check out the github page for the tool for further options, and more information on potential issues and how to solve them.

The code is open source, so we encourage you to fork the code and modify it to suit your particular needs if you have a more specific workflow.