Microsoft 365 Community Community Demos, 25 Aug 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Using the Microsoft Graph education endpoints in SPFx to create a my assignments web part

Description

In this 18-minute developer-focused demo, Tony Philips delivers an option for those using the Assignments capability in Microsoft Teams for Education, to render an aggregated list of assignments in SharePoint. This is now possible using the My Assignments web part carefully explained here. Learn about the education related APIs in Microsoft Graph. EDU specific end points shown: /education/me, /ms/joinedTeams, /education/me/classes, /education/me/assignments. Review API permissions, caching service, refresh technique and capability limitations. Requires Education tenant. Separate student and teacher views of assignments. This PnP Community demo is taken from the Viva Connections & SharePoint Framework Bi-weekly sync call recorded on August 25, 2022.

Demo Presenter
• Tony Philips (Cloud Design Box) | @TonyMSTeams

Supporting materials
• Documentation - Education API overview | https://docs.microsoft.com/graph/education-concept-overview
• Repo – My Assignments Web Part by Cloud Design Box | https://github.com/CloudDesignBox/CDBAssignments
• Documentation - Overview of School Data Sync | https://docs.microsoft.com/schooldatasync/overview-of-school-data-sync
• Documentation - Assignments in Teams for Education | https://docs.microsoft.com/microsoftteams/expand-teams-across-your-org/assignments-in-teams

Learn more
• Microsoft 365 Unified Sample gallery - https://aka.ms/m365/samples
• Microsoft 365 Platform Community in YouTube - https://aka.ms/m365/videos
• Microsoft 365 Platform Community - http://aka.ms/m365/community

A

Yeah really excited to show you the my assignments web part today, so in specifically looking at some of the education graph, api endpoints and if you've not uh used an education intent before this might be quite new to you. So hopefully something interesting for everybody.

A

So a bit about myself and founder of cloud design box, I've worked with the sharepoint framework for a long time since preview, but uh I'm not a developer by trade. I started off with using javascript and script editor web parts, one thing led to another and I was making web parts so I've got some contact details there, so blog email and the github repository that we'll be looking at today.

A

So it's there for you to have a look at download edit, make changes to make your own version of, and that's all available and some of the endpoints we'll be looking at in today's demo. So some of these, you might be familiar with from just your standard graph endpoints. Some of these are education specific, so starting with the education me endpoint.

A

This is very similar to the me and pointing graph, except it's got some extended, aad properties that are specific to education, so you get extra stuff like the students grade or, if they're, a teacher or a student, what their status is. That will all come back with that education me endpoint, there's also the me join teams, which is just listing your teams, as you will get it with your standard, graphicals and then two more education, specific ones.

A

So the education me classes is the same as the the groups endpoint, but it's filtered to the type of uh group, which is a template of a class. So inside education we have the concept of a class team and you get thousands of of these made every academic year in a typical, high school and a tenant. You might have hundreds of thousands of these, so this endpoint filters it down. So you can just retrieve the class groups that you're a member of and the me assignments endpoint.

A

This is specific to education, so there is no um no alternative in sort of standard graph endpoints. So in the education version of teams there is a assignments.

A

Part teams where you can set science to students- it's got some really amazing features in there. So you can do things like use ai, to measure students, reading progress and you can set assignments and collect it back so again, if you've not seen it before check it out, and it's only available to education. Tenants, unfortunately, and so you can't sign up to a developer tenants easily.

A

You need to get in touch with the right people at microsoft and all the data inside these teams and inside these endpoints is populated by something called microsoft. School data sync and any school can use that for free uh teams and office. 365 is free for schools and they can upload their data using csvs or they can use one roster apis.

A

There's lots of different ways of getting your data into graph into those aed objects and there's a reference to those at the bottom, and this is a quick screenshot of what the assignments look like inside teams. Just so you can visualize what it is that we're trying to aggregate together inside sharepoint. So the team's assignments is fantastic lots of really cool features in there and like a massive amount of features in there it'll take you all day to look at all of them.

A

In fact, sometimes there's too many, but one thing you can't do is you can't show and aggregate a list of those in your sharepoint intranet? So this is one of the things that we wanted to do with this web part and there's quite a few challenges that we came across. So um the there was no me assignment endpoint until recently, not officially supported, so you had to go a really long way around getting those assignments. You had to get a list of all the classes.

A

Query each class for a list of assignments put them all together, so it was incredibly intensive when you're calling those api calls for the first time and throttling is quite bad in education, because everybody logs in at the same time, at the start of the school day or the lesson, potentially thousands or hundreds of thousands of people logging in loading the same page when they open up their web browser.

A

