# Uniform Siphon - Sitecore CMS Migration Walkthrough

> End-to-end guide for migrating from Sitecore CMS to Uniform using Siphon

Source: https://docs.uniform.app/docs/guides/migration/sitecore/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](https://docs.uniform.app/docs/guides/migration/sitecore/download-reference) (extract phase) and the [migrate command reference](https://docs.uniform.app/docs/guides/migration/sitecore/migrate-reference) (transform and load phases).

## Table of Contents

1. [How the migration works](#how-the-migration-works)
2. [Prerequisites](#prerequisites)
3. [Install and set up Siphon](#install-and-set-up-siphon)
4. [Phase 1 — Extract](#phase-1-extract)
5. [Phase 2 — Transform](#phase-2-transform)
6. [Phase 3 — Transform](#phase-3-load)
7. [Assess and validate the migration](#assess-and-validate-the-migration)
8. [Advanced: extending Siphon](#advanced-extending-siphon)
9. [Troubleshooting](#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.

> **Which tool runs what:**
>
> Every command referenced below is documented in full — required and optional parameters, examples, and conventions — on the command reference pages: [download commands](https://docs.uniform.app/docs/guides/migration/sitecore/download-reference) and [migrate commands](https://docs.uniform.app/docs/guides/migration/sitecore/migrate-reference). This walkthrough links directly to the relevant command as it comes up.

## 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.
- Be able to deploy a file to every Sitecore **CD** instance (that is where the migration service goes — deploying to the whole farm is what makes item and media extraction fast).
- Have administrator access to the Sitecore **CM** server (the Experience Editor renders there, so `download-presentation` needs it).

## 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](https://docs.uniform.app/docs/guides/migration/sitecore/install). 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](https://docs.uniform.app/docs/guides/migration/sitecore/common-reference#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`](https://docs.uniform.app/docs/guides/migration/sitecore/common-reference#logging). 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.

```powershell
PS C:\migration> siphon migration uniform-canvas
```

See [`uniform-canvas`](https://docs.uniform.app/docs/guides/migration/sitecore/migrate-reference#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.

```powershell
PS C:\migration> siphon migration uniform-content
```

See [`uniform-content`](https://docs.uniform.app/docs/guides/migration/sitecore/migrate-reference#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`](https://docs.uniform.app/docs/guides/migration/sitecore/push-reference#uniform-upload-assets) restricts the upload to media actually referenced by content.

```powershell
PS C:\migration> siphon migration uniform-upload-assets
```

See [`uniform-upload-assets`](https://docs.uniform.app/docs/guides/migration/sitecore/push-reference#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:

```powershell
PS C:\migration> siphon migration post-process-assets
```

**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`](https://docs.uniform.app/docs/guides/migration/sitecore/push-reference#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.

```powershell
cd C:\migration\uniform
npm install
npm run uniform:push:content
```

See [`uniform:push:content`](https://docs.uniform.app/docs/guides/migration/sitecore/push-reference#uniform-push-content).

### Push Canvas

Push the generated Canvas data to your Uniform project.

```powershell
cd C:\migration\uniform
npm run uniform:push:canvas
```

See [`uniform:push:canvas`](https://docs.uniform.app/docs/guides/migration/sitecore/push-reference#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.
- Behind a load balancer, confirm the file is on **every** CD node — if it is missing from one, requests fail only when the balancer routes there, which reads as a flaky network rather than a missing file.

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