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.

Table of Contents#

Overview
Prerequisites
Installation and Setup
Phase 1: Download Sitecore Data
Phase 2: Migration to Uniform
Assessment and Validation
Advanced Topics
Reference
Troubleshooting

Overview#

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)

Prerequisites#

System Requirements#

Windows machine
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
Access to the Internet (required for installing Playwright)

Recommendations#

Use PowerShell for running command-line tools
Ensure sufficient disk space for downloaded content
Have administrator access to the Sitecore CM server

Installation and Setup#

1. Extract Siphon Tools#

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

# Recommended location C:\siphon

2. Install Playwright#

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

3. Prepare work directory#

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>

4. Use environment variables#

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.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 $env:SIPHON_DOWNLOAD_ITEMS_OUTPUTDIR='C:\migration\sitecore\items'

Siphon reads .env files from:

Current working directory
Siphon executable directory

5. Configure Logging#

Set up PowerShell logging for the entire session:

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

Log Levels#

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

Phase 1: Download Sitecore Data#

1.1 Setup UniformMigrationService.aspx#

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

Step 1: Locate the Service File#

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

Step 2: Configure Security#

Rename UniformMigrationService.txt to UniformMigrationService.aspx
Open UniformMigrationService.aspx
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";
Save the file

Step 3: Deploy to Sitecore#

Upload the modified file to your Sitecore CM instance's wwwroot (or subfolder like layouts)
If using multiple load-balanced CM instances, deploy to all of them
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.

1.2 Download Items#

Download Sitecore content items using the migration service.

Basic Command Structure#

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"

Required Parameters#

Parameter	Description
`--database`	Sitecore database (e.g., `web`, `master`)
`--uniformServiceUrl`	URL to deployed UniformMigrationService.aspx
`--secret`	Secret phrase configured in the service
`--root`	Root item ID to download with descendants (use `11111111-1111-1111-1111-111111111111` value to download everything)
`--outputDir`	Local folder for downloaded files

Optional Parameters#

Parameter	Description
`--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)

Full Download Example#

# 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

Download Resuming#

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

1.3 Download Media#

Download Sitecore media library items and their associated files.

Basic Command#

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

Required Parameters#

Parameter	Description
`--database`	Sitecore database
`--uniformServiceUrl`	URL to UniformMigrationService.aspx
`--secret`	Service secret
`--outputDir`	Download destination folder

Optional Parameters#

Parameter	Description
`--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

1.4 Download Presentation (Optional)#

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).

Prerequisites#

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

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

Command#

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"

Required Parameters#

Parameter	Description
`--inputDir`	Path to previously downloaded Sitecore content files, for example: `C:\migration\sitecore\items`
`--outputDir`	Presentation files destination, for example: `C:\migration\sitecore\presentation`
`--host`	Sitecore instance URL, for example: `https://sc.dev/`
`--startPath`	Path to the root item of the site, for example: `/sitecore/content/Habitat/Home`
`--loginUrl`	Sitecore login URL, for example: `/sitecore/login`
`--username`	Sitecore username
`--password`	Sitecore password
`--database`	Sitecore database

Optional Parameters#

| --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) |

Phase 2: Migration to Uniform#

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.

Pre-requisites:#

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

2.1 Migrate project map nodes and compositions#

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

Required Parameters#

Parameter	Description
`--inputDir`	Downloaded Sitecore files folder
`--outputDir`	Uniform serialization output folder
`--startPath`	Site root item path

Optional Parameters#

Parameter	Description
`--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 migrate content in all registered languages (default: empty)
`--defaultLanguage`	Set default language (default: `en`)

2.2 Push Canvas Data#

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

Required Parameters#

Parameter	Description
`--inputDir`	Downloaded Sitecore files folder
`--outputDir`	Uniform content output folder
`--startPath`	Site root item path
`--dataSourceId`	Uniform Content Data Source ID, for example: `content`

Optional Parameters#

Parameter	Description
`--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 migrate content in all registered languages (default: empty)
`--defaultLanguage`	Set default language (default: `en`)
`--skipExtraLinkFields`	Skip creation of {link}_Anchor, {link}_Title, {link}_QueryString fields

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

