Deploying M365 Learning Pathways in your GCC High Tenant

[robgarrett]

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 are Learning Pathways?

Microsoft 365 learning pathways is a customizable, on-demand learning solution designed to increase usage and adoption of Microsoft 365 services in your organization.

Microsoft 365 learning pathways is a customizable, on-demand learning solution designed to increase usage and adoption of Microsoft 365 services in your organization. Learning Pathways consists of a fully customizable SharePoint Online Communication site collection, with content populated from the Microsoft online catalog; so, your content is always up to date. Learning Pathways provide integrated playlists to meet the unique needs of your organization.

M365 Learning Pathways build atop of the Look Book Provisioning Service and templates (https://lookbook.microsoft.com).  In a previous blog post, we detailed the nuances of the Look Book Provisioning Service and additional steps required to deploy templates to GCC High tenants. Since Learning Pathways depend on the provisioning service to create a Communication site with customizations, via a Look Book template, this post details the additional steps to follow those from the earlier blog post.

Challenge – Using Learning Pathways in GCC High

Because of provisioning limitations in the GCC High sovereign cloud, documented installation instructions result in errors.

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 M365 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 Microsoft 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.

Apply Learning Pathways to GCC High

Manual configuration steps detailed below make Learning Pathways in GCC High possible.

Looking to update the Learning Pathways Web Parts in an existing deployment? Click here.

Microsoft 365 Learning Pathways offers manual steps to support deployment to an existing SharePoint Online Communication site. Recall from the earlier blog post that the Look Book Provisioning Service is unable to establish a new site collection in GCC High, because of necessary restrictions. We, therefore, deploy Learning Pathways using the manual steps with a pre-provisioned Communication site collection.

Manual setup of Learning Pathways requires experience working with Windows PowerShell and the PnP PowerShell module.

Prerequisites

Before getting into the manual steps, we must meet prerequisites for manual install of Learning Pathways, the following is a summary:

• Create and designate a new Communication in SharePoint Online for Learning Pathways.
• Create a tenant-wide application catalog (steps below).
• Install the latest SharePoint PnP.
• Perform all steps as a SharePoint Tenant Administrator.

Newer versions of GCC High tenants have a ".us" suffix for the tenant name (tenant.onmicrosoft.us).

If you're tenant has a ".com" suffix, replace all instances of ".us" with ".com" in the PowerShell cmdlets in this article.

We begin by creating a new Communication site via the SharePoint Administration site:

https://mytenant-admin.sharepoint.us/_layouts/15/online/AdminHome.aspx#/siteManagement/view/ALL%20SITES

Ensure the appropriate permissions for users of the Learning Pathways site:

1. Open the Learning Pathways site collection in your web browser.
2. From the home page, click the Share link.
3. Add students to the Site Visitors group.
4. Add playlist editors of the pathways site to the Site Members group.
5. Add site administrators of the pathways site to the Site Owners group.

We shall now create the tenant app catalog (if it does not already exist):

6. Open the SharePoint Admin center in your browser.
   

   https://mytenant-admin.sharepoint.us​

7. Select More Features in the left sidebar.
8. Locate the Apps section and click Open.
   

   https://mytenant-admin.sharepoint.us/_layouts/15/online/TenantAdminApps.aspx​

9. Select the App Catalog.
10. If you do not already have an app catalog, provide the following details:
    • Title: App Catalog
    • Web Site Address Suffix: preferred suffix for the app catalog, e.g. apps.
    • Administrator: SharePoint Administrator.

We shall now turn our attention to installing the latest version of PnP.PowerShell. At the time of writing this blog, the latest version of PnP.PowerShell is 1.5.x. Follow the instructions, in the box below, to install the latest pre-release version (required).

You can check the available versions of installed PnP.PowerShell with the Get-Module PnP.PowerShell -ListAvailable. If you do not have version 1.5.x or greater follow the instructions in the below box.

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.

• 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).
• Ensure unrestricted execution policy with:
  

  Set-ExecutionPolicy Unrestricted​

• Check the installed version of PowerShellGet with the following cmdlet:
  

  Get-PackageProvider -Name PowerShellGet -ListAvailable​

