Posted by on May 10, 2016 in #Office365Dev | 0 comments

Changes to findMeetingTimes API, find more information on our blog post. http://dev.office.com/microsoft-graph-findmeetingtimes-api-update. This change will take effect from May 19th, 2016.

What is the Find Meeting Times API?

The Microsoft Graph contains a great amount of data, insights and intelligence. If you have only thought about the Microsoft Graph as a service to read and write data from the Microsoft Cloud – there is much more than that! One of the most exciting parts about the Microsoft Graph is the ability to take advantage of its intelligence. One of these abilities is called the Find Meeting Times API. This is a REST API, familiar to the ones we have been calling the in the past with the Microsoft Graph. Using this brand new (still in beta) service, you can let the Microsoft Graph find the perfect time for a set of individuals to meet up. But not just by looking at their calendars, you can also configure a set of constraints to fine tune the computation – and it’s all taken care of by the Microsoft Graph.

Please note that the Find Meeting Times API is still in preview. Meaning operations, response models and other aspects of the REST API are subject to potential changes.

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/

How does it work?

Once you have the authentication piece in order. It’s just a matter of sending a JSON object, containing the data needed by the API to perform the computation. It’s extremely straight forward and there are a few properties you can set to your liking. Such a request object may look something like this:

As for the attendees property, you can specify the individuals (in the tenant) you want to be present as either Required or Optional attendees. You can identify them by the address property. Next up is the locationConstraint property, this is essentially the constraint for the location of the happening. You can optionally set this constraint, or have the Microsoft Graph suggest a location for you using the suggestLocation property. The last constraint is the timeConstraint property, which contains a set of timeSlots for when the meeting may take place. Finally the length of the meeting is set with the meetingDuration property in an ISO8601 format (http://www.iso.org/iso/iso8601). In the above example, the duration is set to an hour (as noted by the 1H part).

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 contains the required Calendars.Read scope (http://graph.microsoft.io/en-us/docs/authorization/permission_scopes).

Now, if the Microsoft Graph is able to compute at least one time slot for us – it will be returned in a JSON response.

The response itself is self-explanatory, apart from a few additional properties that I want to point out . The confidence property is a percentage value that represents the likelihood of all attendees attending. Also, if you set the returnSuggestionHints property to true in the request object, you will also be given suggestionHint (string) properties with a reason for every suggestion.

Proof of Concept (C#)

For this post I created the following code sample piece that requests meeting time suggestions for a couple of members in my Office 365 tenant.

To achieve this, I created the following C# classes to help us serialize and deserialize the JSON data model which the Find Meeting Times API is using. I will be using Json.NET in this sample (http://www.newtonsoft.com/json).

Below are all of the models, which finally spawn the FindMeetingTimeResponseModel and FindMeetingTimeRequestModel (at the bottom) classes used as the representation of the request and response objects:

In addition, I created a helper method for posting the data to the Find Meeting Times API:

With the models and helper method 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 work with the Find Meeting Times API.

findmeetingtimes

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

-Simon Jaeger