This blogpost covers two topics. The first one - "Wish list" - describes improvements that I'd like to see in the next few months for Site Designs and Site Scripts. The second one - "Improvements that might be coming" - describes things that I've tried out and seem to be under development.
Wish list
|
|
Improvement
|
Notes
|
All the management occurs
programmatically. PowerShell is probably the most used tool to manage Site
Designs and Site Scripts. It would be great to manage Site Designs directly
from the new SharePoint admin center. E. g.: Manage scope, Set default design,
Site Designs and Site Scripts overview etc.
|
|
Teams integration
|
It’s actually a topic from the great
Chris O’Brien. Check out his tweet 😊 He is right about that! I’d also appreciate
having the possibility to teamify the group using Site Designs.
|
Preview of actions to apply
|
If you apply the Site Design through
the settings menu inside an existing site, you’ll see the preview of the
action to apply. In all other scenarios using Site Designs, there is no
preview. So, if you haven’t created the Site Design, you don’t know what you
are going to roll out when applying the Site Design.
|
Url property for list
|
The createSPList action doesn’t
support defining a value for the URL. It uses the displayName property as the
value for the URL instead. In some cases, you end up with an URL like this:
“…Lists/Company%20Party%202018…”
|
The addSPField action has an optional property
for internal name. If this value is not specified, the internal name will be based on the display name. An internal name should always be a required property.
|
|
Error when script is created without
required properties
|
If you don’t define required
properties, you won’t be notified during Site Script creation that you're missing them. You won’t see any error until you apply a Site Design which uses the broken Site Script:
 |
Things
that might be coming
|
|
Improvement
|
Notes
|
There is already an action to
create pages under development. createPage will support the
following properties: fileName, title, bannerImageUrl, canvasContent1,
layoutWebpartsContent and setAsHomePage. Here is what the JSON looks like:
{
"verb": "createPage",
// The file name of the
page. E.g.: News.aspx
"fileName": "",
"pageData": {
// The title of the page.
E.g.: News
"Title": "",
// The URL of the image
to be displayed in the
// banner.
"BannerImageUrl": "",
// The content to be
displayed in the canvas, as a
// string of XML.
"CanvasContent1": "",
// Information about the
page layout, as a string of
// JSON.
"LayoutWebpartsContent":""
},
// Whether or not to set
this page as the homepage. The
// default is false.
"setAsHomePage": true
}
If you try to apply it, you’ll
receive the following message:
I hope this action will be
released soon!
|
|
Wait until Flow is complete
|
waitForReply is a boolean property that belongs to the triggerFlow action.
If it is set to true, the Flow must execute a HTTP POST request to
SetSiteScriptStageOutcome with the Stage Id to update the status. The Site
Design won’t block, but it will be considered incomplete until the reply is
done. Here is what the request URL might look like:
Update 17.07.2019:
Authentication wasn't correct
here. Therefore, I was getting Forbidden 😊 I triggered now the API using the Flow action "Send
an HTTP request to SharePoint" and got BadRequest since the stageId parameter
wasn't provided. I believe that Site Designs will provide this parameter when
triggering Flow.
|
Set site branding
|
Microsoft has already published the
documentation for the setSiteBranding verb, although it is still under
development. This new verb only works on communication sites and for the hub
navigation. Furthermore, it supports the following properties: navigationLayout,
headerLayout and headerBackground. Check
out the documentation for more information. Here is what the JSON looks
like:
{
"verb": "setSiteBranding",
// Specifies the
navigation layout as Cascade or
// Megamenu
"navigationLayout": "Megamenu",
// Specifies the header
layout as Standard or Compact
"headerLayout": "Compact",
// Specifies the header
background as None, Neutral,
// Soft or Strong
"headerBackground": "Strong"
}
If you try to work with this verb, you'll get the following exception:
Update 27.10.2019: It seems as if the setSiteBranding action has been released since the error message above is no longer displayed and the specified branding updates are successfully applied.
|
Extract Site Script from web
|
At SharePoint Conference 2019, Microsoft announced a new feature to create a site script from a web. This
new capability supports extracting lists, branding, theme, regional settings,
external sharing capability as well as links to exported items. Here is what this new feature looks like in PowerShell:
Get-SPOSiteScriptFromWeb
- IncludedLists
- IncludeBranding
- IncludeTheme
- IncludeRegionalSettings
- IncludeSiteExternalSharingCapability
- IncludeLinksToExportedItems
This feature was first rolled out
then rolled back. The reason here could be the support for extracting
branding. Since setSiteBranding is also under development.
If you try to request the GetSiteScriptFromWeb
API, you'll end up with a BadRequest which returns the following message: “The requested operation is part
of an experimental feature that is not supported in the current environment.”
Check out Vesa Juvonen's video for more information about it. Update 27.10.2019: There's good news here as well! Get-SPOSiteScriptFromWeb can be used with SharePoint Online Management Shell from version 16.0.19418.12000 This is what the output looks like when getting the Site Script from web with the configuration below:
Get-SPOSiteScriptFromWeb
-IncludeBranding
-IncludeTheme
-IncludeRegionalSettings
-IncludeSiteExternalSharingCapability
{
"$schema": "https://developer.microsoft.com/json-schemas/sp/site-design-script-actions.schema.json",
"actions": [
{
"verb": "setSiteBranding",
"navigationLayout": "Megamenu",
"headerLayout": "Standard",
"headerBackground": "None",
"showFooter": true,
"navAudienceTargetingEnabled": false
},
{
"verb": "setSiteExternalSharingCapability",
"capability": "ExternalUserAndGuestSharing"
},
{
"verb": "setRegionalSettings",
"timeZone": 13,
"locale": 1033,
"sortOrder": 25,
"hourFormat": "12"
}
]
}
Warning: This site is not themed. Please apply a theme to the site before exporting the theme.
Edited 06.11.2019: At Microsoft Ignite 2019, Microsoft announced that this feature will be available soon 🥳 What does soon mean? 😀 Well, I'm already able to use Get-SPOSiteScriptFromWeb in my tenant which runs as targeted release. Thank you very much for the feedback about this topic! I assume that Microsoft has been rolling out this feature gradually to Office 365 tenants and hope you will have it soon 😀 in your tenant. |
Site Script package
|
Edited 29.10.2019:
Along with the Site Script json definition file, admins will be able to
store extra assets in a package file (so called Site Script package). These
extra assets must be referenced in the Site Script json definition in order to
be used during provisioning. For instance, this new capability supports users
adding a Word document to the default document library (Shared Documents) using
Site Designs. In this case, the Word document must be added to the package and
a reference to the document must be added to Site Script json definition.
Edited 13.12.2019: The SharePoint Online Management Shell supports from the version 16.0.19515.12000 the Add-SPOSiteScriptPackage cmdlet. Unfortunately, trying to run this command results in the well known experimental error message: The requested operation is part of an experimental feature that is not supported in the current environment. Nevertheless, it is nice to see improvements in this feature. I've listed below the supported properties for this command: Add-SPOSiteScriptPackage -Title "Project Package" -Description "Content and optical enhancements for project sites." -ContentPath "C:\Packages\ProjectPackage.zip" Similar to Add-SPOSiteScript, Add-SPOSiteScriptPackage returns its ID which then can be used in a Site Design. |
Add File
|
Edited 29.10.2019:
How awesome would it be to add Word, PowerPoint, Excel, PDF etc. files to
document libraries in SharePoint using Site Designs? Well, this is going to be
addFile action’s task 😃
"verb": "createSPList",
"listName": "Customers",
"templateType": 101,
"subactions":
[
{
"verb": "addFile",
// The place in the document library to copy the
// file to. Note that path must include
filename. // E.g.: Price list.pdf
"destination": "",
// The place in the Site Script package to
// copy the file from. E.g.: Assets/Price list.pdf
"source": ""
}
]
 |
