This article demonstrates how to use schema extensions.
Imagine you're a developer in a Learning Management Software company called "Graph Learn" that builds training courses and materials for businesses. You use the collaborative experience of Microsoft 365 groups to deliver course content and record exercises among participants for both online courses and instructor-led courses. You want to make the Microsoft 365 groups used for training courses easily identifiable as training courses, which will allow other developers to discover your groups and build rich experiences on top of your learning courses.
For this scenario, this article will show you how to:
View available schema extension definitions that you could use.
Register a schema extension definition that targets groups for training courses.
Create a new group with custom data based on the schema extension definition that you registered.
Add, update, or remove custom data in an existing group based on a schema extension definition.
Read a group and the extension data.
Note
Apart from groups, schema extensions are also supported and can be managed for other resource types.
1. View available schema extensions
First, as a developer, you might want to find any other schema extension definitions that our app could reuse.
In the following example, you query the schemaExtension resource for a specific schema extension by its id.
Notice that the extension returned in the response has Available as the status value, which indicates that any app that has permission to the resources in the targetTypes property can use and update the extension
with additive changes. In general, this operation returns any schema extensions that satisfy the specified filter regardless of status, so do check the extension status before using it.
GET https://graph.microsoft.com/v1.0/schemaExtensions?$filter=id eq 'graphlearn_test'
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.SchemaExtensions.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "id eq 'graphlearn_test'";
});
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new SchemaExtensionsRequestBuilderGetRequestConfiguration();
$queryParameters = new SchemaExtensionsRequestBuilderGetQueryParameters();
$queryParameters->filter = "id eq 'graphlearn_test'";
$requestConfiguration->queryParameters = $queryParameters;
$requestResult = $graphServiceClient->schemaExtensions()->get($requestConfiguration);
2. Register a schema extension definition that describes a training course
If you can't find a schema extension that is appropriate for your needs, you can create and register a new extension definition for training courses on the group resource.
When creating a schema extension definition, you should provide a string for the id property. Assuming you've verified your vanity domain graphlearn.com with your tenant, you'll concatenate the verified domain name (graphlearn) with a name
for the schema extension (courses), and assign id with the resultant string, graphlearn_courses. This id becomes the name of the schema extension property on a group. See an example of the other way to assign id in the request that requires you to provide only a schema name.
Then, specify a description, target resources this extension applies to, and the custom properties that make up the schema. In this example, specify the courseId, courseName and courseType custom properties and their types.
Notice that when you initially create a schema extension, its status is InDevelopment. While you're developing the extension, you can keep it in this status, during which only the app that created it can update it with additive changes or delete it. When you're ready to share the extension for use by other apps, set status to Available.
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new SchemaExtension
{
Id = "graphlearn_courses",
Description = "Graph Learn training courses extensions",
TargetTypes = new List<string>
{
"Group",
},
Properties = new List<ExtensionSchemaProperty>
{
new ExtensionSchemaProperty
{
Name = "courseId",
Type = "Integer",
},
new ExtensionSchemaProperty
{
Name = "courseName",
Type = "String",
},
new ExtensionSchemaProperty
{
Name = "courseType",
Type = "String",
},
},
};
var result = await graphClient.SchemaExtensions.PostAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new SchemaExtension();
$requestBody->setId('graphlearn_courses');
$requestBody->setDescription('Graph Learn training courses extensions');
$requestBody->setTargetTypes(['Group', ]);
$propertiesExtensionSchemaProperty1 = new ExtensionSchemaProperty();
$propertiesExtensionSchemaProperty1->setName('courseId');
$propertiesExtensionSchemaProperty1->setType('Integer');
$propertiesArray []= $propertiesExtensionSchemaProperty1;
$propertiesExtensionSchemaProperty2 = new ExtensionSchemaProperty();
$propertiesExtensionSchemaProperty2->setName('courseName');
$propertiesExtensionSchemaProperty2->setType('String');
$propertiesArray []= $propertiesExtensionSchemaProperty2;
$propertiesExtensionSchemaProperty3 = new ExtensionSchemaProperty();
$propertiesExtensionSchemaProperty3->setName('courseType');
$propertiesExtensionSchemaProperty3->setType('String');
$propertiesArray []= $propertiesExtensionSchemaProperty3;
$requestBody->setProperties($propertiesArray);
$requestResult = $graphServiceClient->schemaExtensions()->post($requestBody);
POST https://graph.microsoft.com/v1.0/groups
Content-type: application/json
{
"displayName": "New Managers March 2017",
"description": "New Managers training course for March 2017",
"groupTypes": [
"Unified"
],
"mailEnabled": true,
"mailNickname": "newMan201703",
"securityEnabled": false,
"graphlearn_courses": {
"courseId": "123",
"courseName": "New Managers",
"courseType": "Online"
}
}
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new Group
{
DisplayName = "New Managers March 2017",
Description = "New Managers training course for March 2017",
GroupTypes = new List<string>
{
"Unified",
},
MailEnabled = true,
MailNickname = "newMan201703",
SecurityEnabled = false,
AdditionalData = new Dictionary<string, object>
{
{
"graphlearn_courses" , new
{
CourseId = "123",
CourseName = "New Managers",
CourseType = "Online",
}
},
},
};
var result = await graphClient.Groups.PostAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new Group();
$requestBody->setDisplayName('New Managers March 2017');
$requestBody->setDescription('New Managers training course for March 2017');
$requestBody->setGroupTypes(['Unified', ]);
$requestBody->setMailEnabled(true);
$requestBody->setMailNickname('newMan201703');
$requestBody->setSecurityEnabled(false);
$additionalData = [
'graphlearn_courses' => $requestBody = new Graphlearn_courses();
$ requestBody->setCourseId('123');
$ requestBody->setCourseName('New Managers');
$ requestBody->setCourseType('Online');
$requestBody->setGraphlearn_courses($graphlearn_courses);
];
$requestBody->setAdditionalData($additionalData);
$requestResult = $graphServiceClient->groups()->post($requestBody);
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new Group
{
AdditionalData = new Dictionary<string, object>
{
{
"graphlearn_courses" , new
{
CourseId = "123",
CourseName = "New Managers",
CourseType = "Online",
}
},
},
};
var result = await graphClient.Groups["{group-id}"].PatchAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new Group();
$additionalData = [
'graphlearn_courses' => $requestBody = new Graphlearn_courses();
$ requestBody->setCourseId('123');
$ requestBody->setCourseName('New Managers');
$ requestBody->setCourseType('Online');
$requestBody->setGraphlearn_courses($graphlearn_courses);
];
$requestBody->setAdditionalData($additionalData);
$requestResult = $graphServiceClient->groupsById('group-id')->patch($requestBody);
If you want to update the values of the extension data, put the entire extension complex type in the body of a PATCH request (similar to adding custom data to an existing resource).
To remove custom data added to a resource instance, but keep the schema extension property on the resource instance, set the corresponding extension property to null.
To remove a schema extension from a resource instance, set the extension complex type in that instance to null.
5. Get a group and its extension data
A handy way to look for a group (or groups) is to use $filter to match for specific extension property values,
such as an extension name or ID.
Then, to get the custom data in a group, use $select to include the extension by name (in this case by graphlearn_courses).
The following example looks for the group that has the graphlearn_courses extension with a courseId property value matching 123, and gets the group properties displayName, id, and description, and the custom data in the graphlearn_courses extension.
GET https://graph.microsoft.com/v1.0/groups?$filter=graphlearn_courses/courseId eq '123'&$select=displayName,id,description,graphlearn_courses
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.Groups.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "graphlearn_courses/courseId eq '123'";
requestConfiguration.QueryParameters.Select = new string []{ "displayName","id","description","graphlearn_courses" };
});
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new GroupsRequestBuilderGetRequestConfiguration();
$queryParameters = new GroupsRequestBuilderGetQueryParameters();
$queryParameters->filter = "graphlearn_courses/courseId eq '123'";
$queryParameters->select = ["displayName","id","description","graphlearn_courses"];
$requestConfiguration->queryParameters = $queryParameters;
$requestResult = $graphServiceClient->groups()->get($requestConfiguration);
HTTP/1.1 200 OK
Content-Type: application/json
{
"value": [
{
"displayName": "New Managers March 2017",
"id": "14429ae5-3e74-41a2-9fa8-028fbb984637",
"description": "New Managers training course for March 2017",
"graphlearn_courses": {
"@odata.type": "#microsoft.graph.ComplexExtensionValue",
"courseId": "123",
"courseName": "New Managers",
"courseType": "Online"
}
}
]
}