2.5 Upload Assets#

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

Required Parameters#

Parameter	Description
`--inputDir`	Downloaded files folder
`--UNIFORM_API_KEY`	Uniform API key
`--UNIFORM_PROJECT_ID`	Uniform Project ID

Optional Parameters#

Parameter	Description
`--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

2.6 Migrate Releases#

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"

Required Parameters#

Parameter	Description
`--inputDir`	Downloaded files folder
`--UNIFORM_API_KEY`	Uniform API key
`--UNIFORM_PROJECT_ID`	Uniform Project ID
`--timezone`	Define a timezone of releases

Optional Parameters#

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

Assessment and Validation#

Analyzing Migration Results#

To assess migration quality, analyze the log files:

Re-run with warnings only:
C:\siphon\Siphon.Migration.exe uniform-content [params] --logLevel Warn | Tee-Object .\assessment.txt
Review in text editor:
- Open assessment.txt in Notepad++
- Menu → Edit → Line Operations → Remove duplicate lines
- Review each unique warning/error
Common issues to check:
- Missing field mappings
- Unsupported field types
- Reference resolution failures
- Language-specific problems

Advanced Topics#

7.1 Extensibility for Developers#

Siphon can be extended by overriding services for custom field handling.

Creating Custom Extensions#

Create .NET 8 Console project
Add reference to Siphon
Create custom engine:

internal class CustomSiphonEngine : SiphonEngine { protected override ContentService GetContentService(ContentImportOptions options) { return DependencyInjection.Register<ContentService>(new CustomContentService(options)); } }

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; } } }

7.2 Transformation Commands#

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

Replace Image URL Fields#

Convert Contentful image URLs to Uniform asset references:

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

Replace Data Types#

Update data source IDs in Uniform resources:

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

Find Orphaned Data Types#

Identify unused data type definitions:

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

Calculate Migration Scope#

Analyze usage of specific data sources:

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

Convert Entries to Components#

Transform entries into reusable components:

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

Reference#

File Structure After Download#

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

Troubleshooting#

Common Issues#

UniformMigrationService.aspx not accessible
- Check IIS configuration
- Verify file permissions
Download interruptions
- Use resume functionality
- Check network connectivity
- Run outside of peak hours of content editing
- Reduce thread count if experiencing timeouts
Memory issues with large datasets
- Process in smaller batches using --root parameter
- Increase available system memory
- Use --skipUnusedMedia to reduce data volume
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.

On this page

Table of Contents#

Overview#

Prerequisites#

System Requirements#

Recommendations#

Installation and Setup#

1. Extract Siphon Tools#

2. Install Playwright#

3. Prepare work directory#

4. Use environment variables#

5. Configure Logging#

Log Levels#

Phase 1: Download Sitecore Data#

1.1 Setup UniformMigrationService.aspx#

Step 1: Locate the Service File#

Step 2: Configure Security#

Step 3: Deploy to Sitecore#

1.2 Download Items#

Basic Command Structure#

Required Parameters#

Optional Parameters#

Full Download Example#

Download Resuming#

1.3 Download Media#

Basic Command#

Required Parameters#

Optional Parameters#

1.4 Download Presentation (Optional)#

Prerequisites#

Command#

Required Parameters#

Optional Parameters#

Phase 2: Migration to Uniform#

Pre-requisites:#

2.1 Migrate project map nodes and compositions#

Required Parameters#

Optional Parameters#

2.2 Push Canvas Data#

2.3 Migrate to Content#

Required Parameters#

Optional Parameters#

2.4 Push Content Data#

2.5 Upload Assets#

Required Parameters#

Optional Parameters#

2.6 Migrate Releases#

Required Parameters#

Optional Parameters#

Assessment and Validation#

Analyzing Migration Results#

Advanced Topics#

7.1 Extensibility for Developers#

Creating Custom Extensions#

7.2 Transformation Commands#

Replace Image URL Fields#

Replace Data Types#

Find Orphaned Data Types#

Calculate Migration Scope#

Convert Entries to Components#

Reference#

File Structure After Download#

Troubleshooting#

Common Issues#