Migrating On-Prem File Servers to SharePoint and OneDrive

This guide provides a detailed, step-by-step process for migrating data from an on-premises file server to SharePoint Online or OneDrive for Business using the SharePoint Migration Tool (SPMT).

TL;DR

• Scan First: Always scan source files with SPMT to identify issues like long paths, unsupported characters, and large files before migration
• Use Bulk Task Files: Define migration tasks using JSON or CSV to specify sources, targets, and settings
• Replication, Not Deletion: SPMT copies data—it does not delete or alter source files
• Mind the Limits: File size (250 GB), path length (400 characters), and unsupported file types will be skipped

Background and Scope

This procedure applies to IT administrators managing file server data migrations into SharePoint or OneDrive. The migration process copies data only—no data is deleted from the source. Place migrated files in a dedicated folder (e.g., "Migrated Files") to prevent confusion.

Prerequisites

Requirement	Details	Notes
SharePoint Migration Tool (SPMT)	Latest version	Download from Microsoft
User Accounts	Active in Microsoft 365	Users must have signed into OneDrive at least once
Permissions	Administrator access	Local admin on source; Site Collection Admin on target
Network	Internet access	Verify firewall/proxy allows M365 endpoints
Target Storage	Sufficient capacity	Confirm adequate space in target location
Task Definition File	CSV or JSON	Required for migration source/target mappings

Procedure

Step 1 – Scan the On-Prem File Share

Before migrating, scan the source to identify potential issues.

1. Create the Scanning CSV:

   scan-source.csv

   File Path,File Type
   \\fileserver\share\folder1,Folder
   \\fileserver\share\folder2,Folder

2. Run the SPMT Scan: Open SPMT → Scan Source → Upload CSV

3. Review Scan Results: Analyze reports for:

   • Unsupported files
   • Files exceeding size/path limits
   • Invalid characters or reserved names

4. Remediate Issues:

   • Rename files with invalid characters
   • Exclude temporary/system files
   • Restructure directories to shorten paths
   • Split files larger than 250 GB

Step 2 – Create the Task JSON for Migration

For bulk migrations, use a JSON file to define all tasks.

migration-tasks.json

{
  "Tasks": [
    {
      "SourcePath": "\\\\fileserver\\share\\folder1",
      "TargetPath": "https://tamucs-my.sharepoint.com/personal/joe_aggie_tamu_edu",
      "Settings": {
        "PreserveSharePermissions": true,
        "MigrateHiddenItems": true,
        "SkipFilesWithExtensions": ["tmp", "log"]
      }
    },
    {
      "SourcePath": "\\\\fileserver\\share\\folder2",
      "TargetPath": "https://tamucs-my.sharepoint.com/personal/jane_aggie_tamu_edu",
      "TargetList": "Documents",
      "TargetListRelativePath": "Migrated Files"
    }
  ]
}

Key JSON Fields:

Field	Description
SourcePath	UNC path to source (backslashes escaped: \\)
TargetPath	Full URL for OneDrive or SharePoint library
TargetList	List/library name (e.g., "Documents")
TargetListRelativePath	Folder to create for migrated content

Username Formatting

When constructing OneDrive TargetPath, replace special characters with underscore (_), except hyphens.

Example: joe.aggie@tamu.edu → joe_aggie_tamu_edu

Step 3 – Run the Migration

1. Load the JSON File: Open SPMT → Select migrate → Upload JSON task file
2. Review and Start: Verify source/target mappings → Begin migration
3. Monitor Progress: Watch real-time progress and generated logs

Step 4 – Post-Migration Validation

1. Verify Target Data: Manually check files and folder structure
2. Review Migration Reports:
   • Summary Report: High-level success rates
   • Task-Level Report: Individual task status
   • Error Report: Issues requiring resolution
3. Notify Users: Provide testing window for verification

Reference

How SPMT Works

Aspect	Details
Data Flow	Source → Azure Blob Storage (temp) → SharePoint/OneDrive
Security	HTTPS in transit, encrypted at rest
Resilience	Automatic retry, resume interrupted migrations
Scalability	Agent groups for distributed workloads

Common Settings

Setting	Description
PreserveSharePermissions	Migrate folder-level share permissions
MigrateHiddenItems	Include hidden files and folders
MigrateOneNoteNotebook	Migrate OneNote folders as notebooks
SkipFilesWithExtensions	Array of extensions to exclude

File and Path Limitations

Limit	Value
File Size	250 GB maximum
File Path Length	400 characters (full URL-decoded path)
File Name Length	260 characters

Unsupported Files

• Temporary files (.tmp, ~*)
• System files (.lnk, desktop.ini, .ds_store)
• Reserved names (CON, PRN, AUX, COM1.txt)
• Files with names ending in space or period
• Hard links and junction points
• Locked files in active use

Related Resources

• Official SPMT Documentation
• SPMT JSON/CSV Format Guide
• SPMT Performance Guidance
• SharePoint Permissions Guide