Microsoft 365 Community PnP Webcasts, 30 Jan 2017

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: PnP Webcast - Introduction to SharePoint webhooks

Description

This PnP webcast gives you an introduction into SharePoint Webhooks. SharePoint Webhooks allow developers to build services which receive notifications on specific events that occur in SharePoint. When one of those events is triggered, SharePoint will send a HTTP POST payload to the subscribed service. SharePoint Webhooks will be supported for asynchronous events, like for ItemAdded or ItemAttachmentAdded. To be able to subscribe to SharePoint Webhooks, you'll need to build a service, which will response on the subscribed validation messages and will process the incoming events.
Details on covered content is available from https://dev.office.com/blogs/introduction-to-sharepoint-webhooks.
Presentation used in this webcast is available from http://docs.com/OfficeDevPnP.
Webhooks documentation is available from https://dev.office.com/sharepoint/docs/apis/webhooks/overview-sharepoint-webhooks.
The sample used in this webcast can be found here https://github.com/SharePoint/sp-dev-samples/tree/master/Samples/WebHooks.List.AzureAD.

A

Hello, everyone welcome to the introduction to SharePoint web hooks. This webcast will give you an overview of what SharePoint web ebooks are and how you can leverage them in your SharePoint developments with me today. I have a vessel Vernon FSI. Can you please introduce absolutely.

B

So my name is I openin, a Mustaine, your program manager from office, traces, the file, ship and engineering to paper, size and I'll. Be your bird's, lovely assistant today, asking random questions. Hopefully,.

A

Not too difficult question fester, so I I'm Burton I'm a surgeon here inside Microsoft, so going on. Let's quickly talk about what is PNP yeah.

B

So let me do it quickly, this slide just to explain for those who might have watched these videos for the first time. Sharepoint PNP is an engineering driven community initiative where we were together with community MVPs and on MVPs to provide code samples, guidance document, ations, monthly community calls and other community calls and case studies. We have them as well.

B

The themes are in shape on framework, which is the new shiny thing going to qi a relatively soon while we're recording this video and then obviously sharepoint add-ins, remote api's in general, Microsoft graph of straight 65 80 is the guidance applies for both shipment on on a line and on-premises for the lab. Well, whatever is actually supported in on-premises as an example. That's a good example of SharePoint framework. First gonna be released in SharePoint Online. Then it's gonna land on ship on 2016 later on, 2017 akms, sharepoint PMP, is the one address to remember.

B

You find ultimate cast all the other stuff from there, but let's actually jump on today's topic and I'll. Let Bert delete the discussion and I'll jump in whenever needed. Thank.

A

You versa. So what are red books? Actually, oh, you can see Web books as a way for SharePoint to notify you of a particular change. So let's give an example: if you upload a document to a library- and you would have a web book on that particular library SharePoint- would notify you like a something happened on your library.

A

It's a bush model, so SharePoint's pushes information to you and it is an asynchronous model. So we're not supporting the item, adding events for the classic SharePoint guys. So it's always an after-the-fact event that happens.

B

And that's actually a good point to remember so you cannot use a web hook to cancel an operation. You you get a notification. That operation has completed. That's really the key point. Yes,.

A

Yes, now my books, it's not something that the SharePoint team invented or a top 25 team invented. Essentially web books is a universal model used by many cloud providers.

A

Wordpress is using it get-ups, using it a lot, MailChimp, etc. So we're just using what's common in the industry today, and we think now is that Web books are released to production as of January 2017 for SharePoint lists. So current implementation, only sporting events happening on SharePoint list. Sure.

B

And additional support is coming at some point and will absolutely make announcements from those as well.

A

Ok, sir, the following slides will show you how to subscribe to a book and then what happens when a web book fires and how to handle that. So, let's first start with subscribing to a web book what you need to do now. First, your application will need to make the subscription. Essentially that means we're doing a post to an arrest endpoint, which is the lists, slash subscriptions endpoint, and we provide information in JSON format about which list do we want to subscribe and importance?

