PnP-SP-Starter-Kit Hints and Tips

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.

If you follow through the GitHub docs you may find that the set up guidance isn’t there yet… don’t worry, more documentation is coming sometime in the beginning of June. However, I am impatient and I wanted to see all of the cool things inside the starter kit! When I first started, I found myself seeing some errors and issues when trying to provision and load the files.

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. You may want to wait for the official documentation to be released… as this is entirely brand new!

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.

Clone

Or, you can use the following git commands

git clone https://github.com/SharePoint/sp-starter-kit/

Folder Structure

Looking at the image above, you can see the what the folder structure looks like. The web parts and customizers and other SPFx code is listed within the Solution folder. If you wanted to just manually deploy these assets instead of everything else within the starter pack, you could do so by navigating to the solution folder using command line, and running the following commands.

npm i
gulp bundle –ship
gulp package-solution –ship

This will create your sppkg file for your solution. These are built using the new ClientSideAssets… For more information on the deployment of SPFx solutions, follow this link.

If you’d like to know how the starter kit gets provisioned, you’d want to look into the provisioning folder. The readme file will let you know how to deploy the starter kit.

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

To deploy the starter kit,  the first thing you must do is build the SharePoint Framework solution using the following commands from within the solution folder.

npm i
 gulp bundle --ship
 gulp package-solution --ship

The deploy.ps1 should be handling this for you, but an error is causing it to build improperly. I am told this code should be fixed over the weekend.

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 -WeatherCity "Denver"

The WeatherCity parameter is for the weather web part 🙂

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 then deploy your SPFx package into your app catalog, and subsequently install the app package on 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!

Apply-PnPProvisioningTemplate Error

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. As mentioned, the script may not be creating the .sppkg file as expected. If you haven’t manually built the .sppkg package as mentioned above in “Deploy the starter kit”, do so now. Once you have packaged the solution, re-run the deploy.ps1.

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.

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).

navigation.png

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.

accessdenied.png

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!

APIManagement.png

 

User login is required

If you’ve configured the permissions in API management, you may find that the web parts still aren’t loading.

User login is required

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.

Emails.png

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!

Alerts

Once you have, you should be able to refresh your page see the alerts show up on your modern pages!

AlertDialog

 

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 will be coming from the team about how to provision the starter the pack. I hope this might be helpful to the people like me, who are impatient and can’t wait for the documentation to come out! 🙂

Thanks to the PnP team and Vesa for all their continued effort. Sharing is caring.

Security Trimmed Hub Site Navigation Updates!

I had recently posted a blog  about a SharePoint Framework (SPFx) application customizer I built for use with hub sites in Office 365. The problem I currently have with Hub navigation is that all of the links are static links. This means, that whoever creates the common navigation must be cognizant of what links end users have access to. With that in mind, I built a new navigation the replaces the out-of-the-box hub site navigation elements with a security trimmed listing of sites within a Hub.

For brevity, this isn’t an all inclusive tutorial. It’s just discussing the high level changes to the original implementation of the application customizer.

How it works

The new navigation uses a combination of the SharePoint Search API and the new Hub sites API. When a user lands on a site collection that belongs with in a hub, I grab the hub site information to find all of the sites that exist within the hub using the Search API. The benefit of this, is that I can security trim a listing of sites with in the navigation. That means I can have sites in a hub that a user may not have access to, yet include them as elements in the global hub site navigation.

HubNavSite

What’s wrong with V1?

While this approach is great and I have had quite a bit of success building out security trimmed navigation, the default implementation lacks the ability to use the existing hub site navigation elements. This is why I have released v2 which is available on GitHub for download.

The new application customizer still implements the “Sites” listing node in the navigation.
NewNav

Adding existing Hub navigation

Version 2 is almost identical to version 1 with the exception that I am now pulling in the static elements from the default hub navigation. To do this, I’ve made some modifications to the base ReactHubsiteNavbarApplicationCustomizer.ts file, to set the Navigation property equal to the navigation array that returns from the _api/web/hubsitedata endpoint.

this._currentHubSiteData = await  searchService.getHubSiteData().then((hubData: IAssociatedSite) => {
if(hubData){
return searchService.getHubID(hubData).then((hub: IHubSiteData) => {
//add existing hub navigation
hub.Navigation = hubData.navigation;
return hub;
});
}
else{
return null;
}
});

Now that I have the elements as part of the _currentHubSiteData object, I just have to modify my HubNavBar.tsx component to accommodate loading the existing navigation nodes. One thing that isn’t working currently with the commandbar, is the ability to have a navigation element with children, in which the parent link is clickable.

SiteTrimmedMenuCode

You may notice the methods are almost identical. Rather than refactoring… I’ve separated them out because I have some future changes I’d like to make specifically to the rendering of the trimmed sites listing.

Ability to edit navigation

Now that we are showing the existing navigation elements and hiding the existing Hub navigation html…I needed a way to allow users to add and edit the original Hub navigation. There is an endpoint at _api/Navigation/SaveMenuState for saving changes to the menu, however it is undocumented by Microsoft so I will avoid using it for now. Instead, I am going to re-use the out-of-the-box Hub site navigation control to manage adding/editing elements.

To do this, I am checking if the user has ManageWeb permission, and then I will show an edit button which will show/hide the original Hub navigation.
//if user has manage web permissions, show edit button
const hasPermission:boolean = this.props.context.pageContext.web.permissions.hasPermission(SPPermission.manageWeb);


if(hasPermission){
commandBarItems.push({
key:"editButton",
name:"Edit",
itemType:ContextualMenuItemType.Header,
onClick:this._editOnClick,
className:"editButton",
href:"#"
});
}

Caveat: The out of the box permission for managing Hub navigation is the new “Edit” permission. Which means that users in the Member group have access to change the navigation. I think this is a bit too much permission, so I am restricting the permissions to “ManageWeb”.

The Result

hubnavnew

The end result is a combination of security trimmed sites listing within the hub and the existing hub site navigation. User’s with ManageWeb permissions on the Hub site will be able to see the edit button to modify the existing navigation elements.

Notes

Because of the caching in the customizer, it may take 15 minutes for changes to appear!

GitHub – https://github.com/bcameron1231/SharePoint-Framework/releases/tag/v2.0

Code is in pre-release and subject to change (refactoring).