Deployment guide.md

SharePoint web hooks reference implementation - Deployment guide

This guide will provide you step by step guidance on how to deploy this sample application. We'll first start with preparing the Azure resources, then we'll prep the application and SharePoint needs and finally we'll show you how to deploy the needed components.

Preparing Microsoft Azure for hosting the web hook sample application

For this sample we're using Azure Web Apps to host the SharePoint Add-In and host the Azure Web Jobs, we using an Azure Storage Account for it's queuing option and finally we use a SQL Azure database to host our data. In this chapter you'll be guided in how to setup these. All of the work in below chapters is done using the Azure management portal (https://portal.azure.com).

Creating the Azure Web Application

1. Adding a new Azure Web App

2. Give your web app a unique name, pick the subscription and resource group you want and finally select a service plan:

Important Remember the url you've chosen (pnpwebhookdemo.azurewebsites.net) in above screen-shot

3. Once the Web App is provisioned navigate to it and download it's publishing profile.

Important Store the publishing profile as you'll need this file later on

Creating the Azure SQL Server database

1. Adding a new Azure SQL database

2. Give your database a name, pick the subscription and resource group you want, select a service plan and select a server

Important Remember the name you've chosen (PnPWebHookDemo) in above screen-shot

2.1) Select an existing Azure SQL server if you already have one

2.2) or create a new Azure SQL server

Important Remember the name of the server you've chosen

3. Navigate to the created database and go to the server firewall settings

4. Configure the Azure SQL server firewall to allow access to the IP your using.

Creating the Azure Storage account

1. Add a new storage account

2. Configure the storage account: use the classic deployment model, select your subscription and resource group and finalize the account creation

3. Once the storage account is available navigate to it, go to Keys and copy the primary connections string

Important Remember the storage account connection string

Preparing SharePoint to host the application

1. Browse to the site you want to deploy the application on and create a new principal via hitting the appregnew.aspx page. You can generate the client id and secret, give it a title and define the app domain being the Azure Web app you've created earlier on (pnpwebhookdemo.azurewebsites.net) and finally enter the redirect url (https://pnpwebhookdemo.azurewebsites.net in this case).

Important Remember the client id and client secret

2. Verify you can access your applications app catalog which you can reach via your SharePoint Administration site

2.1) If you do not yet have an app catalog then create one

Prepare the application

Configure the SQL Azure database

1. Using SQL Server Management Studio (SSMS) connect to your SQL Azure database server

2. Open a new query for the SQL Azure database you've created earlier on (PnPWebHookDemo) in this case. The SQL script can be found in the SharePoint.WebHooks.Common project, folder SQL/scripts.

SET QUOTED_IDENTIFIER OFF;
GO
IF SCHEMA_ID(N'dbo') IS NULL EXECUTE(N'CREATE SCHEMA [dbo]');
GO

-- --------------------------------------------------
-- Dropping existing tables
-- --------------------------------------------------
IF OBJECT_ID(N'[dbo].[ListWebHooks]', 'U') IS NOT NULL
    DROP TABLE [dbo].[ListWebHooks];
GO

-- --------------------------------------------------
-- Creating all tables
-- --------------------------------------------------
CREATE TABLE [dbo].[ListWebHooks] (
	[Id] uniqueidentifier NOT NULL,
    [ListId] uniqueidentifier  NOT NULL,
    [LastChangeToken] nvarchar(max)  NOT NULL
);
GO
ALTER TABLE [dbo].[ListWebHooks]
ADD CONSTRAINT [PK_ListWebHooks]
    PRIMARY KEY CLUSTERED ([Id] ASC);
GO

3. Open a new query for the master database and run the below shown SQL command to create a new login

CREATE LOGIN WebHooksAdmin WITH PASSWORD = 'Pass@word1'

4. Create a database user and grant it permissions

CREATE USER [WebHooksAdmin] FOR LOGIN [WebHooksAdmin] WITH DEFAULT_SCHEMA = dbo

-- Add user to the database reader/writer roles
EXEC sp_addrolemember 'db_datareader', 'WebHooksAdmin'
EXEC sp_addrolemember 'db_datawriter', 'WebHooksAdmin'

Update the configuration files (web.config and app.config)

Update the web.config file from the SharePoint.WebHooks.MVCWeb project as shown below:

