Uniform Siphon - Downloading Sitecore CMS Migration Walkthrough

This guide walks you through the complete process of downloading content, media, and presentation details from Sitecore CMS for further migration to the Uniform platform.

  1. Overview
  2. Prepare work directory
  3. Prepare Sitecore
  4. Configure Siphon
  5. Download data
  6. Troubleshooting
  7. Next steps

The migration process happens in 3 logical phases:

  • Source content and media is downloaded from Sitecore with siphon to a Windows machine
  • Downloaded data is processed with Siphon.Migration.exe and Uniform files are produced
  • Uniform files are pushed to Uniform using Uniform CLI (@uniformdev/cli)

This guide only touches the first phase.

  • Ensure sufficient disk space for downloaded content
  • Have administrator access to the Sitecore CM server

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} command that have particular parameter.

For example:

# works for all commands with --outputDir param $env:SIPHON_OUTPUTDIR='C:\migration\sitecore\items' # works for `download-items` command only $env:SIPHON_DOWNLOAD_ITEMS_OUTPUTDIR='C:\migration\sitecore\items'

Siphon reads first .env file it can find from:

  • Current working directory
  • Siphon executable directory

Siphon comes with a built-in serilog logger. It creates several log files in the current directory:

C:\migration\ ├── ... ├── .siphon.log.debug.txt ├── .siphon.log.info.txt ├── .siphon.log.warn.txt ├── .siphon.log.error.txt └── ... other files

The log level is configured with SIPHON_LOGLEVEL (or --logLevel parameter) that takes these values:

  • DEBUG
  • INFO
  • WARN
  • ERROR

It is recommended to use the default INFO and switch to DEBUG only if something goes wrong.

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:\> cd C:\migration PS C:\migration>

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

  1. Rename C:\siphon\UniformMigrationService.txt to UniformMigrationService.aspx
  2. Open UniformMigrationService.aspx
  3. Set a secure secret and valid until on Lines 5-7:
    // the default secret will not work, you must change it const string Secret = "(your-complex-secret-phrase-here)"; const string ValidUntil = "(date-which-is-several-month-in-the-future)"
  4. Save changes
  1. Upload the modified file to your Sitecore CM instance's 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 the browser — it is expected to see a SecurityException

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.

In the current terminal window run configuration wizard and follow the instructions:

PS C:\migration> siphon configure-download

Here's example output:

======================================================================= Siphon Download Configuration Wizard ======================================================================= This wizard will help you configure the Siphon Download phase. It will generate a .env file with all necessary settings. Press Enter to accept values shown in [brackets]. ----------------------------------------------------------------------- Work Directory ----------------------------------------------------------------------- Base directory for all downloaded files. Subdirectories will be created: \items, \media, \presentation > Work Directory [default: C:\migration]: ----------------------------------------------------------------------- Common Settings (used by all download commands) ----------------------------------------------------------------------- The Sitecore database to download from (e.g., 'web' or 'master'). > Database [default: web]: Full URL to the deployed UniformMigrationService.aspx on your Sitecore CM. Example: https://sc.dev/layouts/UniformMigrationService.aspx > Uniform Service URL: This field is required. Please enter a value. > Uniform Service URL: https://sc.dev/layouts/UniformMigrationService.aspx The secret phrase configured in UniformMigrationService.aspx (Line 5). > Secret: This field is required. Please enter a value. > Secret: ***** ----------------------------------------------------------------------- 1. Download Items Settings ----------------------------------------------------------------------- Root item GUID to start downloading from (with all descendants). It is typically the Home item. In a multi-site solutions there are 2 options: - Download sites one by one - Download everything by using root ID: 11111111-1111-1111-1111-111111111111 > Root Item ID: This field is required. Please enter a value. > Root Item ID: ITEM-ID-OF-YOUR-HOMEPAGE Languages to download (comma-separated, e.g., 'en,ja-JP,da'). Leave empty to download all registered languages. > Languages: en,da Number of parallel download threads (1-16). > Threads [default: 4]: Download rendering datasource items outside of root? Unsure or in doubt? Use the default option. > Download Renderings Datasources [Y/n]: Download field-referenced items outside of root? Unsure or in doubt? Use the default option. > Download Fields References [Y/n]: ----------------------------------------------------------------------- 2. Download Media Settings ----------------------------------------------------------------------- Number of parallel download threads for media (1-16). > Threads [default: 4]: ----------------------------------------------------------------------- 3. Download Presentation Settings (Optional) ----------------------------------------------------------------------- Presentation download captures page layouts using Playwright. This is optional - skip if you only need content migration. Unsure or in doubt? Use the default option. > Configure presentation download? [Y/n]: Sitecore Host URL (base URL of your Sitecore instance). Example: https://sc.dev/ > Sitecore Host: https://sc.dev/ Path to the site root item in Sitecore. Example: /sitecore/content/Habitat/Home > Start Path: /example/path/to/your/first/site/home/item Virtual path to download a sub-set of the website (optional). Example: /about-habitat (leave empty for entire site) > Virtual Path: Sitecore login page URL for authentication. Example: https://sc.dev/sitecore/login > Login URL: https://sc.dev/sitecore/login Sitecore username for presentation download. > Username: admin Sitecore password for presentation download. > Password: * Number of parallel download threads (1-8). > Threads [default: 4]: [OK] Configuration saved to: .env ======================================================================= Configuration Summary ======================================================================= Work Directory: C:\migration Common: Database: web Service URL: https://sc.dev/layouts/UniformMigrationService.aspx Secret: ******** Download Items: Root: ITEM-ID-OF-YOUR-HOMEPAGE Output: C:\migration\items Threads: 4 Download Media: Input: C:\migration\items Output: C:\migration\media Threads: 4 Download Presentation: Host: https://sc.dev/ Start Path: /example/path/to/your/first/site/home/item Login URL: https://sc.dev/sitecore/login Threads: 4 ======================================================================= Next Steps: ======================================================================= 1. Copy the .env file to your migration working directory 2. Run the download commands: siphon download-items siphon download-media siphon download-presentation

First, download content items:

PS C:\migration> siphon download-items

Verify the command returned no critical errors and exit code is 0. If the error code is not 0, halt and contact Uniform migration team.

All download commands support resuming downloading: if it failed after 2 hours, it won't try to download what's already there.

Next, run two remaining commands. These commands are independent and can be run in parallel, although it is not recommended.

PS C:\migration> siphon download-media PS C:\migration> siphon download-presentation

When everything is complete, review the downloaded files:

C:\migration\ ├── items\ │ ├── _languages.json # Available languages │ └── {language}\ │ ├── index.json # Language-specific index │ └── {item-id}.json # Individual items ├── media\ │ ├── _languages.json # Available languages │ └── ...Binary media files └── presentation\ ├── test-results # For azure devops reporting tool └── {language}\ ├── {first-level-children}\ │ ├── {second-level-children}\ │ │ ├── .... │ │ ├── index.html │ │ └── index.json │ ├── index.html │ └── index.json ├── index.html └── index.json

  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. Authentication failures in presentation download

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

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

When downloading is completed, upload the C:\migration directory to the provided URL and contact Uniform migration team.

Alternatively, you can migrate the data yourself:

Last modified