A SharePoint Site Script can become confusing depending on its size. During Site Script creation, it’s easy to misspell a verb or to create an inconsistent JSON object. These issues can result in trial and error sessions until the Site Script gets created. I’ve dealt with different issues while creating Site Scripts in the past. In this blogpost, I want to share these experiences with you. I’ll also demonstrate how to avoid those problems.

Issues:

1. Inconsistent JSON
2. Misspelled verbs
3. Misspelled properties / Missing required fields

1. Inconsistent JSON:

Site Scripts are JSON files. Hence, it’s very important to take care of the JSON syntax. Otherwise, the Site Script engine won’t be able to deserialize the JSON object. The code below shows an inconsistent JSON since it is missing a comma:

{
    "$schema": "schema.json",
    "actions": [
       {
           "verb": "addNavLink",
           "url": "https://devjhorst.blogspot.com"
           "displayName": "JHorst Blog"
       }   
    ]
}

The problem you have:

If you try to create a Site Script based on the JSON above, you’ll get the following error:

Set-SPOSiteScript: Error setting value in extension data for type 'Microsoft.SharePoint.WebTemplateExtensions.SiteScriptManager+DeserializationScriptAction'.

How to avoid this issue:

I suggest you write your Site Scripts using Visual Studio Code since it is a very convenient tool which supports validation for the JSON syntax. Consider using a JSON formatter and validator tool as well. I can recommend this site since they visualize the errors found.

2. Misspelled verbs:

Each action in a Site Script is specified by a verb value which must be written correctly since they are treated as case sensitive values. The code below demonstrates this scenario with the addNavLink and applyTheme verbs:

{
    "$schema": "schema.json",
    "actions": [
       {
           "verb": "AddNavLink",
           "url": "https://devjhorst.blogspot.com"
           "displayName": "JHorst Blog"
       },
 {
            "verb": "ApplyTheme",
            "themeName": "Blue Sky"
       }
    ]
}

The problem you have:

Note that the Site Script engine only returns an error for the first verb. Hence, trying to find the mistakes can take a few minutes.

Set-SPOSiteScript : Unable to handle action AddNavLink. No action handler was registered for this action.

How to avoid this issue:

I suggest directly working with the Site Designs JSON Schema documentation. There you find the correct spelling for the supported verbs. Yannick Plenevaux has created a SPFx solution which offers Site Scripts creation through a web part. Have a look at his SPFx solution since it is handy! Last but not least, I'd like to introduce Mikko Punamäki's website which allows you to design SharePoint Site Scripts online. Have a look at https://www.sitedesigner.io/ and be impressed.

3. Misspelled properties / Missing required fields:

JSON values complete the verbs. Since they are treated as case sensitive values as well, they must also be written correctly. The code below demonstrates this scenario with the displayName and themeName properties:

{
    "$schema": "schema.json",
    "actions": [
       {
           "verb": "addNavLink",
           "url": "https://devjhorst.blogspot.com",
           "displayname": "JHorst Blog"
       },
       {
            "verb": "applyTheme",
            "themename": "Blue Sky"
       }   
    ]
}

The problem you have:

This is the most deceitful issue I found. If you try to create a Site Script with the script above, you succeed. At first sight you might think that things are working, but that is not true 😊 You won’t see any error until you apply a Site Design which uses the broken Site Script. This is how the exception looks in SharePoint:
Important: Note that missing required fields also results in the same error!

How to avoid this issue:

In some cases, Site Designs gives you a preview of the actions that will be applied to the site. If an action doesn't have content, then you probably have misspelled the property and must fix it. I also recommend following the suggestions for issue 2 since they can also be used to avoid issue 3. The picture below shows a Site Design preview with broken actions:


Summary:

Creating a Site Script is not difficult but depending on the script’s complexity, things can become confused. It is important to keep some steps in mind, so you can avoid or quickly fix errors.


Links: