If you are like me, you followed all of the updates at SharePoint Conference North America 2018 and you heard about an awesome new starter pack created by the PnP Team, and you couldn’t wait to install it and deploy it into your environment. You can find the Starter Kit here.
Please note, this blog post isn’t official documentation, nor am I a part of the PnP team… but these are just some issues I have seen as I’ve started exploring.
Before going any further
Before you follow the rest of this blog, please note that the PnP team has updated some of the deployment documentation. I highly recommend running through this documentation to make sure your environment is prepared for the PnP Starter Kit.
Documentation found here and tenant settings here.
Foreword
What is important to know is that this solution is an all encompassing solution. It provides you with web parts, customizers, site designs, MSGraphClient configuration, a hub site, lists, content types, a sample LOB application and more. This might be the most exhaustive example of modern SharePoint provisioning I have seen. There really is an impressive amount of work that was put into this! Kudos to the team and community for putting this together.
A few Hints
Downloading the Project
Downloading the project is quite simple, assuming you’ve developed SPFx before. If you haven’t, you may want to spend some time setting up your development environment.
To download the project, navigate to the starter kit from the link above. You can clone this repository to your local machine using the Github UI.
Or, you can use the following git commands
git clone https://github.com/SharePoint/sp-starter-kit/
If you’d like to know how the starter kit gets provisioned, you’d want to look into the provisioning folder. You’ll find a collection of PowerShell scripts which will help you deploy the starter-kit. Before you go any further, please read the documentation on GitHub and make sure you have configured your environment and followed the deployment procedures.
Update your PnPPowerShell module
You’ll want to update your PnPPowerShell module to the latest version. In order to do this, open up Powershell and execute the following command.
Update-Module SharePointPnPPowerShell*
Deploy the starter kit
- Make sure you’ve updated your PowerShell module above.
- Make sure your development environment is configured correctly here.
- Make sure your tenant is configured following this page.
- Make sure your tenant is “targeted release for everyone”.
- Wait 24 hours after enabling this
- Make sure your tenant has an app catalog
- Wait 24 hours after creating one
- Make sure you are a term store administrator.
To deploy the starter kit, you’ll need to upload the sharepoint-portal-showcase.sppkg from the /package folder to your app catalog. To learn how to upload files to your app catalog, follow this link.
Then open up Powershell and navigate to your provisioning folder. Once inside the folder, execute the following command to start the provisioning process.
.\deploy.ps1 -TenantUrl https://YourTenant.sharepoint.com -SitePrefix Demo
The SitePrefix parameter is for the prefix of the newly created site collections.
When you execute this command, you’ll notice a ton of actions happen. The solution is going to create a couple demo sites for you. “Demo_Portal”, “Demo_hr”, “Demo_Marketing”. The script is going to create the Demo_Portal site as a hub site, and connect the other two sites to it.
The script will install the app package you previously uploaded in the app catalog into the sites that are being created. It will then create two site designs for Team sites and for a Communication site, and then create new navigation elements for your hub sites.
The deployment script will also create a handful of pages for your Portal site and automatically provision the web parts to the page. This is just the start… the deployment script actually provisions and exhaustive set of functionality, however this post isn’t about all of the functionality. 🙂 Have a look yourself and see what it provisions!
Deployment Failed
When upload the .sppkg file to the AppCatalog, you may receive an error stating “Deployment failed”. Just delete the .sppkg file and re-upload the package to the app catalog!
Error in application
When uploading the .sppkg file into the App Catalog, you may receive this error. If you had just recently created your App Catalog, you may need to wait up to 24 hours for the change to fully propagate successfully. So wait 24 hours and try to upload the .sppkg file again!
Apply-PnPProvisioningTemplate Error #1
Apply-PnPProvisioningTemplate : Object reference not set to an instance of an object. At C:\Users\beaucameron\spfx\sp-starter-kit\provisioning\deploy.ps1:96 char:5
This will likely be the first error you see when trying to deploy the solution. Make sure the .sppkg file is already in the app catalog. If you haven’t manually deployed it, please do so now by following in the instructions at the top of this blog. If you haven’t created an App Catalog in your tenant, you will also need to do this.
If you just recently created the App Catalog, you may have to wait up to 24 hours for it to be completely functional.
App Package Not Valid
Apparently some people have been unable to deploy the solution to the app catalog and receive an error that the app package is not valid. Garry Trinder mentioned this issue, and so far others have confirmed that it is because API Management configuration is missing from your admin center. If this error happens for you and you are also missing API Management from the new Admin Center could you let me know (confirmation)?
In order to add API Management to your admin center, you must enable “Targeted Release” for your tenant, instead of specific users. It may not be immediate and may take a few hours for the changes to propagate to your tenant. When doing this, you should do it on a non-production tenant.
New-PnPSite Error
If you are receiving the following error:
New-PnPSite : {"d":{"Create":{"__metadata":{"type":"SP.Publishing.CommunicationSiteCreationResponse"},"SiteStatus":3,"SiteUrl":""}}}
Could you confirm if you have had previously deployed the starter-kit and then subsequently deleted the site collections and re-deployed? If so, could you let me know. It appears that there may be an issue with the New-PnPSite command when executing against a deleted communication site.
I have repro’d this error by running the deploy.ps1 using no -SitePrefix parameter. I then deleted the sites that were created, and re-ran the deploy.ps1. Even the though the sites do not exist, the New-PnPSite command cannot create a new site.
Try re-executing the command but modifying it by adding a new SitePrefix. .\deploy.ps1 -TenantUrl https://YourTenant.sharepoint.com -SitePrefix NewSitePrefix
If you’d like to re-use an existing SitePrefix, you can a couple PowerShell commands to clean up the deleted sites. Per @Andreas (thanks!)
//permanently delete all deleted sites
Connect-SPOService -Url “SharePoint Admin Tenant Url”
Get-SPODeletedSite | foreach { Remove-SPODeletedSite -Identity $_.Url }
//Remove hubsite associations
Get-SPOHubSite | ? {$_.Title -eq “PnP SP Starter Kit”} | Unregister-SPOHubSite
A service principal with the name SPFx-LOB-Function could not be found / a service principal with the name SPFx-LOB-WebAPI could not be found.
Inside API management in the admin center, you may find that when you are trying to approve the API permissions you receive this error on the LOB-Service application. I believe the reason is because the LOB service API doesn’t get provisioned with the deploy.ps1 script. So these service principals aren’t a part of your tenant’s AAD.
If you look inside your repo/folder structure, you’ll see a folder named sample-lob-service, which holds a Visual Studio solution for a sample WebAPI project. This solution needs to be deployed to your Azure environment, and two service principals have to be created with two permissions scopes:
- a default “user_impersonation” scope
- a custom “Customers.Read” scope
The service principals needs to be created and given permission to your sample-lob-service API.
Long story short – You need to register a resource in Azure for this WebAPI, subsequently deploy it and configure the service principals. There isn’t any documentation yet about setting this up. As this is a new starter-kit… documentation is still being created by the PnP Team. I suspect more information on how to setup/configure/deploy this will be coming in the future.
My navigation isn’t showing up
One of things you may notice after deploying the starter kit, is that the hub navigation doesn’t work. In general, hub navigation is a bit finicky but a simple way to make the navigation show up is by editing the navigation and cancelling out… or just wait for it to fix itself (caching).
Personal Web Parts aren’t loading
If you navigate to the personal page in the navigation, it brings you to a really awesome page with a bunch of SPFx web parts on it that utilize Microsoft Graph. These web parts include:
- Upcoming Meetings,
- My Tasks
- Personal Contacts
- Personal Email
- Recent Documents
- Recent Sites
You may find the personal web parts aren’t loading correctly, here are some possible reasons.
Access is denied. Check credentials and try again.
You may find that your personal web parts, aren’t loading at all and showing you that your credentials are invalid. This is because (at least in my environment), you need to explicitly give permission to the SPFx web parts to have access to the Microsoft Graph. If you navigate to the new admin center, https://yoursite-admin.sharepoint.com/_layouts/15/online/AdminHome.aspx on the left hand side, select API Management under Advanced. You’ll see a list of pending approvals for the new applications. Approve this request and your web parts will start working!
User login is required
If you’ve configured the permissions in API management, you may find that the web parts still aren’t loading.
It appears there is a bug (race condition?) that has effected acquiring a token for the AadHttpClient/MSGraphClient. Creating a new page and/or workbench, may allow you to see the web part temporarily. However, the bug/issue still exists and is linked below.
I found there is a support ticket on this issue which can be found on GitHub, issue 1810.
I have no Alerts
One of the cool application customizers deployed with this starter pack is a top header that shows configurable alerts. This is one of the only lists that doesn’t pre-populate with data through the deployment process. If you’d like to test it out, navigate to site contents and add some alerts to the Alerts list!
Once you have, you should be able to refresh your page see the alerts show up on your modern pages!
More…
If you’d like to know more of the features that are included in the starter kit, Robert Shouten has made a great post outlining the web parts and functionality here.
Disclaimer
Once again, I’d like to re-iterate that this isn’t any official documentation and that more documentation is linked at the top of this post.
Thanks to the PnP team and Vesa for all their continued effort. Sharing is caring.
Beau Cameron 