Monday, March 11, 2019

Wish list / Improvements that might be coming for SharePoint Site Designs and Site Scripts

Site Designs is a pretty new feature that improves provisioning in Office 365. Well, what's old in Office 365 πŸ˜Š In any event, I really love this new capability and like the development of the past months. There is no doubt that Site Designs has much more potential! In my opinion, Site Designs can become much more powerful than it already was.

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: I’ve tried out this property, but I've always gotten Forbidden as a response from the SetSiteScriptStageOutcome API. I’m looking forward to more information about it.

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.

I’m looking forward to seeing how to work with this new Site Script package.

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 πŸ˜ƒ

This action acts as a sub-action of createSPList. I wonder if there will be support for updating existing files since there is no override property yet. Here is what the JSON looks like:


"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"""
    }

]

Trying to add files using addFile results in the following exception:


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!

7 comments:

  1. Get-SPOSiteScriptFromWeb doesn't appear to be working with version 16.0.19418.12000 - still getting experimental feature message.

    ReplyDelete
    Replies
    1. Hello there,

      thank you for your feedback. I'm facing a different behavior. I've just updated this section with the output of this command. My Office 365 tenant runs as standard release! I'll continue testing this command and update my feedback here!

      Regards,
      Jarbas

      Delete
    2. Hello,

      I figured out the problem. I tested that a couple of times and it seems that Get-SPOSiteScriptFromWeb only works if the tenant is running as targeted release. I forgot that my tenant was actually running as targeted release :) Sorry for the misunderstanding here. If I change my release preferences to standard release, this PowerShell command stops working!

      I hope this helps.

      Regards,
      Jarbas

      Delete
  2. Win10p on FastTrack w/12000 installed. Still no Get-SPOSiteScriptFromWeb .... UGH.... What else did you have to do to get that enabled?

    ReplyDelete
    Replies
    1. What is the output in PowerShell when you request:
      Get-Module Microsoft.Online.SharePoint.PowerShell | Format-Table -Property Name,Version

      In my environment I get
      Microsoft.Online.SharePoint.PowerShell 16.0.19418.12000

      Delete

    2. I get the same results. I did change the release preferences to targeted yesterday. The change should have propagated by now, right? Locally I'm on 19013.1000 (OS). This is honestly really odd.

      http://s341.photobucket.com/user/MurrayShaun/library/SPOMS

      Delete
    3. Hello Shaun,

      thank you for your reply. I don't think that the changes propagate immediately. It can take a while until you get the new features. From my point of view, you have the correct settings. It could be that your tenant doesn't have this feature yet.

      I've just created a new Azure Virtual Machine (Win10p). I was able to successfully request Get-SPOSiteScriptFromWeb using both, the SharePoint Online Manage Shell and the Microsoft.Online.SharePoint.PowerShell module with version 16.0.19418.12000. Therefore, I don't think that the problem relies on your computer. I assume that your tenant doesn't have this feature available yet. Note that Microsoft gradually rolls out these features!

      If you want to ensure that your environment is not the problem, you can try to request this process by using CSOM. Here is what the request looks like:

      var tenant = new Tenant(clientContext);
      var temp =
      tenant.GetSiteScriptFromSite("https://example.sharepoint.com/", new TenantSiteScriptSerializationInfo() { IncludeBranding = true });
      clientContext.ExecuteQuery();

      This is the output:
      {
      "$schema": "https://developer.microsoft.com/json-schemas/sp/site-design-script-actions.schema.json",
      "actions": [
      {
      "verb": "setSiteBranding",
      "navigationLayout": "Cascade",
      "headerLayout": "Standard",
      "headerBackground": "None",
      "showFooter": false
      }
      ]
      }

      Regards,
      Jarbas

      Delete