Documentation

# Document migration

The Epona migration system provides tools for moving documents and their metadata from legacy or external document management systems into SharePoint during provisioning.

Audience

Anyone new to the Migrator. Read the ProvisioningService overview first — the Migrator assumes the SharePoint environments it migrates into have already been provisioned.

# What Epona Migrator does

Epona.Migrate (Epona.Migrate.exe) is a Windows Forms desktop application that migrates documents and their metadata from legacy Document Management Systems (DMS) into SharePoint Online matter sites provisioned by Epona ProvisioningService. It handles the full migration pipeline: scanning the source, building a migration manifest, uploading files, monitoring progress in real time, and reporting on errors.

The application supports two migration modes:

  • Direct CSOM upload — standard mode, suitable for smaller volumes
  • Azure Blob Storage migration — high-speed mode using SharePoint's native Migration API, recommended for large volumes (500+ documents). This path bypasses throttling limits that affect CSOM.

# Supported source systems (plugins)

Each source DMS is supported by a plugin DLL (Epona.Migrate.[Source].dll) loaded at startup. Plugins add a tab to the main window. Only plugins whose DLL is present in the application directory are loaded.

Plugin assembly Source system
(built-in) Windows file system (network shares, local folders)
Epona.Migrate.Advosys.dll Advosys legal DMS
Epona.Migrate.Box.dll Box cloud storage
Epona.Migrate.iManage.dll iManage Work (on-premises)
Epona.Migrate.iManageWeb.dll iManage Work (cloud / Web API)
Epona.Migrate.NextMatters.dll NextMatters matter management
Epona.Migrate.OpenText.dll OpenText eDocs (SQL Server-backed DMS)
Epona.Migrate.Sharepoint.dll SharePoint-to-SharePoint migration (re-migration or tenant move)
Epona.Migrate.Worldox.dll Worldox document management

Each client deployment typically includes only the relevant plugin(s).

# The migration database

Every migration uses a local SQLite or SQL Server database (configured via the Create/Edit Database button) that tracks every document, its migration state, job IDs, errors, and warnings. This database is the single source of truth for migration progress. For SQLite, the database file is created automatically if it does not yet exist. For SQL Server, the database must already exist on the server — the Migrator only creates the schema (tables) on the first Import run, if it doesn't exist yet. Retain the database until the migration is verified complete.

The same database is used across multiple migration runs for the same engagement — resuming after a failure uses the database to skip already-migrated documents.

Exception — OpenText plugin

The OpenText plugin does not use a separate migration database. It connects directly to the OpenText SQL Server database and creates a tracking table (_ToDMSforLegal) in that database. See the OpenText connector for details.

# High-level migration phases

