Abstract: This is the first in a series of posts on how to customize the PnP Partner Pack based on business requirements. PnP Partner Pack allows you to extend the OOTB experience of Microsoft Office 365 and Microsoft Online by providing a variety of capabilities. PnP Partner Pack is using the PnP core component, which increases developer productivity with CSOM and REST based operations. In this blog, I will demonstrate how to extend the PnP Partner pack to meet our business requirements.
PnP Partner Pack is part of the Office 365 PnP.
In the first post, I will introduce the architecture of the PnP Partner Pack, overall capabilities it provides and what can be extended.
SharePoint Online Site provisioning
The PnP Partner Pack solution includes the following capabilities:
- Self-service site collection and sub site provisioning solution
- Fully configurable to meet business requirements
- Existing Sites can be saved as site template
- No need to learn about the knowledge about XML
- Remote provisioning through a remote timer job hosted on Azure
- Site Templates are available throughout the tenant
- UI package to avoid custom master pages
- Tools for administrators for governance: apply SharePoint tenant-wide branding, refresh site templates, creation of site collections
- Remote timer jobs (i.e. Azure Web Jobs) to perform typical enterprise governance operations to existing site collections and sites
- Branding and text elements are configurable
PnP Site Provisioning Engine
Here are some screen shots of the PnP Partner Pack:
Overview of Solution
The overall architecture of the PnP Partner Pack is based on an Azure Web App called OfficeDevPnP.PartnerPack.SiteProvisioning and on Azure Active Directory. Actually, all of the capabilities of the PnP Partner Pack are provided by an Azure Active Directory Application, and it is hosted in the Windows Azure Environment. The PnP Partner Pack was implemented as an Azure Active Directory Application, instead of a SharePoint Add-In, so we can apply the extensions and to play with the app targeting through the Azure Active Directory Application. There is no need to install the SharePoint Add-in for each target Site Collection.
The application runs against the SharePoint Online Tenant via an App Only access token, which allows the application to communicate with SharePoint regardless of what the current user is using the PnP Partner Pack and whether or not the current user has the appropriate permissions to the target SharePoint site collection. The application also consumes the Microsoft Graph API with an OAuth access token related to the current user identity.
The application requires tenant-level permissions. Furthermore, there are several web Jobs, which are provisioned along with the same Azure Web App which hosts the PnP Partner Pack Sites Provisioning Infrastructure. The Site Provisioning is implemented as an ASP.NET MVC Web Application, and depends on the PnP Core Component, as well as other required SharePoint client side assemblies.
Template Site Collection
In order to store artifacts that are required for provisioning a site, a site collection will be created during the setup process. This Site Collection includes document libraries which are used to store common site or site collection templates that are exported by the PnP Site Provision Engine, as well as the running information of the provisioning jobs.
- PnPProvisioningJobs: Document Library that stores the running information of provisioning Jobs. You can learn about the about the running status of provisioning job the user submits.
- PnPProvisioningTemplates: This document library stores site collection templates and sub site templates which you can select from when the user wants to create a site collection or a sub site.
These artifacts are available throughout the tenant and can be retrieved by the PnP Partner Pack Windows Azure Web App.
Custom Timer Job
Scenario: You have a customer who needs to create their own custom site template instead of the templates that the PnP Partner Pack provides. They want to specify a region, business unit, composed look, and site logo for every new site collection and sub site for tagging purpose.
There is an abstract class called ProvisioningJob which declares some basic information that provisioning a site requires. Every single job type is handled by a Job Handler, which again is a custom type that inherits from the ProvisioningJobHandler which is declared in the OfficeDevPnP.PartnerPack.Infrastructure.Jobs.Handlers namespace. There are some OOTB Job Handlers in the PnP Partner Pack solution:
- SiteCollectionProvisioningJobHandler
- SubSiteProvisioningJobHandler
- ProvisioningTemplateJobHandler
- BrandingJobHandler
- SiteCollectionsBatchJobHandler
- RefreshSitesJobHandler
Also, there are two classes called SiteCollectionProvisioningJob and SubSiteProvisioningJob, both classes derive from ProvisioningJob. These information will be used while provisioning a site 
If SiteCollectionProvisioningJob or SubSiteProvisioningJob don’t do what you want, you can create a totally new job type by inheriting from the ProvisioningJob instead of SiteCollectionProvisioningJob and SubSiteProvisioningJob. You need to define a custom Job Handler by inheriting from the base abstract class ProvisioningJobHandler. You will have to implement the RunJobInternalabstract method, and you will also need to implement the Init abstract method. Do what you want in both methods.
The next step is to create the custom ProvisioningJobHandler. There is also an abstract class called ProvisioningJobHandler and two basic Job handlers called SiteCollectionProvisioningJobHandler and SubSiteProvisioningJobHandler, which inherit from ProvisioningJobHandler.
The class SiteCollectionProvisioningJobHandler is responsible for creating a new site collection and provisioning it with the PnP site collection template that is the default template or custom template that the user exports from an existing site collection. Similarly, the class SubSiteProvisioningJobHandler is responsible for creating a sub site in the site collection and provisioning it with the sub site template.
In our scenario, we will define two custom classes for provisioning site collection and sub site by inheriting from SiteCollectionProvisioningJobHandler and SubSiteProvisioningJobHandler.
Configuration
The PnP Partner Pack leverages a custom configuration section, which allows you to define custom settings related to the current SharePoint Online tenant, the Azure Active Directory Application settings, as well as the configuration of the Provisioning Jobs and Provisioning handlers.
This section declares what the Job Handlers, the Job Types, and the execution model of the Job Types are. An execution model value of Scheduled means that the Job will be executed by the ScheduledJob, and the model value of Continous means that the Job will be executed by the ContinousJob. If you create any custom Job, you will have to define the Job Type and the Job Handler in this section shown in the red section above.
Conclusions
PnP Partner Pack is a very powerful pack for provisioning site collections and sub sites with some customization by supporting some extension capabilities: Custom Provisioning job, custom provisioning job handler and so on. For more detailed information regarding the architecture and implementation details please see here.
In my next post, we will demonstrate how to extend PnP Partner Pack in detail.
See also:
- Architecture and implementation details
- PnP Partner Pack – Manual Setup Guide
- Patterns and Practices
