Importing and Exporting Content
Overview
Exporting and importing content is an important tool in many content-workflow processes. By the end of this tutorial, you will be able to export and import content and content models between spaces.
The tools
Our export, import, and migration tooling are separated into different command-line tools that can be installed and used separately.
- https://github.com/contentful/contentful-import
- https://github.com/contentful/contentful-export
- https://github.com/contentful/migration-cli
The rest of this tutorial will assume the tools to have been installed using the following commands.
npm install -g contentful-import
npm install -g contentful-export
npm install -g contentful-migration-cli
Exporting content
After you have the export CLI tool installed and at the command line, run contentful-export [options].
The possible options are:
Options:
--version [bool] Display the version number.
--space-id [string] The ID of the space containing data to export.
--management-token [string] Use the Contentful management API token for
the space you want to export.
--export-dir [string] Define the path where you want to store the
exported JSON file.
By default, the path is the current directory.
--include-drafts [bool] Include drafts in the exported entries.
--skip-content-model [bool] Skip exporting content models.
--skip-content [bool] Skip exporting assets and entries.
--skip-roles [bool] Skip exporting roles and permissions.
--skip-webhooks [bool] Skip exporting webhooks.
--download-assets [bool] Download assets.
--max-allowed-limit [number] Set a maximum number of items per http request.
--management-host [string] Set the host to call for the management API.
The default is api.contentful.com.
--proxy [string] Configure the HTTP proxy.
Specify it in HTTP auth format:
host:port or user:password@host:port
--error-log-file [string] Specify the dull path to the error log file.
--use-verbose-renderer [bool] Display progress in more detail,
which can be useful for debugging.
--save-file [bool] Save the export in JSON format.
--config Use a configuration JSON file that
contains all of the options.
All of these options can be put in an external config.json file. You can find a reference config file here.
Next, run your export.
contentful-export --config example-config.json
The exported JSON file has the following structure:
{
"contentTypes": [],
"entries": [],
"assets": [],
"locales": [],
"webhooks": [],
"roles": [],
"editorInterfaces": []
}
You can use this structure with the import tool to import content into another space.
Limitations
- This tool does not support exporting space memberships. They have to be manually created in the destination space.
- For security reasons, exported webhooks do not contain authentication information. Therefore, you need to manually create credentials within the destination space.
- Custom UI extensions are not exported. For managing extension please use the Contentful Extension CLI.
Importing content
After you have the import CLI tool installed and at the command line, run contentful-import [options] from your command line.
The possible options are:
Options:
--version [bool] Display version number.
--space-id [string] The ID of the space to import content to.
--management-token [string] Use the Contentful management API token
for the space you want to import to.
--content-file [string] The JSON file that contains the data to be
imported into your space.
--content-model-only [bool] Import only content types.
--skip-content-model [bool] Skip importing content types and locales.
--skip-locales [bool] Skip importing locales.
--skip-content-publishing [bool] Skips content publishing.
Creates content but does not publish it.
--error-log-file [string] Specify the full path to the error log file.
--proxy [string] Configure the HTTP proxy.
Specify it in HTTP auth format:
host:port or user:password@host:port
--config Use a configuration JSON file that
contains all of the options.
Similar to the export tool these settings can be stored in an external json file. You can find a reference config file here.
Note that you also need to reference a JSON file that contains the exported content. The expected format is the same as the export format from the export tool above.
Next, run your import.
contentful-import --config example-config.json
Limitations
- This tool does not support the import of space memberships.
- This tool is expecting the target space to have the same default locale as your previously exported space.
- Imported webhooks with credentials will be imported as normal webhooks. Credentials should be added manually afterwards.
- If you have custom UI extensions, you need to reinstall them manually using the Contentful Extension CLI.
Migrations
Contentful also provides a tool for content migrations. A migration is different from a direct export/import in that it also allows you to define content model changes that should be applied to the target space. For example you could opt to add completely new fields, or split an existing field into two.
The migrations CLI tool has its own powerful DSL (Domain Specific Language) that contains a multitude of options to allow you to specify your migration granularly. It is best learnt by visiting our migration examples.