Amongst the ongoing flood of new and improved SharePoint Online capabilities, the new site design and script actions really stood out for me.
What the benefits are and how can you get started using them in a practical sense, are all key topics in this article. Time for a plunge into what this brings to the table as a new lightweight approach to customizing SharePoint Online sites in Office 365.
What are these site designs you speak of?
Site designs are basically combinations of configuration actions (e.g. creating lists, setting themes and logos etc.) that can be combined and applied to a site when it it’s provisioned in SharePoint Online. And it’s fully automatic!
So, whenever a user creates a new site via the Office 365 SharePoint tile, some additional configuration tasks can be performed automatically like applying a corporate theme and setting a logo (more examples to follow throughout the article).
That’s seems like a great addition for provisioning sites that are consistent in look and feel throughout the organization.
These relatively simple requirements often depended on custom code, but this can now be handled automatically without writing provisioning scripts or using a separate provisioning engine.
There are still a lot of scenarios where more advanced solutions are still very much valid, but site designs may surely help to accomplish some of those typical customization tasks.
Advantages of site designs
The biggest advantage of site designs and site scripts is that it is provided as part of the user’s workflow when using the built-in self-service site creation feature on the SharePoint tile in Office 365.
There is no separate custom form where a user must go to, the magic all happens in a familiar environment.
Secondly, as you will learn in this article, the framework behind the site designs and site scripts is relatively easy to adopt for IT Pro’s that have been requested to provide consistency of sites across the organization. There are no advanced coding skills required. Hence the term ‘Lightweight’ 😊
Proficient knowledge of (SharePoint Online) PowerShell and the typical markup used to define the site scripts and designs is all that’s required. And this has been properly documented by Microsoft for you to use.
Another benefit is that site designs and site scripts are super flexible. Specific actions can be combined into a single site script or separated for reuse in different site designs.
Not for every scenario
Site designs also come with some limitations and it may not be the best solution for your specific scenario.
For starters, it is only available for SharePoint Online and I’m not aware of support coming to on-premises environments any time soon.
It’s also not intended to support a full site customizations scenario. For those cases, a provisioning engine like OfficeDevPnP is still the best way to go.
Also, the number of supported actions is currently still limited. You can:
- Create a SharePoint list
- Add a navigation link
- Apply a theme
- Set a site logo
- Join a hub site
- Trigger a Flow
- setSiteExternalSharingCapability
The last one in this list evens seems odd to me, as it doesn’t really seem to be design related. “Trigger a Flow” on the other hand, is a good integration point to potentially trigger other actions or additional customization using a provisioning engine of some sort.
It may be expected that the list of supported actions will grow over time, which will be very welcome. For now, the most basic things are in there and the capability is also in a production state available within all tenants.
So, where might I find these site designs
Prior to diving into the ways on setting up site designs and site script actions, I’d like to start with the result to illustrate the ease of use. This part of the article is pretty much in line with the Microsoft documentation, but it is a good starting point nevertheless.
Let’s kick off with a very simple scenario when creating a Communication site at the point where the user clicks the “Create site” button on the Office 365 SharePoint Online tile, the dropdown list with default site designs is shown (“Topic”, “Empty”, “Showcase”).
When a custom site design has been added, this list is extended with a new option. In our scenario the extra option is called “Contoso Portal”.
In case the user selects this option, a custom preview image of the design would show, combined with a short description of what the design is all about.
After the user has provided a title and site description, the site is instantly provisioned, and the user is automatically redirected to the homepage of the new sites. At that point, the site looks standard and no themes or logo are set yet.
But within milliseconds, a special pane appears on the right side of the screen, informing the users about “Getting a few things ready!”.
his is where the site design starts to do its work. Applying a logo, setting a theme and adding some additional navigation link. All custom actions that need to be performed as part of the design are executed and relatively quickly!
In case the scripts contain any bugs, the pane will also provide feedback about what has gone wrong.
After all actions complete, the user can refresh the page by clicking on the button “View updated site”. The page refreshes and presto, all customizations have been applied. The logo is in the right place, the dark blue Contoso corporate theme was applied, and the “Contoso public website” link was added to the navigation.
This is a very simple scenario where the lightweight site designs directly provides benefits.
So, would it be very difficult to set this up?
Let’s have a peek under the hood
To create custom site designs, we need custom site script actions. These are written according to a specific JSON-schema (VS Code works well), stored as JSON-files and then uploaded to the Office 365 tenant using PowerShell. We’ll get to the adding them a bit further in the article.
The markup is relatively simply and quite flexible when it comes to either combining of separating site scripts.
{
"$schema": "schema.json",
"actions": [
<one or more verb actions separated by commas>
],
"bindata": { },
"version": 1
};
Basic JSON-markup for a site script
Apart from the prerequisite markup as shown in Listing 1, the only challenge is to get the specific “verbs” (the actual actions) in there which Microsoft has prefabbed for us.
The following examples are the ones we need for branding our Contoso portal site with a logo, theme and additional navigation link. The theme requires some extra actions, but we’ll get to that later!
{
"verb": "setSiteLogo",
"url": "https://contoso.sharepoint.com/SiteAssets/contoso_logo.png"
}
JSON-markup for setting a custom logo
{
"verb": "applyTheme",
"themeName": "Contoso corporate"
}
JSON-markup for applying a theme
{
"verb": "addNavLink",
"url": "https://www.contoso.com",
"displayName": "Contoso public website",
"isWebRelative": false
}
JSON-markup for adding a navigation link
For our simple setup, all actions are combined together. This results in the complete markup as shown in the following list:
{
"$schema": "schema.json",
"actions": [
{
"verb": "setSiteLogo",
"url": "https://contoso.sharepoint.com/SiteAssets/contoso_logo.png"
}, {
"verb": "applyTheme",
"themeName": "Contoso corporate"
}, {
"verb": "addNavLink",
"url": "https://www.contoso.com",
"displayName": "Contoso public website",
"isWebRelative": false
}
],
"bindata": {},
"version": 1
};
Full JSON-markup for the Contoso Portal
Adding the site scripts
Now that
the 3 actions are combined in a single JSON-file, it can be uploaded to the
tenant. For this we use our beloved PowerShell.
Please ensure to have the latest version of the SharePoint Online Management
Shell installed. I used version 16.0.7521.1200 from 29 March 2018 which comes
with some improvements since the first release supporting site designs and site
scripts.
Once connected to SharePoint Online via the Management Shell, run the following cmdlets to add the site script to the tenant.
Get-Content 'combined-actions.json' -Raw | Add-SPOSiteScript -Title 'Contoso Portal actions'
PowerShell cmdlets to add the site scripts
The script reads the JSON-file from disk after which it is added to the tenant using the specified name.
Upon completion, PowerShell returns the GUID (a.o.) from this newly added site script, which is required in the next step.
In case site scripts are split up into separate JSON-files, this routine would be repeated for each one of them, preserving each output-GUID for the next step.
Creating the site designs
The next step is to create a site design, so users can leverage the site script actions when creating new sites.
Add-SPOSiteDesign `
-Title 'Contoso portal' `
-WebTemplate '68' `
-SiteScripts 'f077cf67-ff3f-4b7f-b5cc-75c3ed6f729e' `
-Description 'Contoso portal site design' `
-PreviewImageUrl 'https://contoso.sharepoint.com/SiteAssets/contoso _portal.png' `
-PreviewImageAltText 'Contoso portal site design preview image'
If the site design should contain multiple site scripts, these can be listed (comma separated) behind the “-SiteScripts” parameter.
Notice the “68” as a value for “WebTemplate”. This refers to the Communication site type where “64” refers to the Group-enabled Team site. So the number you fill in there determines which site type is being targeted for customization.
Also, the preview image needs to be an existing image as users will see this after selecting the design from the list upon site creation.
After the cmdlet has been successfully run, the new site design is directly available for end-users to work with.
Targeting site designs
We can optionally limit access to the new design using the ‘Grant-SPOSiteDesignRights’ cmdlet.
This may help organizations to target certain designs for specific audiences (individual users or groups) and it would be a useful way to support certain site designs that would include a hub site association.
Default site designs
Custom site designs can be added using the “IsDefault” switch. For Communication sites (WebTemplate: 68) this means that all the built-in “Topic”, “Empty” and “Showcase” options would be subject to the customizations within the custom site design.
Group-enabled Team sites (WebTemplate: 64) natively come with only one flavor, so the customizations would apply to choosing that option without introducing additional dropdown list choices.
Adding multiple Team Sites site designs would still be an option though. If a new custom site design is added for a Team site next to the built-in one, a dropdown list would appear showing the newly added option next to the existing one.
Applying designs to existing sites
Something not available in the initial release of the PowerShell capability (it was via the REST API), was the option to apply a site design to an existing site. This is now possible!
Invoke-SPOSiteDesign -Identity '18a2e012-5b68-4b56-89fa-95e59bb14d8e' `
-WebUrl 'https://contoso.sharepoint.com/sites/ExistingPortalSite'
PowerShell cmdlet to invoke a site design
Simply performing an Invoke-SPOSiteDesign including the GUID of the site design and target web Url will do the trick. PowerShell will return a table-formatted list of all performed actions. It works like a charm and can be easily built-in into a PowerShell function to perform bulk actions!
Script actions and site themes
Prior to applying a “Contoso corporate” theme through our site design, we first need to generate it and upload it to the tenant. Otherwise, it will not be available for use in site scripts.
A theme can be easily generated using the Microsoft Theme Generator tool (http://aka.ms/spsitetheming).
Once the theme “Contoso portal” theme is finished, the resulting PowerShell output (amongst other formats) can be copied into the PowerShell script shown below and executed.
Param ([Hashtable]$ht)
$dictionary = New-Object "System.Collections.Generic.Dictionary``2[System.String,System.String]"
foreach ($entry in $ht.GetEnumerator()) {
$dictionary.Add($entry.Name, $entry.Value)
}
return $dictionary
}
$themepallette = HashToDictionary(
<Output from theme generator tool>
)
PowerShell markup for a custom site theme definition
Next, the theme can be added to the tenant using the following cmdlet that reads the “$themepallette” variable data from the previous step:
Add-SPOTheme -Name "Contoso corporate" -Palette $themepallette -IsInverted $false
PowerShell markup to add a custom site theme
After adding the theme, it will be directly available for users authorized to “Change the look”.
When creating a site script later, you need to refer to the exact name as specified when adding the custom theme.
In addition, you can hide the built-in themes through:
Set-SPOHideDefaultThemes $True
Site designs and Microsoft Teams
One of the questions I got from my customers, was if and how this capability would work for sites that are created in the background when creating a new Office 365 Group or Microsoft Team. What I’ve seen, is that if a site design has been set as default, the customizations will still fire when the user first visits the site. It will then show the customization pane same as with the typical scenario.
Conclusion
The new site designs and site scripts capability provided a great way to implement consistency across sites in an organization in a lightweight manner easily adopted. It’s not quite finished yet, but the foundation works stable and consistent.
As with most innovations, Microsoft may develop this capability over time, making it more powerful to automate those typical customization tasks. Keeping my eye on this one for sure!
This article was first published in the DIWUG magazine in June 2018.
