hello I'm Jason Johnston a senior content developer with the outlook ecosystems team today I'm going to show you how to connect your no GS app to office 365 and get update and delete calendar data on your calendar so let's get started to start with I've got this basic node J s app that we've developed over the previous two sessions right now we can log in and we can do basic calendar or sync now we'll take that those calendar items that we're syncing and be able to take some actions on those in case you missed the previous two set sessions the code that I'm starting with right now is available in the session to branch and the github repo which is included in the comments below ok so this app uses the node outlook library to do all of the API calls back to the Outlook api's we've already got it installed from our previous session so let's start by taking a look at the app as it stands right now if I log in and sync my calendar I get these items in a table with a view item link or right now the view item link doesn't work so let's fix that we switch over to our code and in the app j/s we'll add a view item route this view item route gets the item ID from the query parameters and then we set up a call to the get event method in the calendar namespace and no dot out node the node outlook library unlike with our sync calls we don't have to use the raw make API call here no doubt look already implements this functionality for us so all we need to do is set this get event parameters object with our access token and the item ID at the event that we want to retrieve and then call get event we pass the event that gets returned to us in our callback to the item detail page template so let's see that in action now if we click view item we actually get some details about the item and below we see the raw JSON dump of all the details that come back now this is nice but if you look at our form we're only displaying a few of the fields here the subject location how many minutes beforehand the reminder will fire and the start and end time but if we look at the JSON we're getting back a lot more data and then we're actually using this may not be that big of a deal but it is a little wasteful so we can trim that down and only get back the fields that we care about to do that we'll modify our view item we're out here to add a select this is a standard OData query parameter which allows you to specify the fields that you want back on a particular entity we just separate them with commas and I've included all the ones that we care about and display in the form and now we just need to add those parameters to our get event parameters so that they're passed to the API call and that should do it so if we restart the app now we should see a smaller results that returned again we see all the fields that we care about being displayed in our form but this time the JSON that comes back is much smaller and only includes the fields that we asked for since we're looking at the JSON here take a second to point out some of the new features from the v2 endpoint one is the time zone by setting our preferred time zone in the node outlook library we pass a prefer header which specifies that time zone so as you can see our start and end times are returned to us in Eastern Standard Time which is the time zone that I specified if we don't set that time zone these times would come back in UTC time or zoo the time the other new feature that I point out quickly is the reminders we have two new properties now in the v2 endpoint on events is reminder on and reminder minutes before start the is reminder on is a boolean that just tells us if there is a reminder set on the event and if it is set reminder minutes before start tells us how many minutes before the start of the appointment the reminders should fire pretty straightforward okay so let's get back to the code as you can see we have a couple of new buttons here on the form update item into lead item so let's start by implementing the update item okay so this should look fairly similar to some of the other routes that we've already added we get the item ID from the query parameters and the access token from our session we also get the new subject and new location from our query parameters which are passed in the form when we submit it then we construct an update payload now notice here that we're only setting subject and location we're not creating an entire new event entity whenever you do an update you only have to include the fields that you want to change we packages all up again into a parameters object with the token the item ID and our update payload and we pass that to the update event and the calendar namespace if it succeeds we redirect back to the view item view so that we can see our new changes so let's give it a try we'll change the subject and the location field and go ahead and update the item okay so as we see here we're getting an error access denied message well that's because the permissions that we requested in our app only gave us the ability to read the user's calendar we never requested the ability to write to the user's calendar so we can change that now we don't need to modify our application registration we just need to modify our code to request that scope as part of the login process so if we go to off helper j/s we'll swap out the calendars not read scope for the calendars dot read/write scope and that's all that we need to do now if we restart the app and sign in we're presented with a consent screen again that's because we've changed the permissions from the last time that the user granted consent as you can see we now have the read and write your calendars permission instead of just read your calendar now we should have the proper permissions to update the item and now we have the new values in our results if we look here we have the new subject in the new location and quickly we can verify that it has been updated ok great so now let's look at updating delete item again no doubt look has a built-in function for us here so we don't have to implement it ourselves and we get the item ID from the query parameters on the incoming request and we set up an event parameters delete event parameters object here with the token and the item ID and we call the lead event now here on success we redirect back to the sync page and that's because since we deleted the item we can't do it anymore if we try to view an item with that item ID we would get nothing back okay so let's give that a shot and see how that works okay so now that we have delete in place we'll go ahead and give that a try let's see what happens let's delete our doctor's appointment because we just don't feel like going to the doctor today that processes and then come kicks us back to the sink calendar page and that's it we've added get update and delete functionality for the calendar to our app be sure to check out dev dot lucam and dev office comm for more information and getting started materials for node and other platforms with office 365 if you'd like to get the completed source of the app that we developed over these sessions you can get that a github the link will be below in the description the master branch should reflect the finished app thanks for watching you
Monday, 21 October 2024
(2) Building Node.js apps to connect to Office 365 Calendar Sync
hello I'm Jason Johnston a senior content developer with the outlook ecosystems team in this video I'm going to show you how to connect your node J s app to office 365 and do a basic calendar sync so to start with I've got this basic nodejs app that we developed in the first video in this session to do the authentication piece we're gonna build on that work and add calendar sync so let's go ahead and get started in order to do all of our API calls back to the outlook calendar API we'll use the node outlook library which is a lightweight wrapper around the REST API so the first thing that we want to do there is install that library using NPM and once that's installed we need to require it in a pious okay so if we go back to the app that we implemented earlier what hey right we were left with this sync button that we haven't implemented yet it's pointing to a slash sync route in our app so let's start by implementing that okay so there's a lot here so let's go through it bit by bit so we use the outlook base namespace for this functionality and the reason that we do that is that no doubt look is as I said earlier very lightweight it implements a few basic functions but it also implements the ability to use any API call even if we haven't implemented a wrapper around it that's what the base namespace is really for so the first thing that I do here is use the set API endpoint function to point all of our API calls at the version 2.0 outlook endpoint we're going to make some use of some of the new features in version 2.0 during this so I'll use that endpoint the next thing I do is set the anchor mailbox to the user's email this is why we went through the trouble of extracting the user's email from the ID token in the first session and then I set a preferred time zone this is a new feature in the version 2.0 endpoint the ability to specify a preferred time zone and have all calendar times returned in that time zone so that you don't have to do all the calculations yourself okay so to start with we're going to manually configure our API request since we don't have a wrapper around it the first thing we do is set up the request URL when you're doing calendar sync that all works off of the calendar view endpoint in the API which is a view on a window of time we're going to do this for a week starting from today in seven days out so we set this to the me calendar view next we're gonna set up that time window as I said the start date will be today at midnight and the end date will be seven days from that time then we're going to set some prefer headers which will enable the sink functionality that we're after there's a couple of prefer header entries that we need to add one we need to set Oh dat ax dot track changes that tells office365 that we want to be able to synchronize data as changes come in the next thing that we set is our max page size here we're saying 5 which will limit the return results for each call to 5 results now we package up all of those things that we built before and to this API options object which gets passed to the make API call function so now that we have that there let's go ahead and run the app and see what happens okay so as you can see we have basically a raw dump of the json response for our synchronization requests we get back an event entity for each item on the calendar up to the maximum of five that we specified so great we see that that works but what happens if we have more than five items or changes come in after we do that initial sync how do we how do we continue to get changes well if we take a look in the response here at the end we have this item called OData delta link this is how we continue on with our sync so the way that calendar sync works is that the requests that we just made is considered the initial sync request from that we always get a delta link included in the response so the next thing that we should do is issue a second call to that delta link if there's more changes we'll receive them if there are no more will receive an empty response the response will include a delta link if there are no more changes and at that point we can save that delta link and periodically make calls to it to get any changes that come in if there are more changes more than the maximum that we have set in the prefer header we'll get a next link instead so after the initial sync we can look if there is a next link there are more changes if it's a delta link there are no more changes and we can wait however long we want to wait until we do the next sync so with that in mind let's modify our code a little bit to save the delta link and use that on the next call to sync so here I'm checking our sessions see if we have saved a sink URL and we'll use that instead of the basic me calendar view if it's not there then we'll just use the base URL but in order for it to be in the session we need to save it so let's go come back down here to where we process our response and save our Delta now we're taking a simplistic approach here for this demo if there's a next link we save that as our next sink URL otherwise if there's a delta link we save that we'll use whichever one we get back so now that we have that let's rerun the app and see what happens okay so we'll do our first initial sync and we get back five items now if we click sync again we get one more item that used the Delton link to get further information now if we click sync again with our new Delta link we get back no changes so we received all the changes that are there let's take a look at the code in pages yes that actually renders those changes that come in so we basically take the changes they come in and loop through each one of them we check if there is a reason property on each change that's set to deleted if we have that then that we know that it's a deleted item rather than an added or updated item deleted items are a little different in that you don't get all of the properties on the item since it no longer exists you do get back the item identifier so if you're saving this into a back end somehow keeping them in sync it's a good idea to be able to find the item in your back end based on the item identifier so that you can remove it if it's not a deleted item then we just set the entry in the table to use the subject of the appointment and add it into our table now let's take a quick look have what happens if we add an item after we've completed our sink so we'll go to the users calendar and we'll just add an item here now if we switch back to the app and do another sync we should see the new item that we just created and we'll see the flipside of that will delete the item and do another sink and this time we get back a delete change with the ID of the item and that's it we've done basic synchronization functionality join us in the next session where we'll take a look at doing it a little bit more with the calendar viewing items updating items and the leading items all from our app be sure to check out develop calm and dev office.com for more information and getting started materials for node and other platforms thanks for watching
(1) Building Node.js apps to connect to Office 365 Authenticating
[Music] [Music] hi I'm Jason Johnston a senior content developer with the Outlook ecosystems team today I'm going to show you how to authenticate your node.js web app to call the calendar API to access your calendar in Office 365 so let's get started to start start with I've got this very basic node.js website that uses the Express framework it doesn't really do a whole lot yet but we're going to change that in this session the code that I'm starting with is available on GitHub the link will be available in the comments below um we have a clean slate branch on this repo that will uh correspond to what I'm starting with here today so let's switch over to the code and get started um in order to implement ooth we're going to use a an open source Library called Simple ooth 2 so the first thing that we need to do is install that using mpm okay now that we have that installed we can go ahead head and make use of it so we're going to add a file to our project here to hold all of our author authentication methods called athh helper. Js okay so what I've done here is implemented all the functions that we need for authentication through the magic of code Snippets um we'll go over each one as we get to them uh the first thing that you might me you might notice is that we have these values here at the top that are currently empty we need to get values for those um and the way that we do that is we register our application in the Microsoft app portal this is the application registration portal I've already signed in using my Office 365 uh user account and I can go ahead and create an app registration here so I click the add app and I'll give it a name once this is done we will have an application ID which we'll use for the client ID value in our [Music] code so I'll just copy the application ID here and put it in for my client ID the next thing that we need to do is get a client secret uh we can do this here by generating a new password now pay close attention to this dialogue this is the only time that you'll be able to see this password so you do need to copy it now if you come back you can only see the first three characters so be sure to copy it when you generate it the last thing is our redirect URI this is where the Azure authentication process will redirect back into our web app after the authentication is completed um so we're going to go ahead and set this to the authorized route in our app now we do need to also specify that in our application registration the authentication process will only redirect to URLs that we have preconfigured in our registration so to do that we will come to the platform section in the registration and click add platform we're a web app so we're going to click web and here we can enter our redirect URI we'll go ahead and click save to finalize that registration we'll SW switch back to the code while that's saving the next thing you might uh notice is the Scopes array this this is where we specify what permissions our application needs in order to function um I've only included three here uh open ID will allow the authentication process to tell us a little bit of information about the user such as their display name and their email address we will use that later so we include that here offine access is important if you want to be able to have continuous access to the user's data after that initial log on process that's that's accomplished by getting a refresh token as part of the authentication process which you can then silently acquire new access access tokens as they uh expire then finally we have this calendars. read scope which will allow us to read the user's calendar and we'll see that in action now the first export that we have in this off helper module is the get off URL all this does is use the simple oo2 library to generate the sign on URL back to our Azure authentication endpoint this is the first function that we're going to make use of so we'll switch back over to our uh app.js and find our homepage currently we are just setting a hash URL for the log on button so we'll replace that by using that get off URL function first we do need to require our new module okay so now our button should have a valid link when we rerun the app but before we do that let's go ahead and and Implement some of the rest of it um we set our redirect URI to go to an authorized route in our app which we currently don't have implemented so let's go ahead and add that okay so if we take a a quick look at this um we check the query parameters of the incoming request for a code parameter this is how the um Azure off process gives us back the authorization code that we need to exchange for a token so we take that code and we are passing it to the get token from code function also in our othh helper we'll take a quick look at that one all this is doing here is using the simple o off to library again to get the token it passes in the authorization code and again our redirect URI which matches what we uh used in the o o request and we include all of our Scopes this is going to call back into a call back function which we specified in app.js token received again we haven't implemented that yet so let's go ahead and do that so we can get this up and running in the token call back we are going to just get the access token and refresh token from the um result that is returned to us and save it in our session and finally we will redirect to a login complete page let's go ahead and add that and then we should be able to actually see this in action so on the login complete we read the access token and refresh token back out of the session and we simply dump it to the screen that should be enough for us to see this working and and verify that everything's working so let's go ahead and run the app and see it in action okay now if we uh rerun the app we will see that uh clicking the signin button actually takes us to the login page I'm going to log in with my Office 365 user and once the authentication process is complete and we're redirected back into the app I can see that I have my access token so great everything's working so now that we're logged in we can do some things some interesting things with the data the first thing that we want to do is actually get some information about the user themselves um and the way that we're going to do that is by using the ID token we already have a function in othh helper. JS that can extract the user's email address from the ID token the ID token is returned to us along with the access token and refresh token as part of the authentication process so let's add a function in our token received to call this get email function and save it in our session and then in login complete we'll get get that email address back out of the session and instead of just dumping into the screen we'll pass that email address to our login completed page template now if we restart the app sign in again this time we actually get something a little nicer so you can see we have the user's email address that we got from the ID token and we have a few buttons here sync Calendar refresh tokens and log out so the sync calendar will cover in the next session but uh refreshing tokens and logging out is still part of the authentication process so let's go ahead and take a look at those so refreshing tokens is something that your app will need to do every once in a while when you get an access token it's good for an hour after that hour is up you've got to get a new one um using a refresh token is the way to do that without any user interaction so let's implement the refresh tokens I'm going to start by adding a refresh token route to our app so as you can see we get the refresh token out of the session and then we pass that to get token from refresh token in our off helper we also reuse our token received call back here um because it does exactly what we need it to do let's take an off take a look at the get token from refresh token function in athh helper very quickly again simple oo 2 makes this super easy for us we just need to create a token object from the refresh token and then call Refresh on it it's important to note that when you use the refresh token to get a new access token you also get a new refresh token so it's a best practice to always always update your refresh token with the new one refresh tokens are pretty long lived but they can expire so it's always best to get the freshest one possible okay so before we rerun the app and see refresh token at work let's go ahead and Implement log out log out for us will be very easy since we're storing the tokens in our session all we'll do is destroy the session and go back back to the homepage easy enough so now let's restart the app one last time and see it all at work okay and if we sign in now we can refresh the token now didn't really do anything that we could see but if we take a look at our console output we can verify that we got a new token and then finally if we log out we're right back to where we started and that's it that's all we need to do to implement the authentication piece which is really the hard part of connecting your node app to Office 365 in the next session we'll go ahead and take a look at implementing calendar sync um if you want to compare your source with what we did in this session if you go back to the GitHub repo and look at the session one branch that should match what we've done in this session and that's it we've implemented authentication and connected our app to Office 365 we've gotten past the hard part so in the next session we'll go ahead and take a look at implementing basic calendar sync that's pretty much all that I wanted to show you in this session if you'd like to learn more be sure to check out dev. outlook.com or dev.off do.com for more getting started materials and information on node and other platforms thanks for watching [Music]