Thursday 4 January 2018

Using Site Designs or PnP templates for SharePoint site provisioning

So the new “site designs and site scripts” capability for creating SharePoint sites from a template is starting to become available in Office 365. This provides an alternative approach to using Microsoft’s Patterns and Practices (PnP) provisioning library and XML, which has been the way that most experienced implementers have been creating custom site templates in recent times. For a full “self-service” implementation, it’s typical to provide a custom form for end-users to request sites and provide any required information - the PnP building blocks provide support this, although some tailoring is needed in most cases plus the work to implement in the organization’s Office 365 and Azure environment. Microsoft are introducing site designs/site scripts as an alternative way of templating SharePoint sites, which is more baked-in to Office 365.

However, it’s not just a simple “either/or” decision between site designs and PnP – both are valid approaches, and there are quite a few considerations which could lead you to use one or the other. In addition, it’s also possible to combine both approaches by calling a PnP template *from* a site design. This is very welcome since:

  • there are lots of tweaks to a SharePoint site that are not possible yet with site designs
  • lots of organizations have an existing investment in custom site templates implemented with PnP

So, the implementer can choose between site designs, PnP provisioning, or a combination of the two. In this post I’d like to explore some of the factors around your SharePoint site creation/templating strategy.

Key considerations for Site Designs

1. End-users create sites directly (with no approval step)

Site designs that you define become available for selection in the out-of-the-box site creation experience. There is no approval process, and in general you have to be happy with the user experience which is provided. It’s the "SharePoint home" page where the site creation UI is surfaced - accessed from the 'SharePoint' text in the Office 365 header or the 'SharePoint' app in the app launcher. Self-service site creation must be enabled on the tenant for the 'Create site' link to show (SharePoint Admin Center > Settings > Site Creation > “Show the Create site command to users who have permission to create sites”). Note that it is possible to restrict the use of specific site designs to certain groups of people (e.g. if you had a template for an 'executive site' or a 'finance site', and only certain groups of people should see this option) with commands such as Grant-SPOSiteDesignRights or GrantSiteDesignRights (REST), but the top-level switch which enables all users to create sites must be enabled on the tenant – those commands only hide/show specific templates.  

Here’s what the experience looks like:

COB site design - create site

COB site design - site design selection

COB site design - form 1

COB site design - form 2 

2. It’s possible to provide a custom form, but implementation effort is needed (especially to collect custom metadata)

As users create sites, it’s common to want to collect some custom metadata – things like business unit, purpose, cost centre and so on. Happily, it appears possible to provide a custom form to facilitate this (but it’s not working yet in any of my tenants):

Custom site creation form

It’s not yet clear what form (ahem) the form is expected in. It could be that a PowerApp form is expected here, in which case we’d be specifying something like:

Custom site creation form - PowerApps

However, in addition to implementation effort required to develop and host the custom form, I envisage that a chunk of work is required for that custom metadata to be applied somewhere. After all, you’ll need to decide whether this gets stored somewhere in the site (e.g. property bag) or in some centralized list or database somewhere. So as an accompanying point, it’s perhaps worth remembering that…

2.5 There is no site directory “list”, except for your site collection list in the SharePoint Admin Center

