Posted by on Apr 26, 2016 in #Office365Dev | 0 comments

What is the Outlook Task REST API?

If you want to be able to integrate with the millions of users in the Outlook services, the Outlook REST APIs (https://msdn.microsoft.com/en-us/office/office365/api/api-catalog) is a great way for doing so. The Outlook REST APIs combines multiple REST APIs into a single endpoint, giving you the ability to take advantage of all the data and intelligence in the Outlook space, across the Office 365 service and Outlook.com.

One of these REST APIs is the Outlook Task REST API, which lets you create, read, synchronize, update and delete a user’s tasks – one of the core modules in Outlook.

Please note that the Outlook Task REST 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/

Outlook Tasks

The concept of tasks in Outlook has been around for some time. They play a crucial role in many users’ ability to organize their day-to-day business. Tasks can be something as simple as an item with a subject line, to something with a very descriptive HTML content body, recurring alerts, status labels, priorities and much more. As you might be aware, these tasks are available both in the Office 365 service and Outlook.com

task1

The object model for tasks in the different services is practically identical. Making it very easy to build a solution that spans across these different services.

task2

Using the Outlook Task REST API, we get a very easy way of dealing with the object model using a JSON representation. Which could look something like this:

In this blog post, we will create a task for a user (Office 365/Outlook.com user) if none exist. Then we will extract and display all of the tasks.

In order to create a task for a user, you need to POST a JSON model of the task object to the Outlook Task REST API.

In return you will receive the JSON object with a couple of additional properties, such as the id property. To update an existing task, use the task id to PATCH the task 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 tasks to: http://graph.microsoft.io/en-us/docs/authorization/permission_scopes

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

Proof of Concept (C#)

For this post I created the following code sample piece that adds a task to the user if there is none. The task only sets the subject line and a simple text body.

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

Below are the various parts defining the task 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 Outlook Task REST API (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 work with Outlook tasks.

task3

Be aware that the tasks functionality is only deployed in the beta branch of the Outlook REST APIs – so it is highly subject to changes and updates. Learn more about Outlook Tasks and the different operations at: https://msdn.microsoft.com/en-us/office/office365/api/task-rest-operations#Updatetasks

-Simon Jaeger