Migrating OneDrive Data to SharePoint using PnP PowerShell

Migrating OneDrive files to SharePoint is crucial for better collaboration, document management, and access control. Using PnP PowerShell, you can automate and streamline the migration process while maintaining folder structures, metadata, and permissions.

Introduction
Prerequisites
Connecting to SharePoint and OneDrive
Exporting OneDrive Files and Folders
Uploading Files to SharePoint Document Library
Maintaining Folder Structure
Setting Metadata and Permissions
Verifying Migration
Automating the Migration
Best Practices
Conclusion

1. Introduction

Migrating data from OneDrive for Business to SharePoint Online is often needed when transitioning from personal storage to team collaboration. This guide covers:
Exporting files and folders from OneDrive
Uploading them to a SharePoint Document Library
Maintaining metadata and folder hierarchy
Assigning permissions

By using PnP PowerShell, you can perform this migration efficiently and at scale.

2. Prerequisites

Before starting, ensure:

You have PnP PowerShell installed. If not, install it using: Install-Module -Name PnP.PowerShell -Scope CurrentUser -Force
You have SharePoint Administrator or Site Owner permissions.
You have access to the OneDrive account (Admin or User-level).
You have the SharePoint Document Library URL where files will be migrated.

3. Connecting to SharePoint and OneDrive

First, authenticate with SharePoint Online and OneDrive.

Step 1: Connect to OneDrive

$OneDriveURL = "https://yourtenant-my.sharepoint.com/personal/username_domain_com/Documents"
Connect-PnPOnline -Url $OneDriveURL -Interactive

Replace yourtenant with your actual tenant name.
Replace username_domain_com with the user’s OneDrive URL structure.

Step 2: Connect to SharePoint

$SharePointSiteURL = "https://yourtenant.sharepoint.com/sites/YourTeamSite"
Connect-PnPOnline -Url $SharePointSiteURL -Interactive

Replace YourTeamSite with your actual SharePoint site name.

4. Exporting OneDrive Files and Folders

Retrieve all files and folders from OneDrive.

Step 1: Get OneDrive Files List

$OneDriveFiles = Get-PnPListItem -List "Documents" -Fields FileRef, FileLeafRef

This command fetches all files from the OneDrive Documents Library.

Step 2: Download Files to Local Storage

$LocalBackupPath = "C:\OneDriveBackup"
if (!(Test-Path -Path $LocalBackupPath)) { New-Item -ItemType Directory -Path $LocalBackupPath }

foreach ($File in $OneDriveFiles) {
    $FileUrl = $File["FileRef"]
    $FileName = $File["FileLeafRef"]
    $LocalPath = Join-Path -Path $LocalBackupPath -ChildPath $FileName

    Get-PnPFile -ServerRelativeUrl $FileUrl -Path $LocalPath -AsFile -Force
}

This script downloads all OneDrive files to the local machine.
The directory C:\OneDriveBackup will store the files before uploading to SharePoint.

5. Uploading Files to SharePoint Document Library

Once downloaded, upload them to the target SharePoint Document Library.

Step 1: Define SharePoint Library URL

$SharePointLibrary = "Shared Documents"

Replace "Shared Documents" with your target library name.

Step 2: Upload Files

foreach ($File in Get-ChildItem -Path $LocalBackupPath) {
    Add-PnPFile -Path $File.FullName -Folder $SharePointLibrary
}

This command migrates files from your local backup folder to SharePoint Online.

6. Maintaining Folder Structure

To keep the same folder hierarchy, you need to recreate folders in SharePoint.

Step 1: Get OneDrive Folder Structure

$OneDriveFolders = Get-PnPListItem -List "Documents" -Fields FileRef, FileLeafRef | Where-Object { $_["FileRef"] -match "/Forms/" -eq $false }

This command extracts folders excluding system-generated directories like Forms.

Step 2: Create Folders in SharePoint

foreach ($Folder in $OneDriveFolders) {
    $FolderPath = $Folder["FileRef"] -replace "/personal/username_domain_com/Documents", ""
    New-PnPListItem -List $SharePointLibrary -Values @{"FileLeafRef" = $FolderPath}
}

This creates empty folders in SharePoint before uploading files.
Ensure that the FolderPath mapping is correct based on your OneDrive structure.

7. Setting Metadata and Permissions

When migrating, it’s best to preserve metadata like created date, modified date, and author.

Step 1: Preserve Metadata

foreach ($File in $OneDriveFiles) {
    Set-PnPListItem -List $SharePointLibrary -Identity $File.Id -Values @{
        "Created" = $File["Created"]
        "Modified" = $File["Modified"]
        "Author" = $File["Author"]
    }
}

This ensures original timestamps and authorship details remain intact.

Step 2: Assign Permissions (Optional)

Set-PnPListItemPermission -List $SharePointLibrary -Identity 1 -User "user@domain.com" -AddRole "Read"

This grants a user Read permissions to the migrated files. Modify as needed.

8. Verifying Migration

After migration, check if the files and folders were successfully transferred.

Step 1: Get Migrated Files

Get-PnPListItem -List "Shared Documents" | Format-Table ID, FileRef

This lists all files in the SharePoint Document Library.

Step 2: Check File Integrity

Manually open some files in SharePoint to ensure they were migrated correctly.

9. Automating the Migration

To schedule and automate future migrations, save this script as Migrate-OneDriveToSharePoint.ps1 and use Task Scheduler or Azure Automation to run it periodically.

Step 1: Save the Script

Save the entire PowerShell script as a .ps1 file.

Step 2: Schedule via Task Scheduler

Open Task Scheduler.
Click Create Basic Task.
Set Trigger (Run at a specific time or daily).
Set Action to Start a Program.
Choose powershell.exe and provide the script path as an argument.
Save and enable the task.