So it's really important to keep the api usage to a minimum, to use caching, so we're not calling it too many times. So without that me endpoint, we couldn't do it very well. We had to use some server-side caching to do that previously. So that's really good. That is now supported and we can use it in this example.

A

um There is an academic rollover process in education as well again, something that happens around this time of year. That's why we're all stressed at the moment, and we have to archive all the old class teams again, hundreds of thousands of them do a clean up process and then upload the new data for the new academic year.

A

So there's a big processor in september of creating hundreds of thousands of teams inside education, tenants, potentially with loads of assignments as well, because if you imagine, if you're in 20 different classes in your high school uh your over the year, you're going to have lots of assignments set, so they add up really quickly so I'll start off just by jumping into a demonstration and then we'll have a look at the code.

A

So I'm on a sharepoint page here um and if I go to add a web part, so this is running from my local host and I type in assignment you'll, see um microsoft last week released an assignment web part, but it doesn't show you aggregated assignments. It only shows you the assignment, if you put it on a class team page, which is um a new home page that they're designing in teams another new feature to education. So if I add this to the page, it doesn't do anything um so this this web part's still useful.

A

um So if we go and add the my assignments web part that we've created this is what it looks like it shows me all. The assignments have been set inside teams, and I can just check that so I can go into teams. Go to my aggregated assignments, for you inside teams. You can see I've got some here and that I've set this one is in the past, so we filtered that in the web parts, and I can see the assignments that do I can.

A

If I just publish the page, we've got some paging on here, because the list can get very big if teachers don't remember to close off assignments at the end of the day and if I click on an assignment, it will take me straight to that team's assignment.

A

So if I just use the web app it'll take me straight into that team's assignment, so I can go to it really quickly and easily straight from sharepoint straight from my school intranet homepage, and I've got a refresh button here, because we cache it for a couple of hours just to avoid lots of throttling. So you can press the refresh button or go and fetch the data again so back into the code. So I'll start off with the api permissions that we're using in here.

A

So um some of the endpoints share some of the api permissions. So we only require three. This is a minimal amount of permissions. You need to make this web part work. So we've got the assignments read which lets us read any assignments for us. For us. As a user, we've got the user reader, which gets fetches us back. The user type and the user attributes which will tell us if this person is a member of staff or, if they're, a student, because we need to show a slightly different view of assignments.

A

If you remember staff than if they're a student, because assignments might be overdue, if you're a student, but for the teacher, it's not overdue, it's either set or it's closed and there's also the edu roster. So this this gets us a list of classes and the list of teams, and this actually gives us that join teams permission as well. So we don't need to add that as an extra api permission, so those are the permissions we've used in this example. I've used react, so I started using react.

A

A couple years ago found it really useful in reducing development time. um Once I got my head around it, and so starting off just uh in the main file, we've got the web part properties. So there are some settings that we allow end users to do so. We've got a slider to assign the paging value. How many assignments we want to show.

A

In one view, we've got the ability to hide overdue assignments because they can get quite big if teachers don't close them off, and we can also show archived teams so from previous academic years and the settings for that, if I just edit the web part you'll see, these are the settings that we have here. I've only got a few times here. So if I change it, I can change it to five.

A

So you can't see the paging in action, but that will create another page and I better flick through the pages of assignments when they get quite big.

A

So uh going into our our main react component, so we've got main react component where I do pretty much everything and then we've got the child components for the assignment item which refreshes, whenever the state changes in the parent item. So um what we've got is some states that we use in this particular web part. So a lot of this data is coming back from graph async. So it's going to come back to us at different times, so we refresh the web part as that data comes in as we know more about it.

A

So we've got assignments in there. Teams, courses and uh one really useful tip if you are using the graph api, is to download the graph types, because that will let you define uh some of those uh interfaces much easier, so I can bring in. uh Let me show you a quick example: the education class and it already maps all those properties. That's going to come back from that api endpoint, so I'm not having to manually. Do that and create you know complex uh interfaces.

A

So that's definitely a really useful thing that we use when calling graph and just go through the different graph calls that we use in here. um So the first graphical we do is to get the education me endpoint and the only reason we do that is to find out if they're, a member of staff or, if they're a student.

A

So we only select the primary role and when that comes back to us, it will tell us if they're, a user, if they're a student or if they're, a teacher, we set that in the states again that refreshes the content and it will style the content for a student.

A

So the reason we do that is some assignments might be overdue for a student, so we mark them as read and overdue, and with teachers we show it slightly differently, so an assignment inside to set in the future or it's set in the past and what you'll see is I've created a caching service? I use use this with most of the web parts that I create, which is way I can just cache the uh any of the uh graph api calls in local storage.

A

