Importing and exporting taxonomies with the Contentful Taxonomy CLI

Contentful follows a strategy of creating a flexible, future-proof solution for managing entities within an organization. As part of this approach, dedicated commands for importing and exporting taxonomy at the organizational level have been introduced. This method enhances the current import/export functionality, which operates at the environment-level, and provides the foundation for adding additional organizational-level entities in the future.

The CLI commands outlined here are designed to export the full taxonomy model (concept schemes including concepts and it’s subconcepts) or import an external taxonomy into your organization.

Additionally, an option to synchronize entities by removing those not present in the import file is available.

Requirements

• A (free) Contentful account.
• Locally installed contentful-cli.
• Authenticated with contentful-cli.

Exporting content

The export command exports the full taxonomy hierarchy from a specified organization into a file or outputs it directly to the terminal (stdout).

Export command:

`contentful organization export --organization-id ``

Export output format:

The output will include all taxonomy-related data under a taxonomy key. This includes both concepts and conceptSchemes as shown below:

{
  "taxonomy": {
    "concepts": [],
    "conceptSchemes": []
  }
}

The CLI uses existing endpoints to fetch concepts and concept schemes in their current shape.

Transform command:

The transform command converts input data into Contentful's export format using a user-provided JavaScript file with a standardized function. This function, receiving a transform object, processes the data to generate a valid import document.

contentful organization taxonomy-transform --organization-id <organization-id> --transform-script custom-import-transform.js

Transform output format

We output the identical shape as we get from the export. This will be the same format used for the import.

{
   "taxonomy": {
      "concepts": [],
      "conceptSchemes": []
   }
}

Import Command

The import command imports a taxonomy tree from a referenced file into the specified organization. The process involves matching existing entities by their IDs and either creating new entities or overwriting existing ones.

Import command:

contentful organization import --organization-id <organization-id> --content-file <path>

Example import usage:

contentful organization import --organization-id 12345 --content-file ./taxonomy-import.json

Import Strategy

• The import process follows an overwrite strategy where the source (local file) reflects the state of the target (organization).
• Entities are matched by their unique IDs, and the CLI ensures that existing entities are updated or created accordingly.
• This import might be executed in multiple steps internally, first to create the entities and then to establish any necessary references between them.