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. It focuses on what happens at each step and why — for the exact syntax and every parameter of the commands you run, follow the deep links into the command reference — split into the Download commands reference (extract phase) and the migrate command reference (transform and load phases).

Table of Contents#

1. How the migration works
2. Prerequisites
3. Install and set up Siphon
4. Phase 1 — Extract
5. Phase 2 — Transform
6. Phase 3 — Transform
7. Assess and validate the migration
8. Advanced: extending Siphon
9. Troubleshooting

How the migration works#

Siphon is built around the Extract-Transform-Load (ETL) pattern common to data-migration tooling. Rather than a single monolithic step, the migration is broken into checkpoints that persist their output to disk, so any phase can be inspected, re-run, or resumed independently.

The process happens in three logical phases, each driven by its own tool:

1. Extract — source content, media, and presentation are downloaded from the live Sitecore instance with Siphon.Download.exe onto a Windows machine.
2. Transform — the downloaded Sitecore data is converted by Siphon.Migration.exe into files in the format Uniform understands (Canvas compositions, Content entries, assets, releases).
3. Load — those Uniform files are pushed to your Uniform project with the Uniform Sync CLI (@uniformdev/cli).

Because each phase writes to the local disk, the recommended pattern is to keep everything under a single work directory (for example C:\migration\) with predictable sub-folders for items, media, presentation, and the generated Uniform output.

Prerequisites#

System requirements#

Extract phase#

1. A Windows machine to run the Siphon executables.
2. Direct HTTP(S) access from that machine to the source Sitecore instance. An HTTP proxy is supported when configured via Windows' Settings → Proxy → Manual proxy setup.

Transform phase#

1. Access to "Extract phase" data
2. A Windows machine to run the Siphon executables.

Load phase#

1. Access to "Extract phase" and "Transform phase" data
2. A Windows machine to run the Siphon executables.
3. Internet access to https://npmjs.com and https://uniform.app
4. Node.js installed to run @uniformdev/cli.

On the Uniform side#

Before the transform/load phase you will also need:

• A Uniform project
• A Uniform Content data source configured in that project.
• An API key with the Developer role.

Recommendations#

• Use PowerShell for running the command-line tools.
• Ensure sufficient disk space for the downloaded content and media.
• Have administrator access to the Sitecore CM server (needed to deploy the migration service).

Install and set up Siphon#

Setting up the toolkit — extracting the distribution packages, unblocking the executables, installing Playwright, and putting siphon on your PATH — is covered step by step in the dedicated installation guide. Complete that first, then return here.

Two conventions established during setup are worth internalizing because they apply to every command you'll run:

• Parameters can be set as environment variables or a .env file rather than long command lines. This keeps secrets out of your shell history and lets settings be reused across commands. See configuring commands for the SIPHON_* naming rules and .env resolution order.
• Logging is written to .siphon.log.*.txt files in the working directory, with verbosity controlled by --logLevel. Keep it at INFO and only switch to DEBUG when something goes wrong.

Phase 1 — Extract#

The extract phase pulls three kinds of data out of Sitecore, in order: items (content), media (binaries) and presentation (page layout markup). All three are downloaded by Siphon.Download.exe through a small service you deploy into the Sitecore instance.

Phase 2 — Transform#

In this phase Siphon.Migration.exe converts the downloaded Sitecore data into Uniform Canvas and Content JSON serialization files. Pages become Uniform Canvas project map nodes and compositions; reusable content items become Uniform Content entries.

Before you start#

• The item and media downloads must be complete (presentation too, if you want component hierarchy).

Generate Canvas (project map and pages)#

uniform-canvas reads the downloaded items (and the presentation data) and generates Uniform project map nodes and compositions.

See uniform-canvas for the full parameter list.

Generate Content (entries)#

uniform-content transforms the Sitecore content items into Uniform Content entries. When you also migrated pages via uniform-canvas, pass --excludePages so page items are not duplicated as entries.

See uniform-content for the full parameter list.

Stage 3 — Load#

The load stage runs in dependency order: upload the media first, resolve the asset URLs that the media upload makes available, and only then push the Canvas and Content so what you push already carries real URLs.

Upload assets#

Upload the downloaded media binaries to the Uniform Asset Library. As with the download, --skipUnusedMedia restricts the upload to media actually referenced by content.

See uniform-upload-assets for the full parameter list.

Resolve asset URLs (post-process-assets)#

When Canvas and Content were generated, media that is embedded in rich-text fields, general links, and image fields was written as a placeholder URL of the form /uniform_asset/{asset-id} — the real delivery URL isn't known until the asset exists in Uniform. Now that the assets have been uploaded, this step rewrites those placeholders, in the generated files, to the assets' real Uniform URLs:

Why it's needed: without it, those references stay as /uniform_asset/… placeholders and the published site renders broken images and media links — and because validate/deploy/publish do not check for it, the run otherwise looks green. It must run after the asset upload (so every id resolves) and before the Canvas/Content push below (so the pushed serialization already carries real URLs); ids that were never uploaded are left as-is with a warning.

See post-process-assets for the full parameter list.

Push Content#

Push the generated entries to your Uniform project. Run npm install once in the output folder before the first push.

See uniform:push:content.

Push Canvas#

Push the generated Canvas data to your Uniform project.

See uniform:push:canvas.

Assess and validate the migration#

The migration log files are your primary tool for judging migration quality. The most effective way to review them is to re-run a transform command at SIPHON_LOGLEVEL=Warn and =true level and collapse duplicate lines.

1. Re-run with warnings only and no-timestamps
2. Review in a text editor — open log file in Notepad++, then use Edit → Line Operations → Remove duplicate lines, and read each unique warning or error.
3. Look especially for:
   • Missing field mappings
   • Unsupported field types
   • Reference resolution failures
   • Language-specific problems

Troubleshooting#

UniformMigrationService.aspx not accessible

• Check the IIS configuration and verify file permissions.

Download interruptions

• Use the built-in resume functionality (just re-run the command).
• Check network connectivity.
• Run outside the peak hours of content editing.
• Reduce the thread count if you hit timeouts.

Memory issues with large datasets

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

Authentication failures in presentation download

• Verify the Sitecore credentials.
• Check that the login URL is accessible.
• Ensure Playwright is properly installed.

For additional support, contact the Uniform migration team with the DEBUG log file.