Microsoft 365 Community PnP Webcasts, 5 Sep 2016

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: PnP Webcast - Getting started with SharePoint Webhooks

Description

In this PnP Web Cast we concentrated on showing how to get started with upcoming SharePoint Webhooks. SharePoint Webhooks allow developers to build service integration which subscribe to receive notifications on specific events that occur in SharePoint. When one of those events are triggered, SharePoint will send a HTTP POST payload to subscriber. 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.

Notice: When this webcast was released SharePoint Webhooks were not yet released. They will be provided for Developer Preview soon with support for list item specific events for lists and libraries.

Presentation used in this web cast is available from http://docs.com/OfficeDevPnP.

If you want to learn more about SharePoint Webhooks you should also checkout the web cast we did about the reference implementation for SharePoint webhooks: https://www.youtube.com/watch?v=j3hWCAI9R20

A

Hello: everyone welcome to the SharePoint patterson practices webcast today we're going to talk about getting started with sharepoint web hooks. My name is Becky uncen I'm, a service engineer inside Microsoft and my host for today is it's Jesse. You Vernon hello,.

B

My name is Ivan and I'm a senior program manager in SharePoint engineering on the customization side and bird is going to late today, the presentation, but let's actually quickly to the typical setup of within the webcasts, what we do in that BNP webcast, so just to clarify for those who are watching this webcast for the first time these are and delivery under the unparalleled SharePoint patterns and practices or or also known as office, raises 25 developer buttons and practices, because this particular webcast is all about sharepoint and sharepoint web hooks, which are going to be available really really soon when the video is out or if you're watching the videos are slightly later, when we have released then over, so they are own, but we are under the sharepoint BMP umbrella, because, like mentioned, this is the wrong shape on the ship went.

B

Vm p is around providing you code, samples, gardens documentation. We have monthly community calls. We have other community calls as well case studies I like to play meteor and volvo are available. The themes within sharepoint patterns and practices are on the SharePoint framework, which is the new thing currently in the Developer Preview, when this video is recorded, and obviously the existing technologies like to SharePoint add-ins, Microsoft graph of a 365 API usage and really in this sense of remote provisioning and client-side development.

B

But let's move back on the on the actual topic of today, which is the SharePoint web hooks and I'll. Let Bert lead the discussion and I'm going to ask them questions and while we move within the slides, yes.

A

So what our web books, let's give a quick introduction and what they are and essentially web book, is a fairly simple model where SharePoint will push information to you. So if you want to be notified of a particular event and sharepoint web book is the way to go web books only a kind of after effects event asynchronous events, so when, when the document is uploaded to a library at that point, after the upload, for example, you will your web google fire sharepoint will notify you like something happened in their particular library.

A

So in that sense it's different than the remote event receivers we have today, which also support synchronous web books on his own. It's not something invented by Microsoft. We are actually adopting an industry standard which is being used by other companies like WordPress, get up, etc. So it's pretty cool thing used by a lot of companies today to inform the consumers of the way after a service of changes inside the service.

B

And one thing: I will run that one. Actually, it is not a Microsoft technology dependent as well, so you can absolutely implement your stuff using non Microsoft technologies as in the end point so because everything is based on its ddb absolutely.

A

Yep and yep today we have it already running for onedrive and outlook and, as already mentioned by vessel in the introduction, will soon have this available as a developer preview for sharepoint online.

A

Are coming slides, I want to explain you the two typical flows that you will see with web books. So one is: how do I subscribe to web book and a second this? Okay, what happens if a web book is fired? How does it work and then in the demo, will will show these two flows in the most simplistic way that we can show them to you? So, let's start with subscribing to a web book what happens so?

A

First of all, your application will need to make a call to SharePoint actually saying, like SharePoint I, want to subscribe to web book to this particular list. So if you see the top right, we subscribe to a list or resource which is a list or we give the expiration date, which is maximum six months.

A

