SharePoint Online site designs: Monitoring site script run errors

Article
1/17/2024

Site designs

Site designs are an amazing feature that allows you to apply a template to your site. Site designs can be used each time a new site is created or applied to exist modern sites (group-connected Team and Communication sites). Most actions typically affect the site itself, such as setting permissions or creating lists, but, with the help of Flow, site design can also record the new site URL to a log or send a tweet.
Site designs and site scripts can automate provisioning new or existing modern SharePoint sites that use your own custom configurations.

Where to start?

If you are new to site designs, have a look at this PnP Webcast where Vesa Juvonen and Erwin van Hunen introduce SharePoint Site Designs and Site Scripts:
View

On Microsoft Docs you can find all site design and site script Powershell cmdlets this article refers to.

UI

When a site design is applied to your site, some of the settings may fail, and you will be able to view them:

Powershell

In order to get a better overview of failures and success during the application of site design, use Powershell. The following cmdlets require SharePoint Online Management Shell.

Errors in past runs

In order to view the status and errors of the past runs, use Powershell Get-SPOSiteDesignRun and Get-SPOSiteDesignRunStatus.

$run = Get-SPOSiteDesignRun -WebUrl https://etr56.sharepoint.com/sites/fullsitedesign4 -SiteDesignId 6e7dbb3b-3657-4cbb-881c-bb2ba959719a
Get-SPOSiteDesignRun -WebUrl "https://etr56.sharepoint.com/sites/fullsitedesign4" -SiteDesignId 6e7dbb3b-3657-4cbb-881c-bb2ba959719a | Get-SPOSiteDesignRunStatus

$run = Get-SPOSiteDesignRun -WebUrl https://etr56.sharepoint.com/sites/fullsitedesign4 -SiteDesignId 6e7dbb3b-3657-4cbb-881c-bb2ba959719a
Get-SPOSiteDesignRunStatus -Run $run

https://raw.githubusercontent.com/PowershellScripts/AllGalleryScriptsSamples/master/pics/Capture.PNG

Current runs

You can also apply and RE-APPLY a site design on existing sites using Powershell Invoke-SPOSiteDesign

Invoke-SPOSiteDesign -Identity 6e7dbb3b-3657-4cbb-881c-bb2ba959719a   -WebUrl https://etr56.sharepoint.com/sites/fullsitedesign4

This will display in Powershell window list of site script actions and their outcomes:

Add-SPOSiteDesignTask

Very useful cmdlet, but not functional at the time of writing this article, is Add-SPOSiteDesignTask, which allows you to schedule more time-consuming site scripts. You will be able to view the results of the run with Get-SPOSiteDesignTask.

Export to csv

All of the previously seen results can be exported to csv or a text file:

Invoke-SPOSiteDesign -Identity 6e7dbb3b-3657-4cbb-881c-bb2ba959719a   -WebUrl "https://etr56.sharepoint.com/sites/fullsitedesign4" | out-file c:\users\public\sitedesign.txt

Invoke-SPOSiteDesign -Identity 6e7dbb3b-3657-4cbb-881c-bb2ba959719a   -WebUrl https://etr56.sharepoint.com/sites/fullsitedesign4 | export-csv c:\users\public\sitedesign.csv

Practical scenario

Let's imagine that you have a bunch of sites for which you apply your new site designs and site scripts. When the scripts have run and all the sites have been updated, you want to see if there were any errors for any of the sites.

Prepare your settings:

$cred = Get-Credential -UserName ana@etr56.onmicrosoft.com -Message "Enter password"
Connect-SPOService -Url "https://etr56-admin.sharepoint.com" -Credential $cred
$CSVPath = "C:\Users\Public\siteoutcomes.csv"

You can import your sites from a csv file using Import-CSV cmdlet:

$sites = import-csv C:\path\yourfilewithsites.csv

In the example, there are only 2 sites, so I declare the array directly:

$sites = ("https://etr56.sharepoint.com/sites/sitedesign44","https://etr56.sharepoint.com/sites/sitedesign45")

Now that we know in which sites the site scripts will run, let's invoke the site design in each of them:

foreach ($site in $sites)
{
 
$outcomes = Invoke-SPOSiteDesign -Identity 6e7dbb3b-3657-4cbb-881c-bb2ba959719a   -WebUrl $site

All the outcomes - the successes, skips, and failures - are in the $outcomes variable. If you want, you can output it all to a csv:

$outcomes | Export-CSV $CSVPath -Append

You can also filter the results and pick only failed actions, e.g.

foreach($outcome in $outcomes)
    {
        if($outcome.Outcome -eq "Failure")
        {
            Write-Host $site $outcome.Title  # $outcome.OutcomeText

You can also export filtered results to a csv file:

$outcomes = Invoke-SPOSiteDesign -Identity 6e7dbb3b-3657-4cbb-881c-bb2ba959719a   -WebUrl $site
 
    foreach($outcome in $outcomes)
    {
        if($outcome.Outcome -eq "Failure")
        {
            Write-Host $site $outcome.Title  # $outcome.OutcomeText
 
            [pscustomobject]@{
                Site = $site
                FailedAction = $outcome.Title
                Reason = $outcome.OutcomeText
                } | Export-Csv -Path $CSVPath -Append
        }
    }

Full solution

$cred = Get-Credential -UserName ana@etr56.onmicrosoft.com -Message "Enter password"
Connect-SPOService -Url "https://etr56-admin.sharepoint.com" -Credential $cred
$CSVPath = "C:\Users\Public\siteoutcomes.csv"
 
$sites = ("https://etr56.sharepoint.com/sites/sitedesign44","https://etr56.sharepoint.com/sites/sitedesign45")
 
foreach ($site  in $sites)
{ 
 
$outcomes = Invoke-SPOSiteDesign -Identity 6e7dbb3b-3657-4cbb-881c-bb2ba959719a   -WebUrl $site
 
    foreach($outcome in $outcomes)
    {
        if($outcome.Outcome -eq "Failure")
        {
            Write-Host $site $outcome.Title  # $outcome.OutcomeText
 
            [pscustomobject]@{
                Site = $site
                FailedAction = $outcome.Title
                Reason = $outcome.OutcomeText
                } | Export-Csv -Path $CSVPath -Append
        }
    }
 
}

You can also find it at my GitHub: https://github.com/PowershellScripts/SPO-Management-Shell-samples/blob/master/SiteDesigns/MonitorErrors.ps1 where it welcomes all your input.

Share via