Managing Hybrid SharePoint Environments using PnP PowerShell

A Hybrid SharePoint Environment consists of both SharePoint Online (SPO) and SharePoint On-Premises (SP On-Prem). Managing both environments efficiently requires automation using PnP PowerShell.

This guide covers:
Connecting to SharePoint Online and On-Prem
Syncing Site Collections and Libraries
Managing User Permissions in Hybrid Mode
Automating Content Synchronization
Hybrid Search and Taxonomy Management

Step 1: Prerequisites

1.1 Install and Update PnP PowerShell

Ensure you have PnP PowerShell installed:

Install-Module PnP.PowerShell -Scope CurrentUser

To update:

Update-Module PnP.PowerShell

1.2 Connect to SharePoint Online

Connect-PnPOnline -Url "https://yourtenant.sharepoint.com" -Interactive

Result: Successfully connected to SharePoint Online.

1.3 Connect to SharePoint On-Premises

For SharePoint 2019, 2016, or 2013, use:

Connect-PnPOnline -Url "https://yourserver/sites/YourSite" -UseWebLogin

If using credentials:

$Cred = Get-Credential
Connect-PnPOnline -Url "https://yourserver/sites/YourSite" -Credentials $Cred

Result: Successfully connected to SharePoint On-Premises.

Step 2: Sync Site Collections Between Online and On-Premises

2.1 Retrieve Site Collections

To list all SharePoint Online site collections:

powershellCopyEditGet-PnPTenantSite | Select Title, Url

To list all On-Premises site collections:

Get-PnPSite -Includes Url, Title

2.2 Create a Site in Both Environments

To create a site collection in both Online and On-Premises:

# Create in SharePoint Online
New-PnPTenantSite -Url "https://yourtenant.sharepoint.com/sites/HybridSite" -Title "Hybrid Site" -Owner "admin@yourtenant.com" -TimeZone 13 -Template "STS#3"

# Create in SharePoint On-Premises
New-PnPSite -Url "https://yourserver/sites/HybridSite" -Title "Hybrid Site" -Owner "domain\admin" -Template "STS#3"

Result: The Hybrid Site is created in both environments.

Step 3: Manage Document Libraries and Sync Files

3.1 List Document Libraries

To retrieve document libraries in both environments:

Get-PnPList | Where-Object {$_.BaseType -eq "DocumentLibrary"} | Select Title

3.2 Copy Documents from On-Prem to Online

$LocalDocs = Get-PnPListItem -List "Documents"

foreach ($Doc in $LocalDocs) {
    $FilePath = $Doc["FileRef"]
    Add-PnPFile -Path $FilePath -Folder "Shared Documents" -List "Documents"
}

Result: Copies documents from On-Premises to SharePoint Online.

3.3 Migrate Files from SharePoint Online to On-Prem

$OnlineDocs = Get-PnPListItem -List "Documents"

foreach ($Doc in $OnlineDocs) {
    $FilePath = $Doc["FileRef"]
    Add-PnPFile -Path $FilePath -Folder "Shared Documents" -List "Documents"
}

Result: Copies files from SharePoint Online to On-Premises.

Step 4: Sync User Permissions Between Online and On-Prem

4.1 Retrieve Users and Permissions

To get users and their roles in SharePoint Online:

Get-PnPUser -Web "https://yourtenant.sharepoint.com/sites/HybridSite"

To get users in SharePoint On-Premises:

Get-PnPUser -Web "https://yourserver/sites/HybridSite"

4.2 Assign the Same Permissions in Both Environments

# Get users from Online
$Users = Get-PnPUser -Web "https://yourtenant.sharepoint.com/sites/HybridSite"

# Assign same permissions in On-Premises
foreach ($User in $Users) {
    Set-PnPListItemPermission -List "Documents" -User $User.Email -AddRole "Contribute"
}

Result: Syncs user permissions between Online and On-Prem.

Step 5: Enable Hybrid Search

5.1 Enable Hybrid Search Configuration

Enable-PnPFeature -Identity "SearchExperience" -Scope Site

Result: Enables Hybrid Search across environments.

5.2 Query Hybrid Search Index

To search for content across both environments:

Submit-PnPSearchQuery -Query "Project Report" -All

Result: Returns results from both SharePoint Online and On-Prem.

Step 6: Sync Taxonomy and Metadata

6.1 Retrieve Terms from On-Prem

Get-PnPTermGroup -Identity "Corporate Metadata"

6.2 Copy Terms to SharePoint Online

$Terms = Get-PnPTerm -TermGroup "Corporate Metadata" -TermSet "Departments"

foreach ($Term in $Terms) {
    New-PnPTerm -TermSet "Departments" -Name $Term.Name -TermGroup "Corporate Metadata"
}

Result: Syncs metadata between Online and On-Prem.

Step 7: Automate Hybrid Management with a Scheduled Task

1️⃣ Save the script as HybridSync.ps1
2️⃣ Open Task Scheduler in Windows
3️⃣ Create a new task
4️⃣ Set the trigger to Daily
5️⃣ Set the action to Run PowerShell script:

powershell.exe -ExecutionPolicy Bypass -File "C:\Scripts\HybridSync.ps1"

Result: Automates hybrid management daily.