Posted by on Feb 2, 2016 in #Office365Dev | 1 comment

What is the Microsoft Graph?

If you haven’t heard, there is an easy way to call a great amount of Microsoft APIs – using one single endpoint. This endpoint, so called the Microsoft Graph (https://graph.microsoft.io/) lets you access everything from data, to intelligence and insights powered by the Microsoft cloud.

This is a part of my Microsoft Graph posts – to get started you will need to configure your application in either Azure AD or the new Application Registration Portal (converged app model v2.0). The Azure AD approach is well-tested and production-ready, whereas the new converged application model is still in preview – but it covers both Azure AD and Microsoft accounts. Pick the approach that suits your needs.

Authentication with Azure AD: http://simonjaeger.com/microsoft-graph-authentication-with-azure-ad/
Authentication with app model v2.0 (preview): http://simonjaeger.com/microsoft-graph-authentication-with-the-converged-model-preview/

Outlook Extensions

If you have worked with Azure AD and its Graph API in the past – you might know about the Entity Data Model. This is essentially the schema for the various entities in the service (e.g. users, groups, etc.). This schema describes the different properties on the entities and its value types. This functionality also exists in the beta version of the Microsoft Graph – and it spans into the Outlook services.

This is great for anyone who needs to extend the current data model with custom data or properties – relevant to your service. It saves you time and capacity by not having to manage and store this data on your end.

As for Outlook extensions, you can create extensions on messages, events and contacts. It’s well worth to mention that this works for both Office 365 users and Microsoft accounts.

The extensions that you define for an entity is called an openTypeExtension entity. In short, this is an OData open type for defining runtime custom data on entities in the Entity Data Model. Apart from your own data – they will contain two different identifiers. These identifiers (id and extensionName) are properties on the openTypeExtension entity.

The id property is readonly and concatenates the extension type (Microsoft.OutlookServices.OpenTypeExtension for openTypeExtension) and the extension name (e.g. Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.MyExtension). Use this to reference the extension entity in the Microsoft Graph.

The extensionName property is defined by your application. Be sure to make your extensionName property value unique, to avoid collisions and overwrites. A good approach is to use a reverse domain name notation, for instance: Com.Contoso.MyExtension.

Finally, you can specify other properties on the extension to be stored as a JSON payload. To create the extension entity you need to POST a JSON object representation to the Microsoft Graph.

In return you will receive the JSON object with a couple of additional parameters, such as the id property.

To update an existing extension entity, use the extension id to PATCH the entity using your updated JSON object representation.

Be sure to include the Authorization header (with your access token) and set the Content-Type header to application/json. Also, make sure that your access token has the required scope for the resources you want to read/write extensions to: http://graph.microsoft.io/en-us/docs/authorization/permission_scopes

In addition, you can both GET and DELETE the extension entities using the same approach with the extension id – following the common CRUD conventions.

Proof of Concept (C#)

For this post I created the following code sample piece that adds an extension (Com.Contoso.MyExtension) to every event in the user calendar. The extension entity contains two simple properties (someString and someNumber) illustrating the functionality.

To achieve this, I created the following C# classes (for calendar events and extension entities) to help us serialize and deserialize the JSON data model which the Microsoft Graph is using. I will be using Json.NET in this sample (http://www.newtonsoft.com/json).

The following represents the extension property.

Below are the various parts defining the calendar event model. In addition, the response is delivered in a collection – so the events will be encapsulated within the ResponseModel class.

In addition, I created a couple of helper methods for calling the Microsoft Graph (GET and POST methods):

With the models and helper methods in place (and assuming you have sorted the authentication piece) – let’s get to it! This is how I implemented the flow:

Everything in this sample is done in a console application, which is most likely not what you are going to be using. However the flow and approach should stay the same (excluding the authentication part, which will differ depending on what you are building). Hopefully this gives you an idea of how to extend the Entity Data Model in Outlook to store your own custom data – saving you both time and complexity!

Be aware that the Outlook Extensions functionality is only deployed in the beta branch of the Microsoft Graph – so it is highly subject to changes and updates. Learn more about Outlook Extensions and the different operations at: http://graph.microsoft.io/en-us/docs/api-reference/beta/resources/opentypeextension

-Simon Jaeger