Uniform Siphon - Contentful CMS Migration Walkthrough

This guide walks you through the complete process of migrating content and assets from Contentful CMS to the Uniform platform using Uniform Siphon tools.

  1. Prerequisites
  2. Installation and Setup
  3. Phase 1: Download Contentful Data
  4. Phase 2: Migration to Uniform
  5. Assessment and Validation
  6. Advanced Topics

The migration process happens in 4 logical steps:

  • Source content and media is downloaded from Conetntful with contentful-cli to a Windows machine
  • Content are processed with Siphon.Migration.Contentful.exe and Uniform files are produced
  • Media files are pushed to Uniform project using Siphon.Migration.Contentful.exe
  • Uniform files are pushed to Uniform using Uniform CLI (@uniformdev/cli)
  1. Windows machine
  2. Direct HTTP access to Contentful space and Uniform project
  • Use PowerShell for running command-line tools
  • Ensure sufficient disk space for downloaded content

Extract all siphon-*-XXXXXXX-X.zip distribution packages provided by Uniform to a local folder:

# Recommended location C:\siphon

Create a work directory for all files will be downloaded and processed, for example: C:\migration\.

Open a new PowerShell session and navigate there:

PS C:\migration> cd C:\migration PS C:\migration>

It is recommended to create .env file in the work directory and use environment variables instead of command-line arguments.

Environment variables can be used instead of command-line arguments:

  • SIPHON_{PARAMETER} works with all Siphon executables and all commands that have particular parameter,
  • SIPHON_{COMMAND}_{PARAMETER}: works only with {COMMAND} that have particular parameter within Siphon.Migration.Contentful.exe.

For example:

# equivalent of --inputDir for all Siphon commands # it will work for C:\siphon\Siphon.Migration.Contentful.exe uniform-content # it will work for C:\siphon\Siphon.Migration.exe uniform-content $env:SIPHON_INPUTDIR='C:\migration\contentful' # equivalent of $env:SIPHON_INPUTDIR for uniform-content command only $env:SIPHON_UNIFORM_CONTENT_INPUTDIR='C:\migration\contentful'

Siphon reads .env files from:

  • Current working directory
  • Siphon executable directory

Set up PowerShell logging for the entire session:

PS C:\migration> Start-Transcript -Path "C:\migration\siphon.log" -Append

All commands accept --logLevel parameter with these values:

  • debug - Includes all types (default)
  • info - Also includes warn and error
  • warn - Also includes error
  • error - Only error messages

Create a work directory for all files will be downloaded and processed, for example: C:\migration\contentful.

Open a new PowerShell session and navigate there:

PS C:\migration> cd C:\migration\contentful PS C:\migration>
PS C:\migration> npm install -g contentful-cli

1.2 Download Content#

Download contentful content using the contentful-cli.

The export produces a JSON file for content, plus assets folders with binary files.

PS C:\migration\contentful> contentful space export ` --space-id $SPACE_ID ` --environment-id $ENVIRONMENT_ID ` --management-token $CMA_TOKEN ` --delivery-token $CDA_TOKEN ` --download-assets
ParameterDescription
--space-idID of Space with source data
--environment-idID of Environment with source data, default: master.
--management-tokenContentful management API token.
--delivery-tokenContentful delivery API token - Required for published content migration, without this token the latest content from the space will be migrated.
--download-assetsWith this flags assets will also be downloaded.

Migrate content entries and content types from Contentful to Uniform Content Entries. The process transforms the extracted data from Contentful and pushes it to the Uniform platform.

  • Ensure that the download of Contentful data is complete.
  • Prepare a Uniform Project and manually add all languages that were previously downloaded
  • Set up a Uniform Content Data Source in your Uniform project
  • Create an API Key with a Developer role

2.1 Migrate to Content#

Transform Contentful content types and entries into Uniform Content content types and entries.

PS C:\migration> C:\siphon\Siphon.Migration.Contentful.exe uniform-content ` --outputDir C:\migration\uniform ` --inputDir C:\migration\contentful ` --languages "en-US" ` --dataSourceId "content" ` --slugFieldId "slug"
ParameterDescription
--inputDirDownloaded Contentful data folder
--outputDirUniform content output folder
ParameterDescription
--dataSourceIdUniform Content Data Source ID, for example: content
--slugFieldIdField name in the Contentful entry that will be used for the Uniform entry slug
--languagesLimit to specific languages (e.g., en-US,da-DK), empty value means migrate content in all registered languages (default: empty)

2.2 Push Content Data#

Deploy content entries to Uniform platform.

cd C:\migration\uniform npm run uniform:push:content # For parallel processing (4 threads) npm run uniform:push:content-p4

Upload media assets to Uniform Asset Library.

