Uniform Siphon - Sitecore CMS Migration Walkthrough

This guide walks you through the complete process of migrating content, media, and presentation from Sitecore CMS to the Uniform platform using Uniform Siphon tools.

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

The migration process happens in 4 logical steps:

  • Source content and media is downloaded from Sitecore with siphon.download.exe to a Windows machine
  • Content files are processed with siphon.migration.exe and Uniform files are produced
  • Media files are pushed to Uniform project using siphon.migration.exe
  • Uniform files are pushed to Uniform using Uniform CLI (@uniformdev/cli)
  1. Windows machine
  2. Direct HTTP access to Sitecore instance
    • The Windows workstation needs direct HTTP(s) access to the source Sitecore instance
    • HTTP proxy is supported when configured via Windows' Settings → Proxy → Manual proxy setup
  3. Access to the Internet (required for installing Playwright)
  • Use PowerShell for running command-line tools
  • Ensure sufficient disk space for downloaded content
  • Have administrator access to the Sitecore CM server

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

# Recommended location C:\siphon

Install Playwright to enable downloading presentation (not required for basic content-only migration) using elevated PowerShell session (Run as admin):

PS C:\siphon> .\playwright.ps1 install

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_DOWNLOAD_{PARAMETER} works with all commands that have particular parameter within Siphon.Download.exe,
  • SIPHON_DOWNLOAD_{COMMAND}_{PARAMETER}: works only with {COMMAND} that have particular parameter within Siphon.Download.exe.

For example:

# equivalent of --outputDir for all Siphon commands # it will work for C:\siphon\Siphon.Download.exe download-items # it will work for C:\siphon\Siphon.Migration.exe uniform-content $env:SIPHON_OUTPUTDIR='C:\migration\sitecore\items' # equivalent of --outputDir for `Siphon.Download.exe download-items` command only # it will work for C:\siphon\Siphon.Download.exe download-items # but C:\siphon\Siphon.Migration.exe uniform-content will throw an error that --outputDir is missing $env:SIPHON_DOWNLOAD_ITEMS_OUTPUTDIR='C:\migration\sitecore\items'

Siphon reads .env files from:

  • Current working directory
  • Siphon executable directory

Set up PowerShell logging for the entire session:

PS C:\migration\uniform> Start-Transcript -Path "C:\migration\uniform\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

Before downloading data, you must deploy the migration service to your Sitecore instance.

Find UniformMigrationService.txt in the Siphon directory (extracted from siphon-download-XXXXXXX-X.zip archive).

  1. Rename UniformMigrationService.txt to UniformMigrationService.aspx
  2. Open UniformMigrationService.aspx
  3. Set a secure secret on Line 4:
    // the default secret will not work, you must change it const string Secret = "your-complex-secret-phrase-here";
  4. Save the file
  1. Upload the modified file to your Sitecore CM instance's wwwroot (or subfolder like layouts)
  2. If using multiple load-balanced CM instances, deploy to all of them
  3. Verify the page works by accessing it via browser

Important: Some folders may restrict *.aspx execution.

Also, in rare cases the IIS configuration may prohibit runtime compilation of *.aspx files. To overcome this, it needs to be deployed alongside with the application during normal deployment phase.

Download Sitecore content items using the migration service.

PS C:\migration> C:\siphon\Siphon.Download.exe download-items ` --database web ` --uniformServiceUrl https://sc.dev/layouts/UniformMigrationService.aspx ` --secret my_secret ` --root "DAC24EDD-44FB-42EF-9ECD-1E8DAF706386" ` --outputDir "C:\migration\sitecore\items"
ParameterDescription
--databaseSitecore database (e.g., web, master)
--uniformServiceUrlURL to deployed UniformMigrationService.aspx
--secretSecret phrase configured in the service
--rootRoot item ID to download with descendants (use 11111111-1111-1111-1111-111111111111 value to download everything)
--outputDirLocal folder for downloaded files

| --languages | Limit to specific languages (e.g., en,ja-JP,da), empty value means download content in all registered languages (default: empty) | | --deviceId | Sitecore device ID (default: Default device) | | --force | Force re-download existing files (default: false) | | --threads | Number of download threads (default: 4) | | --downloadRenderingsDatasources | Download rendering datasource items (parsed from Shared/Final Renderings layout field) when they are outside of the root item ID (default: false) | | --downloadFieldsReferences | Download field-referenced items when they are outside of the root item ID (default: false) | | --disableKeepAliveCheck | Skip the health check to work around systems with /sitecore/service/keepalive.aspx page restricted or removed (default : false) | | --excludeItemsFile | Exclude specific items from download using a JSON file (default: empty, file format: {"id1": "comment", "id2": "comment", ...}) | | --unsuccessfulDownloadsFileName | A custom name for the file for tracking unsuccessful downloads (default: empty) | | --inputFile | JSON file path with the list of content items to download (default: empty) |