A

Let me zoom in right here this notification URL, so you need to tell the SharePoint where your web book service, you is listening, its list living sorry, because SharePoint needs to call out that end point to tell you something happened. Remember so time you provide that end point, which is the notification URL and in.

B

A

Language, what will happen is that SharePoint will validate whether your end point your notification service, it's actually alive, so we will do a post to your service, providing a validation, token URL parameter, and we expect you, as the owner of the end point to return that validation, token value, which is a GU it. So we want you to return it within less than five seconds. This less than five seconds rule actually applies to all web book service calls.

A

So whether this is this validation call available through a real web book service call made by SharePoint sharepoint will terminate the connection after five seconds, so your implementation always needs to be able to respond in less than five seconds, and once that's done so suppose your service was up and running. You notify SharePoint like I'm, good, that point SharePoint will say like okay. What book has been created and will notify you when HTTP it to a one message saying it about book? Is there and it will provide you an idea around this particular book subscription.

B

So, let's actually, let's kind of a reiterate this one, so this is kind of the operation that a SharePoint I want to have a notification to this web address. Whenever there's a new item created as an example and then it's SharePoint wants to validate that, URL said that it's actually because it's a pushed ribbon operation from a ship one side, it doesn't just randomly want to call URLs which would not be valid.

B

So that's the reason for the validation and then, like you mentioned the respond within less than five seconds really important thing and that relates on the owned operations as well. So if you do, you have a long-running operation, you need to implement that using an aging pattern. It's we probably come to see you today as well. So let's, let's talk about that one in the later slides.

A

Okay, so previous light explained you how to get your web book set up, everything is set up, you're all ready, a certain point. Let's say you, you added a web book to a document library, someone uploads a document to your library. So what will happen?

A

What will happen is that SharePoint will make a call to your web book endpoint now. One important thing to know is that is that SharePoint will not immediately make the call so another course. What will happen is that we'll see something happens so in da current was added and the library will create a solid information in torreón SharePoint and there is a dynamo job running a short interval which will kind of see where there is something the process in this case.

A

Okay, we have example one document added to your library and maybe also one has changed. So we see a change for this particular library and at that point, when the timer job is running, it will pick up that change and we'll do the notification to you.

A

So it means that you can have notification like a few minutes after the actual event, so something that need to take an account when you design your usage of web books, what we will send you, it's also interesting to to ever look at we're sending you the subscription ID we're just your web book subscription important we're sending you the resource, ID and the web ID as well resource is actually your library. Your list, web patty, is the web world change word it in happens for the list is living, so we're not sending you information around.

A

Oh, this particular document was added, or this document was deleted or no we're just saying new. Something happened in this particular place in this library, which is completely different compared to the classic remote event ratios.

B

Sure so, you're not actually getting the details on the file name of our an item name or the properties which has been changed, you're just getting an ID. That's yes, you.

A

Just get notified like something happened for this library. You are expected to respond like okay, I, accept it this notification. If you do not respond in five seconds, we will retry so there's a baked in a retry mechanism. So we keep on trying a number of times. If your service is still not up by then eventually the event will not fire, but at least we will try to notify your service a and we'll have kind of an incremental backup strategy there as well.

A

Okay, so remember we Chevron call out your service and we told you like something happened in this library. Now. How do you deal with that? What do you do.

A

First step: let's switch to an asynchronous mode, let's just already mentioned seriously: cuz we're gonna process, this web book notification, but we don't know what happened. Actually, we only know like something happened for this library, but maybe someone at a Bullock upload and wished 1,000 documents in there hmm and most likely, your replica implementation code can't handle that in less than five seconds, so the safest way is to a switch to the asynchronous model and with Azure using a storage.

A

Cubes is one way to do so, so we essentially put the message we get from SharePoint in a storage cube and respond SharePoint like we're good. We processed your notification so yeah. We acknowledge, we got it once inside the starch queue. You need to act upon the messages in the queue. So an easy way to do so is is using as your web jobs, which you can automatically monitor the queue and get the triggers run or something in the queue. And then the clue here is: let's use the gate.

