Asynchronous on-demand site collection provisioning to Office 365 with Azure WebJobs
This is follow up post for my previous post related on building on-demand asynchronous operations using Azure storage queues and Azure WebJobs. Like mentioned in the initial post, one of the typical use cases for this kind of pattern would be to use it for site collection provisioning in the Office 365.
In this blog post we will walkthrough our reference sample for asynchronous on-demand site collection provision to Office 365 with Azure WebJobs. This is pretty typical solution needed for customers in the Office 365 if they are looking for self service site collection capabilities for their end users. Our sample scenario is relatively simple and concentrates on provisioning new site with out of the box site definition and only customization is a custom branding, which is applied to the site. You could though easily extend this solution for example to have following typical capabilities.
- Request approval – Provision requests entry to SP site and start actual site creation when item is approved
- Complex templates – provision always oob site, but apply difference customizations based on end user selection
- Site metadata – Collect metadata from the site and store that to reusable location
- Site directory – Show information on provisioned sites with for example filtering support on collected metadata
Logical design for our solution
Here’s a logical design and usage of the different techniques for achieving this solution.
- Provider hosted app is installed and hosted in Office 365
- Provider hosted app shows the different template options and collects other relevant metadata for creation
- Notice that these could be abstract templates like just templates called as X, Y and Z. Each one will be based on oob team site, but difference is the changes which are applied to the site after the oob site provision is completed. You do not want to use web templates or site templates.
- Actual request is added to storage queue for async processing and end user will be notified on this saved request
- Storage queue will automatically fire a connected WebJob, which will then have responsibility to provision requested site with given configuration and branding
- Actual site is provisioned to the Office 365 using app only token by the WebJob
Reference solution structure
Here’s the Visual Studio solution structure.
Provision.Cloud.Async.WebJob.Console.Create
This is helper project to ensure that you have properly registered app id and app secret with tenant permissions to your site collection. You can do this by using appregnew.aspx and appinv.aspx pages. See Kirk Evan’s blog post for more information on this.
You should update tenant name and admin account email to the app.config. You should also update AppId and AppSecret keys accordingly in the app.config.
<appSettings>
<add key="TenantName" value="contoso" />
<add key="SiteColTestOwnerEmail" value="admin@contoso.onmicrosoft.com" />
<!-- Register app id and secret with tenant permissions for this -->
<add key="ClientId" value="[Your App ID]" />
<add key="ClientSecret" value="[Your App Secret]" />
</appSettings>
Provision.Cloud.Async.WebJob.Console.Message
This is helper project which can be used to ensure that you have storage queues connection string properly available and you can use this project to easily send site collection creation messages to the storage queues without running any UI elements. You should be updating the Azure storage connection string from the app.config project to ensure that this works properly and if you truly want to test the whole provisioning story, update also the tenant name and owner email information.
<appSettings>
<add key="TenantName" value="contoso" />
<add key="SiteColTestOwnerEmail" value="admin@contoso.onmicrosoft.com" />
<add key="StorageConnectionString" value="DefaultEndpointsProtocol=https;AccountName=[AccountName];AccountKey=[AccountKey]" />
</appSettings>
Provision.Cloud.Async.WebJob
This is the actual SP app project for the provider hosted app UI. We do ask permission to the Web level so that we can resolve details on the user who is accessing the app in the code.
Provision.Cloud.Async.WebJob.Common
This is the business logic component used by the helper projects and the actual projects for storage queue handling and also for the site collection creation.
Provision.Cloud.Async.WebJob.Job
Actual web job project, which is deployed to the Azure web site. This is continuous running WebJob which will be automatically called when new items are being added to storage queue. You will need to configure app id and app secret in the app configuration and also the connection strings for the WebJob as follows.
<appSettings>
<!-- Use AppRegNew.aspx and AppInv.aspx to register client id with proper secret -->
<add key="ClientId" value="[Your Client ID]" />
<add key="ClientSecret" value="[Your Client Secret]" />
</appSettings>
<connectionStrings>
<!-- The format of the connection string is "DefaultEndpointsProtocol=https;AccountName=NAME;AccountKey=KEY" -->
<!-- For local execution, the value can be set either in this config file or through environment variables -->
<add name="AzureWebJobsDashboard" connectionString="DefaultEndpointsProtocol=https;AccountName=NAME;AccountKey=KEY" />
<add name="AzureWebJobsStorage" connectionString="DefaultEndpointsProtocol=https;AccountName=NAME;AccountKey=KEY" />
</connectionStrings>
Notice that above settings can be configured either in app.config before you deploy WebJob to Azure or from web site configuration tab in the Azure side.
Provision.Cloud.Async.WebJobWeb
This is the self service user interface to request site collections. You can use this to fill the form and submit request to the storage queue. Actual message submission logic is actually called from the Common project.
<appSettings>
<add key="ClientId" value="bd8b31ca-ea88-448a-875f-33eb9e99ae73" />
<add key="ClientSecret" value="g63EIwWqa/RwrBUxLw8eVTcOftQ+WSbjMNXUJ74htJo=" />
<add key="StorageConnectionString" value="DefaultEndpointsProtocol=https;AccountName=[AccountName];AccountKey=[AccountKey]" />
</appSettings>
Here’s the current user interface for requesting new site collections from end user perspective.
When a request has been submitted, end user will be shown following confirmation on the received message. Request is actually added to Azure storage queue, which will then automatically start up the provision process from WebJob.
Video on the solution usage in practice
Here’s a short video on using this solution in practice, which explains the solution structure and purpose of each project. Notice that this one does not explain details on the pre-requisites related on Azure storage queues and web job deployment, which are the same as for the sample in the “Using Azure storage queues and WebJobs for async actions in Office 365”.
Office 365 Developer Patterns and Practices
Techniques showed in this blog post are part of the Provisioning.Cloud.Async.WebJob solution in the Office 365 Developer Patterns and Practices guidance, which contains more than 100 samples and solutions demonstrating different patterns and practices related on the app model development together with additional documentation related on the app model techniques.
Check the details directly from the GitHub project at https://aka.ms/OfficeDevPnP. Please join us on sharing patterns and practices for the community for the benefit of the community. If you have any questions, comments or feedback related on this sample, blog post or anything on PnP, please join us and more than 1700 others who are using Office 365 Developer Patterns and Practices Yammer group at https://aka.ms/OfficeDevPnPYammer.
“From the community for the community” – “Sharing is caring”