<appSettings>
    <add key="webpages:Version" value="3.0.0.0" />
    <add key="webpages:Enabled" value="false" />
    <add key="ClientValidationEnabled" value="true" />
    <add key="UnobtrusiveJavaScriptEnabled" value="true" />
    <!-- Add here a client id and secret for a principal that you grant permissions the needed permissions to the site you're installing this app to
    e.g. d54d2421-b7d5-44b5-b310-800f198f649b
    -->
    <add key="ClientId" value="<ADD THE CLIENT ID>" />
	<!-- e.g.RCmuPd9Y+JxGy5x6k1M0wdxxxxxxxx-->
    <add key="ClientSecret" value="<ADD THE CLIENT SECRET>" />
    <!-- Connection string to Azure storage account: we use a queue for async processing of web hook notifications 
         e.g. efaultEndpointsProtocol=https;AccountName=pnpwebhooksdemo;AccountKey=lG+wBesZObYg8r1pfHHZWf+XtjFuG+4EAHxxxxxx -->
    <add key="StorageConnectionString" value="<ADD THE CONNECTION STRING FOR STORAGE ACCOUNT>" />
    <!-- Name of your tenant e.g. contoso.sharepoint.com -->
    <add key="TenantName" value="<YOUR TENANT NAME>.sharepoint.com" />
    <!-- Url of your web hook service e.g https://pnpwebhookdemo.azurewebsites.net/api/webhook -->
    <add key="WebHookEndPoint" value="https://<ADD AZURE WEB APP NAME>.azurewebsites.net/api/webhook" />
  </appSettings>
  <connectionStrings>
    <!-- SQL Azure version -->
    <!-- We need to store the last used change token per subscription and use an Azure SQL database for doing so 
	e.g. metadata=res://*/SQL.ListWebHooks.csdl|res://*/SQL.ListWebHooks.ssdl|res://*/SQL.ListWebHooks.msl;provider=System.Data.SqlClient;provider connection string=&quot;data source=tcp:xxx.database.windows.net,1433;Database=PnPWebHookDemo;User ID=WebHooksAdmin;Password=xxxx;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;MultipleActiveResultSets=True;App=EntityFramework&quot;" providerName="System.Data.EntityClient
	-->
    <add name="SharePointWebHooks" connectionString="metadata=res://*/SQL.ListWebHooks.csdl|res://*/SQL.ListWebHooks.ssdl|res://*/SQL.ListWebHooks.msl;provider=System.Data.SqlClient;provider connection string=&quot;data source=tcp:<YOUR SQL SERVER>.database.windows.net,1433;Database=<YOUR DATABASE NAME>;User ID=<YOUR USER ID>;Password=<YOUR PASSWORD>;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;MultipleActiveResultSets=True;App=EntityFramework&quot;" providerName="System.Data.EntityClient" />
    <!-- Local dev version -->
    <!--<add name="SharePointWebHooks" connectionString="metadata=res://*/SQL.ListWebHooks.csdl|res://*/SQL.ListWebHooks.ssdl|res://*/SQL.ListWebHooks.msl;provider=System.Data.SqlClient;provider connection string=&quot;data source=(localdb)\MSSQLLocalDB;initial catalog=SharePointWebHooks;integrated security=True;multipleactiveresultsets=True;application name=EntityFramework&quot;" providerName="System.Data.EntityClient" />-->
    <!-- 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="<ADD THE CONNECTION STRING FOR STORAGE ACCOUNT>" />
    <add name="AzureWebJobsStorage" connectionString="<ADD THE CONNECTION STRING FOR STORAGE ACCOUNT>" />
  </connectionStrings>

Update the app.config file from the SharePoint.WebHooks.Job project as shown below:

<appSettings>
    <!-- Add here a client id and secret for a principal that you grant permissions the needed permissions to the site you're installing this app to
    e.g. d54d2421-b7d5-44b5-b310-800f198f649b
    -->
    <add key="ClientId" value="<ADD THE CLIENT ID>" />
	<!-- e.g.RCmuPd9Y+JxGy5x6k1M0wdxxxxxxxx-->
    <add key="ClientSecret" value="<ADD THE CLIENT SECRET>" />
    <!-- Name of your tenant e.g. contoso.sharepoint.com -->
    <add key="TenantName" value="<YOUR TENANT NAME>.sharepoint.com" />
    <!-- Url of your web hook service e.g https://pnpwebhookdemo.azurewebsites.net/api/webhook -->
    <add key="WebHookEndPoint" value="https://<ADD AZURE WEB APP NAME>.azurewebsites.net/api/webhook" />
  </appSettings>
  <connectionStrings>
    <!-- SQL Azure version -->
    <!-- We need to store the last used change token per subscription and use an Azure SQL database for doing so 
	e.g. metadata=res://*/SQL.ListWebHooks.csdl|res://*/SQL.ListWebHooks.ssdl|res://*/SQL.ListWebHooks.msl;provider=System.Data.SqlClient;provider connection string=&quot;data source=tcp:xxx.database.windows.net,1433;Database=PnPWebHookDemo;User ID=WebHooksAdmin;Password=xxxx;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;MultipleActiveResultSets=True;App=EntityFramework&quot;" providerName="System.Data.EntityClient
	-->
    <add name="SharePointWebHooks" connectionString="metadata=res://*/SQL.ListWebHooks.csdl|res://*/SQL.ListWebHooks.ssdl|res://*/SQL.ListWebHooks.msl;provider=System.Data.SqlClient;provider connection string=&quot;data source=tcp:<YOUR SQL SERVER>.database.windows.net,1433;Database=<YOUR DATABASE NAME>;User ID=<YOUR USER ID>;Password=<YOUR PASSWORD>;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;MultipleActiveResultSets=True;App=EntityFramework&quot;" providerName="System.Data.EntityClient" />
    <!-- Local dev version -->
    <!--<add name="SharePointWebHooks" connectionString="metadata=res://*/SQL.ListWebHooks.csdl|res://*/SQL.ListWebHooks.ssdl|res://*/SQL.ListWebHooks.msl;provider=System.Data.SqlClient;provider connection string=&quot;data source=(localdb)\MSSQLLocalDB;initial catalog=SharePointWebHooks;integrated security=True;multipleactiveresultsets=True;application name=EntityFramework&quot;" providerName="System.Data.EntityClient" />-->
    <!-- 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="<ADD THE CONNECTION STRING FOR STORAGE ACCOUNT>" />
    <add name="AzureWebJobsStorage" connectionString="<ADD THE CONNECTION STRING FOR STORAGE ACCOUNT>" />
  </connectionStrings>

Update the app.config from the SharePoint.WebHooks.Common project as shown below:

  <connectionStrings>
    <!-- SQL Azure version -->
    <add name="SharePointWebHooks" connectionString="metadata=res://*/SQL.ListWebHooks.csdl|res://*/SQL.ListWebHooks.ssdl|res://*/SQL.ListWebHooks.msl;provider=System.Data.SqlClient;provider connection string=&quot;data source=tcp:<YOUR SQL SERVER>.database.windows.net,1433;Database=<YOUR DATABASE NAME>;User ID=<YOUR USER ID>;Password=<YOUR PASSWORD>;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;MultipleActiveResultSets=True;App=EntityFramework&quot;" providerName="System.Data.EntityClient" />
    <!-- Local dev version -->
    <!--<add name="SharePointWebHooks" connectionString="metadata=res://*/SQL.ListWebHooks.csdl|res://*/SQL.ListWebHooks.ssdl|res://*/SQL.ListWebHooks.msl;provider=System.Data.SqlClient;provider connection string=&quot;data source=(localdb)\MSSQLLocalDB;initial catalog=SharePointWebHooks;integrated security=True;multipleactiveresultsets=True;application name=EntityFramework&quot;" providerName="System.Data.EntityClient" />-->
  </connectionStrings>

Deploy the application

Deploy the SharePoint Add-In - deploying to Azure

1. Right click on the SharePoint.WebHooks.MVCWeb project and choose publish

2. Import the earlier on downloaded publishing profile file

3. Switch the destination url to https

4. Choose the Debug configuration (at least if you want to remotely debug), select the created database and click on Publish

Deploy the SharePoint Add-In - deploying to SharePoint

1. Right click on the SharePoint.WebHooks.MVC project and choose publish

2. Select Package the add-in

3. Add your client id

4. Upload the created app package to the tenant app catalog

Deploy the Azure web job

1. Right click on the SharePoint.WebHooks.Job project and choose Publish as Azure WebJob

2. Define a schedule: choose continous + remove dots from the default name

3. Import the earlier on downloaded publishing profile file

4. Switch the destination url to https

5. Choose the Debug configuration (at least if you want to remotely debug) and click on Publish

6. Go to Azure management portal and verify the web job is created and in running state

Add the application to your SharePoint site

1. Add the add-in to your site via site contents

2. Select the correct add-in to add

3. The add-in will need to be trusted upon installation. Note that it can take a few minutes before the add-in installation is complete, please wait a bit before testing it.

Congrats!! You've completed the installation of this sample.