A

Changes see some API so with the gate, changes API, essentially you're, going to the libraries saying like their library. What happens with you? What other changes you got from this particular point in time. Give me all the complete list of changes. So if there would be one document edit, you get one change if there will be a block up out of 1,000 documents combined with 500 additions, you you get 1500 change events and then in your web job you can process all the change events in the right order.

A

At that point, it can also take longer than 5 seconds. You can take the necessary time that you need to process the change. Few.

B

Things kind of a mention on this one and I think the well just the process that changes over say will happen based on the changes. What you're getting? Obviously the web shop is an optional thing. You could actually replace that with an usher function as well, that's one option and there could be alternative ways of processing the storage cube, but the web shop is kind of a classic way to do that because you can queue up and the web job to get executed immediately went message to sell it on the storage.

B

Get super super useful scenario. Same applies actually for our show functions and to get changes. Technically, it doesn't have to be a season API. As long as it's a remote API, it could be a REST API. Your.

A

Restful as well, yes, exactly.

B

But but that's really needed to get ok, so what has actually happened? I got the IDs I got the identity is so what has happened? We're within this list.

A

Yep, just going back on our functions, you could use in no GS with JavaScript in an azure function and then use Nita, catchiest REST API to build some carriages, not using C so model which is not using C sharp at all. That's definitely not.

A

Okay, now the site might be a little bit complicated. We were gonna walk over it step by step, but essentially it gives you an enterprise, ready, get changes pattern to handle web book notifications so going back to the first step when I create a web book which we described earlier on now when we do that, we're also gonna grab the current change token from the list we subscribe to. So we need to have this current change token, which we're gonna persist because, later on, when we ask the changes, we're gonna ask the changes.

A

As of that particular moment in time, and we made a subscription which is identified by the current change token.

B

Yeah, because we don't want to have changes from years back, yes, since the last execution absolutely make sense. This.

A

Is the most easiest model I think to implement? Otherwise you would always have to deal with the potential of processing the same change again and again and again, which sure you could build logic around that, but I think it's easiest to just grab the correct set of changes, so we have to persist it somewhere, like it's equal, Azure database, for example. Then, when sharepoint calls your endpoint because the change happened, you persist the change in the queue like we discussed, there's the web job that is done, processing the change.

A

In this case the web job will grab the latest change token from the database. So when the web job runs, it only gets the changes which will not process before, because after the web shop did its thing after you call to get changes and processed all of them. You simply persist the use. The change token, the last years change token that you got back into the database. So next time you only get the changes as of this processing, which is a.

B

A

Model to deal with get changes in SharePoint, sure sure, okay, let's switch gears a little bit. Let's move to Asia functions a. Why do we want to highlight this because I know functions is really an intuitive, an easy way for you to host your SharePoint book notification service.

A

So this screenshot is showing the area function. Development of I am I, decide it's in the router, so you.

A

Use any language well uh yeah, probably and he's a bit too broad, but you can use C, sharp, JavaScript, powershell common languages to write your notification service and inside the browser and with Azure functions as your is the one that essentially is hosting it for you and also scaling it for you. So you don't need really need to worry about that.

A

What I really like around other functions is it makes developing the function easier because it is by design hosted on the internet and available for SharePoint. So you you can kind of do some life debugging with it, which will show in the demo. You can, for example, validate your function.

A

There's a look at the right side here there is a built-in desk console inside the UI, where you can, in this case I a data validation, talk around, remember, I we needed to validate when you make a subscription, you need to respond with the validation, talk that you get from SharePoint, so you can easily try that you just create a add, a parameter, specify some value, a Goods and hit on the Run button, and you will see in the lock like okay, my red book was triggered and this happened so really powerful way to develop and test your your web book services.

A