# Set environment variables PS C:\migration> $env:SIPHON_LOGLEVEL='info' PS C:\migration> $env:SIPHON_SECRET='your-secret-here' PS C:\migration> $env:SIPHON_UNIFORMSERVICEURL='https://sc.dev/layouts/UniformMigrationService.aspx' PS C:\migration> $env:SIPHON_DATABASE='web' PS C:\migration> $env:SIPHON_LANGUAGES='en,da' PS C:\migration> $env:SIPHON_DOWNLOAD_ITEMS_OUTPUTDIR='C:\migration\sitecore\items' PS C:\migration> $env:SIPHON_DOWNLOAD_ITEMS_ROOT='DAC24EDD-44FB-42EF-9ECD-1E8DAF706386' # /sitecore/content/Habitat/Home PS C:\migration> $env:SIPHON_DOWNLOAD_ITEMS_THREADS='2' # Execute download PS C:\migration> C:\siphon\Siphon.Download.exe download-items

Siphon supports resuming interrupted downloads:

  • Previously downloaded files are skipped
  • Uses existing {outputDir}/{item-id}.json files to determine completion
  • Note: Some of the content created between download attempts may not be included automatically

Download Sitecore media library items and their associated files.

PS C:\migration> C:\siphon\Siphon.Download.exe download-media ` --database web ` --uniformServiceUrl https://sc.dev/layouts/UniformMigrationService.aspx ` --secret my_secret ` --outputDir "C:\migration\sitecore\items" ` --mediaRootDir "C:\migration\sitecore\media" ` --skipUnusedMedia
ParameterDescription
--databaseSitecore database
--uniformServiceUrlURL to UniformMigrationService.aspx
--secretService secret
--outputDirDownload destination folder

| --root | Media library root (not supported with --skipUnusedMedia) | | --skipUnusedMedia | Download only media directly referenced by previously-downloaded content (default: false) | | --mediaRootDir | Media root directory to download binary files to (default: {outputDir}/media) | | --excludeUnsupportedMimeTypes | During the media download process, exclude files with mime types that are not yet supported by Uniform (default: false) | | --mediaPrefix | Change default media URL prefix (default: /-/media/) | | --excludeItemsFile | Exclude specific items from download using a JSON file (default: empty, file format: {"id1": "comment", "id2": "comment", ...}) | | --unsuccessfulDownloadsFileName | A custom name for the file for tracking unsuccessful downloads (default: empty) | | --inputFile | JSON file path with the list of content items to download (default: empty) | | --skipUnusedMedia | Download only media files referenced by content (default: false) | | --disableKeepAliveCheck | Skip the health check to work around systems with /sitecore/service/keepalive.aspx page restricted or removed (default : false) |

For versioned media: Disable Media.RequestProtection.Enabled and clear cache via /sitecore/admin/cache.aspx

Download Sitecore presentation layer for migration to Uniform Canvas. It is used to detect hierarchy of the components and enable code-gen of react components (experimental feature).

The command will find all SC items among the previously downloaded files that are descendants of the --startPath parameter and that have presentation assigned to it (Layout field or Page Design field must have some value).

Install Playwright for logging in to Sitecore and downloading pages markup in Experience Editor mode:

PS C:\migration> .\playwright.ps1 install
PS C:\migration> C:\siphon\Siphon.Download.exe download-presentation ` --outputDir C:\migration\sitecore\presentation ` --inputDir C:\migration\sitecore\items ` --host https://mysitecore_cm ` --startPath /sitecore/content/Habitat/Home ` --loginUrl https://mysitecore_cm/sitecore/login ` --username admin ` --password b ` --database "web"
ParameterDescription
--inputDirPath to previously downloaded Sitecore content files, for example: C:\migration\sitecore\items
--outputDirPresentation files destination, for example: C:\migration\sitecore\presentation
--hostSitecore instance URL, for example: https://sc.dev/
--startPathPath to the root item of the site, for example: /sitecore/content/Habitat/Home
--loginUrlSitecore login URL, for example: /sitecore/login
--usernameSitecore username
--passwordSitecore password
--databaseSitecore database

| --languages | Limit to specific languages (e.g., en,ja-JP,da), empty value means download content in all registered languages (default: empty) | | --force | Re-download the HTML files with Experience Editor tags and regenerate presentation details index.json files, even if they exist in the cache (default: false) | | --disableKeepAliveCheck | Skip the health check to work around systems with /sitecore/service/keepalive.aspx page restricted or removed (default : false) |

Migrate both pages and content items from Sitecore to Uniform Canvas and Uniform Content Entries. The process transforms the extracted data from Sitecore and pushes it to the Uniform platform.

  • Ensure that the download of Sitecore items and media is complete.
  • (Optional) Ensure that the download of Sitecore Presentation 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

Generate Uniform Canvas project map nodes and compositions from Sitecore data.