PS C:\migration> C:\siphon\Siphon.Migration.Contentful.exe uniform-upload-asset ` --inputDir C:\migration\contentful ` --UNIFORM_API_KEY "your_api_key" ` --UNIFORM_PROJECT_ID "your_project_id" ` --languages "en-US" ` --skipUnusedMedia
ParameterDescription
--inputDirDownloaded files folder
--UNIFORM_API_KEYUniform API key
--UNIFORM_PROJECT_IDUniform Project ID
ParameterDescription
--languagesLimit to specific languages (e.g., en-US,da-DK), empty value means migrate content in all registered languages (default: empty)
--skipUnusedMediaUpload only media directly referenced by previously-downloaded content (default: false)
--threadsUpload threads (default: 4)

To assess migration quality, analyze the log files:

  1. Re-run with warnings only:

    C:\siphon\Siphon.Migration.Contentful.exe uniform-content [params] --logLevel Warn | Tee-Object .\assessment.txt

  2. Review in text editor:

    • Open assessment.txt in Notepad++
    • Menu → Edit → Line Operations → Remove duplicate lines
    • Review each unique warning/error

  3. Common issues to check:

    • Missing field mappings
    • Unsupported field types
    • Reference resolution failures
    • Language-specific problems

Siphon includes various transformation commands for post-migration cleanup and optimization.

This utility processes Uniform serialization exported from Contentful and migrates inline Contentful asset URLs into Uniform assets.
It scans entries, compositions, and component parameters for embedded Contentful asset URLs (e.g., ctfassets.net/...) and replaces them with Uniform asset references.
If Uniform project credentials are provided, missing assets can also be uploaded automatically.

contentful-migrate-inline-assets --contentfulExportFolder <contentful_export_path> --inputDir <uniform_path> --outputDir <output_path>
ParameterDescription
--contentfulExportFolderPath to the Contentful export folder (JSON + assets)
--inputDirPath to the folder containing Uniform serialization data (entry, etc.)
--outputDirPath to the folder where transformed data will be written
ParameterDescription
--UNIFORM_API_KEYUniform API key (required for asset upload to Uniform)
--UNIFORM_PROJECT_IDUniform Project ID (required for asset upload to Uniform)
--UNIFORM_CLI_BASE_URLUniform CLI base URL (default: https://uniform.app)
--logLevelSets the log level. Options: debug, info, warn, error (default: debug)
--no-timestampsDisable timestamps in logs

This utility processes Uniform serialization exported from Contentful and replaces fields that contain raw Contentful image URLs with proper Uniform asset fields.
It is useful when Contentful exports store images as plain text fields or image URLs, and you want to migrate them into Uniform’s structured asset model.

contentful-replace-image-url-field --contentfulExportFolder <contentful_export_path> --inputDir <uniform_path> --outputDir <output_path> --textFields imageReference|mobileImageReference
ParameterDescription
--contentfulExportFolderPath to the Contentful export folder (JSON + assets)
--inputDirPath to the folder containing Uniform serialization data (entry, etc.)
--outputDirPath to the folder where transformed data will be written
ParameterDescription
--textFieldsComma/semicolon/pipe-delimited list of text field IDs to migrate into asset fields. Example: `imageReference
--logLevelSets the log level. Options: debug, info, warn, error (default: debug)
--no-timestampsDisable timestamps in logs

This utility processes a Uniform serialization dataset and replaces Contentful datatypes (singleEntry / multipleEntry) with components and patterns.
It migrates data from a specified datasource (datatypeId) into components, embedding entry content directly and generating new patterns if needed.
This allows phasing out datatype dependencies and making components self-contained.

contentful-replace-datatype-with-components --inputDir <uniform_path> --outputDir <output_path> --contentfulExportFolder <contentful_export_path> --datatypeId <datatypeid> --datatypeType <datatypeType> --componentId <componentId>
ParameterDescription
--inputDirPath to the folder containing Uniform serialization (composition, pattern, etc.)
--outputDirPath to the folder where transformed data will be written
--contentfulExportFolderPath to the Contentful export folder (JSON + assets)
--datatypeIdThe ID of the existing datatype to be replaced (e.g., blogPosts)
--datatypeTypeType of the datatype. Supported: contentful
--componentIdTarget component ID that will replace the datatype
ParameterDescription
--languagesLanguages to include. If not set, all languages will be processed
--logLevelSets the log level. Options: debug, info, warn, error (default: debug)
--no-timestampsDisable timestamps in logs

Scans a Uniform serialization and the linked Contentful export to find orphaned data resources — i.e., Contentful data resources that reference entry IDs which don’t exist in the export.
Supports both singleEntry and multipleEntry archetypes. Checks data resources defined at the composition/entry level and inside overrides.

contentful-find-orphaned-dataresources --inputDir <uniform_path> --contentfulExportFolder <contentful_export_path>
ParameterDescription
--inputDirPath to the folder containing Uniform serialization (composition, entry, etc.)
--contentfulExportFolderPath to the Contentful export folder (must include JSON and assets)
ParameterDescription
--datasourceIdLimit the scan to a specific datasource ID. If omitted, all datasources are checked.
--logLevelLog verbosity: debug, info, warn, error (default: debug)
--no-timestampsDisable timestamps in logs

Migrates a Uniform project from one datasource provider to another by:

  • Re-creating datatype definitions under the new provider, and
  • Rewriting dataResources and JPTR tokens in compositions/entries to the new pointer format.

Supports singleEntry and multipleEntry archetypes for Contentful exports.

contentful-replace-datatype --inputDir <uniform_path> --outputDir <output_path> --contentfulExportFolder <contentful_export_path> --datasourceId <source_datasource_id> --new-datasourceId <target_datasource_id>
ParameterDescription
--inputDirPath to the folder containing Uniform serialization (composition, entry, datatype, etc.)
--outputDirPath to the folder where transformed data will be written
--contentfulExportFolderPath to the Contentful export folder (JSON + assets)
--datasourceIdID of the existing datasource to migrate (must include singleEntry / multipleEntry datatypes)
--new-datasourceIdID of the target datasource provider to migrate to
ParameterDescription
--logLevelLog verbosity: debug, info, warn, error (default: debug)
--no-timestampsDisable timestamps in logs

For additional support, contact Uniform support with detailed log files and error messages.

Last modified