One thing to notice here is that edge functions are available in a free way, just like as your app services are, but this case then you're bound to a timeout of five minutes. So if your function would need to run beyond five minutes, it would timeout if you have a paid version and you flip on the always own switch in your Asia web application settings.

A

Then your function can keep on running and just to kind of think about the broader picture, and so this function that you see on screen shot and one will also show in the demo coming up soon. It's essentially accepting the call from SharePoint, so your notification from SharePoint is accepted by the function. Then it's persisted in a queue in a storage queue, so we're not processing the actual queue inside this function, so we're using the asynchronous model with an azure function.

A

So you get the message you put in a storage queue and then we say SharePoint well done so consider. This is the first function. Now you could write a second function that is listening on that queue. So function can be triggered by a message in a queue just like a webshop can be triggered by a message inside a queue. Also, a function can be traitors, so imagine you're, building a second function, which is an is triggered by the message in the queue and processes.

A

There's a processing, and the reason why we need to do function is because simply the first one needs to respond to five seconds. So there is no real way to do all the work in five seconds, because you can have multiple changes so.

B

This is pretty much the exact same same thing, as we explained on the previous slide that the enterprise-ready pattern for handling the things setting in a queue, and then the code is, though, in the same location, which is kind of neat as well. Yeah.

A

So same bedroom, but then using Azure functions instead of using a and as your web job and.

B

A regular as your web application.

A

A

Okay, lots of theory, and now, let's switch to a demo, all right. Welcome to this demo, I'm gonna. First of all start with showing you the application, so I'm gonna refresh the screen so roll good. So this is an azure ad application that essentially allows you to for a given site to manage your Web books.

A

So this case I already have one web book subscription for one list called for a documents list, but this application allows me to add additional web books to additional libraries that I have in this particular site collection before I'm gonna, add a new web book, I'm gonna switch to the azure functions.

A

Because in this demo, I'm gonna combine the hid application with Azure functions which are hosting the web books, so I have one other function. Host of here called PMP functions. If you don't don't have a function host yet easiest way to do so is click on the plus sorry click here for the marketplace new and you search on function, I think it was function rap, yes and then you you can create a new function app from here.

A

So I'm going to go back to my pre, created PNP functions, function app and once it's loaded, I'm gonna, go to the sharepoint web book is ready, function, demo long name, oh yeah, and it already has the codes and the code is available it for you as well talk about that soon. um But what I want to show you is the the locks, so it has built-in logging, so I'm, gonna, open the locks gonna make a nice, make them bigger response and, let's clear them. Alright, so locks are clear.

A

The function is hosted in Azure now back to my sample application and let's create a web hook for let's take the site pages. For example, sites various library I'm gonna hit create so now SharePoint goes to my phone to my web book notification. Service I need to respond to it, I'm good and then once that happens, the web book will be created. So this seemed to work, and we should see that also in our Rock and yes, we do.

A

We clearly see that our function was triggered. We received from SharePoint the GUI test, validation token, and we responded with that guiit so and function, and it's successfully it's why I love other functions because it really makes you see immediately the feedback. So it's pretty cool okay, so this one's ready, let's see if we can then have SharePoint trigger our web book.

A

So here is the site web book demo I'm gonna go to the documents. Library focus you already pre-created in and web book. Let's upload documents, the empirics yay.

A

So the document has been uploaded and you might expect to immediately see something popping up here, but it isn't because again, SharePoint is processing that this as a timer job, so it will do whenever the anguish of runs, so this will can take up to five minutes before the actual event is fired and before we see action happening. So while we wait for this, let's go a little bit of source code. Well, actually, let's first show something the place where you can find the demo.

A

So this demo, it's called web book still listed as your ad and it's an azure ad application which you can find in the SP dev samples repository. We also have the same demo in a classical. Let's call, let's call it classic. Sharepoint rare classic SharePoint provider hosted editing application.

A

So if you go to samples where books dot list is a similar application, but then this is a provider host application.

B

A

B

And there was, by the way, a node.js implementation for web hooks as well. In.

A

