Manage your tasks with the Microsoft To Do API

One of the challenges of the modern enterprise is task management. How can organizations get visibility into a world of collaborative microwork where tasks are split up into individual toolchains and workflows with very little visible product? Some tasks don’t fit into project plans and often surface in an ad hoc, asynchronous manner. 

That doesn’t stop people from wanting to keep on top of their assignments, no matter how small. What’s needed is a way to programmatically add tasks to a familiar, low-impact tracker that can check off tasks and report completion as necessary. You could build your own from scratch, iterating on any of the myriad distributed “Hello, world” applications out there, or you could work with the APIs of an app that’s likely to be on every user’s desktop—and every user’s phone.

Managing tasks with To Do in the Microsoft Graph

Microsoft 365 includes a subscription to To Do, a desktop task manager that integrates with Teams and Outlook and with iOS and Android clients. It’s the successor to the popular Wunderlist and is built on top of the Microsoft Graph to store and manage lists of tasks. The app is easy to use, with the option of sharing tasks across groups as well as keeping your own task list, but the Graph support and the associated APIs might be its most important feature, as these allow it to interact with other applications and workflows.

If you’re building code to work with the To Do API, it helps to be familiar with the Microsoft Graph and how it works, as a set of REST APIs that require authentication to work effectively. You can use the Graph Explorer tool to experiment with queries before writing code, before using tools such as Postman to verify calls. If you’re interested in exploring what’s next, an experimental version of the next release of the To Do API is in the Microsoft Graph’s beta namespace.

At the heart of the To Do API are four key elements: the task list, the task, the checklist item, and the linked resource. All four navigate To Do resources and construct calls. One key feature of the To Do APIs is an important entity type in the Microsoft Graph: a “linked resource.” The idea is that data should be able to point back to the application that sourced it. For example, a To Do task generated from an email should contain a pointer to that original email.

This gets more interesting: Any source application can be a linked resource. If you have a bespoke application running a key business function that generates a To Do task, that task will contain a link to your application so that a user can go straight from the task to the application.

This approach reduces the cognitive complexity associated with application switching; the user’s flow remains associated with the task. People can go straight from a call to action in an assigned task to the action itself in the application that posted the task. Once the task is complete, the user can clear the task in To Do, which clears out any other associated notifications in other users’ task lists, ensuring that there’s no need for oversight. At the same time, it can trigger new tasks in other To Do instances, such as letting approvers know that they need to complete an action.

The To Do data model

The task list is the highest level of resource once you’re logged in and querying the available data. It’s best thought of as a container for a set of tasks. If you’re dynamically populating a user’s To Do with specific responsibilities, use the task list to group tasks set by a specific application or workflow. Tasks are individual pieces of work within a task list, which itself can be broken down into subtasks as a set of checklist items in a task. Each task can then be associated with a linked resource. A useful option, delta queries only fetch changes in a task or task list collection, using a local cache to store data. This can speed up responses but does require more processing in your application to handle the cached data.

Once you’re authenticated and working with a user’s tasks through the Microsoft Graph, you can work with task data much like any other data source. You can show all the available lists for a user before getting details of a specific task. Operations follow the familiar CRUD (create, read, update and delete) pattern, with data sent and received as JSON.

Task lists are collections of tasks, with each task again managed using CRUD, while you can work with any associated checklists or linked resources using additional API calls. Much of your code will need to work with the properties associated with a task: tracking or changing its status and setting reminders and recurrence patterns. You can add your own properties to a task using extensions if you have the correct permissions for the resource you’re extending. Like any graph object, extensions need an ID, a body, and a name.

Having an extendable data model is useful, but in practice, most tasks should be defined without needing additional data beyond linked resources. These are delivered and stored as URLs along with display data so that users can see what application they will be launching and why. It’s possible to deliver deep links here so that for a task that requires updating a customer record in Dynamics 365, a user can be linked directly to the record so they don’t spend time navigating another user interface and losing their context, ultimately breaking flow and reducing productivity.

Power Automate connectors to To Do

Although you can use the API from your own code, Microsoft exposes it through a Power Automate connector. Adding To Do to process automation makes sense, quickly turning emails into tasks or linking to tasks from other ecosystems such as Google’s or from tools such as Jira or GitHub. Microsoft has been using Microsoft 365 to break out functionality from SharePoint and other tools, with Power Automate providing a low-code glue to link them. This lets you assign things from Planner or Bookings, allowing you to quickly build To Do into a tool for managing frontline staff.

Actions can create new task lists and add tasks to existing lists; there are also ways to assign all the outstanding tasks to a user, though you may need additional logic to get the state of a specific task. The connector provides triggers that source event-based messages that can be consumed by other flows or by external applications so you can track when new tasks are created and when their state changes.

With a mix of traditional APIs and low-code connectors, the Microsoft Graph has become the way Microsoft 365 applications expose their functionality to the wider world, making familiar desktop and mobile apps a common UI layer for more complex line-of-business systems. Why build a UI for business functionality when you can inject it into tools like To Do or Teams?

The value: Not only do users stay in one application context to manage their duties, but you can deliver code more quickly as you don’t have to develop and test UIs at scale. You’re able to work with tools that are already verified by thousands, even millions, of users.