What sharepoint will do want to see such a request? It actually will validate that the service you gave so the notification relative right over here that that endpoint is available. So the end point must be reachable by sharepoint online before it can truly accept the web book subscription. So sharepoint it's your endpoint, giving it a validation token and expects that you as the endpoint return the pass validation token within five seconds.

A

If endpoint does that, then the subscription succeeds, if not it fails, and you will be notified in the end, whether succeeded, which means the HTTP 201 message or whether it failed.

A

So that's the flow important aspect, areas that SharePoint needs to be able to reach your endpoint even a subscription time.

A

Further long and- and we did to our subscription- everything is fine. Now what happens during an event, so suppose you subscribed and a web hook to a list, and someone goes to the listing ads. An item at that point. Sharepoint will send a message to your endpoint, providing information about the list where the change was where the change occurred. We're not providing actual change data as such will tell you like.

A

Okay in this list there was a change and then you need to respond that you acknowledge the notification and then up to your service to do something with the notification. So a typical approach is then usually get changes. Api in SharePoint go to the list. Figure out what has changed and process the changes, we just send your typical business logic.

A

This is not shown in this particular session, but we have a reference, upland and implementation of web books that goes in and depth on how to deal with actually processing a message: how to do this in a synchronous way, how to call get changes to get the changes that happen in that list, etc. So all of that is implemented in reference reference implementation, which we will share at the end of this session. The session is really focused on the basic, simple process of setting it up and seeing it work.

A

Now, before diving into the demo, I want to explain bit of the tools we use for the demo. Now a particular. We use two tools: postman and ng rock- to enable this end-to-end flow, so postman, which you can grab YH ps3 the real not to get boys Malcolm is essentially a tool that can issue a get request of a post request is an easy way to issue those requests, so we're going to use postman as the clients to send requests to SharePoint.

A

Now we need to authenticate and in order to authenticate, to conserve an edge already application which gives us in an access token, which we don't use a postman to hit SharePoint, so that part is covered by. The second part is slightly more complicated.

A

I would say certain sense is that ok, you develop your endpoint, your service when you press a 5 that runs a local host, so it runs on your box alabama that I told you that when we subscribe a web hook, sharepoint wants to hit your endpoint your service rota, validate whether it's available or not. Well, unfortunately, SharePoint cannot reach local host because there are too many local hosts in the world, so that won't work and therefore we use ng rock as a kind of a man-in-the-middle service.

A

So essentially, when we subscribed with our SharePoint, the endpoints is living at party ng rock address and with the NGO clients, we connect our client with the public endpoint, so the data will flow from the ng rock io site to our local host, and this case it wasn't, for example, hits our break point. So we can see the end-to-end flow happening.

B

So that's kind of a similar thing as microsoft, azure storage bus, which it was terrible when a visitor parking, a service, paas, obviously yeah when I do d parking of a remote Devon to save us in a classic, adding mode pretty much you used service bus for that and and the model is pretty much the same. It's.

A

The same model yesterday only this requires a little bit manual steps, but they are not not super hard. That is the same model. Yes, yeah okido right.

A

We try to make this one a fairly smooth going webcast, so we already into demo after five minutes. So that's good! So then we're going to show postman and j-rok the test drive the sharepoint web hooks so in a first step, I'm going to actually switch to my ulcer and I already load it and the azure portal, because we're going to create an an application inside as your ad and through so you need to go to https manage adult windows, azure com. We just did the Asia manage the portal portal.

B

A

In there you should see once you log on with your talent account you should see an active directory. This case is called broad slap I'm going to go in the directory, going to go to the applications and, depending on how much you experimented, you have one or more applications listed. Oh we're! So, let's add a new application. This application that my organization is developing I need to give it a name.

A

This call it demo, you need to take the type web application or web api, so the first type, because that's actually what we're building we need to give it a sign on URL and that app ID. Essentially that doesn't really matter what you put in there. So let me see if I can take this guy over here, so I'm going to copy sign on URL, which I run and let's call this guy.

A

This one doesn't really matter as well. You see something unique, so I typically take my tenant named.

A

A