A stress position: there is also a web book, still no GS one over here, correct, yes, just pointing out that there is an extensive deployment guide. So if you want to play around with web hooks, this guy shows you all the steps to implement this reference sample. It contains all the azure ad steps in all details.

A

It explains also how to set up to actuate the application if I scroll down, so you get to complete the application set up. Everything is there.

B

And the easiest way always to learn, is by doing by doing it by yourself, I would say, because then you get the hands-on feeling on hey, that's how it works. Actually, okay, yes, absolutely.

A

A little bit of code, that's right! So three projects we have your Y, which is the azure ad application. We have our book implementation and we have a common library, utility library which contains all the common guests across those two projects.

A

What's specific here is because this is an edge of the application. Are we are using regular SharePoint to REST API and see some. We need to have a way to transform the Suad login information.

A

Your issue in this session to a SharePoint client context objects, and for that we have this context provider helper class, which has in this case in the the home controller, which is the one driving the screen we haven't, get web application, client context methods which essentially, is using a PNP so using the PNP authentication manager class to transform your hid web application context to a SharePoint client context. So this is running under your your user context, like it has two provisions. You have this user.

A

However, when you are in your web book at that point, you wish to use the context anymore. So how can that web hook that code running in a web book of the SharePoint, because it needs to do to get changes called the SharePoint? So it needs to authenticate against sharepoint online for that we essentially have implemented the app only snail with Azure ad. So to do so, you connect and certificate to assure the application and then provide that certificate later on to actually to authenticate that's kind of how the azure ad a pony flow works.

A

Luckily, P&P again can help you here so um and now switch to the change manager class, which is in the books common project where we grab a client context, object to do the web book processing so that this is the web job that runs and then it doesn't doesn't have a user context, so it uses they get app, only client context methods.

A

Here we see again that we use into the Takeshi.

B

A

Class from PNP this time we're using the.

B

A

Hid app only authenticated context, which is using a certificate to get a valid client context. So these are two things you need to be aware of. When you great net and Azure ad applications versus Shevin right, hosted, add-ins.

A

But I said all the code is available on github: there's extensive documentation how to set up things so the easiest way for you to rounders. This is grab the code and deploy it and play around.

A

Let's see the sir, if in the meanwhile I think.

B

It was cold and.

A

Like it was cold, so I seen my locks that the web ProQuest triggers SharePoint traitor, bat, okay, great I, see the payload. So you see the message that SharePoint sent to you, which contains description, ID the resource we just lists, etc. And then, in the code opal happens, we will dis utilize, the JSON and then we'll kind of great individual messages in the queue for change.

A

So this happened so which then also should mean that we have some action in our site. So going back to the side going back to my over here, so an implementation we have essentially when there is a change and it's processed, it will lock a message inside this workbook is to relist. So if I go over here, I see that these two I did before the demo is used to verify. That takes running fine, but really this is the last one.

A

So we had a new one changed type ads, so essentially just telling you that this document was edit and I put notified you about it, which proves that it all works. So.

B

A

B

A

Showing that this work, it's.

B

A flow it's a flow. What, where painter, can you actually sure that get changed this implementation, just a kind of a clarifying that one still that's in a whip job right? Yes,.

A

B

Goes to the story skew it fires the web chart and then the web shop is processing. The item yeah.

A

So that's inside the it's run by the web book correct and the code is inside the shared class in the common in the change manager, class.

A

So here we have our post notification, so we create a client context.

A

You saw some processing, but here's the interesting part. This division grabbed a list changes and do something with them. So essentially we do a change. Query.

A

And we're gonna here below here, we're executing the change queries, change queries have to be executed in a loop because, depending on the amount of changes, you will need to run it once twice thrice three times whatever, because it the results, are kind of coming back in batches. So all of this logic is implemented in this reference implementation.

A

But at the end of this you will have a set of changes which you can then process.

A

So here, at the very end to work, we have our changes, which can be many, many many or just one. Then the do work is the one where we do our great demo, essentially adding an item and history list.

