Using SharePoint Look Book in your GCC High Tenant (New PNP)
Published Mar 24 2021 12:20 PM 5,875 Views
Microsoft

Contributors:

Rob Garrett - Sr. Customer Engineer, Microsoft Federal 

John Unterseher - Sr. Customer Engineer, Microsoft Federal

Martin Ballard - Sr. Customer Engineer, Microsoft Federal 

 

This article replaces the previous article, which used the - now legacy - version of PnP PowerShell.

 

What is Look Book? 

 

SharePoint Look Book templates build upon the open-source Patterns and Practices site provisioning engine.

 

Look Book templates are a set of Microsoft-provided site designs that programmatically add custom user interface elements to SharePoint Online sites. Microsoft has published a public web site with a set of showcase templates to should satisfy most customer needs: 

https://lookbook.microsoft.com 

 

Each category of templates targets the functionality of various industry verticals. For example, the Organization category contains templates for customizing SharePoint sites for Crisis Communication, Organization News, Leadership Information, to name a few. 

 

SharePoint Look Book templates build upon the open-source Patterns and Practices site provisioning engine: 

https://docs.microsoft.com/en-us/powershell/sharepoint/sharepoint-pnp/sharepoint-pnp-cmdlets?view=sh... 

 

The templates themselves are a set of web assets (CSS, images, etc.) with accompanying template XML file that instructs the provisioning engine how to apply the customizations to an existing SharePoint Online site collection.  SharePoint Look Book templates follow Microsoft recommended SharePoint User Interface Design principles: 

https://spdesign.azurewebsites.net/ 

 

Users of Look Book templates should understand that the templates are “after-market” customizations applied to existing site collections. The base SharePoint Online offering in Office 365 does not provide these templates, nor their associated branding/customization. The templates are not available for end users to select from a central gallery as with earlier versions of SharePoint Server on-premises. 

 

The Look Book web site facilitates the creation of a new Communication site collection and then the application of the template customizations to that site collection. The Look Book provisioning web site achieves this process via a tenant application, which requires tenant administration consent. Administrators deploying the first Look Book templates will see a consent dialog like the following: 

robgarrett_1-1615411610942.jpeg

The Look Book provisioning service works with the regular Government Community Cloud (GCC) but not in the High variant without modification.

 

Challenge – Using Look Book in GCC High

 

Microsoft strives to implement functionality parity between all sovereign clouds. However, since each Office 365 cloud type serves a different customer audience and requirements, functionality will differ between these cloud types. Of the US clouds – Commercial, Government Community Cloud, Government Community Cloud High, and DOD Cloud, the last two offer the least functionality to observe US Federal mandates and compliance.  

 

As Microsoft develops new functionality for Office 365 and Azure clouds, we typically release new functionality to commercial customers first, and then to the other GCC, GCC High, and DOD tenants later as we comply with FedRAMP and other US Government mandates. Open-source offerings add another layer of complexity since open-source code contains community contribution and is seldom developed with government clouds in mind. 

 