PS C:\migration> C:\siphon\Siphon.Migration.exe uniform-canvas ` --outputDir ` --inputDir C:\migration\sitecore\items ` --startPath /sitecore/content/Habitat/Home
ParameterDescription
--inputDirDownloaded Sitecore files folder
--outputDirUniform serialization output folder
--startPathSite root item path

| --presentationDir | Setting Sitecore presentation files folder enables generating compositions with hierarchy of components | | --nextProjectDir | Next.js app folder for component generation (experimental React code generation) | | --excludePaths | Comma-separated paths to exclude | | --languages | Limit to specific languages (e.g., en,ja-JP,da), empty value means download content in all registered languages (default: empty) | | --defaultLanguage | Set default language (default: en) |

Deploy generated Canvas data to Uniform platform.

cd C:\migration\uniform npm install npm run uniform:push:canvas

2.3 Migrate to Content#

Transform Sitecore content items into Uniform Content entries.

PS C:\migration> C:\siphon\Siphon.Migration.exe uniform-content ` --outputDir C:\migration\uniform ` --inputDir C:\migration\sitecore\items ` --startPath /sitecore/content/Habitat/Home ` --dataSourceId "content" ` --excludePages
ParameterDescription
--inputDirDownloaded Sitecore files folder
--outputDirUniform content output folder
--startPathSite root item path
--dataSourceIdUniform Content Data Source ID, for example: content

| --excludePages | Exclude Sitecore pages from entries when used alongside with uniform-canvas command | | --contentRootPaths | Additional content root paths | | --languages | Limit to specific languages (e.g., en,ja-JP,da), empty value means download content in all registered languages (default: empty) | | --defaultLanguage | Set default language (default: en) |

2.4 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.exe uniform-upload-asset ` --inputDir C:\migration\sitecore\items ` --mediaRootDir "C:\migration\sitecore\media" ` --UNIFORM_API_KEY "your_api_key" ` --UNIFORM_PROJECT_ID "your_project_id" ` --skipUnusedMedia
ParameterDescription
--inputDirDownloaded files folder
--UNIFORM_API_KEYUniform API key
--UNIFORM_PROJECT_IDUniform Project ID

| --skipUnusedMedia | Upload only media directly referenced by previously-downloaded content (default: false) | | --mediaRootDir | Media root directory to download binary files to (default: {outputDir}/media) | | --threads | Upload threads (default: 4) | | --unsuccessfulUploadMediaFileName | Custom file name format for unsuccessful media uploads |

Deploy generated releases to Uniform platform.

PS C:\migration> C:\siphon\Siphon.Migration.exe uniform-releases ` --inputDir C:\migration\uniform ` --UNIFORM_API_KEY "yourApiKey" ` --UNIFORM_PROJECT_ID "yourProjectId" ` --timezone "Europe/London"
ParameterDescription
--inputDirDownloaded files folder
--UNIFORM_API_KEYUniform API key
--UNIFORM_PROJECT_IDUniform Project ID
--timezoneDefine a timezone of releases

| --unsuccessfulUploadMediaFileName | Custom file name format for unsuccessful media uploads | | --defaultLanguage | Set default language (default: en) |

To assess migration quality, analyze the log files:

  1. Re-run with warnings only:

    C:\siphon\Siphon.Migration.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 can be extended by overriding services for custom field handling.

  1. Create .NET 8 Console project
  2. Add reference to Siphon
  3. Create custom engine:
internal class CustomSiphonEngine : SiphonEngine { protected override ContentService GetContentService(ContentImportOptions options) { return DependencyInjection.Register<ContentService>(new CustomContentService(options)); } }
  1. Implement custom content service:
internal class CustomContentService : ContentService { public CustomContentService(ContentImportOptions options) : base(options) { } protected override void SaveTypeField(string type, string schemaName, string fieldName, Field field, IList<TypeField> fields, bool localizable, string groupName = null) { switch (type) { case "CustomRefField": fields.Add(CreateContentTypeField<TextField>(fieldName, field, type, groupName: groupName)); break; default: base.SaveContentTypeField(schemaName, fieldName, field, fields, groupName); break; } } protected override void SaveValueField(string type, Dictionary<ShortItem, List<Field>> items, Field field, ref ValueField resultValue, bool isMultiLanguageField) { switch (type) { case "CustomRefField": CustomFieldProcessor.Process(items, field, ref resultValue, Options, isMultiLanguageField); break; default: base.SaveValueField(type, items, field, ref resultValue, isMultiLanguageField); break; } } }

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>
outputDir/ ├── _languages.json # Available languages ├── _index.json # Item metadata index ├── _unsuccessful-downloads-*.json # Failed downloads ├── {language}/ │ ├── index.json # Language-specific index │ └── {item-id}.json # Individual items └── media/ ├── {language}/ └── files/ # Binary media files

  1. UniformMigrationService.aspx not accessible

    • Check IIS configuration
    • Verify file permissions

  2. Download interruptions

    • Use resume functionality
    • Check network connectivity
    • Run outside of peak hours of content editing
    • Reduce thread count if experiencing timeouts

  3. Memory issues with large datasets

    • Process in smaller batches using --root parameter
    • Increase available system memory
    • Use --skipUnusedMedia to reduce data volume

  4. Authentication failures in presentation download

    • Verify Sitecore credentials
    • Check login URL accessibility
    • Ensure Playwright is properly installed

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

Last modified