Demo, all right going to save it's validating that your eye is unique saving, and this brings us to the confirmation page of the particular application so one hit on configure and then we need to do a few things in this application to prep it for the demo. So I said sign on your l doesn't really matter, but I already put this one: just get postman calm, /, 02 / call back in there because that needs to be the reply.

A

Well, so to reply URL, this one must be like list of here: Deborah the way that get posted come /, 02, / call back, and that's because we will use later on use postman to make the request and works on roles authenticate against using this SharePoint every application.

A

What else is important? It's the client ID so I'm going to copy that. Already, I'm going to paste that window, I'm going to create a client secret because we need to authenticate and going to hit, save after saving the client secret will be shown to. You is often that you copied at that point, because if you leave this page, you will never ever see it again anymore, so copy the client, ID and client secret and put them in, but somewhere save them so does goods. What else do we need?

A

An application needs permissions, so a default actually the application, only yes basic, lock on permissions to as ready. So we need to add user actually granted permission to sharepoint online, so I'm, going to pick SharePoint Online over here, say: okay and then I need to give it permissions. In this case. For this demo, we need to give it weight and right items and all items and lists adult site collections. So like this all right, let's save this should conclude the setup of our application.

A

So now we have an edge of the application defined. We have declined, declined secrets which you can use for the actual to authenticate using postman. So let's try to do that. So I'm, going to switch to postman postman is in a free, open source tool. Well, external chew, through this open source as a free tool that you can use due to a issue requests to our web service.

A

So in this case, gonna first ensure that we haven't education token before we can hit SharePoint, so I open postman. The default opens with an empty tap with the header authorization selected, so I'm going to select all 2.0, because that's the model that, as your ad is using I'm going to ask a new access token, and it will ask you to fill information now. In my case, things already pre-populated because I tried it before, but essentially it will ask you multiplication, URL, which is expected like this one.

A

So look at microsoft, online.com /, common /, 02, /, authorized ? and then resource important here and resources that arel is encoded. Let the only gift the host so the hose of your tenant, conocido, sharepoint calm, my company appointed calm, don't specify anything behind it. It's actually just telling that this is resource that we want to get authorized for, and then we specify the URL to access the logo and actually so the.

B

A

Token low URL, so it is already pasted in over here I'm, going to update my client, ID and client secret with right values. So, let's copy down from screen.

A

And copy this guy's well.

A

Voila, so if I now hits request token it if you're not authenticated already, it will ask you to provide your credentials, so you provide your talent, figure, user credentials and you log on and we'll give you a token. So I can select the token I see that I got an access token back with the Refresh token, so the regular auto point is 0 axis and refresh token.

A

Next step is: let's try to hit sharepoint, so we're going to do a get request and in this case, I'm going to do a request to grab the ID of a library. So this is and backed online. This particular site web book demo and I want to grab documents list, get exceeded the title and ID from the documents list to do so. I need to use the embed authorization header stokin inside here at the pair of token, so I'm going to click on the use token over here.

A

If we then switch to head us, it nicely edits that token as a bear in my header, and that should be it for a get request. So let's hit sent and we it worked. So what really it won't it would we get what if we get back our the ID of our documents list in that particular site?

A

So you copy this value because you needed later on so okay, so far so good. Now, let's actually before we do the real subscription, let's go to visual studio because remember that our service needed to be running so I'll switch close to do, and this is a basic basic web api service. The shows you have to deal how to process the web book. Notifications actually did the service and everything that I've showed before all the URLs you, the complete set of steps, is fully documented and that documentation will become available as well.

A

Once we release the web developer preview, so then you will have bit more documentation about all of this. One of the things described in that documentation is that you need to add a few models to your project, describing like the web web book notification. So typical feels that you would send or get back during web notifications and the most important classes, the web book controller oops.

A

Here we go web controller, which is a Web API controller like a basic basic Web, API servers, endpoint and in there this is important, if condition so if the service is hit initially, with your new setup, we provide the validation token and we expect you to respond for the validation token. That's during set-up time afterwards, once the web prog is set up, we don't provide the validation token. So we end up in this flow, where we do something with the provided payload.