B

A

Implementation.

B

Would be here exactly exactly so the key point: what you're getting from the get chains is that you're getting the change type you're getting to item details you're getting all of that. So you could access that item again and do modifications or if we delete it, an item. We get a notification on that one as well. If we associate at all of these things in a web hook, so it's a then it's up to the business logic. What are we doing here? That's that's really! The key point. Yes,.

A

Cool all right, I'm gonna switch back to slides.

A

And let's do a few closing slides, let's clarify also, what's the difference between web books versus remote event receivers, so my books, they have a retry mechanism. So if your end points not listening, we will retry, which we don't keep on retrying forever. Keep that in mind. So it's always a best practice to have your endpoints listening or have them deployed on a ship in a redundant way so that they're also available compared to remote event receivers.

A

Web ebooks are less taxing for you, your service endpoint, because we call them less essentially because we're batching changes. If you upload my home documents, we only send you one. Notification.

A

Second, is at the payload that we sent you. You saw the message. Deviation, it's spin! It's just a few bytes of data that you get, which also means that they're more secure because we're not sending any specific context about the change. So if someone would sniff the data it would it wouldn't give them any value.

B

Yeah, even though it's an SSL endpoint that theory that's but still.

A

Slightly, you never know yes, yes, yeah what books are more easier to consume, because it's it's a regular and because you want to develop SharePoint developers, because it's regular HTTP services, so you saw the demo as your function with seashell, but you for the same. We could have also used I, know GS, which are script in Azure functions or Python or whatever you want. It's totally not bound to the the sharepoint way of doing things. So you can just write your service in anything that you want.

A

A

All right, it might be initially may be challenging to debug your service because the service needs to be available on the internet, because SharePoint wants to call it with Asia functions. I think you have an easy way to do so, so you left the live feedback here in the Berk lock, which will make your life easier.

A

If you do not use Azure functions, you can, and you just deployed it to Azure. What I typically do is just connect remote debugger in Asia. If you deploy a debug, build to measure and then remote debugging, it really works great nowadays with Azure, so perfect opportunity and a third option is using the ng Iraq service, which essentially allows you to kind of have your service running localhost.

A

We just connected to a public endpoint provided by ng Rock, and this way sharepoint calls ng Rock, which then tunnels the requests to your local host service, endpoint, where it will hit the breakpoint, for example, so three options to debug and develop your service.

A

So you should be good for doing that. Kim here is an extensive list of resources. It's showing the generic. What our Web books article, but a lot of sharepoint web book links the documentation rose to the three samples Web books is not just sharepoint it's in onedrive in an Outlook as well. So if you're interested in those, we have some links for you as well, but with that I think we can close this webcast.

B

Absolutely and then there's one thing: what I noticed on this slide, which is always bothering oh.

A

Yeah I saw I, know.

B

Yeah the gear is wrong anyway, great bit, past Thank, You Burt on the thing, I really think the web, who is the future of SharePoint, editing and right now they are key aid in the in the shipment online and we're looking in the on-premises story at some point as well, and everything else will make announcements as we move along depending on when you're watching the video over.

B

So what's the status, but we would I think Burton and I we're absolutely encouraging people to have a look on the samples, what we're providing run through the samples to get a basic feeling out. This is how it actually works. This particular sample awesome documentation, step us that this is how you set it up in Tulsa, shows to Microsoft assure I should function side of the story as well, so create stuff available for you to take advantage.

B

A

Else, birch yeah, just one thing: if you try it out and you have questions- concerns feedback, just let us know using the regular PNP channels creating an issue in the repository or using social channels to reach out to us, so we'd love to know how the sample works for you and what what can be improved. Potentially, yes,.

B

What else would we need it so that we get to help people get started on their own? This kind of a implementations, absolutely absolutely, but okay, cool I think that's it Thank You bird from white behalf, great presentation and great demos, yep.

A

Thank you, sir. Thanks for the tough questions. Yes, Cheers. Alright, guys, bye, bye,.