Documentation

# FileSystem migration connector

Migrates documents from a local or network filesystem to SharePoint, and exports SharePoint documents back to a filesystem.

Built-in: integrated in Epona.Sharepoint.Client.dll — no separate connector DLL required.

Audience

Technical consultants with SharePoint and Epona365 knowledge. Read the migration overview before starting.

# What it does

  • Excel-driven import — reads an import Excel file listing source files and their target SharePoint locations
  • Database-driven import — queries a SQL database to produce the import file, enabling large-scale or automated migrations
  • Metadata upload — preserves document author, creation date, modification date, and custom metadata columns
  • Version migration — imports multiple versions of a document using the __v<number> filename convention
  • Folder mapping — transforms source folder paths to SharePoint paths via configurable replacement rules
  • File filtering — skips system files, hidden files, temp files, and import files automatically
  • Export to filesystem — exports all documents from SharePoint matter libraries to a local or network folder on a schedule
  • Error reporting — exports failed and cancelled items to an Excel file for review and retry

# How it differs from other connectors

Unlike the OpenText, iManage, or Box connectors, the FileSystem connector:

  • Requires no vendor API or database — reads files directly from any accessible drive or UNC path
  • Uses an import-file approach — the consultant prepares an Excel file or SQL query that describes exactly which source files go to which SharePoint location
  • Is built in — no connector DLL needs to be deployed; the class library ships inside Epona.Sharepoint.Client.dll

# Prerequisites

  • Source files accessible on a local drive or UNC network path
  • An import Excel file with the required columns (see Import columns), or a database connection with a query that returns import item columns
  • Target SharePoint matter sites provisioned by Epona ProvisioningService
  • SharepointCfg JSON file configured with the target SharePoint tenant credentials

# Deployment

No additional DLL is required. The connector is included in Epona.Sharepoint.Client.dll, which ships with Epona.Migrate.

  1. Start Epona.Migrate.exe — the FileSystem tab appears automatically
  2. Prepare your import file (Excel file or database query)
  3. Create a FileSystem configuration (see Step 1)

# Step 1 — Configure settings

In the FileSystem tab, click the ... button next to the configuration dropdown to open the FileSystem Configuration editor. Settings are grouped into three categories.

# Global

Setting Type Default Description
Name string — Required. Unique name for this configuration — saved as Config\FileSystem\{Name}.json
Debug bool false Enable verbose debug logging
TimeZone int 2 The timezone that the Created and Modified values in the import file represent. The connector converts these local timestamps to UTC using this setting before writing them to SharePoint. Select the correct value from the dropdown in the configuration editor

Set the correct timezone before migrating

TimeZone only applies when the import Excel file or database query explicitly provides Created or Modified values (file-based imports). The connector treats those values as local time in the selected timezone and converts them to UTC before writing to SharePoint.

For directory-based imports (rows with SourceDirectory), timestamps are read directly from the filesystem as UTC — TimeZone has no effect on those files.

If the wrong timezone is selected, every document whose timestamp comes from the import file will be stored with an incorrect timestamp in SharePoint, and there is no automated way to fix this without re-migrating. It has nothing to do with the local machine's timezone or the SharePoint site's regional setting.

Confirm the timezone of the source data with the client before starting a file-based import.

# Migrate

Setting Type Default Description
ReplaceFolders string — Maps source folder paths to SharePoint target paths. Applied before uploading each document. See Folder path mapping for full syntax, special tokens, and examples

# Database

Used when loading the import file from a SQL database instead of an Excel file. Both DatabaseConnectionString and DatabaseSql must be set to activate database mode.

Setting Type Default Description
DatabaseConnectionString string — ADO.NET connection string or a named connection string from the application config
DatabaseSql string — SQL query that returns import item rows, or a path to a .sql or .txt file containing the query (resolved relative to the Epona.Migrate application directory). The query must return columns matching the import file column names (see Import columns)
DatabaseConnectionStringProviderName string — ADO.NET provider factory name. Leave empty for SQL Server (defaults to System.Data.SqlClient). Only set this for non-SQL-Server databases. Provider names are listed in the ADO.NET overview (opens new window) or can be queried via DbProviderFactories.GetFactoryClasses(). Common values: System.Data.OleDb, System.Data.Odbc
DatabaseCommandTimeout int (seconds) 30 SQL command timeout in seconds. Increase for large queries that exceed the default timeout

# Step 2 — Prepare the import file

The import file defines which source files are migrated and where they land in SharePoint. Provide it as an Excel file or a SQL query (configured in the Database settings).

