You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Calling the PnP provisioning engine from a site script
3
3
description: Build a complete SharePoint site design using the PnP provisioning engine
4
-
ms.date: 07/04/2020
4
+
ms.date: 11/25/2020
5
5
localization_priority: Priority
6
6
---
7
7
8
8
# Calling the PnP provisioning engine from a site script
9
9
10
+
> [!NOTE]
11
+
> This article uses a version of PnP PowerShell that is currently in pre-release and planned to GA in January 2021. As Azure Functions run PowerShell Core, you'll have to use this version of PnP PowerShell in your Azure Function. For more information about this version of PnP PowerShell see https://pnp.github.io/powershell.
12
+
10
13
Site designs offer a great way to standardize the look and feel of your site collections. However, you can't do some things with site designs, like add a footer to every page. You can use the PnP provisioning engine to create a template that you can use to provision an Application Customizer to a site. This Application Customizer can then update your page design, for example to register a footer on every page.
11
14
12
15
This article describes how to create a site design that applies a PnP provisioning template to a site. The template will add an Application Customizer to render a footer.
@@ -18,51 +21,31 @@ The steps in this article use the following components:
18
21
- Azure Queue storage
19
22
- Azure Functions
20
23
- A SharePoint Framework (SPFx) solution
21
-
- A PnP provisioning template
24
+
- A PnP site template
22
25
- A PnP PowerShell script
23
-
- An app ID and app secret with administrative rights on your tenant
26
+
- An Azure AD App Registration
24
27
25
28
You'll use these components to trigger the PnP provisioning code after you create the site and apply the site design.
To set up app-only access, you need to have two different pages on your tenant—one on the regular site, and the other on your SharePoint administration site.
32
-
33
-
1. Go to following URL in your tenant: `https://[yourtenant].sharepoint.com/_layouts/15/appregnew.aspx` (you can go to any site, but for now pick the root site).
34
-
35
-
2. Next to the **Client Id** and **Client Secret** fields, choose the **Generate** button.
36
-
37
-
3. Enter a title for your app, such as **Site Provisioning**.
38
-
39
-
4. In the **App Domain** box, enter **localhost**.
40
-
41
-
5. In the **Redirect URI** box, enter **https://localhost**.
42
-
43
-
44
-
45
-
6. Choose **Create**.
46
-
47
-
7. Copy the values for **Client Id** and **Client Secret** because you will need them later.
48
-
49
-
<br/>
34
+
We are going to use authentication with a clientid and a certificate in this tutorial.
50
35
51
-
Next, trust the app, so that it has the appropriate access to your tenant:
36
+
1. Create a new self-signed certificate with PnP PowerShell on your computer:
1. To confirm that you want to trust this app, choose **Trust It**.
46
+
As a result of the command a new Azure AD Application will be registered, permissions will be set correctly, and you will have provided consent to use this application in your tenant. Notice that you require write access to the Azure AD for this.
65
47
48
+
1. Copy the values the cmdlet returns as you will need the pfx file and the AzureAppId value later.
66
49
67
50
## Create the Azure Queue storage
68
51
@@ -79,7 +62,6 @@ To set up the Azure Queue storage:
79
62
1. Enter **pnpprovisioningqueue** for the name, or enter your own value; be sure to follow the naming standard. Make note of the queue name; you will need this value when you create the Azure Function.
80
63
1. Go to **Access Keys** and note the **Storage Account Name** and the **key1 Key value**. You will need these values when you create the flow.
81
64
82
-
83
65
## Create the flow
84
66
85
67
To put a message in the queue, you need to create a flow.
@@ -123,7 +105,7 @@ To put a message in the queue, you need to create a flow.
123
105
1. Choose the first step in your flow ('When an HTTP request is received') and copy the URL.
124
106
1. Save your flow.
125
107
126
-
Your flow should look like the following.
108
+
Your flow should look like the following:
127
109
128
110
Invoke-RestMethod -Uri $uri -Method Post -ContentType "application/json" -Body $body
138
120
```
139
121
140
-
When you go to the main screen of your flow, you will see a run history. If your flow worked correctly, it will show `Succeeded`.
122
+
When you go to the main screen of your flow, you'll see a run history. If your flow worked correctly, it will show `Succeeded`.
141
123
Now go to the queue you just created in Azure and choose **Refresh**. You should see an entry that shows that you correctly invoked the flow.
142
124
143
125
## Provision the SPFx solution
@@ -171,116 +153,81 @@ Copy the following provisioning template XML to a new file and save the file as
171
153
172
154
1. Go to the [Azure Portal](https://portal.azure.com).
173
155
1. Choose **+ Create a resource**.
174
-
1. Search for **Function App** and create a new function app. In the **Storage** field, select **Use existing**, and select the storage account that you created earlier. Set the other values as required.
175
-
1. Within the Function App select **Configuration** > **Function runtime settings** and change the runtime version from **~3** to **~1**.
156
+
1. Search for **Function App** and create a new function app. In the **Storage** field, select **Use existing**, and select the storage account that you created earlier. Set the other values as required, but make sure to select **PowerShell Core** as the **Runtime** and select **7.0** as the **Version**
176
157
177
-
158
+
178
159
179
-
> [!NOTE]
180
-
> Function Apps based on the runtime version ~3 or ~2 only support PowerShell Core as programming language. At this moment, PnP PowerShell cmdlets can be only executed under PowerShell (and not on PowerShell Core).
181
-
>
182
-
> First, to make available Powershell at the level of the Function App, the runtime version has to be set to **~1**.
183
-
>
184
-
> Secondly, PowerShell can be only activated from the **classic experience** of the Azure Portal, by enabling the **Experimental Language Support**, at the level of the Function App.
185
-
>
186
-
> Read more about [Azure Functions runtime versions.](https://www.microsoft.com/download/details.aspx?id=35588)
160
+
1. When created, navigate to your new Function App
161
+
1. Select **App Files**
162
+
163
+
187
164
188
-
1.Temporarly switch the Azure Function App's user interface to the **classic experience** from the current experience. Select **Overview** in the left-hand navigation and select **Switch to Classic experience**as shown in the following figure.
165
+
1.In the dropdown menu, select **requirements.psd1**and add a new entry as follows
189
166
190
-
167
+
```powershell
168
+
# This file enables modules to be automatically managed by the Functions service.
169
+
# See https://aka.ms/functionsmanageddependency for additional information.
170
+
#
171
+
@{
172
+
# For latest supported version, go to 'https://www.powershellgallery.com/packages/Az'.
173
+
'Az' = '5.*'
174
+
# For the latest supported version, go to 'https://www.powershellgallery.com/packages/PnP.PowerShell'.
175
+
'PnP.PowerShell' = '0.2.17-nightly'
176
+
}
177
+
```
178
+
Save the file. Notice, that if you do no intent to use the Azure PowerShell Cmdlets you can remove that entry from this file. The requirements.psd1 file makes sure that specific PowerShell modules will be available to all functions. At the first execution of the Azure Function these modules will be downloaded and made available. You can also use wildcard references for the version. See for more information about this file here: https://docs.microsoft.com/azure/azure-functions/functions-reference-powershell?tabs=portal#dependency-management
191
179
192
-
1. Create a new Azure Function **Functions** > **New function**:
180
+
1. Create a new Azure Function **Functions** > **Add**:
193
181
194
182
195
183
196
-
1. Enable **Experimental Language Support**:
197
-
198
-
199
-
200
-
1. Create a new Queue Triggered function based upon PowerShell:
184
+
1. Create a new Azure Store Queue Trigger function:
201
185
202
186
203
187
204
-
1. Name the function **ApplyPnPProvisioningTemplate**.
188
+
1. Name the function **InvokePnPSiteTemplate**.
205
189
1. Enter the name of the queue you created earlier.
206
-
1. Choose **Create**. An editor where you can enter PowerShell cmdlets will open.
207
-
208
-
Next, you'll upload the PnP PowerShell module so that you can use it in the Azure Function.
190
+
1. Choose **Add**. A new page opens where you can modify the function.
209
191
210
192
> [!NOTE]
211
193
> The Storage account must be in the same region as of Azure Function App, because the resources that talk to one another should be co-located in the same region. This is a requirement for Azure Functions.
212
194
213
-
## Upload the PnP PowerShell module for your Azure Function
214
-
215
-
You'll need to download the PnP PowerShell module so that you can upload it for your Azure Function.
Notice that you're using two environment variables: ```SPO_AppId```and ```SPO_AppSecret```. To set those variables, go to the main Function App page in the Azure Portal (the one with the yellow light bolt icon), select **Configuration** and add two new application settings:
266
-
267
-
1. ```SPO_AppId``` - Set the value to the Client ID you copied in the first step when you created your app on your tenant.
268
-
2. ```SPO_AppSecret``` - Set the value to the Client Secret that you copied in the first step when you created your app on your tenant.
217
+
Replace **[insertyourAppIdHere]** with the value that the `Register-PnPAzureApp` cmdlet returned for AzureAppId.
269
218
270
219
## Create the site design
271
220
272
-
Open PowerShell and make sure that you have the [SharePoint Online Management Shell](https://www.microsoft.com/download/details.aspx?id=35588) installed.
273
-
274
-
Connect to your tenant using **Connect-SPOService**.
221
+
Open PowerShell and connect to your tenant using **Connect-PnPOnline**.
Add-PnPSiteScript -Title "Apply PnP Site Template" -Content $script
264
+
Get-PnPSiteScript
318
265
```
319
266
320
267
1. You will see a list of one or more site scripts, including the site script you just created. Select the ID of the site script that you created and copy it to the clipboard.
321
268
1. Use the following command to create the site design:
322
269
323
270
```powershell
324
-
Add-SPOSiteDesign -Title "Site with footer" -SiteScripts [Paste the ID of the Site Script here] -WebTemplate "64"
271
+
Add-PnPSiteDesign -Title "Site with footer" -SiteScriptIds [Paste the ID of the Site Script here] -WebTemplate TeamSite
325
272
```
326
273
327
-
The **Add-SPOSiteDesign** cmdlet associates the site design with the team site. If you want to associate the design with a communication site, use the value "68".
328
-
329
274
## Verify the results
330
275
331
276
After you created your Azure Queue storage, you created the app ID for app-only access, the Azure Function, and the site design. You then triggered the Power Automate flow from the site design.
0 commit comments