I set some keys for them, so I've got a little helper functions to do that and then inside here, what you see is when the when the data comes back, uh we set that in the caching key as well just before we refresh the state. So if we ever refresh the page, it doesn't have to load that again. It's already got it so minimal.

A

Api calls where possible- and one really disappointing thing we have to do- is call the join teams endpoint and the only reason we have to do that is to find out if the team is archived, because the education endpoint for classes doesn't show that aad property. If it did, we wouldn't need to do this call at all. So, unfortunately, it adds on an extra call when we're creating uh the web parts, um which obviously isn't great, but it's only one call.

A

So it's uh not the end of the world, we'll just call it and find out. If the class is archived or not, we go and get the classes. uh So we get the course name and the display name of that particular class, and then we go and get the assignments for me, and so we could just return the assignments for me, but you wouldn't know which class those assignments belong to, which course it belonged to which isn't great for the student experience.

A

So um that's why we, we call the assignments api and there is a lot of limitations to using this at the moment. So we can't do a lot of filtering on this. We can't filter by dates again quite disappointing, so we're having to manually do that in some of the functions inside the code, um which is a real shame. Really, but um again, it just adds a bit more complexity to that web part. So we're sorting stuff by time- and we also add in the paging as well.

A

So again, um I've just set the paging as part of the state and then what we do when we actually go to render the web parts. So if I just go down into the render code here, you'll see that we're under the html that we've aggregated up from that child components.

A

But we also render the pages so the paging and where we are in that page. So whenever that state gets updated, somebody clicks on the button and it calls back that function and refreshes the state with a new page number that will then filter down into this render function, and it will refresh the child components now, if you show what the assignments item looks like. So this is the assignment item. It's quite quite simple react components.

A

We've got a url to open up that direct link to the assignment, and it's a very long url, um where we have to add in the class id which we got from. Another reason why we have to get the class id is we need. We need it to link to the assignments and we go and get the assignment id as well. So once we've got that we can generate that link to go straight into that assignment item inside teams.

A

So that's what we do in terms of uh the uh the child item um and in terms of uh just a quick look at the other things I was gonna, show you so in terms of the caching one thing that we do is we refresh your cache, if maybe spit out a date, and the student needs to press the refresh button, so we have a function uh where we do that.

A

So if I just have a quick look at where the cache is refreshed here, so we do a check for the cache before we call the apis, and that means we don't even need to bother calling the apis if it exists in the cache, because this function runs. It checks the cache on the local machine and then it will refresh the state with that cache data. So once it's got that we know, then that we don't need to call the apis.

A

So what you see in the render function here we check the cache first, once we've checked the cache. If it's empty, then we'll then call the assignments, api, we'll call the teams api and the course api and the end user api to get that data into that web parts.

A

So another thing I was, I was also going to show you as well, is what happens when we refresh the data. So somebody presses the refresh button. We run this function and this clears all the cache.

A

So it removes the cache from the user's machine, and then we just set the status blank and then, when the web part refreshes, it knows it needs to call the api again and get that data back and what you also might be aware of, is we create quite a complex caching string so again where this might differ to using cash in other places is in schools.

A

You might have a shared device where student logs in and then another student logs in um to the same device, and if we don't include the login name, then the cache will include assignment data from the previous user.

A

And if we don't include the location, we might have a multi-tenant setup where we've got multiple schools on a single tenant. So we have to remember where that web part is on the page, so that we mark that when we're caching the data in the cdb assignments area- and then it's pretty straightforward in terms of you know styling for the web parts quite minimal css in there um and yeah.

A

That's a that's a pretty much a very quick overview of the assignment web parts, and this is free to download from github, um so yeah feel free to check it out. Have a look at the code, I'm I'm happy to answer any questions that you might have about it as well, and hopefully that gives you a bit of an insight into what's happening in the education tenants which, like I say, slightly different to what you might get in your standard and developer tenants.

A

um You get features like the assignments you get class teams, um so you get a whole host of features that you might not be aware, exists inside teams until you start working with an education, specific tenant.

A

So back to you basically.

B

Excellent, thank you tony really, cool stuff, and I and it's it's I would say it's always it's not just about the education tenant and the education apis. It was also about the how you implement that the refreshing and the implemented the web part. It's that's, always an interesting uh scenario to go through and learn from that, because there's always new people in this call who haven't necessarily even written at their first web part. Yet so it's it's. Thank you for explaining.

A

Things I I would recommend you know using the microsoft documentation, that's where I lent all this from was you know the graphic examples on the microsoft site and really simple, really easy to do, and you can just apply it to anything whether it's the education endpoints, whether it's teams endpoint it just works, really well.

B

Excellent thanks tonic really really cool stuff.