A

So what this demo will do is this will simply use a trace writer to write it to the output. So you can see what happens you can see if something comes in in real life. You would add this logic in this location, preferably even with a message in the queue. So you can do an asynchronous processing of what of the your business logic, since the service needs to be a kind of this response back to SharePoint in less than five seconds, so you gone through anyhow run long running processes inside this service.

A

The point is to.

B

Clarify at that point, so the with Q Bert means the usher, store, excuse or whatever alternative cueing mechanisms, so typically to usher storage school with your writing stuff in Microsoft Azure. So you would task in a queue and then the stuff is getting processed to synchronously, because we need to process the stuff or response back that hey we got. It will take care of it from this moment forward. Otherwise the SharePoint will reave submit that same event.

A

Yep right Bert: yes, yes, so we have an incremental for resubmit model, so we will keep from resubmitting for a while, so I'm going to press a five now actually launching the service. Now that point it will launch in local host, which is fine, so remember that we're going to do a little trick to connect the local host with to make it the reachable by sharepoint online. So the service is running. You need to take a note of the port number that the service is running on so three to nine.

A

To one mic is so, let's remember that now, let's launch ng rock to build the bridge to the internet, so I have a console open over here.

A

I, never do an LS, you get the ng rock suitable. Is there it's just when you install it the just one, simple executable, so that's fairly easy.

A

So what I'll do right now is I'm going to hit the ng rocket Lexie one table HTTP bridge, listening on port 3 to 9 to 14 localhost. So essentially I will connect my running localhost instance with the internet on a particular address, and that address is this guy, so it should be sdf-1, etc. Each time when you restart this ng rock, you will get a new address, so I'm going to copy copy this value, because I needed.

A

So, based at any other screen all right, so ng raucous wedding, our end point can be reached now now we can conclude with doing the actual subscription. So switching back to post man, let's do a subscription, so the URL for subscription.

A

Operation and if you look at your girl, it's again to the side to the particular list, so this is the documents library. So we remember that we grabbed the ID in order to specify it in this operation. Sorry and then I bought. The new thing is / subscriptions.

A

It's the end point. We need to hit to work with the web book subscriptions.

A

We already have the header in, but we need to add a few more at us. One of them is the accept header that, except over here with this value, Ron Jason, broad metadata and one last one- is the content type type which should be application. / Jason, then, since this is a post requests, we need to have a body so for the body we need to construct it so Jason.

A

Essentially it is giving me the resource and.

A

So we have the resource again so the pointing to our home documents, library, notification. Well, this is important on this actually telling sharepoint. Where is this particular web hook listening? Where do we need to hit it, and you see that they still have to update the ng rocket address in this one we have expiration dates can be up to six months from now and a client state.

A

So if you specify a client state, then each time a notification is fired, we will give the client said to you, so you can kind of additional security check like this notification. Coming back having the same client state, then I use when subscribing. If not, I can abort of just neglect that particular notification.

A

So let me update this ng Rock address.

A

It's that looks good.

A

All right. Everything should be in place. Let's do this end of this request, we're sending and it did work again, it's my lucky day, so it succeeded and when I succeeds, you get back the ID, so the idea is actually the unique identifier of the particular subscription that you just made.

A

So this is a verification that description succeeded. Another way to cross check whether it's exceeded is essentially and doings request.

A

To the subscriptions and point at that point, we should select this authorization- header, okay, let's hit Send and we get back a list of this is a list, an array because you can have multiple web book subscriptions to the same library.

A

Alrighty, so everything a set up web book is available. Now, let's get get it to work so.

B

We're just out of curiosity and the slides you you mentioned that they will say a one-step just a cleric on that type as well. There was a one-step way. You said that there's a five second timeout to response back. Where did this saw that five second timeout to respond span? Well.

A

