Provisioning SharePoint sites for K2 app using PnP Provisioning Engine

Monday, 13 June 2016

Office Dev Patterns and Practices initiative provides set of tools, libraries and samples for operations against SharePoint and Office 365 environments using client-side APIs and templates. I started to explore PnP Provisioning engine a little bit more in last few weeks, and especially excellent set of sessions provided by Vesa, Erwin and Paolo at this year’s SPC Adriatics conference in Zagreb. For me, most interesting area of research are scenarios that involve PnP Provisioning tools and K2 blackpearl using K2 App for SharePoint.

Integration between K2 and SharePoint is technically implemented as a custom Provider-Hosted/SharePoint Hosted app that contains a Custom Ribbon Action and Custom List Forms that replace OOTB Forms. After our K2 solution is completed and needs to be deployed to the destination site, it is necessary to create identical SharePoint artefacts on the destination site where K2 solution will be deployed – Lists, Custom Columns, Custom Content Types. To accomplish that, manual approach would require the following (https://help.k2.com/onlinehelp/k2forsharepoint/userguide/current/default.htm#Working_with_K2_for_SharePoint/Deploy.htm%3FTocPath%3DWorking%2520with%2520K2%2520for%2520SharePoint%7C_____3):

  1. Package K2 solution components to a KSPX package
  2. Uninstall K2 app from SharePoint site
  3. Create Site template / List Template from source site (SharePoint package)
  4. Create Site / List on destination environment from SharePoint package
  5. Install K2 app to destination site
  6. Deploy K2 solution from KSPX package

That process could be automatized by creating Site template/List Template in Visual Studio that would be deployed to both environments. However, there is another way:

We can use Patterns and Practices Site Provisioning Engine for customizing SharePoint sites that are “ready” for K2 App deployment, without the need for performing steps 2,3 and 4. This is particularly useful during development, as the K2 App does not have to be uninstalled and installed again during incremental development cycles.

When we use PnP Provisioning engine, we can create provisioning template from existing site using extension method on Web object

public static ProvisioningTemplate GetProvisioningTemplate(this Web web, ProvisioningTemplateCreationInformation creationInfo);

One of arguments of this method is ProvisioningTemplateCreationInformation that defines parameters of template creation process. One of those parameters is a set of processing handlers – that correspond to processing of artefacts on the source site that will/will not be included in the provisioning template. By default, all components of the source site will be included, and if we want to exclude something from a template, we need to exclude handlers from HandlersToProcess collection.

For a deployment of K2 solution, we need to create a site that does not include any K2 artifacts. That in turn means we need to create a template without custom commands (ribbon actions and button commands). We can accomplish this by disabling CustomAction handler.

Except for that, it is also possible to configure if we want to persist branding, include site groups, Managed Metadata Terms etc.

Here is my code snippet that I was using for provisioning template:

ProvisioningTemplateCreationInformation creationInfo
        = new ProvisioningTemplateCreationInformation(sourceWeb);
creationInfo.HandlersToProcess ^= Handlers.CustomActions;
creationInfo.HandlersToProcess ^= Handlers.SiteSecurity;
creationInfo.HandlersToProcess ^= Handlers.ContentTypes;
creationInfo.IncludeSiteGroups = false;
creationInfo.PersistBrandingFiles = true;

ProvisioningTemplate template = sourceWeb.GetProvisioningTemplate(creationInfo);

In my case I also disabled SiteSecurity and ContentTypes handler, and configured that I want to save current branding applied to the site.

Once I have ProvisioningTemplate, I can apply it to the target site. This can be done in similar way – there is a extension method ApplyProvisioningTemplate

public static void ApplyProvisioningTemplate(this Web web, ProvisioningTemplate template, ProvisioningTemplateApplyingInformation applyingInformation = null);

that has an argument ProvisioningTemplateApplyingInformation that defines parameters of process that applies template to created site.

ProvisioningTemplateApplyingInformation applyingInformation
        = new ProvisioningTemplateApplyingInformation();
applyingInformation.HandlersToProcess ^= Handlers.CustomActions;
applyingInformation.HandlersToProcess ^= Handlers.SiteSecurity;
applyingInformation.HandlersToProcess ^= Handlers.ContentTypes;

destinationWeb.ApplyProvisioningTemplate(template, applyingInformation);

This would be one approach for preparing sites for K2 installation on multiple environments using Patterns and Practices Provisioning Engine. It would help you to provision K2-ready sites faster and safer than to create them manually using wsp/stp packages of existing sites. You can read more about Provisioning Engine  on MSDN and play around with similar code sample available on  GitHub.

Let me know what you think about this article by commenting below or reach me via twitter. Looking forward to discuss Smile