Managing SharePoint Site Scripts using PnP PowerShell

SharePoint Site Scripts are JSON-based definitions used to automate site provisioning by applying custom configurations, settings, and assets to SharePoint Online sites. These scripts work in combination with Site Designs to provide a structured and repeatable way of setting up sites.

With PnP PowerShell, administrators can:
Create, add, update, and remove Site Scripts
Apply Site Scripts to SharePoint Online sites
Export and import Site Scripts for automation

Prerequisites

Before managing Site Scripts, ensure:

PnP PowerShell is installed

Install-Module -Name PnP.PowerShell -Force -AllowClobber

You are connected to SharePoint Online

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

You have Global Admin or SharePoint Admin permissions.

Step 1: Understanding Site Scripts

A Site Script is a JSON definition that outlines configurations, list structures, branding, permissions, and more to be applied to a site.

Example Site Script (JSON Format)

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/site-design-script-actions.schema.json",
  "actions": [
    {
      "verb": "createSPList",
      "listName": "Project Documents",
      "templateType": 101,
      "subactions": [
        {
          "verb": "setTitle",
          "title": "Project Docs"
        }
      ]
    }
  ],
  "bindata": {},
  "version": 1
}

What This Script Does:

Creates a new document library named Project Documents
Sets its display title to Project Docs

Step 2: Adding a New Site Script Using PnP PowerShell

1️⃣ Save the JSON File

Create a file named SiteScript.json and save the JSON content from above.

2️⃣ Run the Following PnP PowerShell Command

# Read JSON content
$scriptContent = Get-Content -Path "C:\Path\To\SiteScript.json" -Raw

# Add Site Script
$siteScript = Add-PnPSiteScript -Title "Project Documents Script" -Content $scriptContent

# Display the Site Script ID
$siteScript.Id

Adds the Site Script and returns its unique ID.

Step 3: Retrieving and Listing Site Scripts

To get a list of all existing Site Scripts, use:

Get-PnPSiteScript

Lists all Site Scripts with their IDs and Titles.

Step 4: Updating an Existing Site Script

To update an existing Site Script, use the ID retrieved earlier:

# Update Site Script
Set-PnPSiteScript -Identity "<SiteScriptID>" -Title "Updated Script" -Content $scriptContent

Updates the Site Script with the new JSON definition.

Step 5: Removing a Site Script

To delete a Site Script, use:

Remove-PnPSiteScript -Identity "<SiteScriptID>"

Deletes the Site Script permanently.

Step 6: Exporting and Importing Site Scripts

Export Site Scripts to JSON File

Get-PnPSiteScript | ConvertTo-Json -Depth 10 | Out-File "C:\Path\To\ExportedSiteScripts.json"

Saves all Site Scripts to a JSON file for backup or migration.

Import Site Scripts from a JSON File

$importedScriptContent = Get-Content -Path "C:\Path\To\ExportedSiteScripts.json" -Raw
Add-PnPSiteScript -Title "Imported Script" -Content $importedScriptContent

Restores Site Scripts from a saved JSON file.

Step 7: Applying a Site Script to a SharePoint Site

Site Scripts alone cannot be applied directly; they must be linked to a Site Design.

1️⃣ Create a Site Design with the Site Script

$siteDesign = Add-PnPSiteDesign -Title "Project Site Design" -SiteScriptIds "<SiteScriptID>" -WebTemplate "64" -Description "Applies Project Docs library"

Creates a Site Design for team sites (WebTemplate "64").

2️⃣ Apply Site Design to a Site

Invoke-PnPSiteDesign -Identity $siteDesign.Id -WebUrl "https://yourtenant.sharepoint.com/sites/YourSite"

Applies the Site Design (and its Site Script) to a SharePoint site.

Step 8: Removing a Site Design

To remove a Site Design:

Remove-PnPSiteDesign -Identity "<SiteDesignID>"

Deletes the Site Design but not the Site Script.

Step 9: Automating Site Script Deployment

To automate the deployment of Site Scripts across multiple sites, use:

$sites = @(
    "https://yourtenant.sharepoint.com/sites/ProjectA",
    "https://yourtenant.sharepoint.com/sites/ProjectB",
    "https://yourtenant.sharepoint.com/sites/ProjectC"
)

foreach ($site in $sites) {
    Invoke-PnPSiteDesign -Identity $siteDesign.Id -WebUrl $site
    Write-Host "Applied Site Design to $site"
}

Applies the same Site Script to multiple SharePoint sites.

Troubleshooting Common Issues

1. Site Script Not Applied?

Ensure the Site Script is linked to a Site Design.
Run Get-PnPSiteScript to verify if the script exists.

2. Permission Errors?

Use a Global Admin or SharePoint Admin account.
Ensure Connect-PnPOnline is connected to the admin center (-Url "https://yourtenant-admin.sharepoint.com").

3. JSON File Not Recognized?

Validate JSON structure using https://jsonlint.com/.
Ensure -Raw is used when reading the JSON file (Get-Content -Raw).