Creating a custom site script in SharePoint

To customize SharePoint further, the next step is to apply a site template. Microsoft offers a variety of default site templates, each with its own specific theme and some even come with pre-designed pages, lists, navigation, and other useful features that are automatically applied when used on a site. In the menu used to apply site templates, there’s also the option to apply a template provided by your organization.

However, initially, there won’t be any templates available, so we’re going to create a custom template for our organization.

Overview of a site script

Before we create the template, we must first develop a site script. This site script is a set of actions that are executed whenever a template is applied to a site. Using site scripts, we can apply themes, set up new SharePoint lists, add logos, generate pages with content, and much more. Once the site script is created, we’ll apply it to a new site template for our organization.

We’ll use the Add-SPOSiteScript cmdlet in PowerShell to create a new site script for our SharePoint environment. The parameters are relatively self explanatory. We have the title which is the Title of the script, the Description which describes what the script does and the Content which defines what the script does.

Content parameter

As you might have guessed, the Content parameter is the one we’re going to spend the most time looking at. It takes a JSON value which defines a list of actions to be performed. As you add these actions in the JSON, they will be executed in order from first to last.

At the start of this JSON object we’ll define the schema to be used, and then define the actions.

$site_script = '
{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/site-design-script-actions.schema.json",
  "actions": [
    ...
  ]
}
'

Each action is specified by the "verb" value. The first action we’ll add to our JSON will apply a theme using the applyTheme verb and specifying the theme we created last time.

"actions": [
  {
    "verb": "applyTheme",
    "themeName": "Bens theme"
  }
]

Some of the more complex actions also have subactions which are verb values too. The action to create a list, createSPList is one that makes use of subactions. This is how it can be used to create a list with two fields, name and age.

"actions": [
  {
    "verb": "createSPList", // Verb of the action
    "listName": "Ben's list", // Name of the list being created
    "templateType": "100", // type of list - 100 is a generic list
    "subActions": [
      {
        "verb": "setDescription",
        "description": "Test list for Ben"
      },
      {
        "verb": "addSPField", // Verb of the subaction
        "fieldType": "Text", // List field type
        "displayName": "Name", // List field name
        "isRequired": false, // Whether list field is required
        "addToDefaultView": true, // Whether the field is added to the default list view
      },
      {
        "verb": "addSPField",
        "fieldType": "Number",
        "displayName": "Age",
        "isRequired": false,
        "addToDefaultView": true,
      }
    ],
  }
]

The full list of actions and subactions along with examples of how to use them can be found in the Microsoft documentation.

Putting it all together

Using Connect-SPOService, we’ll connect once again to our SharePoint admin which will allow us to run these commands on our site.

With our Content parameter defined in a variable, we can now add it to our site as a new script using the Add-SPOSiteScript cmdlet along with a Title and Description.

$site_script = '
{
    "$schema": "https://developer.microsoft.com/json-schemas/sp/site-design-script-actions.schema.json",
    "actions": [
        {
            "verb": "applyTheme",
            "themeName": "Bens theme"
        },
        {
            "verb": "createSPList",
            "listName": "Bens list",
            "templateType": "100",
            "subActions": [
            {
                "verb": "setDescription",
                "description": "Test list for Ben"
            },
            {
                "verb": "addSPField",
                "fieldType": "Text",
                "displayName": "Name",
                "isRequired": false,
                "addToDefaultView": true,
            },
            {
                "verb": "addSPField",
                "fieldType": "Number",
                "displayName": "Age",
                "isRequired": false,
                "addToDefaultView": true,
            }
        }
    ]
}
'

Connect-SPOService -url "https://ben-admin.sharepoint.com"
Add-SPOSiteScript -Title "Bens Script" -Content $site_script - Description "A description of my script"

When Add-SPOSiteScript is executed, if everything is successful there will be some details about the script returned in the console.

Id                  : 2b54abds-14c3-4eww-bceb-4faba493b5dc
Title               : Bens Theme
Description         : A description of my script
Content             : 
Version             : 0
IsSiteScriptPackage : False

You will see things like the Title and Description that you gave the script, but the important thing to take a note of is the Id for your script which is automatically generated by SharePoint. This Id is used to associate this site script to a site template.