Hi Sanya & Sneha! Great job on all the tickets thus far 👨🍳 we're going to switch gears from MongoDb and Prisma to Microsoft Exchange Calendars! A lot of the technologies we use here will look different from everything you all have learned so far this semester, so come into this ticket with an open mind and eager to learn everything about Microsoft Azure Groups, Microsoft Graph API, and access into our app registered on Azure! This ticket is due on April 27th at 11:59pm, but please let me know if you like an extension and need more time. Alright, let's get started!
Git Thangs
Make sure to run git checkout master and git pull origin. I added a new function in AuthProvider.ts that I will explain soon on this ticket. It is required to make the Microsoft Graph API calls. Then run yarn install and yarn dev.
Once you can locally run the application, please make a branch called microsoft-intro. Make all changes on this branch.
Access Token Jawns
If you have not already, please try to get acquainted with all the new changes to the codebase with respect to authentication. I would say the main files to look at are the following:
/frontend/app/auth/AuthProvider.ts
/frontend/app/auth/authconfig.ts
/frontend/services/auth.ts
Especially with the first one, this includes some functions we can use to sign a client in, check if a client is signed in, get the client's information when signed in, and get metadata regarding our MSAL instance. Newly added is also retrieving an Access Token needed for performing API calls to Microsoft Graph and needed for this ticket. So having a firm understanding of the technologies used here is pretty important. For more information regarding implementation, please take a look at the documentation of msal-node. But the main idea here is to use an AuthProvider instance/objct to call these functions, especially for retrieving an Access Token every time we make a request to Microsoft Graph API. Once, you kind of have an idea of what is going on, you can move on to the next steps!
IMPORTANT: please the following to your .env file:
NEXT_PUBLIC_GRAPH_API_ENDPOINT="https://graph.microsoft.com/"
Please this secret when creating your Microsoft Graph API routes to avoid repetition.
Groups (I hate this part)
To provide a brief description of how everything works together, we own an organization on Azure where our application is registered on. We have created a "group" in this organization (and will continue to make more), where we can add members from the organization and create shared material between the members of these groups. Eventually, in this group, we will have a shared calendar. These are the calendars that will be broadcasted and shown on the Ithaca Community Recovery website, switching from Google Calendar integration 🥲 So the workflow is the following:
We will use an access token to access all groups in our organization
Once we our group's id, we will use that to access the default calendar of the group
After, we will use the calendar id to create meetings on the shared calendars of this specific group
In the next ticket, we will focus on creating a meeting
To begin lets create a new folder in frontend/app/api/ called groups. Please add a file in this folder called routes.ts. Here is where you will create a GET function similar to how we always have done it in Next.js fashion. Here, in this GET function, you will configure the endpoint, header, and authorization to make the call to Microsoft Graph. Check out the following documentation to see how the endpoint is constructed (specifically the sections "HTTP Request", "Request Headers" (don't include ConsistencyLevel), and "Example 1: Get a list of groups"):
https://learn.microsoft.com/en-us/graph/api/group-list?view=graph-rest-1.0&tabs=http
In the request body of your GET function, you should expect to receive a field called "accessToken". Extract this field and add it to your header under Authorization. After, please use the new secret we added in .env for configuring the endpoint. Ping Microsoft API using the await and fetch keywords. It should like pretty similar to the handleClick functions we implemented in frontend/app/test/page.tsx. Once finished, return a Response object with jsonified group list data and a status code or just a failure status code. It should look similar to the return of frontend/app/api/retrieve/meeting/route.ts. If you need further clarification about anything, lmk!
Where the Calendars at???
In this section, we will be retrieving the default calendar object associated to a specific group given its id. Pretty much same methodology for using Mircosoft Graph API except with a different endpoint.
Create a new folder in frontend/app/api/ called calendars. Then make another folder inside of it called getCalendars. Please add a file in this folder called routes.ts. Here is where you will create a GET function similar to the last function. Here, in this GET function, you will configure the endpoint, header, and authorization to make the call to Microsoft Graph. Check out the following documentation to see how the endpoint is constructed (specifically the sections "HTTP Request" and "Request Headers"). We will be using the GET /groups/{id}/calendar endpoint to reach Microsoft Graph API:
https://learn.microsoft.com/en-us/graph/api/calendar-get?view=graph-rest-1.0&tabs=http
In the request body of your GET function, you should expect to receive a field called "accessToken" and "groupId". Extract these fields and add it to your header under Authorization. After, please use the new secret we added in .env for configuring the endpoint. Ping Microsoft API using the await and fetch keywords. This whole part pretty much follows from the last section. Once finished, return a Response object with jsonified default calendar data and a status code or just a failure status code. It should look similar to the return of frontend/app/api/retrieve/meeting/route.ts. If you need further clarification or if something does not work as intended, lmk!
Testin' 🫨
In frontend/app/page.tsx, please create a new section called "Microsoft Exchange Calendars" and add two testing button under this section. Connect them to two handleClick functions:
one that calls your route for getting groups, supplying an access token in the request body.
another that calls your route for getting the default calendar of a group, which requires making a call to your first function to retrieve a group_id to supply in the request body along with the access token.
Have these functions console.log() whatever they return.
Submission
In a PR, please submit a screenshot of the console as well as a 2-3 sentence description of what you have done!
Hi Sanya & Sneha! Great job on all the tickets thus far 👨🍳 we're going to switch gears from MongoDb and Prisma to Microsoft Exchange Calendars! A lot of the technologies we use here will look different from everything you all have learned so far this semester, so come into this ticket with an open mind and eager to learn everything about Microsoft Azure Groups, Microsoft Graph API, and access into our app registered on Azure! This ticket is due on April 27th at 11:59pm, but please let me know if you like an extension and need more time. Alright, let's get started!
Git Thangs
Make sure to run
git checkout masterandgit pull origin. I added a new function inAuthProvider.tsthat I will explain soon on this ticket. It is required to make the Microsoft Graph API calls. Then runyarn installandyarn dev.Once you can locally run the application, please make a branch called
microsoft-intro. Make all changes on this branch.Access Token Jawns
If you have not already, please try to get acquainted with all the new changes to the codebase with respect to authentication. I would say the main files to look at are the following:
Especially with the first one, this includes some functions we can use to sign a client in, check if a client is signed in, get the client's information when signed in, and get metadata regarding our MSAL instance. Newly added is also retrieving an Access Token needed for performing API calls to Microsoft Graph and needed for this ticket. So having a firm understanding of the technologies used here is pretty important. For more information regarding implementation, please take a look at the documentation of msal-node. But the main idea here is to use an AuthProvider instance/objct to call these functions, especially for retrieving an Access Token every time we make a request to Microsoft Graph API. Once, you kind of have an idea of what is going on, you can move on to the next steps!
IMPORTANT: please the following to your .env file:
NEXT_PUBLIC_GRAPH_API_ENDPOINT="https://graph.microsoft.com/"Please this secret when creating your Microsoft Graph API routes to avoid repetition.
Groups (I hate this part)
To provide a brief description of how everything works together, we own an organization on Azure where our application is registered on. We have created a "group" in this organization (and will continue to make more), where we can add members from the organization and create shared material between the members of these groups. Eventually, in this group, we will have a shared calendar. These are the calendars that will be broadcasted and shown on the Ithaca Community Recovery website, switching from Google Calendar integration 🥲 So the workflow is the following:
To begin lets create a new folder in
frontend/app/api/calledgroups. Please add a file in this folder calledroutes.ts. Here is where you will create a GET function similar to how we always have done it in Next.js fashion. Here, in this GET function, you will configure the endpoint, header, and authorization to make the call to Microsoft Graph. Check out the following documentation to see how the endpoint is constructed (specifically the sections "HTTP Request", "Request Headers" (don't include ConsistencyLevel), and "Example 1: Get a list of groups"): https://learn.microsoft.com/en-us/graph/api/group-list?view=graph-rest-1.0&tabs=httpIn the request body of your GET function, you should expect to receive a field called "accessToken". Extract this field and add it to your header under Authorization. After, please use the new secret we added in
.envfor configuring the endpoint. Ping Microsoft API using theawaitandfetchkeywords. It should like pretty similar to the handleClick functions we implemented infrontend/app/test/page.tsx. Once finished, return a Response object with jsonified group list data and a status code or just a failure status code. It should look similar to the return offrontend/app/api/retrieve/meeting/route.ts. If you need further clarification about anything, lmk!Where the Calendars at???
In this section, we will be retrieving the default calendar object associated to a specific group given its id. Pretty much same methodology for using Mircosoft Graph API except with a different endpoint.
Create a new folder in
frontend/app/api/calledcalendars. Then make another folder inside of it calledgetCalendars. Please add a file in this folder calledroutes.ts. Here is where you will create a GET function similar to the last function. Here, in this GET function, you will configure the endpoint, header, and authorization to make the call to Microsoft Graph. Check out the following documentation to see how the endpoint is constructed (specifically the sections "HTTP Request" and "Request Headers"). We will be using theGET /groups/{id}/calendarendpoint to reach Microsoft Graph API: https://learn.microsoft.com/en-us/graph/api/calendar-get?view=graph-rest-1.0&tabs=httpIn the request body of your GET function, you should expect to receive a field called "accessToken" and "groupId". Extract these fields and add it to your header under Authorization. After, please use the new secret we added in
.envfor configuring the endpoint. Ping Microsoft API using theawaitandfetchkeywords. This whole part pretty much follows from the last section. Once finished, return a Response object with jsonified default calendar data and a status code or just a failure status code. It should look similar to the return offrontend/app/api/retrieve/meeting/route.ts. If you need further clarification or if something does not work as intended, lmk!Testin' 🫨
In
frontend/app/page.tsx, please create a new section called "Microsoft Exchange Calendars" and add two testing button under this section. Connect them to two handleClick functions:Have these functions console.log() whatever they return.
Submission
In a PR, please submit a screenshot of the console as well as a 2-3 sentence description of what you have done!