# Import columns

All columns except SourceFile or SourceDirectory are optional.

Column Type Description
SourceFile string Absolute path to the source file. Provide either this or SourceDirectory
SourceDirectory string Absolute path to a directory — all files in the directory and all subdirectories (at any depth) are imported. The subdirectory structure is preserved as target folder paths within the document library
MatterCode string Matter code used to resolve the SharePoint document library URL. Use either MatterCode or DoclibUrl — not both
ClientCode string Optional client code used together with MatterCode for resolving the SharePoint document library URL
DoclibUrl string Direct SharePoint document library URL. Use either DoclibUrl or MatterCode — not both
TargetFolder string Subfolder path within the document library. For SourceFile rows: the file is placed directly in this folder; ReplaceFolders is applied to it. For SourceDirectory rows: acts as a root prefix — the relative subfolder from the directory scan is appended to it, and ReplaceFolders is then applied to the combined path. Example: TargetFolder=Contracts, file in subdirectory Old → combined path Contracts\Old → ReplaceFolders applied to Contracts\Old
DocumentName string Override the filename in SharePoint. Defaults to the source filename
Modified datetime Modification date stored in SharePoint. Primarily used with SourceFile rows to set a per-file date. When absent, the file's filesystem LastWriteTimeUtc is used instead (no timezone conversion). When set on a SourceDirectory row, the same value is applied to every file in the directory
Created datetime Creation date stored in SharePoint. Same behaviour as Modified above
DocumentVersionNumber int Version number for multi-version imports
Source string Grouping key that identifies a document across all its versions and across migration runs. When not set, the connector derives it automatically: if DocumentVersionNumber is set, Source is {SourceFile directory}\{DocumentName}; otherwise it is the SourceFile path. Set it explicitly when version files live in different directories (e.g., database-driven imports where each version is stored separately). All rows with the same Source value are treated as versions of the same document. The Source value is also the key used for delta tracking — it must be stable and unique per document across all runs of the same migration. See Version migration
(any other column) any Stored as a custom SharePoint column value

# Automatic file filtering

The connector skips the following files during directory scans:

  • Hidden files and system files
  • Extensions: .tmp, .nrl, .url, .ds_store
  • System files: Thumbs.db, desktop.ini, ehthumbs.db, .DS_Store
  • Import files: files starting with _DMSforLegalImport (.xls, .xlsx), DMSforLegalImport_ (.csv)
  • Export files: files starting with _DMSforLegal_ExportDocuments (.xlsx)
  • Legacy migration file lists: files.csv, _WSExporterFiles.csv
  • Reparse points (symlinks and junctions)
  • __MACOSX macOS metadata directories

# Step 3 — Import (filesystem → SharePoint)

  1. Select the FileSystem configuration from the FileSystem dropdown
  2. Select the SharePoint environment from the main window SharePoint Environment dropdown
  3. Select the import source:
    • Excel — browse to and select the prepared import Excel file
    • Database — set UseDatabaseSource in the configuration; the connector uses the DatabaseConnectionString and DatabaseSql settings
  4. Set the import options (see table below)
  5. Click Import

# Import options

Option Description
Ignore existing shortcuts When enabled, .url shortcut files next to source files are ignored. When disabled (default), the shortcut's modification date is used as a fast-path skip check — see Shortcut-based skip below
Hide shortcuts When enabled, the .url shortcut created after upload (see FileSystemCreateShortcuts) is marked as hidden in the source directory
Import empty directories When enabled, SourceDirectory rows also create empty folders in SharePoint for source directories that contain no importable files

What happens during Import:

# 1. Load rows

All rows are loaded from the Excel file or SQL query.

# 2. Group by target document library

Rows are grouped by DoclibUrl, or by MatterCode + ClientCode when no DoclibUrl is set. Each group is processed as a separate parallel task, so multiple matters are migrated concurrently. Multiple rows pointing to the same matter — whether SourceFile or SourceDirectory — are merged into the same task and share one SharePoint connection.

# 3. Expand SourceDirectory rows

Within each group, SourceDirectory rows are expanded first: the connector scans the directory recursively, applies automatic file filtering, and creates one item per discovered file. The relative subfolder path is combined with any TargetFolder value from the row. SourceFile rows are kept as-is. The result is a flat list of individual files — regardless of how the original rows were specified.

# 4. Apply ReplaceFolders

ReplaceFolders rules are applied to each file's resolved TargetFolder path (the combined path for directory-sourced files). A rule returning null (via __SKIP__) marks the file as skipped.