• If you see version 2.2.5.0 or greater, skip the next two bullets.
  Note: if you have PowerShell 5.1 and 7.x installed, you may have different versions of PowerShellGet for each version of PowerShell.
• 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​

• Close and reopen your PowerShell console (again, as an administrator).
• Install PnP.PowerShell with the following:
  

  Install-Module -Name PnP.PowerShell -AllowPrerelease -SkipPublisherCheck -Scope AllUsers -Force​

• Close and reopen your PowerShell console (run as administrator not required this time).
• Confirm that PnP.PowerShell is installed with the following:
  

  Get-Module -Name PnP.PowerShell -ListAvailable​

11. Open a new PowerShell console (v5.1 or Core 7.x).
    
12. Ensure the PnP.PowerShell module is loaded with the following:
    

    Import-Module -Name PnP.PowerShell

    If you have multiple versions of PnP.PowerShell install, target a version greater than 1.5.x with the -RequiredVersion flag.

13. Run the following script ONCE per tenant to create an Azure App Registration for PnP:
    Note: Replace tenant with your tenant name.
    

    Register-PnPAzureADApp -ApplicationName "PnP PowerShell" `
    -Tenant [TENANT].onmicrosoft.us -Interactive `
    -AzureEnvironment USGovernmentHigh `
    -SharePointDelegatePermissions AllSites.FullControl, User.Read.All

    Login with user credentials assigned Global Administrator role.
    If you previously registered PnP.PowerShell, check the App Registration in the Azure portal and make sure it has delegated permissions for AllSites.FullControl and User.Read.All. Also make sure that you've granted consent as an Administrator.
14. Make a note of the GUID returned from step #13. This is the App/Client ID of the new PnP Azure App Registration.

Deploy Learning Pathways Template

Learning Pathways deploys as from a dedicated Look Book template. The following steps details downloading the template and deploying it via PnP.PowerShell.

Download the template files from https://github.com/SharePoint/sp-dev-provisioning-templates/tree/master/tenant/M365LearningPathways 

15. Open a new PowerShell console (v5.1 or Core 7.x).
16. Ensure the PnP.PowerShell module is loaded with the following:
    

    Import-Module -Name PnP.PowerShell

    If you have multiple versions of PnP.PowerShell install, target a version greater than 1.5.x with the -RequiredVersion flag.

17. Connect to your Learning Pathways site collection with the following:
    

    Connect-PnPOnline `
    -Url "Url of your Learning Pathways Site" `
    -AzureEnvironment USGovernmentHigh `
    -Interactive `
    -Tenant "[TENANT].onmicrosoft.us `
    -ClientID "Client ID from AAD app registration in Step #13"​

18. Enable custom scripts on your site with the following (note: check with you security team before enabling this feature):
    

    Set-PnPTenantSite -Identity "Url of your Learning Pathways Site" -DenyAddAndCustomizePages:$false​

19. Apply the template with the following:
    

    Invoke-PnPSiteTemplate -Path M365LP.pnp​

20. Connect the SharePoint Framework Web Part to your learning site with the following:
    

    Set-PnPStorageEntity `
    -Key MicrosoftCustomLearningSite `
    -Value "<URL of Learning Pathways site collection>" `
    -Description "Microsoft 365 learning pathways Site Collection";
    
    Set-PnPStorageEntity `
    -Key MicrosoftCustomLearningTelemetryOn `
    -Value $false `
    -Description "Microsoft 365 learning pathways Telemetry Setting";​

Updating the SharePoint Framework (SPFx) Web Parts

The template files, which you downloaded earlier contains the latest Sharepoint Framework (SPFx) web parts. Users looking to update just the SPPKG file in the SharePoint App Catalog can do so, as follows:

21. Locate the M365LP.pnp file from the downloaded template files.
22. Make a copy of this file as M365LP.pnp.zip
23. Open the ZIP file and look for the file with SPPKG extention in the Files folder of the Archive.

    The filename should look like <GUID>.sppkg.

24. Extract the SPPKG file.
25. Upload the SPPKG file to the SharePoint App Catalog site collection.