Remote Provisioning Schema Documentation

Provisioning Schema

The provisioning Schema is defined as an XML Schema file, with annotations for further documentation.

Schema Namespace

The current schema namespace is:

http://github.com/OfficeDev/PnP-Provisioning-Schema/0.5

Namespace Location

Some editors can support inline schema validation and might require the schema location. A recommendation is to always specify the schema location using the XML Schema instance schemaLocation attribute.

<p:Provisioning xmlns:p="http://github.com/OfficeDev/PnP-Provisioning-Schema/0.5"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:schemaLocation="http://github.com/OfficeDev/PnP-Provisioning-Schema/0.5   https://raw.githubusercontent.com/OfficeDev/PnP-Provisioning-Schema/0.5/OfficeProvisioningSchema-0.5.xsd"
  >

Remote Provisioning Schema basics

The following are a high-level description of the schema

Provisioning Schema vs ye olde SharePoint Schema

In order to provide as much backwards compatibility with CAML and the SharePoint schemas, this provisioning schema uses the same XML formatting rules as the wss.xsd (Pascal Case elements, attributes and values). Also some elements have a direct representation in the provisioning schema: For instance this CAML Field definition can be copied to the provisioning schema and only a namespace definition has to be added. From:

<Field ID="{7B2B1712-A73D-4ad7-A9D0-662F0291713D}" Name="HealthRuleCheckEnabled" 
  Type="Boolean" Group="_Hidden" AllowDeletion="FALSE" DisplayName="Aktiverad"  
  SourceID="http://schemas.microsoft.com/sharepoint/v3/fields" 
  StaticName="HealthRuleCheckEnabled"  />

to:

<p:Fields>
  <Field 
    xmlns="http://github.com/OfficeDev/PnP-Provisioning-Schema/0.5"
    ID="{7B2B1712-A73D-4ad7-A9D0-662F0291713D}" Name="HealthRuleCheckEnabled" 
    Type="Boolean" Group="_Hidden" AllowDeletion="FALSE" DisplayName="Aktiverad"  
    SourceID="http://schemas.microsoft.com/sharepoint/v3/fields" 
    StaticName="HealthRuleCheckEnabled"
    ProvisioningAction="Provision" />
</p:Fields>

Artifact or template file

The artifact file is an XML file, that is defined by the Remote Provisioning Schema. The artifact file can also be called a template file.

Parameters

Each artifact file has a set of Parameters. Parameters can be defined in the artifact or template file or provided as arguments to the Remote Provisioning Engine. Parameters are used as replacements in the artifact/template file. Specific attributes in the schema has the type ReplaceableString. These attributes can have Parameters embedded, surrounded by curly braces ('{' and '}'). The ReplaceableInt can either be in integer or a integer parameter enclosed in curly brackets

<p:SiteCollection 
  ID="sc1" 
  Title="Team sites" 
  Url="https://{O365TenantName}.sharepoint.com/teams/team-sites"
  PrimarySiteCollectionAdmin="[email protected]"
  OverwriteOptions="Allowed">
  <BaseConfiguration Locale="{lcid}">STS#0</BaseConfiguration>
...
</p:SiteCollection>

Sequences

All artifacts that are to be provisioned belongs to a Sequence. The Sequences must be provisioned in the order that they appear in the artifact file. Each sequence contains one or more Containers (see below) that is to be provisioned. Each sequence can either be synchronous or asynchronous. For asynchronous sequences all containers can be provisioned asynchronous, if the engine supports it.

Containers

A Container is the base of everything that can be provisioned.

Supported Containers

The Schema currently support the following top level Containers

• Site Collection (SPO)
• Site (SPO)
• TermStore (SPO)

Future containers

• Mailbox (EXO)
• Yammer Group (Yammer)
• User (Azure AD)
• Group (Azure AD)

Other inner containers are

• Site (SPO)
• Lists, Files, Pages (SPO)
• Site Groups (SPO)
• Term Groups, Term Sets, Terms (SPO)

To provision or not provision a Container?

The Schema has an attribute ProvisioningAction that is used to define how the Container or item should provisioned or not. The default value is Provision which indicates that the engine MUST provision the item. A value of Unprovision indicates that the engine MUST unprovision or permanently delete the item. A value of Ignore indicates that the engine MUST ignore/skip provisioning/unprovisioning of the item.

Templates

The artifact file can also contain Templates, then the file is usually called a template file. Containers can have a corresponding Template.

To use a Template in a Container, the Container should support the child element TemplateReference of the type TemplateReferenceType that contains the value (string) of the ID of the Template.

For instance SiteTemplate is the Template for the Site and SiteCollection Container.

Extensions

The Extensions element in the schema can contain any arbitrary XML. This element is ment to be used for extensions to the Schema. It might be vendor or engine specific extensions or fill gaps that the current schema does not currently support.

Extensions can be used in a Container or in a Sequence.

<p:Extensions>
  <pnp:TypeExtension xmlns:pnp="http://pnp" assembly="Abc.Def" type="Abc.Def.Ghi"/>
  <np:ThemeExtension xmlns:pnp="http://pnp"
    Name="Contoso"
    ColorFile="Resources/Themes/Contoso/contoso.spcolor"
    FontFile="Resources/Themes/Contoso/contoso.spfont"
    BackgroundFile="Resources/Themes/Contoso/contosobg.jpg"
    MasterPage="seattle.master"
    AlternateCSS="Resources/Themes/Contoso/Contoso.css"
    SiteLogo="Resources/Themes/Contoso/contosologo.png"
    Version="1" />
</p:Extensions>