# 5. Upload files

Each file is uploaded to SharePoint with its resolved target folder, metadata, and timestamps. For SourceFile rows, Created/Modified from the import file are converted from the configured TimeZone to UTC. For files sourced from a directory (no explicit timestamps), the filesystem LastWriteTimeUtc/CreationTimeUtc are used directly.

Multiple source directories to one matter

Because rows with the same matter code are merged into one task, you can map multiple source directories to a single document library — each as a separate SourceDirectory row with the same MatterCode. Use TargetFolder on each row to route them to different subfolders within the library.

No duplicate detection

If two rows resolve to the same filename in the same target folder, the second file overwrites the first (or is uploaded as a new version if versioning is enabled). There is no built-in deduplication.

# 6. Create shortcuts (optional)

If FileSystemCreateShortcuts is enabled, a .url internet shortcut is written next to each source file after successful upload, pointing to the document in SharePoint.

# 7. Export error report

Failed and cancelled items are written to an Excel error report saved next to the import Excel file.

# Version migration

Two approaches are supported: filename convention and explicit column.

# Filename convention (__v<number>)

Name source files with a __v<number> suffix. The connector strips the suffix from the SharePoint filename, parses the version number, and groups files with the same base name and directory as versions of the same document:

Contract__v1.docx   → version 1
Contract__v2.docx   → version 2
Contract__v3.docx   → version 3 (current)

All three files must be in the same source directory. The SharePoint document name will be Contract.docx for all versions.

# Column-based versioning

Include a DocumentVersionNumber column in the import file. Each row is one version of a document. Rows are grouped as versions of the same document when they resolve to the same Source key — which is derived from the source file's directory combined with DocumentName. This means:

  • DocumentName must be identical across all version rows
  • SourceFile paths must be in the same directory
  • Or set an explicit Source column to the same value on all version rows — useful when version files are in different directories (e.g., database-driven imports where each version is stored separately). The Source value can be any unique identifier such as a document number:
Source SourceFile DocumentName DocumentVersionNumber
DOC-12345 \\archive\v1\contract.docx Contract.docx 1
DOC-12345 \\archive\v2\contract_final.docx Contract.docx 2
DOC-12345 \\archive\v3\contract_signed.docx Contract.docx 3

All three rows share Source=DOC-12345, so they are uploaded as versions of the same SharePoint document regardless of their source paths.

Decimal version numbers are supported: 1.0 and 2.0 are major versions; 1.1 and 1.2 are minor versions.

# Ordering and target

Regardless of approach, versions are always uploaded in ascending DocumentVersionNumber order. The lowest version is uploaded first, the highest last (becoming the current version).

Same `TargetFolder` required for all versions

TargetFolder is not part of the version grouping key. All rows that belong to the same document version set must have the same TargetFolder value. Mismatched values produce unpredictable results.

# Delta migration

Every import run uses a migration database to track which files have already been migrated. Selecting a database is mandatory — the main window Database dropdown must be set before import can start.

The database records each migrated file in an _EDMSDocument table with the following information:

Column Description
Source The source key (same value used for version grouping)
SourceVersion Version identifier from the import file
SourceLastModified Modification timestamp of the file at the time it was last migrated
TargetDocLib SharePoint document library URL
TargetFolder Target folder within the library
TargetFileName Filename in SharePoint
SharepointFileId SharePoint file identifier
Error Error message if the last upload failed

Skip logic: Before uploading a file, the connector checks the tracking record for the same Source key. If the file was previously migrated successfully (no error, TargetFileName set) and the new modification timestamp is not newer than SourceLastModified, the file is skipped. If the file has been modified since the last migration, it is re-uploaded using overwrite versioning. Files with errors in the database are never skipped — they are always retried. Use the migration database report to identify which matters and files have errors and need reprocessing.

# Shortcut-based skip

When FileSystemCreateShortcuts is enabled, a .url internet shortcut is written next to each source file after upload. On the next import run, this shortcut is checked before the database delta check:

  1. If a .url shortcut exists next to the source file, the Modified= value stored inside it is read. This value is the source file's modification date at the time of the last migration — written into the shortcut during upload or skip.
  2. That stored modification date is compared to the current source file's modification date (Modified from the import file, or LastWriteTimeUtc from the filesystem if not set in the import file):
    • Stored date ≥ current file modification date → file has not changed since the last migration → skip immediately (database check is not reached)
    • Stored date < current file modification date → file has been modified since the last migration → the shortcut's SharePoint URL is used as the upload target (overwrite), and the database delta check runs as normal
  3. If no shortcut exists, the shortcut check is skipped and only the database delta check applies.

