# Microsoft To Do

Create, update and find tasks and task lists in Microsoft To Do, with their steps, links back to their source and file attachments.

## Connect Microsoft To Do

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `microsoft to do` and choose **Microsoft To Do**.
3. Press **Sign in with Microsoft To Do**, then choose your account in Microsoft To Do’s window and allow access.

Before you sign in, the sheet asks:

- **Account type · Optional**: Which Microsoft accounts may sign in: common (work, school or personal; the default when empty), organizations (work or school only) or consumers (personal only). For your own app registered for one directory only (single tenant), its Directory (tenant) ID.

Microsoft To Do works with work, school and personal Microsoft accounts.

**What if it says “Microsoft To Do sign-in isn’t set up here”?**

Signing in with Microsoft To Do needs a Microsoft To Do app on this installation, and it has none yet.

**On Cloud:** The sheet says “It’s set up once for everyone who uses this service, not by an organization.”

**Self-hosted:** An admin of the installation sees **Set up Microsoft To Do sign-in** instead, and sets it up once for everyone. Everyone else sees who to ask.

1. Create an app in Microsoft To Do’s developer settings ([Microsoft To Do’s guide](https://learn.microsoft.com/entra/identity-platform/quickstart-register-app)).
2. In GoRunner, copy the **Redirect address to add in Microsoft To Do’s developer settings**, and add it to the app.
3. Paste the **Client ID** and **Client secret**, then press **Save and sign in**.

[Set up a sign-in app](https://docs.gorunner.io/self-host/oauth-apps#other-providers)

**Can I use my own Microsoft To Do app?**

Yes. In the sheet, open **Use your own Microsoft To Do app** and paste its **Client ID** and **Client secret**. Add the redirect address it shows to your app first. The connection then signs in through your app instead of the installation’s.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Start a workflow

Add a trigger and choose **Microsoft To Do**. The trigger uses the same connection as the steps.

### On Task Added or Updated

Checks a Microsoft To Do list about once a minute and starts a run for each task added, or changed, since the check before. The first check after publishing only takes note of what is there (it starts nothing); changing the trigger starts over the same way. It reads every task of the list (at most 2,000; watch only open tasks for a bigger one). With Only Open Tasks on, a completed task leaves the watched set, and one reopened counts as added again.

- **List · Required**: The task list to watch.
- **Trigger on · Required**: Which changes start a run. Completing a task is an update. Options: Task added, Task updated (completed, renamed, rescheduled …), Task added or updated. Default: Task added.
- **Only Open Tasks · Optional**: Watch only tasks that are not completed: lighter on a long list, but completing a task then starts nothing (it leaves the watched set). Off by default.

A later step can use its data, such as `{{trigger.body}}`, `{{trigger.categories}}`, `{{trigger.change_type}}` and 7 more. See [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Do things in Microsoft To Do

Add a **Microsoft To Do** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Task](https://docs.gorunner.io/apps/microsoft-to-do#fields-f-task): Create · Get · Get Many · Update · Delete
- [Task List](https://docs.gorunner.io/apps/microsoft-to-do#fields-f-list): Create · Get · Get Many · Update · Delete
- [Linked Resource](https://docs.gorunner.io/apps/microsoft-to-do#fields-f-linkedresource): Create · Get · Get Many · Update · Delete
- [Checklist Item (Step)](https://docs.gorunner.io/apps/microsoft-to-do#fields-f-checklistitem): Create · Get · Get Many · Update · Delete
- [Attachment](https://docs.gorunner.io/apps/microsoft-to-do#fields-f-attachment): Add · Get (Download) · Get Many · Delete

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from Microsoft To Do can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When Microsoft To Do says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Microsoft To Do is `pieceId: "microsofttodo"` with `actionId: "microsofttodo"`, set by `resource` and an `operation_…` field, such as `operation_attachment`. Its trigger is `microsofttodotrigger` / `microsofttodo_poll`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Microsoft To Do › Task

### Create

- **List · Required**: The task list. Pick one, or use its id from an earlier step.
- **Title · Required**: What the task is.
- **Notes · Optional**: The task's notes (its body). On Update, leave empty to keep them.
- **Notes Format · Optional**: Whether the notes are plain text or HTML. Options: Text, HTML. Default: Text.
- **Status · Optional**: The task's progress. Completed marks it done. Empty: Not started on Create, unchanged on Update. Options: Not started, In progress, Completed, Waiting on others, Deferred.
- **Importance · Optional**: High shows the task as important (starred). Empty: Normal on Create, unchanged on Update. Options: Low, Normal, High.
- **Due Date · Optional**: When the task is due, such as 2026-11-07. To Do keeps the day.
- **Start Date · Optional**: When work on the task is planned to start.
- **Reminder · Optional**: When To Do reminds you, such as 2026-11-07T09:00. Setting one turns the reminder on.
- **Time Zone · Optional**: The zone of the dates above when they carry no offset, such as Europe/Berlin or Pacific Standard Time. Empty is UTC.
- **Categories · Optional**: Comma-separated category names, as defined in Outlook (such as Red category, Launch). On Update they replace the task's categories.
- **Repeat · Optional**: How the task repeats, as Graph's patternedRecurrence, such as {"pattern": {"type": "weekly", "interval": 1, "daysOfWeek": ["monday"]}, "range": {"type": "noEnd", "startDate": "2026-11-02"}}. A repeating task needs a due date.

### Get and Delete

- **List · Required**: The task list. Pick one, or use its id from an earlier step.
- **Task · Required**: The task. Pick one of the list's tasks, or use its id from an earlier step.

### Get Many

- **List · Required**: The task list. Pick one, or use its id from an earlier step.
- **Status · Optional**: Only tasks with this status. Empty: every task. Options: Not completed (any other status), Not started, In progress, Completed, Waiting on others, Deferred.
- **Importance · Optional**: Only tasks of this importance. Empty: any. Options: Low, Normal, High.
- **Return All · Optional**: Read every task, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many tasks to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **List · Required**: The task list. Pick one, or use its id from an earlier step.
- **Task · Required**: The task. Pick one of the list's tasks, or use its id from an earlier step.
- **Title · Optional**: A new title. Leave empty to keep it.
- **Notes · Optional**: The task's notes (its body). On Update, leave empty to keep them.
- **Notes Format · Optional**: Whether the notes are plain text or HTML. Options: Text, HTML. Default: Text.
- **Status · Optional**: The task's progress. Completed marks it done. Empty: Not started on Create, unchanged on Update. Options: Not started, In progress, Completed, Waiting on others, Deferred.
- **Importance · Optional**: High shows the task as important (starred). Empty: Normal on Create, unchanged on Update. Options: Low, Normal, High.
- **Due Date · Optional**: When the task is due, such as 2026-11-07. To Do keeps the day.
- **Start Date · Optional**: When work on the task is planned to start.
- **Reminder · Optional**: When To Do reminds you, such as 2026-11-07T09:00. Setting one turns the reminder on.
- **Time Zone · Optional**: The zone of the dates above when they carry no offset, such as Europe/Berlin or Pacific Standard Time. Empty is UTC.
- **Categories · Optional**: Comma-separated category names, as defined in Outlook (such as Red category, Launch). On Update they replace the task's categories.
- **Repeat · Optional**: How the task repeats, as Graph's patternedRecurrence, such as {"pattern": {"type": "weekly", "interval": 1, "daysOfWeek": ["monday"]}, "range": {"type": "noEnd", "startDate": "2026-11-02"}}. A repeating task needs a due date.

### Microsoft To Do › Task List

### Create

- **List Name · Required**: The list's name. The built-in Tasks and Flagged email lists cannot be renamed.

### Get and Delete

- **List · Required**: The task list. Pick one, or use its id from an earlier step.

### Get Many

- **Return All · Optional**: Read every list, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many lists to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **List · Required**: The task list. Pick one, or use its id from an earlier step.
- **List Name · Required**: The list's name. The built-in Tasks and Flagged email lists cannot be renamed.

### Microsoft To Do › Linked Resource

### Create

- **List · Required**: The task list. Pick one, or use its id from an earlier step.
- **Task · Required**: The task. Pick one of the list's tasks, or use its id from an earlier step.
- **Application Name · Required**: The app the link points into, shown on the task (such as Zendesk).
- **Title · Optional**: The linked item's title (such as the ticket's subject).
- **Link · Optional**: The address that opens the linked item. Optional: an item in a desktop or phone app may have none.
- **External ID · Optional**: The item's id in that app.

### Get and Delete

- **List · Required**: The task list. Pick one, or use its id from an earlier step.
- **Task · Required**: The task. Pick one of the list's tasks, or use its id from an earlier step.
- **Linked Resource ID · Required**: The linked resource's id (from Get Many or Create).

### Get Many

- **List · Required**: The task list. Pick one, or use its id from an earlier step.
- **Task · Required**: The task. Pick one of the list's tasks, or use its id from an earlier step.
- **Return All · Optional**: Read every linked resource, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many linked resources to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **List · Required**: The task list. Pick one, or use its id from an earlier step.
- **Task · Required**: The task. Pick one of the list's tasks, or use its id from an earlier step.
- **Linked Resource ID · Required**: The linked resource's id (from Get Many or Create).
- **Application Name · Optional**: A new application name. Leave empty to keep it.
- **Title · Optional**: The linked item's title (such as the ticket's subject).
- **Link · Optional**: The address that opens the linked item. Optional: an item in a desktop or phone app may have none.
- **External ID · Optional**: The item's id in that app.

### Microsoft To Do › Checklist Item (Step)

### Create

- **List · Required**: The task list. Pick one, or use its id from an earlier step.
- **Task · Required**: The task. Pick one of the list's tasks, or use its id from an earlier step.
- **Step · Required**: What the step says.
- **Checked · Optional**: Whether the step is ticked off. Empty: unticked on Create, unchanged on Update. Options: Checked, Not checked.

### Get and Delete

- **List · Required**: The task list. Pick one, or use its id from an earlier step.
- **Task · Required**: The task. Pick one of the list's tasks, or use its id from an earlier step.
- **Checklist Item ID · Required**: The step's id (from Get Many or Create).

### Get Many

- **List · Required**: The task list. Pick one, or use its id from an earlier step.
- **Task · Required**: The task. Pick one of the list's tasks, or use its id from an earlier step.
- **Return All · Optional**: Read every checklist item, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many checklist items to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **List · Required**: The task list. Pick one, or use its id from an earlier step.
- **Task · Required**: The task. Pick one of the list's tasks, or use its id from an earlier step.
- **Checklist Item ID · Required**: The step's id (from Get Many or Create).
- **Step · Optional**: New text for the step. Leave empty to keep it.
- **Checked · Optional**: Whether the step is ticked off. Empty: unticked on Create, unchanged on Update. Options: Checked, Not checked.

### Microsoft To Do › Attachment

### Add

- **List · Required**: The task list. Pick one, or use its id from an earlier step.
- **Task · Required**: The task. Pick one of the list's tasks, or use its id from an earlier step.
- **File · Required**: Upload a file, or switch to an expression to use one from an earlier step (such as {{steps.download.result}}). Under 3 MB (Microsoft's limit for attaching a file to a task).
- **File Name · Optional**: The name shown on the task. Empty: the file's own name.

### Get (Download) and Delete

- **List · Required**: The task list. Pick one, or use its id from an earlier step.
- **Task · Required**: The task. Pick one of the list's tasks, or use its id from an earlier step.
- **Attachment ID · Required**: The attachment's id (from Get Many or Add).

### Get Many

- **List · Required**: The task list. Pick one, or use its id from an earlier step.
- **Task · Required**: The task. Pick one of the list's tasks, or use its id from an earlier step.
- **Return All · Optional**: Read every attachment, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many attachments to return (1–2000). Default: 50. Shows when **Return All** is off.

Source: https://docs.gorunner.io/apps/microsoft-to-do