Phase What happens
Scan The source DMS is scanned; documents and folders are written to the migration Excel file and/or the migration database
Prepare The migration manifest (Excel or database source) is read and validated against the SharePoint target structure
Upload Files are uploaded to Azure Blob Storage containers (encrypted at rest by SharePoint's Migration API) or pushed directly via CSOM for small volumes
Submit An Azure Blob Migration Job is submitted to SharePoint's Migration API; SharePoint processes files in the background
Monitor The Monitor window polls Azure Queue messages for progress events (files created, errors, warnings, job end)
Cleanup Job records are finalised in the database; error reports are generated
Delta / Resubmit On subsequent runs, the migration database is checked for already-processed documents — these are skipped. Only documents that are new or have changed since the previous run are uploaded. This allows incremental top-up runs without re-migrating the full set.

# Prerequisites before first use

  1. SharePoint Online environments (matter sites) must already be provisioned by Epona ProvisioningService
  2. A SharepointCfg JSON file must exist in Config\ (shared with the Configurator)
  3. A migration database must be created via the Create/Edit Database button before running any migration
  4. For Azure Blob Storage mode: no manual Azure setup is required — SharePoint automatically provisions the Blob containers and Queue via the Migration API (opens new window) when the first migration job is submitted
  5. The machine running the Migrator must have read access to the source DMS (network share, API credentials, etc.)

# Architecture

The migration system consists of:

Module Responsibility
frmMain Main application window — hosts all plugin tabs, controls Import/Export/Scan operations, manages background worker thread and progress
frmMonitorMigrations Separate window — shows live migration job grid, polls Azure Queue for progress updates
frmMigrationDocuments Shows documents with errors or warnings; allows clearing errors to enable retry
frmMigrationJobDetails Detail view for a single migration job — shows timestamps, file counts, events timeline, log file download
ImportFromFilesystem Core import engine for filesystem-based migrations
AzureBlobMigrationJob Manages a single Azure Blob Migration batch
ImportDatabase All database read/write operations — documents, jobs, events, errors

Source connector plugins implement source-specific authentication, document retrieval, metadata extraction, and SharePoint upload. They are auto-discovered by the migration engine when placed in the same directory as Epona.Migrate.exe.

# General migration settings (SharepointCfg)

Migration behaviour is controlled by the SettingsCfg.Migrate section of the SharepointCfg JSON file. These settings apply to all migration sources unless noted otherwise.

Setting Type Default Description
UseAzureBlobStorage bool false Enable the Azure Blob Storage migration path via the SharePoint Migration API (opens new window). Recommended for 500+ documents. SharePoint automatically provisions the required Blob containers and Queue — no manual Azure setup needed. Not supported by the OpenText plugin.
UseAzureBlobStorageErrorAction enum None What to do with SharePoint documents that fail Azure Blob processing: None (leave as-is), RecycleBin (move to SP recycle bin), Delete (permanently delete). Confirm with the client before starting.
ForceEmailInAutoFilingFolder bool false Always store emails in the AutoFiling folder configured in DMS Configuration
ForceEmailContentType string — Force this content type for all email documents
CleanupOffice2003Documents bool false Strip doc properties and SharePoint default values from .doc/.xls/.ppt/.msg files before upload
CleanupOffice2007Documents bool false Strip doc properties from .docx/.xlsx/.pptx files before upload
CleanupCompletedMonitorDirectory int 14 Remove files from the monitor and log directory after this many days (0 = disabled)

Azure Blob Storage error action

The UseAzureBlobStorageErrorAction setting determines what happens to files with errors at the SharePoint processing stage. None may cause duplicate documents on retry. Always confirm this setting with the client before starting a large migration.

# Getting started

  1. Run Epona.Migrate.exe from the provisioning service bin directory
  2. Select or create a migration database via Create/Edit Database
  3. Open the plugin tab for your source system
  4. Click ... to open the plugin configuration and configure the connection and migration settings
  5. Click Dump to scan the source and produce an overview Excel (clients, matters, document types, users, groups)
  6. Review the dump output to confirm scope and identify user/group mapping needs
  7. Enter the matter codes to migrate in the Workspace(s) text box
  8. Click Import to start the migration
  9. Monitor progress in the progress bar and via the Monitor window (Azure mode) or the log window (CSOM mode)
  10. Click Report to generate a migration status report after the run
  11. Review errors and warnings; clear errors for retry after fixing the root cause

# Upload approaches

Two upload approaches are available. The connector used determines which approaches are supported — check the connector documentation.

# CSOM (direct upload)

Files are uploaded one by one directly to SharePoint via the CSOM API. This is the default and requires no additional infrastructure.

  • Slower for large volumes
  • Suitable for smaller migrations or connectors that do not support Azure Blob

# Azure Blob (SharePoint Migration API)

Files are staged to Azure Blob Storage and pushed to SharePoint in batches via the SharePoint Migration API. Enable by setting UseAzureBlobStorage = true in SettingsCfg.Migrate — no additional Azure configuration required.

  • Significantly faster for large migrations
  • SharePoint processes jobs asynchronously — progress tracked via the monitor window
  • Files larger than 2 GB fall back to CSOM automatically
  • Configurable action for files with errors or warnings at job completion (UseAzureBlobStorageErrorAction: None, RecycleBin, Delete)

See Azure migration jobs and monitor for the full job lifecycle, monitor window reference, and retry workflow.

# Configuration

Migration configuration is typically defined in the same configuration file as provisioning:

  • Source system credentials (API keys, URLs)
  • Field mappings (source field → SharePoint column)
  • Matter/client matching rules
  • Target document library and folder structure
  • Filtering rules to limit scope of migration
Last Updated: 5/11/2026, 2:44:29 PM