The Ignore existing shortcuts option disables this check entirely. When enabled, shortcut files are ignored and the database delta check is the only skip mechanism. Use this when shortcuts are unreliable — for example, when files were previously migrated to a different SharePoint environment and the shortcuts point to the wrong URLs.

Database setup: The database schema is created automatically on first use. Both SQLite (a local .db file) and SQL Server are supported. SQLite is the default and sufficient for most migrations. For large migrations (250,000+ documents) or multiple concurrent runs, SQL Server is recommended for better performance and reliability.

Use the same database for every run of the same migration

The _EDMSDocument table is the only record of what has already been migrated. If a different database is selected — or the database file is moved, deleted, or recreated — the connector has no way to know which files were already uploaded. Every file in the import will be treated as new and migrated again, producing duplicate documents in SharePoint.

Always store the database file in a safe, permanent location and select the same database for every run of the same migration project.

# Dump tools

The Dump group on the Import tab contains utilities for scanning a source directory and generating an import Excel file. Use these to prepare or verify the import file before running the migration.

Select a FileSystem configuration before using any Dump tool — the configuration is used when generating the output file.

Option Description
Skip imported directory/files When enabled, directories that already have a .url shortcut file are excluded from the scan (treated as already migrated)

# Directories

Scans a root directory and produces an Excel file mapping each subdirectory to a matter code.

  1. Click Directories
  2. Browse to the root directory to scan (all subdirectories are scanned recursively)
  3. Optionally select an Excel file containing matter codes (MatterCode column, or the first column if absent) — used to match matter codes against directory names
  4. Browse for the output Excel file

Output columns: Directory, DirectoryLevel, MatterCode, TargetFolder, FileCount, Error

A directory is matched to a matter code when the directory name contains the code as a distinct word (case-insensitive). Subdirectories of a matched directory inherit the same matter code with a relative TargetFolder path.

# Files

Same as Directories but also lists individual files within each directory. Use this to inspect which files will be imported and identify any that would be blocked by SharePoint.

# Permissions

Dumps NTFS permissions for the source directories listed in the selected import Excel file to a new Excel file. Requires an import Excel file to be selected first.

Two confirmation prompts appear before the dump runs:

  • Include files? — whether to include file-level NTFS permissions in addition to directory permissions
  • Create a site entry? — whether to add a root site row to the output

# Analyze

Reads the selected import Excel file, deduplicates SourceDirectory + MatterCode rows, and saves the unique rows to a new Excel file next to the original ({filename}_Unique_{timestamp}.xlsx). Useful for finding duplicate or overlapping source directory entries before importing.

# Report

The Report button on the Import tab generates a migration status Excel report from the selected database — the same report is available on all connector tabs. See Migration database report for the full report description.

# Configuration file location

FileSystem configurations are saved as JSON files in:

[Epona.Migrate.exe directory]\Config\FileSystem\{Name}.json

Each named configuration is a separate file. Renaming a configuration (changing the Name field) renames the file and deletes the old one.

# General migration settings (SharepointCfg)

The SettingsCfg.Migrate section of the SharepointCfg controls migration behaviour shared across all connectors. The setting below is specific to FileSystem migrations.

Setting Default Description
FileSystemCreateShortcuts false When enabled, creates a .url internet shortcut file in the source directory after each document is successfully migrated. The shortcut points to the document in SharePoint

See the migration overview for the full settings reference.

# Troubleshooting

# Documents not uploaded

  • Cause: Matter code not found in SharePoint
  • Resolution: Verify the matter code in the manifest matches an active matter. Check the error report Excel file in the Migrate\ directory for details

# Target folder not created

  • Cause: TargetFolder path contains characters not allowed in SharePoint folder names
  • Resolution: Remove or replace the characters \ : * ? " < > | in the TargetFolder column of the manifest

# Incorrect SharePoint timestamps

  • Cause: Timezone mismatch between the source system and the configured TimeZone value
  • Resolution: Set TimeZone to the Windows timezone ID matching the source system's locale

# Files skipped unexpectedly

  • Cause: File extension or name matches the automatic filter list
  • Resolution: Rename source files to avoid the filtered patterns, or check whether the file is hidden or a system file

# Database query times out

  • Cause: Large result set exceeds the default 30-second command timeout
  • Resolution: Increase DatabaseCommandTimeout to accommodate the query duration
Last Updated: 5/11/2026, 2:44:29 PM