Actually, when we did the set up, let's go to the code, the code is running and we already entered this piece of the goat where Codrus it was a validation token presented by SharePoint as part of a book subscription, and we applied back with it, and actually you can also see this in the the goat that it will list what happens. So you can see here that we already received the validation token that we returned it exactly so so.

B

When we in the postman, when we posted that subscription, our application was already running, so we didn't kind of even realize that we've responded back at all good and then with SharePoint. Us now has a rich. Has our endpoint registered successfully? Yes,.

A

Yes, so actually, this is one option either way. If you switch to the postman screen, you see that we have a new request locked over here so each time it also under something it adds a line.

A

And all right, so let's do the final part of this demo, let's go to our site, so this is the site that I created my book them aside, where we subscribe to the web book for I'm, going to click on documents and I'm going to create a new document.

A

Really doesn't matter was in a Content oops and it already hits my break point, so pretty quick, so I was kind of tell. Sometimes it takes up to five minutes, but now it already hit the breakpoint at split. Second, so that's really really lucky and normally it will be window between one and five minutes molars. So this was super super super fast, but good. So it hit the break point because they added the document over there and I can step through it's easier, lized object.

A

So now even notification objects containing all the information so it, but it shows me the information about the notification I'm going to show it over.

B

Here and like you mentioned birth, a while by looking this one, it's it's really important to realize that we didn't actually get any details on what happened, that we didn't actually get a detailed on what was changed or what was the the modification in a file or and so on.

B

We actually get the resource ID and then we're going to use that within the enhanced version of this code, and there is that existing sample available for people to have a look on going back on a sharepoint and do a change square e and saying hey chip on I got this notification. It seems today that something has changed. So tell me one yes,.

A

So that's how it works. Is this different compared to the regular Hewitt event receivers, where you get details about the actual event, this is works in slightly different way.

B

Yeah, but this is more aligned on the industry standard and how typically these things are implemented, so you get an ID and then you go back on the SharePoint using the you authenticate with in New York. Let's say you have a web job which is in a processing items it from a you which is using then have only to go back on the SharePoint and checks the modification and us whatever is needed. Yes,.

A

It's also way more reliable in this way, because suppose, somehow you missed it, you missed the change. The previous event with next event, you again called get changes, and then you will see the change again. If you didn't cheer down last time so yeah, it helps in reliability as well.

B

But the Buddha Buddha, and that actually mean that you need to track their notifications at that time. When you have last time going to the SharePoint and checked the changes. Yes, you.

A

Were once you successfully process the changes you need to write back the last you exchange token in a store somewhere a database on whatever assistance storage. You have so that next time you only ask the changes. As of that last correctly process to change token yeah.

B

And that's shown in the in the more comprehensive sample so how to do that and I think that's using sequel server to stall that over so you can do whatever is your preference to store the token as long as you have it there somewhere? We have the chains token. These are. This is the time. The last time I checked my changes. What has happened? Yeah.

A

The sec check get implemented in this reference for implementation.

A

We already have a video out of this one describing a bacon, see it in action, but and the coat and the detailed set the documentation and the sample documentation will be available really soon. Once we get this the Developer Preview out, but that will have all of the deserve more enterprise-ready snares built-in in the sample.

B

A

B

Add that link on the video description whenever the link is available. So will we won't be probably updating the presentation but will like to update the the video description in europe and channel 9 on the on this particular video.

A

Good good yeah, I think that sums up this is short walk through. I hope you saw it that you learned how to use ng rock and postman to to play with web books, because in this setup you don't have to be published in cydia. It's at you don't have to push things to Azure. You can simply a few web. Your service during localhost and with the ng rock you connected with the sharepoint online, and then you use postman's and basically quests. No gift gives you a fairly easy model to experiment and Tyrone.

A

Then, if you really want to start using this into in your production code, would recommend checking out the video we have regarding the reference implementation for web books, yep.

B

Absolutely absolutely there's some right notes on that sample order, the reference implementation as well around the flows and all done, but yeah I think that's it. So thank you. Everybody for watching and we'll come up with the new webcast sooner or later, yep sooner.

A

Or later oh I.

A