Microsoft 365 Community Microsoft Graph, 11 Oct 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Introduction to Records Management APIs on Microsoft Graph

Description

In this 13-minute developer focused demo – Cameron Parker and Samriddhi Seth bring viewers along on automating Security, Compliance, Identity and Management (SCIM) with new Microsoft Graph APIs focusing on Records Management (RM), specifically Retention Labels, Events, and Event Types. Records Management and Data Lifecycle Management (DLM) helps organizations manage retention and deletion of data throughout its entire lifecycle. Use cases covered – events-based retention and label management for managing retention schedules. See sample queries in Postman. APIs currently in beta. This PnP Community demo is taken from the weekly Microsoft 365 Platform Community call recorded on October 11, 2022.

Demo Presenters
• Samriddhi Seth (Microsoft)
• Cameron Parker (Microsoft)

Supporting materials
• Documentation – Create retentionEvent | https://docs.microsoft.com/graph/api/security-retentionevent-post?view=graph-rest-beta
• Documentation – retentionLabel resource type | https://docs.microsoft.com/graph/api/resources/security-retentionlabel?view=graph-rest-beta
• Documentation - Use Postman with the Microsoft Graph API | aka.ms/GraphPostman
• Licensing – Microsoft Purview Data Lifecycle Management & Microsoft Purview Records Management | aka.ms/DLM/licensing
• Documentation – Permissions for retention policies and retention labels | https://learn.microsoft.com/microsoft-365/compliance/get-started-with-data-lifecycle-management#permissions-for-retention-policies-and-retention-labels
• Tools – Microsoft 365Developer Program | aka.ms/M365DevProgram
• Documentation - Use the Microsoft Graph records management APIs | aka.ms/DLM/API
• Documentation – Effective permissions | https://learn.microsoft.com/graph/auth/auth-concepts#effective-permissions
• Documentation – Start retention when an event occurs | https://learn.microsoft.com/microsoft-365/compliance/event-driven-retention
• Feedback - Data Lifecycle and Records Management | aka.ms/DLM/Feedback
• Demo - Taking advantage of the Microsoft Graph Postman collections - Rabeb Othmani (Microsoft) | @Rabeb_Othmani - https://youtu.be/DlGcsPu9XfA
• Demo - Introduction to Microsoft Graph Postman collection - Sébastien Levert (Microsoft) | @sebastienlevert - https://youtu.be/ymAPHTuUCM4

Related SCIM API demo
• Demo - Introduction to Privacy APIs on Microsoft Graph – Brian T. Jackett (Microsoft) | @BrianTJackett and Cameron Parker (Microsoft) | https://youtu.be/X3spdOS4jOk?t=394

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

B

Parker I am a product manager on the Microsoft customer and partner experience team I'm joined today by Sam, ready Seth, who is on the records management team.

B

So today we're going to be talking a little bit about automating security, compliance, identity and management with new Microsoft graph apis, and so this is specifically around the records management apis that we'll be talking about today, all right so just a little bit of the agenda uh so overview of the apis in their use cases uh we'll do a little bit of demos, of course, and talk about licensing and monetization demo environments and trials and then kind of end with uh some some links to some resources and things like that so jumping right into it so again included API.

B

So I mentioned skim earlier right so for skim, automation, we're really talking about three different sets of apis uh Records management being the one that we're talking about today, but there is also e-discovery premium as well as privacy and so overview of the uh Records management apis and their use cases. So essentially, these these apis exist to kind of help.

B

Organizations manage that retention and deletion of data to meet their legal obligations and compliance regulations and so kind of to quote uh data lifecycle management is what helps you keep the data you need and delete what you don't a couple sample use cases for the apis that we have available again. These are currently in beta uh and so right now.

B

uh What you're, looking at in terms of use cases is event space retention, uh so you know triggering based off of some sort of internal or external events, such as like an employee leaving the company, as well as label management when using a third-party tool, so automation around like creation, updates of labels and that kind of thing so moving on we're looking at a few of the sample queries via the the API, what they, what these would look like as far as like the raw HTTP request form, and so this particular one is for the events based retention example, and so looking at this use case.

B

Right got a few sample, queries so uh listing or enumerating those retention event, types that you may have retention event type being associated with a label, and then you know using a retention event uh to to again. You know trigger that event right, so that some action can be performed uh based off of labels associated with that that event type and so uh looking to the documentation down here at the bottom.

B

um Moving on to the other use case, we have label management and so again, more of like a crud operations against labels right, so you know creating enumerating labels performing updates via that patch operation. You can delete as well again a link to that documentation, all right and so enough talking.

B

Let's take a look at it and for this we're going to be using Postman, and so uh we recently, uh along with some of the other API sets, we were able to incorporate these into our official Microsoft graph collection for Postman, and so for those of you who may not be familiar with Postman. This is a great API testing tool that allows you to uh you, know craft HTTP, queries and test out the apis without having to write a whole bunch of code.

B

In order to do that, we provide a specifically for Microsoft graph, where we do provide a collection that allows you to essentially have these pre-crafted queries so that you're not having to manually craft each and every query that you want to test out against the Microsoft graph API, and so basically you you can obtain this. It's it's in our documentation, which we'll share a link to a little bit later. But essentially you can Fork. This collection, uh bring it into your local Postman instance and then set it up based off of an application registration.

B

So, of course you know using Microsoft graph you're looking at that uh that that typical setup of you know creating an application registration in Azure uh and then getting your your information, such as your tenant, ID, client, ID, client, secret and so forth, uh and that's what you're going to use in order to get that access token.

B

And so you may have noticed that we're using the authorization code flow in this example, and so uh we are using delegated permissions here uh and so we'll go ahead and get started by grabbing an access token that we'll need all right and you can see that completed successfully, and so now you may have noticed that you know kind of jumped straight into getting that token, even though we were using the authorization code flow, that's only because I've I've already previously consented to that permission.

B

Otherwise you know you would you would see that typical flow of having to sign in with an account uh and then consent to that permission, had you not done so already, all right, and so uh with that, as you may have seen uh just uh just a little bit ago. We have some variables and things like that that we'll be using for the demo. So that's under the kind of root collection here and the variables that I have populated. You will find these apis.

B

The the sample queries for these apis under the compliance folder under delegated. uh Because, again we are using delegated permissions here uh and so compliance folder records management, and then we have you can see. We have the two kind of use cases we talked a little bit about earlier and so moving into we'll go through this label management scenario and so uh starting out. So we've already got our token. uh You can kind of see here how like we've got.

B

You know just the basic layout of Postman and so you've got your get call and then you've got the actual HTTP query here that you would be executing to to make that call and so we'll go ahead and hit send there. Since we got our token all right, and so you can see here, we got a successful.

B

uh You know returns information about existing labels, I haven't created one yet so this is, you know a label that I had previously created, but we'll go ahead and we'll get one created. So you can see a little bit different here, we're using a post call. We do have the body of this request populated with some information that we need to send in order to create that event.

B

uh You may have noticed the uh this kind of weird looking text here with the um uh curly braces around it, and this is just one of those variables right, so you can actually feed the variables into the request bodies, which is, which is a really cool feature of Postman, uh so we'll go ahead and hit send there and if everything goes well uh yep, so we get our 201 created response and we can see that we've successfully created a label, and so what I'll do is I'll actually kind of jump over and show you um so if I go to, you can actually view this under data lifecycle management as well.

B

If we jump to records management, we should be able to take a look at this and so under our file plan, and it might have already refreshed and yep. So we can see here, I believe it's this top one right here. They look similar just from the uh the way that it's kind of uh viewed right now, let's see- and so another note about this- you can see that there's a under this test field.

B

What we're actually doing here as you'll, see here in just a moment, is we're actually capturing the ID, that's being returned in the uh body of the response. It's saving that into a variable so that we can use that in the future, which I'll show you uh here shortly and so, uh as you can see what we did is we found a label into this. This next request- and this is just a get request to basically get that label that we just created.

B

And so again you can do things like you know, enumerating the labels creating I'm, getting details about just this one specific label that we just created. uh You can even go so far as to do an update, so we're doing a a patch for that again using that ID that we just created, you can see a 204, no content right and we effectively updated the uh description for admins there, and you can see that that actually updated and then kind of jumping back to the portal real quick. If I selected the correct one.

B

Oh, it looks like it was second one actually you'll see that if we do a refresh and then if I select that label you'll actually see that it was updated in the UI right, so that's kind of a key takeaway.

B

The reason for showing this is just that you can see that essentially we're performing actions similar what you would be doing through the UI and those actions are reflected uh when made through the API in the UI as well all right and so again you can delete delete if you wanted to with that for that label. We're not going to do that here today, but then again we also have this other use case.

B

uh So definitely recommend that you, you check this out if you're interested, so with that we will go ahead and jump back to our slides. A quick word about licensing and monetization, so some require some operations require an E3 license. Some require an E5, the kind of key takeaway. There is the current apis. They match the feature licensing right, so the the feature associated with you know that graph API operation that you're performing.

B

Please do note that the future records management apis uh they may be metered based on consumption, so just wanted to make sure to call that out. You can learn more about licensing at AKA dot, Ms forward, slash dlm, forward, slash licensing, okay, quick word about permissions, uh so as these apis require delegated permissions, uh I did want to make sure to call out that the uh we have this concept of effective permissions with Microsoft graph right and especially in the context of delegated permit permissions.

B

It's that intersection of not only the Microsoft graph permission that you've you've consented to, uh but also that back-end permission right associated with the essentially the the service right that you're calling right. So the essentially the the records management permissions in this case. So do you want to be uh cognizant of that, and so, uh if you'd like to learn more about the permissions required on the back end, you can check out this link here, all right and so for demo environments and trials.

B

uh So we do have the uh a Sandbox tenant available via the 365 developer program again comes with a 25 E5 licenses. It is 90 days. However, it does self renew as long as you uh keep using that that tenant uh for developer purposes, so you can check that out at AKA dot, Ms forward, slash n365 Dev program, uh not really meant for like load testing or anything of that nature.

B

If you do want to do load, testing, I, recommend kind of checking out an actual tenant with you know additional licenses and so forth, but this is a very useful tool for that uh or I should say, for you know for just like kind of basic sandbox testing and that kind of thing. So for the postman collections, you have AKA dot, Ms forward, slash graph posts, man that was the postman collection that we were going through earlier.

B

So again, if you are interested in taking a look at that, please do check out that link all right now on the roadmap. We do have application permissions uh as well as file plan descriptors, so I just wanted to call that out all right and then so for some additional resources about this uh definitely recommend checking out AKA dot, Ms uh forward, slash dlm forward, slash, API, uh learning more about event, space retention that we talked a little bit about earlier.

B

We have a link here for that and certainly encourage you to leave feedback uh that can be done via aka.ms forward, slash, dlm, forward, slash feedback and with that uh Fabian I will turn it back over to you.

C

Ken, do you have time for some questions, um or do you want to do them in the chat.

B

uh Yes, sir I didn't have a chance to take a look at the chat, so uh we can go ahead and it's, however, you'd like to. If we have time we could certainly take um yeah.

C

Otherwise, yeah so that we can go, um there's a question from aravind asking: is there an API or a UI for end users to see which documents are about to expire through retention label? That's that's that kicks us off.

B

Yeah, sorry same already, would you like to.

A

Yeah I was just uh yeah, okay, first thing, uh hi everyone and great to see this platform. Thank you so much for the opportunity to share this these great apis with everyone, so glad to be here all right and then coming to the question and yeah thanks Cameron for this amazing presentation, love literally, of course, yeah and coming to the question right now. I, don't think we have this. But of course it's a great question. I think it's a great finding for us to uh to see if we can accommodate in the roadmap.

A

uh We do need feedback. That's what we are here for you know to see what your user experiences, what you think is the missing piece and uh we want to deliver the best right there. So yeah, we don't have this right uh at the moment. All.

C

Right is anyone. Thank you, Anthony Rita, for that um responsible question. um I think. That's the only I think there were a few comments, but that was the only one question that I see called out. Did anyone else have. Let me see new comment down here. Yeah.

B

And so one thing I didn't want to call out as well just kind of uh let me jump back to the to the slides, real, quick so going back to the uh permissions here, uh because in the demo I believe I used the the uh the default or the the demo. So I did want to call out this specific Microsoft graph permission that you would be using kind of in addition to those back-end permissions I was referring to, and so that would be the records management.reader.rewrite dot.

B

All permissions so again just wanted to mention that, but uh yeah so with that uh Fabian. Thank you turn it back over to you.

C

All right thanks very much Ken. Thank you also, Aretha.