The Look Book provisioning service (https://lookbook.microsoft.com) relies on open-source Patterns and Practices code and community developed APIs that may operate differently in GCC, GCC High, and DOD clouds.  As an open-source resource, the SharePoint Look Book templates are not directly supported by Microsoft. 

 

At the time of this writing, the Look Book provisioning service works with the regular Government Community Cloud (GCC) but not in the High variant without modification. GCC High places restrictions on cross domain access as well as script execution. GCC High and GCC reside on two different top-level domains: sharepoint.com vs. Sharepoint.us. 

 

Solution – Apply Templates via PowerShell 

 

We can create Communication sites in GCC High and then run PowerShell to affect the customizations after. 

 

Recall that the Look Book provisioning service leverages Patterns and Practices APIs to both create new site collections and lay template customization atop. Specifying a GCC High tenant, the service fails during the request to provision a new site collection. Fortunately, we do not require this service to create vanilla Communication or Team site collections in GCC High tenants. Instead, we can create sites in GCC High and then run PowerShell to affect the customizations after. 

 

robgarrett_2-1615411926897.jpeg

 

The application of Look Book templates, although existing within the Look Book provisioning service, is also available via PowerShell. Assuming a tenant administrator has pre-created an out-of-the-box Communication or Team Site, they may leverage the SharePoint PnP PowerShell Module to apply a template.

 

Required site collection type: Communication or Team, depends on the chosen Look Book template. Some work with Communication sites and some Team sites. See the GitHub link below for more details:

https://github.com/SharePoint/sp-dev-provisioning-templates

 

PnP PowerShell installation is a prerequisite for deploying Look Book templates via PowerShell. The previous edition of this article used the - now legacy - SharePointPnpPowerShell module. At the time of writing, the new steps require the latest bits for PowerShellGet, Nuget Package Provider and PnP.PowerShell module. You only need follow these side-line steps once for a specified Windows machine.

 

  1. Open a PowerShell console as an administrator (right-click, Run As Administrator).
    Note: The latest version of PnP.PowerShell is cross-platform and works with PowerShell Core (v7.x).

  2. Check the installed version of PowerShellGet with the following cmdlet:
    Get-PackageProvider -Name PowerShellGet -ListAvailable​
  3. If you see version 2.2.5.0 or greater, proceed to step #5.
    Note: if you have PowerShell 5.1 and 7.x installed, you may have different versions of PowerShellGet for each version of PowerShell.

  4. Install the required version of PowerShellGet with:
    Install-PackageProvider -Name Nuget -Scope AllUsers -Force
    Install-PackageProvider -Name PowerShellGet -MinimumVersion 2.2.5.0 -Scope AllUsers -Force​
  5. If you ran step #4, close and reopen your PowerShell console (again, as an administrator).

  6. Install PnP.PowerShell with the following:
    Install-Module -Name PnP.PowerShell -AllowPrerelease -SkipPublisherCheck -Scope AllUsers -Force​
  7. Close and reopen your PowerShell console (run as administrator not required this time).

  8. Confirm that PnP.PowerShell is installed with the following:
    Get-Module -Name PnP.PowerShell -ListAvailable​

 

 

The following details the steps to provision a Look Book template via PowerShell:

  1. Download the desired templates from the following location: 
    https://github.com/SharePoint/sp-dev-provisioning-templates/tree/master/tenant  

  2. Open a new PowerShell console (v5.1 or Core 7.x).

  3. Ensure the PnP.PowerShell module is loaded with the following:
    Import-Module -Name PnP.PowerShell

     

  4. Run the following script ONCE per tenant to create an Azure App Registration for PnP:
    Note: Replace tenant with your tenant name and the AzureEnvironment with the associated sovereign cloud.
    Register-PnPAzureADApp -ApplicationName "PnP PowerShell" `
      -Tenant [TENANT].onmicrosoft.com -Interactive `
      -AzureEnvironment [USGovernment|USGovernmentHigh|USGovernmentDoD|Germany|China] `
      -SharePointDelegatePermissions AllSites.FullControl `
      -SharePointApplicationPermissions Sites.FullControl.All `
      -GraphApplicationPermissions Group.ReadWrite.All `
      -GraphDelegatePermissions Group.ReadWrite.All​
    Login with user credentials assigned Global Administrator role.

  5. Make a note of the GUID returned from step 4. This is the App/Client ID of the new PnP Azure App Registration.

  6. If you see the following consent dialog, review the requested permissions and click Accept. If you'd prefer different permissions, change the requested Graph and SharePoint permissions in step #4.

    robgarrett_0-1615417212832.png
  7. Connect to the Communication site collection:
    Note: Replace tenant with your tenant name and the AzureEnvironment with the associated sovereign cloud. Replace the ClientId with the GUID returned in step #4. The URL is to the site collection you want to apply a template.
    Connect-PnPOnline -Url https://[TENANT].sharepoint.[com|us|mil|de|cn]/sites/[SITE COLLECTION] `
      -Interactive -AzureEnvironment [USGovernment|USGovernmentHigh|USGovernmentDoD|Germany|China] `
      -ClientId [ClientID] -Tenant 
    "[TENANT].onmicrosoft.com"​
    Login with user credentials assigned Global Administrator role (some templates make tenant-level changes).

  8. Apply one of the templates to your site collection with the following: 
    Invoke-PnPSiteTemplate -Path  <path to file>\<template>.pnp
  9. The previous command will use the PNP file (contains XML) to instruct the PnP template API to configure the previously created site collection.

robgarrett_1-1615418832112.jpeg

 

Your site collection should now be fully provisioned with the elements of the template you have chosen.  It will be necessary to repeat these steps for any additional Look Book sites you wish to provision for your organization.  Let us know what you think in the comments below. 

 

Note: The SharePoint Look Book provisioning service and SharePoint PnP PowerShell modules are open-source resources not supported by Microsoft.  Additionally, always know the risks associated with making change in your tenant in the Global Admin role when running scripts changing configurations.

 

2 Comments
Version history
Last update:
‎Mar 24 2021 02:22 PM
Updated by: