Add custom data to users using open extensions

In this tutorial, you lean how to use open extensions.

Imagine you're building an application that's available on multiple client platforms, such as desktop and mobile. You want to let users configure their UI experience so it's consistent no matter which device they use to sign in to your app.

For this scenario, this article shows you how to:

  • Represent some roaming profile information about the user using open extensions.
  • Query the user and return the roaming profile.
  • Change the user's roaming profile information stored in the open extension.
  • Delete the user's roaming profile information.

Note

Apart from users, open extensions are also supported and can be managed for other resource types.

Prerequisites

To reproduce the steps in this article, you need the following privileges:

  • Sign in to an API client such as Graph Explorer and the user you want to store the roaming profile for.
  • Grant the app the User.ReadWrite delegated permission for the signed-in user.

Step 1. Add roaming profile information

The user signs in to the app and configures the look and feel of the app. These app settings should roam so that the user gets the same experience on whatever device they sign in to the app from. The app calls Microsoft Graph by running the following request to add the roaming profile information to the signed-in user's resource object.

Request

POST https://graph.microsoft.com/v1.0/me/extensions
Content-type: application/json

{
    "@odata.type":"microsoft.graph.openTypeExtension",
    "extensionName":"com.contoso.roamingSettings",
    "theme":"dark",
    "color":"purple",
    "lang":"Japanese"
}

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('376bdbfc-e41f-4082-a8cf-b31731465eeb')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "extensionName": "com.contoso.roamingSettings",
    "theme": "dark",
    "color": "purple",
    "lang": "Japanese",
    "id": "com.contoso.roamingSettings"
}

Step 2. Retrieve roaming profile information

When the user signs in to the app from another device, the app calls Microsoft Graph to retrieve the user's profile details and expand the extensions navigation property to get their roaming settings, then uses this data to provide the same experience as on the other device.

Request

GET https://graph.microsoft.com/v1.0/me?$select=id,displayName,mail,mobilePhone&$expand=extensions

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,mail,mobilePhone,extensions())/$entity",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET me?$select=signInActivity,accountEnabled",
    "id": "376bdbfc-e41f-4082-a8cf-b31731465eeb",
    "displayName": "Raul Razo",
    "mail": null,
    "mobilePhone": null,
    "[email protected]": "https://graph.microsoft.com/v1.0/$metadata#users('376bdbfc-e41f-4082-a8cf-b31731465eeb')/extensions",
    "extensions": [
        {
            "@odata.type": "#microsoft.graph.openTypeExtension",
            "extensionName": "com.contoso.roamingSettings",
            "theme": "dark",
            "color": "purple",
            "lang": "Japanese",
            "id": "com.contoso.roamingSettings"
        }
    ]
}

Step 3. Change roaming profile information

The user can choose to change their roaming profile information. The app calls Microsoft Graph by running the following query. The request returns a 204 No Content response code.

You must include all properties in the request body as well, even if you want to update only a subset of them. Otherwise, Microsoft Graph removes the properties you don't pass in. To delete data but keep a property, set the property value to null.

PATCH https://graph.microsoft.com/v1.0/me/extensions/com.contoso.roamingSettings
Content-type: application/json

{
    "theme":"light",
    "color":"yellow",
    "lang":"Swahili"
}

Step 4. Delete a user's roaming profile

The user decides that they don't want a roaming profile anymore. To delete the extension property, the app calls Microsoft Graph by running the following request. The request returns a 204 No Content response code.

DELETE https://graph.microsoft.com/v1.0/me/extensions/com.contoso.roamingSettings