Add
Folder
|
Edited 29.10.2019
What
about folders? Microsoft didn't forget them 😃 addFolder will take care of adding folders to
document libraries. This action also acts as a sub-action of createSPList. This
is how the JSON looks:
"verb": "createSPList",
"listName": "Customers",
"templateType": 101,
"subactions":
[
{
"verb": "addFolder",
// The path of the new folder. E.g.: Customers/Events
"path": ""
}
]
If
you try to add folders to a document library using addFolder, you will end up
with the following message:
 |
Set
site logo from file
|
Edited 29.10.2019:
Setting a site logo for communication sites is already possible. For
instance, using the setSiteLogo action which supports setting the logo from an
URL. Microsoft will now support setting the logo from a file which will be
located in the Site Script package. From my point of view, it sounds very good
since admins get more control over the assets that are used during
provisioning. Here is what the JSON looks like:
"verb": "setSiteLogoFromFile",
// The place in the Site Script package to copy the file from.
// E.g.: Assets/Site_Logo.pdf
"source": ""
This is the message that Site Design displays if you try to use this
setSiteLogoFromFile action:
 |
Theme
json
|
Edited 29.10.2019:
Users can already apply a custom theme to a site collection. For that,
applyTheme action must be provided with a theme name. In the future, users will
be able to define the JSON schema for the theme using the themeJson property. On the one hand, admins get more control over the assets. On the other hand, admins
don’t need to add a custom theme to the tenant first in order to use it with
Site Designs. I wonder if themeJson property will also add the theme to the
tenant or if it only applies the theme to the site collection. Here is how
the JSON looks:
"verb": "applyTheme",
// The name of the custom theme to apply.
"themeName": "",
// A valid JSON object which contains the theme specification.
"themeJson": {}
If you know the themeApply action, you already know that themeName is a
required property. But when working with themeJson property the user must decide
between these two properties.
Below the message exception when trying to apply the theme using the
themeJson property:
Please
leave a comment if themeJson property is working on your environment.
Edited 19.11.2019: To apply the theme using the themeJson property, the applyTheme action must be configured as follows: "verb": "applyTheme",
"themeJson": {
"version": "2",
"isInverted": false,
"palette": {
"neutralPrimaryAlt": "#ff4b4b4b",
"themeLighterAlt": "#fff1faf0",
"black": "#ff1d1d1d",
"themeTertiary": "#ff55ae48"
}
}
Note that the themeJson property requires additional properties: version, isInverted and palette. Palette contains the theme definition! You can use this web site to generate a valid theme definition.
The applied theme won't be additionally added to the pool of tenant themes. Depending on the point of view, there is a disadvantage in this approach: If you change the theme applied using the themeJson property through the SharePoint UI, you can't select is again!
|
Set document template
|
Edited 17.01.2020:
Microsoft will bring additional sub actions for enhancing SharePoint lists. setDocumentTemplates is one of them! It provides support for adding one or more files as document templates in document libraries. Here is what its JSON configuration looks like:
"verb": "setDocumentTemplates",
"templateJSON": [
{
"isUpload": true,
"templateId":"Travel Expenses",
"title": " Travel Expenses",
"url": "Form/Travel Expenses.xlsx",
"visible": true
}
]
Since this action only works in combination with a Site Script package, which hasn't been released yet, you will get the following exception, when trying it in SharePoint:
 |
I'm looking forward to the next improvements for SharePoint Site Designs and Site Scripts. I hope Microsoft implements some of the ideas on my Wish List. I would also like to see the features under development released.
I hope you found this blog post interesting. See you on the next post! Follow me on twitter and keep up-to-date!
Follow @devjhorst
