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.

Convert Contentful image URLs to Uniform asset references:

replace-image-url-field --inputDir <uniform_path> --contentfulExportFolder <contentful_path>

Update data source IDs in Uniform resources:

replace-datatype --inputDir <input> --datasourceId <old_id> --new-datasourceId <new_id> --outputDir <output> --contentfulExportFolder <contentful_path>

Identify unused data type definitions:

find-orphaned-datatypes --inputDir <uniform_path> [--delete]

Analyze usage of specific data sources:

calculate-scope --inputDir <uniform_path> --datasourceId <datasource_name>

Transform entries into reusable components:

merge-entries-into-components --inputDir <uniform_path> --outputDir <output_path>

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

Last modified