SharePoint Online Site Designs in Site Scripts – Part 1

Introduction

Site templates can be one of the key elements of a successfull implementation of a SharePoint portal in an organization. With site templates we achieve the same team site structure that is defined in the template. Here I am mostly thinking about lists and document libraries and of course also web parts that are shown on specific pages. On SharePoint on-premises, this part was always implemented by installing WSP packages on the server. In SharePoint Online however, there is no option to install WSP packages or other server-side code. So, Microsoft had to take a different approach to site templates – “Site Designs” and “Site Scripts” were born.

Site Scripts

A site script is a text in JSON form that defines what needs to happen after a site is created. A JSON scheme can also contain commands that run Microsoft Power Automate, which can then also run logic, that is implemented on Microsoft Azure.

Site Designs

A site design on the other hand is just a collection of settings, that must happen after a site is created. What exactly will be created and configured however is defined in the site script.

Creating Site Scripts

To create a site script, we can use any text editor and save the file as JSON. Examples and documentation can be found here:

https://docs.microsoft.com/en-us/sharepoint/dev/declarative-customization/site-design-overview

https://docs.microsoft.com/en-us/sharepoint/dev/declarative-customization/site-design-json-schema

It is important to use predefined expressions and definitions for creating individual elements. Every site script must begin in the following form:

{
    "$schema": "schema.json",
    "actions": [
        ...
        <WE ADD OUR ACTIONS>
        ...
    ],
    "bindata": { },
    "version": 1
};

If we want to upgrade our definition with a new list, which we want to add to our site, we add the list definition, with all the columns, views etc. to our starting version of JSON.

{
    "$schema": "schema.json",
    "actions": [
        {
            "verb": "createSPList",
            "listName": "Xblogs article",
            "templateType": 100,
            "subactions": [
                {
                    "verb": "setDescription",
                    "description": "Xblogs article example"
                },
                {
                    "verb": "addSPField",
                    "fieldType": "Text",
                    "displayName": "Xblogs article title",
                    "internalName":"XblogsArticleTitle",
                    "isRequired": false,
                    "addToDefaultView": true
                },
                {
                    "verb": "addSPField",
                    "fieldType": "Text",
                    "displayName": "Article author",
                    "internalName": "ArticleAuthor",
                    "addToDefaultView": true,
                    "isRequired": true
                }
            ]
        }
    ],
    "bindata": { },
    "version": 1
}

In our example, we will add one list, titled Xblogs article, and we will then add 2 additional form fields into this list.

Implementing on SharePoint Online

To create a new site based on the template, we just defined, we must first import this schema into SharePoint Online.

To import and create a new site design, we must use the following PowerShell commands, which are a part of the SharePoint Online PowerShell module.

$cred=Get-Credential
$adminUrl="https://r0b3r70-admin.sharepoint.com"
$scriptFile="C:\posts\SPO\Pika-site-script.json"

Connect-SPOService $adminUrl -Credential $cred
$siteScript = Get-Content $scriptFile -Raw -Encoding UTF8
$spoSiteScript = Add-SPOSiteScript -Title "Xblogs site script" -Content $siteScript
$siteScriptId=$spoSiteScript.Id
Add-SPOSiteDesign -SiteScripts $siteScriptId `
    -Title "Xblogs article site design" `
    -Description "Xblogs article site design" `
    -WebTemplate 64 #64 = Team Site, 68 = Communication Site, 1 = Groupless Team Site

When the command completes successfully, we can select the new site template from the dropdown menu. After the site updates, a list is created on the site with the columns that were specified in the JSON schema.

In this introductory article I described a basic example of how to prepare a site template for SharePoint Online. In the next article, I will describe the tools that we can use to simplify the preparation of the JSON schema and how we can prepare advanced site templates with the help of Microsoft Azure and Microsoft Power Automate.

Robi Vončina

Author: Robi Vončina

Office Servers and Services MVP, MCT

Leave a Reply

Your email address will not be published. Required fields are marked *