Tuesday, November 12, 2019

Extracting a site collection using SharePoint Site Designs (Get-SPOSiteScriptFromWeb)

At Microsoft Ignite 2019, Microsoft announced that the capability of extracting a SharePoint site collection using Site Designs will be available soon 🥳 Lucky me, because it is already working on my Office 365 tenant which run as targeted release 😀 In this blog post, I want to show you how you can extract a site using Site Designs. In addition, I will also show what is supported when extracting the site.


Short feature overview:

Site Designs was enhanced by the capability of extracting a site as a Site Script. It means that you can reuse an existing site collection to create copies of that. This process supports additional parameters which you can use to define what will be extracted.


What can I extract?

Comparing to other extraction tools like PnP or Sites.asmx service, Site Designs is still very limited in terms of the supported components. Nevertheless, it is a good alternative to existing tools, especially if the scope of components to be extracted is small.

The Site Designs feature for extracting site collections can be enhanced by supportive parameters. These parameters define the components to be extracted. During extraction, these parameters will be converted to Site Script actions/verbs which make the extracted output very easy to be reused. Below I've listed all the supported parameters:

IncludeBranding: Supports extracting the branding of a site collection. Here is what the output of this parameter looks like:

"verb""setSiteBranding",
"navigationLayout""Megamenu",
"headerLayout""Standard",
"headerBackground""None",
"showFooter"true

IncludeTheme: Supports extracting the custom theme of a site collection. The output of this parameter depends if the site is themed or not. If the site is not themed, you will end up with either an exception or a warning message:

Exception: No actions could be successfully exported. Additional information: This site is not
themed. Please apply a theme to the site before exporting the theme.

Warning: This site is not themed. Please apply a theme to the site before exporting the theme.

Here is the output if the site is themed. Note that I shorted the output of the palette property in order to improve readability.

"verb""applyTheme",
"themeJson": {
"version""2",
"isInverted"false,
"palette": {
    "neutralPrimaryAlt""#ff4b4b4b",
    "themeLighterAlt""#fff1faf0",
    "black""#ff1d1d1d",
    "themeTertiary""#ff55ae48",
    "primaryBackground""#ffffffff",
    ...
    }   
}

Very interesting here is the themeJson property! The applyTheme action has been supporting only the themeName property. Now you can use the themeJson property to enter a theme based on its JSON definition instead of its name. That makes the extraction very flexible, since it supports applying this script to another tenant which doesn't have a theme by name.

IncludeRegionalSettings: Supports extracting the regional settings. Here is how the output of this parameter looks:

"verb""setRegionalSettings",
"timeZone"13,
"locale"1033,
"sortOrder"25,
"hourFormat""12"

IncludeSiteExternalSharingCapability: Supports extracting the external sharing capability. Here is how the output of this parameter looks:

"verb""setSiteExternalSharingCapability",
"capability""ExternalUserAndGuestSharing"

IncludeLinksToExportedItems: Supports extracting links from the quick launch. There is a logical dependency between a navigation link and a list. Therefore, this parameter must be used along with the IncludedLists parameter. When using this parameter without the IncludedLists parameter, I ended up with the following exception:

"No actions could be successfully exported. Additional information: No QuickLaunch links
suitable for export could be found. In order to export navigation links pointing to lists, the list needs to be included in the site script as well."

I was testing this parameter also with custom links like "www.microsoft.com", but it didn't extract that. I did also try to extract the link to the Shared Document library but it didn't work. During my tests, this parameter has stopped outputting the link when used correctly. I assume that Microsoft is still working on it 😀

This is what the output looks like if the parameter is used/work correctly:

{
    "verb""createSPList",
    "listName""Project Activities",
    "templateType"100,
    "subactions": [
        ...
    ]
},
{
    "verb""addNavLink",
    "url""/Lists/Project Activities",
    "displayName""Project Activities",
    "isWebRelative"true,
    "navComponent""QuickLaunch"
}

IncludedLists: Supports extracting one or more SharePoint lists. Here is what the output of this parameter looks like:

"verb""createSPList",
"listName""Project Activities",
"templateType"100,
"subactions": [
  {
    "verb""addSPView",
    "name""All Items",
    "viewFields": [
      "LinkTitle"
    ],
    "query""",
    "rowLimit"30,
    "isPaged"true,
    "makeDefault"true,
    "addLink""Project Activities"
  }
]


What kind of site collections are supported?

I tested the Get-SPOSiteScriptFromWeb command with the site collections that my customers have been mostly using. I tried to extract the regional settings, the branding, the theme, the sharing capability and the shared documents library of the corresponding site collections. No matter which site collection I've used, Site Designs was always able to extract the content according to my specifications. Of course, the extraction output depends on the site collection type. For instance, IncludeBranding parameter will always return footer as false for a modern team site (Office 365 group) since a modern team site doesn't support editing the footer area by default. I listed below the site collections that I've used for testing:

- Communication Site
- Modern Team Site (Office 365 Group)
- Classic Team Site
- Modern Team Site without Group


Extract a SharePoint site in different ways:

The extraction of a site collection using Site Design can be done with PowerShell, REST or CSOM. I demonstrated below how to extract a site collection using PowerShell, REST and CSOM:

PowerShell:

Get-SPOSiteScriptFromWeb 
-WebUrl https://example.sharepoint.com/sites/template 
-IncludeBranding 
-IncludeTheme 
-IncludeRegionalSettings 
-IncludeSiteExternalSharingCapability 
-IncludeLinksToExportedItems 
-IncludedLists ("Protocols""Lists/Project Activities")

REST:

POST: https://example-admin.sharepoint.com/
_api/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.GetSiteScriptFromWeb


   "webUrl":"https://example.sharepoint.com/sites/template",
   "info":{ 
      "IncludeBranding":true,
      "IncludedLists":[ 
         "Clients",
         "MyList"
      ],
      "IncludeRegionalSettings":true,
      "IncludeSiteExternalSharingCapability":true,
      "IncludeTheme":true,
      "IncludeLinksToExportedItems":true
   }
}

CSOM: 

var tenant = new Tenant(ctx);

var info = new TenantSiteScriptSerializationInfo()
{
    IncludeBranding = true,
    IncludeTheme = true,
    IncludeRegionalSettings = true,
    IncludeLinksToExportedItems = true,
    IncludeSiteExternalSharingCapability = true,
    IncludedLists = new[] {"Protocols""Lists/Project Activities"}
};

var response = tenant.GetSiteScriptFromSite("https://example.sharepoint.com/sites/template/", info);

ctx.ExecuteQueryRetry();

Note that in CSOM the method to extract the site collection is called GetSiteScriptFromSite! In PowerShell and REST it is called ...FromWeb. So, don't get confused when extracting sites using PowerShell, REST or CSOM 😀


Summary:

The capability of extracting a site using Site Designs is definitely a feature that SharePoint admins have been waiting for since it supports reusing the work already done. The scope of supportive parameters is still very small, but I believe that Microsoft will be publishing other parameters over the time.

I hope you enjoyed reading this blog post. See you on the next post! Follow me on twitter and keep up-to-date!

2 comments:

  1. YES! Your blog has been invaluable for me, thank you so much for taking the time to write everything up... I had a quick question, I'm struggling with the deployment after you get said script. It isn't taking my shortcuts on the left and applying them correctly during provisioning. It is putting them in there, but after the original default settings.

    Might you know of something I might be missing in order to use the updated template that is downloaded instead of mashing it all together?

    ReplyDelete
    Replies
    1. Good morning Shaun!

      Thanks, I appreciate your compliments!!! It looks as the IncludeLinksToExportedItems paramenter isn't working consistently. I tried to get the navigation links by using PowerShell and REST, but it is not working anymore. That must be a bug!

      For now, it looks as you have to fix the script after downloading it 🙁 I will let you know if I find something new.

      BR,
      Jarbas

      Delete