In a typical SharePoint site templating implementation (based on PnP or not), there’s usually a SharePoint list which contains details of all the sites which have been requested and created. Often the implementer will store custom metadata (such as division, cost centre etc.) in this list, particularly if doesn’t need to be updated by the site owner on an ongoing basis. But there’s no such list with the native site creation setup, only your list of site collections in the SharePoint Admin Center - and remember these Group sites will only show in the NEW Admin Center due to be launched in early 2018! It’s not yet clear whether this will support custom metadata and make the whole thing easy, but I doubt it – I’d fully expect there to be work to do to handle your custom metadata, and I think that’s fair..

    3. Cannot block ability to create communication sites

    Some organizations are happy for end-users to create team sites from approved templates, but want communication sites to be a more controlled thing – perhaps because they’re worried some folks will take communication sites too far and create lots of mini-intranets. Unfortunately this isn’t possible currently. If end users can create SharePoint sites (the default), they can create both team sites and communication sites. Certainly, communication sites are a welcome addition to SharePoint Online - but I could believe some organizations will block the out-of-the-box site creation tools and implement their own version with more governance for this reason.

    The first step of creating a site using the out-of-the-box UI is shown below (but not in the series above) – as you can see, both types are available for selection:

    COB site design - site type

    4. Site designs create Office 365 Group sites (unless you have disabled the ability for end-users to create Groups)

    As you might know, when a site is created from the SharePoint home page (as shown above) it’s actually an Office 365 Group which is created – assuming that is, that your Office 365 environment is using the default setting which allows all end users to create Groups. If not, a classic/standalone SharePoint site is created. All this is the case whether a custom site design is applied or not. With a Group of course, a bunch of things are actually being provisioned not just a SharePoint site collection – including a shared mailbox for group conversations, a calendar, a Planner Plan and so on. This is perfect if your collaboration strategy is based on Office 365 Groups – but this requires detailed consideration. Organizations should not wander into this blindly.

    ..but a Team is not automatically created for the Group..

    Notably a Microsoft Team is not provisioned for the Group – similar to if the Group was created from Outlook, Yammer, Power BI or one of the other endpoints. But it is possible to easily add a Team as a separate step if needed. Any user who has permissions to create a Team will see something this option when they go to create a Team:

    COB create new team - 1

    COB create new team - 2

    In all this, you should be considering whether your strategy is based on Office 365 Groups which can be created by any user (the default), or whether you prefer to do something else. This is a fairly big topic, but there are several options here, including:

    • Provide a means for end-users to create (or simply request) SharePoint sites which are not Groups i.e. they are classic standalone SharePoint site collections
    • Restrict who can create Groups in the organization, by using the Set-AzureADDirectorySetting command with the "GroupCreationAllowedGroupId" parameter to restrict Group creation to members of a special group (e.g. I.T. staff) – see Manage who can create Office 365 Groups for more info
      • (N.B. Microsoft recently clarified the licensing requirements around enabling this option – users who ARE able to create Groups must have an Azure AD Premium license, but the rest of the organization does not)
    • Both of the above
    • Don’t use Groups at all
    • Provide a means for end-users to create (or simply request) a site which is an Office 365 Group, but using a custom form as described earlier or an entirely custom interface (e.g. because you have particular requirements not satisfied by the out-of-the-box UI)

    Overall, you can’t really get into site designs for team sites without considering wider aspects of collaboration. Oh and remember, if you provide site designs for communication sites (rather than team sites), those are NOT Group-connected sites. By the way I think Microsoft made the right call there, given the nature of most communication sites..

    5. Using site designs alone does not need Azure

    Most SharePoint site templating implementations which use PnP also use Azure. Certainly if self-service is involved, the typical arrangement is to have users request the site through a form, which adds an item to a list. Because site creation/template application takes some time, it needs to be an async process and so somewhere in there is usually an Azure queue with an Azure web job or Azure Function – this does the heavy lifting, and then e-mails the user and some administrators when the site is available. The PnP provisioning library provides much of these building blocks.

    However, we regularly run into organizations which are using Office 365 and it’s services, but do not use Azure or any competing cloud platform such as AWS yet. Of course, any Office 365 implementer knows that by using Office 365, the org is actually using Azure AD underneath, but really we’re talking about whether it’s possible to deploy remote SharePoint code such as PnP to the cloud. Often the InfoSec or compliance groups have not yet validated whether this is OK for the org, and there might be valid reasons why Office 365 is OK but other cloud services are not (yet).

    So, it might be compelling that site designs themselves bring no requirement for Azure. Sure, you’re limited to the templating options provided by site designs, but the “engine” which is applying the template to the site is Microsoft’s code running within the Office 365 service – no custom code is needed whether PnP or not, and therefore the infrastructure requirements are somewhat simpler.

    6. Site designs cannot be used on-premises, but PnP site templates can..

    Not too much to say here beyond that. Will site designs come to on-premises SharePoint in the future? Difficult to say, but it’s worth remembering that PnP site provisioning can be used in online and on-prem scenarios.

    7. Limitations of site designs

    One big caveat if you’re hoping to use only site designs for your site templates is that you’re currently limited to to what can be accomplished in a site design. The list of things you can add/change in the site is currently:

    • Add list:
      • Set title
      • Set description
      • Add column
      • Add content type (note – it must exist already! Site designs cannot provision new content types yet)
      • Set field custom formatting (with the new JSON-based formatting)
    • Apply theme
    • Join a hub site (although hub sites are not yet launched)
    • Set site logo
    • Add navigation link
    • Trigger a Microsoft Flow

    NOTE – this list will change over time. See the site design JSON schema reference for the latest picture and details of each operation.

    When I think about the other things we often change (using a PnP template) – changing the site locale/region settings, activating features, provisioning a new home page, adding and configuring web parts, setting the site access requests recipient, changing content types/views/applying versioning settings etc. on libraries – it becomes apparent that things are very limited indeed. For us, this is a complete blocker to the idea of using site designs on their own at the moment. Fortunately, the ability to call a Microsoft Flow is intended for you to supplement what the site design/site script is doing – so let’s explore this idea.

    The “site designs + PnP” approach

    In brief, the Flow can trigger some remote code you have to perform other configuration of the newly-created site. This allows you to chain a bunch of other things on to what you were able to do with the site design – for example, actions in my list of things not possible purely in site designs. Of course, the logical thing to do here is actually to apply a PnP template to the site as we would have done before site designs. The pattern is:

    1. Site gets created from site design
    2. Site design steps are applied
    3. Custom Microsoft Flow is called – this puts an item onto an Azure queue with details (e.g. URL) of the new site
    4. The Azure queue uses a QueueTrigger to start an Azure Function (or web job if you prefer)
    5. The function applies a PnP template to the site

    There’s some pretty good early documentation on this approach in Calling the PnP Provisioning Engine from a Site Script. That article shows using a function written in PowerShell which authenticates back to Office 365 using SharePoint Add-in authentication, but you might also choose a C# or node.js code approach which uses Azure AD and ADAL.NET/ADAL.js to authenticate back. Either way, there’s some work to do in Azure to get this running.

    The benefit of course, is that you unlock the ability to do anything you need to meet the requirements of the site, but can take advantage of the out-of-the-box UI for creating sites (and the fact that things are nicely baked-in to Office 365/SharePoint Online). Given that PnP site provisioning continues to expand it’s capabilities and we can now automatically deploy app packages containing SPFx web parts and extensions, or even SharePoint Add-ins, this approach will be common I feel. Indeed, I think we will implement “minimal” site designs which basically only call a Flow, and the entire template implementation is handled in a PnP template.


    It might sound like I’m down on site designs somewhat from the points I’m raising, but I’m not. I think this is a great evolution in SharePoint Online – no longer is all of a site templating solution is left to the implementer, since Microsoft are now taking care of some elements (however small to start with). I love the fact that some thought was given to how to go beyond the capabilities of site designs, and I’m sure the engineering teams were thinking specifically about how PnP templates could be incorporated. If I was king for a day, I would have preferred that the existing PnP template schema was used as the foundation for site designs in the first place (instead of introducing another approach to templating with a new JSON schema) – however, I do understand that the PnP engine is open source/community-driven and is not part of the core Office 365 platform, so perhaps that was part of the reason.

    The introduction of site designs certainly means that there are more options around SharePoint collaboration and site provisioning strategies! Being equipped with as much information as possible is wise – this will help you make the right decisions for you/your organization’s context..

    Also remember that site designs are still in preview (currently being rolled out to Targeted Release tenants) – hopefully it won’t be too long until the initial release hits General Availability, and the capabilities expand along the journey..

    Reference -


    Unknown said...

    Good overview of the options Chris. I'd add that there appears to be no way to capture extra metadata using site designs, though I think this was mentioned as a future possibility. For me this would be a blocker as well as the current limitations.

    Unknown said...

    Good overview of the options Chris. I might add that the site design customisation doesn't appear to allow you to add your own metadata, though I do believe that this was mentioned in a post somewhere that it could come in the future.

    Your comments about the SharePoint Admin Settings - "use the form at this URL" are a bit odd? That setting has been there for a long time and can be used to have your own custom application/form which is accessed from the Create Site link under the SharePoint screen. My company currently uses that exact method. The form is displayed in a dialog by SharePoint.

    best regards


    Jeff said...

    Thanks Chris that is helpful.
    Even though microsoft could have re invest pnp work, i am happy azure isn't mandatory to get some templating options.

    I hope some tool will generate the json for us.

    One question :
    Pnp provisioning template does support Modern site creation ?



    Chris O'Brien said...


    Good to meet the other day!

    You're right - the "Use a form at this URL" option has been there for a long time. I think I overlooked this because my team are so used to implementing a fully custom arrangement (e.g. PnP Partner Pack or similar). It's a good point though, so thanks :)



    Chris O'Brien said...


    Yes, there are already some samples but I'm sure other options for generating the JSON will become prevalent soon. And yes, the PnP building blocks do support provisioning modern sites - after all, a modern site is simply a site with the correct config around the document library experience and with a modern page as the default page - which PnP XML is certainly capable of.