> For the complete documentation index, see [llms.txt](https://docs.blockbrain.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockbrain.ai/for-admins/agents/ms-planner-agent.md). # MS Planner Agent This page provides configuration instructions for the MS Planner Agent, which enables integration with Microsoft Planner and Microsoft To Do for plans, buckets, tasks, and personal task lists
Cover image
Overview
  • Find plans, buckets, and tasks across the Microsoft 365 groups a user belongs to
  • Create, update, complete, and delete tasks, each one confirmed by the user first
  • Produce a deterministic plan progress summary with overdue, due soon, unassigned, and per-assignee workload
  • Apply the plan's own labels by the names users see, and attach reference links to a task
  • Manage personal Microsoft To Do tasks, the My Tasks side of the Planner app, on the same connection
Screenshot 2025-12-04 at 13.51.34.png
Prerequisites
  • Complete the general setup steps from the main AI Agents page
  • Ensure users have active Microsoft 365 accounts with Microsoft Planner enabled
  • Verify appropriate Microsoft 365 licensing for Microsoft Planner
  • Permissions to create and administer an Azure app registration in Microsoft Entra ID
  • An administrator able to grant tenant-wide consent, because one permission requires it
Screenshot 2025-12-04 at 13.51.48.png
{% hint style="info" %} **One agent covers two different Microsoft systems.** The Planner app shows plan tasks and a **My Tasks** view side by side, but those are separate products. Plan tasks live in Microsoft Planner. My Tasks and My Day are Microsoft To Do, which is a different API. The agent covers both, because that is what users see. Both run on the same connection and the same permissions, so there is no second connect step and no extra consent for users. {% endhint %} ### Azure App Registration Configuration #### Required API Permissions All permissions come from **Microsoft Graph**, and all are delegated. Add all eight to your app registration. | Permission | Type | Description | Admin consent | | ------------------------ | --------- | ------------------------------------------------------------ | ------------- | | `Group.Read.All` | Delegated | Read all groups | **Yes** | | `offline_access` | Delegated | Maintain access to data you have given it access to | No | | `Tasks.Read` | Delegated | Read user's tasks and task lists | No | | `Tasks.Read.Shared` | Delegated | Read user and shared tasks | No | | `Tasks.ReadWrite` | Delegated | Create, read, update, and delete user's tasks and task lists | No | | `Tasks.ReadWrite.Shared` | Delegated | Read and write user and shared tasks | No | | `User.Read` | Delegated | Sign in and read user profile | No | | `User.ReadBasic.All` | Delegated | Read all users' basic profiles | No | {% hint style="warning" %} **`Group.Read.All` requires admin consent.** It is the one permission on this list a user cannot consent to for themselves, so an administrator has to grant it for the organization before anyone can connect. The agent needs it because Planner plans are owned by Microsoft 365 groups. Without it the agent cannot find which plans a user has access to, and reading a task's comments stops working as well. {% endhint %} `Tasks.ReadWrite` covers Microsoft To Do as well as Planner, which is why personal tasks need no separate permission and no second connection. #### Redirect URL * Add `https://nango.theblockbrain.ai/oauth/callback` as an allowed redirect URL on your app registration #### Permission Configuration Steps 1. In your Azure app registration, go to **API permissions** 2. Click **"Add a permission"** > **Microsoft Graph** > **Delegated permissions** 3. Search for and select each of the eight permissions listed above 4. Click **"Add permissions"** 5. Click **"Grant admin consent"**. This is required, not optional, because of `Group.Read.All` 6. Confirm every row shows **Granted** before telling users to connect ### Agent Configuration in Blockbrain
#### Configuration Steps 1. **Access Agent Settings**: * Navigate to your Blockbrain admin panel * Go to **Agents** and open the **Connectors** tab * Find **Microsoft Planner** and open its **Tool Configuration** 2. **Enter Azure Credentials**: * **Client ID**: Enter the Application ID from your Azure app registration * **Client Secret**: Paste the client secret you generated (use the eye icon to toggle visibility) 3. **Configure OAuth Scopes**: * Add each of the four scopes individually using the **"Add"** button: * `offline_access` * `Tasks.ReadWrite` * `Group.Read.All` * `User.ReadBasic.All` * Each scope appears as a removable tag * Use the **"X"** button to remove any incorrect scopes 4. **Additional Configuration**: * Add one key-value pair, with the key `tenant` and your Azure tenant ID as the value * This is required, not optional. Without it the **Connect** button fails for every user 5. **Save Configuration**: * Click **"Save"** to apply all settings * Wait for the confirmation message {% hint style="info" %} **Four scopes here, eight permissions in Azure.** That is expected, not a mistake. The scope list is what Blockbrain requests when a user signs in, and it is deliberately the smaller set: these four are what the agent actually uses. An app registration can carry permissions that are never requested, which is why the two lists do not match. Leave the scope list at these four. `Tasks.Read` and `User.Read` are already covered by the read-write and basic-profile scopes above them, and the two `.Shared` permissions apply to task lists owned by other people, which this agent does not touch. Adding any of them only makes the consent screen longer. {% endhint %} ### Tool Permissions The Microsoft Planner connector exposes twenty-one tools. Because ten of them change or delete work in your users' plans, review their permission levels after enabling the connector. **Read-only tools**, safe to leave on **Always Allow**: | Tool | What it does | | ------------------------------------------ | ------------------------------------------------------------------------ | | **List Microsoft 365 Groups for Planner** | Finds the groups a user belongs to, to locate the group that owns a plan | | **List Planner Plans** | Lists a group's plans, or the plans shared with the user | | **List Planner Buckets** | Lists the buckets (task columns) of a plan | | **List Planner Tasks** | Lists tasks for one plan, bucket, or the user, with assignee names | | **Get Planner Task Details** | Reads one task with its description, checklist, and links | | **Get Planner Plan Summary** | Computes plan progress, overdue, due soon, unassigned, and workload | | **List Planner Labels** | Lists the label names a plan has defined | | **Read Planner Task Comments** | Reads the discussion on a task | | **Search Microsoft 365 Users for Planner** | Resolves people to user accounts so tasks can be assigned | | **List My Personal Task Lists** | Lists the user's Microsoft To Do lists | | **List My Personal Tasks** | Lists the personal tasks in one To Do list | **Write tools**, which all default to **Needs Approval**: | Tool | What it does | | -------------------------- | --------------------------------------------------------------- | | **Create Planner Task** | Creates a task in a plan | | **Update Planner Task** | Changes a task's fields, assignees, checklist, labels, or links | | **Complete Planner Task** | Marks a task complete | | **Delete Planner Task** | Deletes a task permanently | | **Create Planner Plan** | Creates a new plan owned by a Microsoft 365 group | | **Create Planner Bucket** | Creates a new bucket in a plan | | **Create Personal Task** | Creates a personal Microsoft To Do task | | **Update Personal Task** | Changes a personal task | | **Complete Personal Task** | Marks a personal task complete | | **Delete Personal Task** | Deletes a personal task permanently | We recommend leaving all ten write tools on **Needs Approval**. The agent is already instructed to restate the exact change and wait for the user to confirm before writing anything, so the approval prompt is a second, enforced checkpoint rather than a redundant one. See [Manage Tools & Connectors](/for-admins/manage-tools-and-connectors.md) for how to set these levels. Pay particular attention to **Delete Planner Task** and **Delete Personal Task**. Planner has no recycle bin, so a deleted task is gone. ### Testing the MS Planner Agent #### Verification Steps 1. **Authentication Test**: * Open a chat with the MS Planner Agent and complete the **Connect** flow * Verify the Microsoft sign-in completes and the connect card does not reappear 2. **Group and Plan Access**: * Ask the agent to list your plans * Verify the titles match what you see at `https://tasks.office.com` 3. **Task Reading**: * Ask what is open or overdue in one plan * Verify assignee names appear rather than raw account identifiers, which confirms `User.ReadBasic.All` is working 4. **Plan Summary**: * Ask how a plan is going * Verify you get totals, per-bucket progress, overdue and due soon tasks, and per-assignee workload 5. **Task Creation**: * Ask for a task in a named bucket with a due date and an assignee, then approve it * Open the plan in Planner and confirm the task, its bucket, and its assignee 6. **Personal Tasks**: * Ask the agent to list your personal task lists, then add a personal task * Confirm it appears in Microsoft To Do and in the Planner app's **My Tasks** view 7. **Comment Reading**: * Comment on a task in Planner, then ask the agent what was said * A task with no comments returns nothing, which is correct rather than an error ### Common MS Planner Integration Use Cases #### Status and Reporting * **Plan Status Summaries**: Ask how a plan is going and get totals, per-bucket progress, and what needs attention first * **Overdue Sweeps**: Find everything overdue across a plan without opening the board * **Workload Balance**: See who is carrying how much work, and what is sitting unassigned #### Task Operations * **Task Capture from Chat**: Turn a decision made in a conversation into a task in the right bucket, assigned and dated * **Bulk Tidying**: Re-bucket, re-assign, or re-date a batch of tasks through conversation * **Checklist Build-out**: Add checklist steps to a task without clicking through the board #### Planning * **New Workstreams**: Create a plan for a new piece of work and lay out its buckets * **Label Hygiene**: Apply the plan's own labels by name, so the board stays consistent * **Reference Links**: Attach the spec, the ticket, or the document to the task that needs it ### Capabilities and Limits #### Task status Planner stores progress as a percentage. The agent maps it the way the Planner UI does. | Value | Meaning | | ----------- | ----------- | | `0` | Not started | | `1` to `99` | In progress | | `100` | Completed | #### Labels * Every plan has **25 label slots**. Their names are set per plan, so the same slot can mean different things on two different boards * The agent reads a plan's label names before applying or filtering, so users can say "tag it Urgent" rather than naming a slot * A listing that spans plans, such as "my tasks", shows slot keys rather than names, because a name only resolves once the plan is known. The agent says so rather than guessing #### Ceilings | Limit | Value | | ------------------------------------- | ------ | | Tasks read per listing or summary | 500 | | Groups searched to find a plan | 500 | | Groups returned by a group listing | 50 | | Personal tasks read per list | 200 | | Checklist items added per call | 20 | | Assignees set per call | 10 | | Labels changed per call | 25 | | Reference links changed per call | 10 | | Comments returned for a task | 25 | | People returned by a user search | 25 | | Tasks named in a summary drill-down | 10 | | "Due soon" window used by the summary | 7 days | #### Not supported * **Posting comments.** The agent reads a task's discussion but cannot add to it. See the note under Security and Compliance for why * **Pinning a task to My Day.** Microsoft exposes no field for it. The agent sets the due date and tells the user to check My Day, rather than claiming it put the task there * **Moving a task between Planner and personal tasks.** They are separate systems, so a task has to be recreated * **Recurring tasks**, **Planner premium features** such as timeline and goals, and **uploading files as attachments**. Links to files work ### Troubleshooting #### Authentication Issues **Problem**: The connect card keeps reappearing after a successful Microsoft sign-in * **Solution**: Verify the redirect URL is exactly `https://nango.theblockbrain.ai/oauth/callback` * **Check**: Confirm the `tenant` key is set in **Additional Configuration** with your Azure tenant ID * **Verify**: Client secret has not expired and is entered correctly #### Sign-in Asks for Administrator Approval **Problem**: Users see a message that an administrator must approve the application * **Solution**: Grant admin consent for the organization in your app registration. `Group.Read.All` cannot be consented to by an individual user * **Check**: Every permission row shows **Granted** in **API permissions** * **Verify**: Consent was granted in the tenant the users actually sign in to #### No Plans Found **Problem**: The agent reports that a user has no plans, or cannot find a plan by name * **Solution**: Confirm the user is a member of the Microsoft 365 group that owns the plan. Planner access follows group membership, not sharing * **Check**: `Group.Read.All` is granted and consented. Without it the agent cannot enumerate a user's groups * **Verify**: The plan exists at `https://tasks.office.com` for that user #### Assignees Show as Identifiers **Problem**: Tasks list raw account identifiers instead of people's names * **Solution**: Confirm `User.ReadBasic.All` is granted and consented * **Check**: Have the user disconnect and reconnect, so the new permission is picked up * **Verify**: The assignee still has an active account in your tenant #### Changed Concurrently **Problem**: The agent reports that a task changed concurrently and asks the user to confirm again * **Solution**: This is working as intended. Someone edited the same task while the agent was writing, so the agent re-reads and shows the current state rather than overwriting * **Check**: Confirm the change once more and it will apply * **Verify**: If it repeats constantly on one plan, look for an automation editing the same tasks #### Personal Tasks Behave Differently **Problem**: A personal task cannot be assigned to someone, or moved into a plan * **Solution**: This is expected. Personal tasks are Microsoft To Do items that belong to one person and have no plan, bucket, or assignee * **Check**: If the user wants to hand work to someone else, it has to be a plan task * **Verify**: Users know which of the two they are looking at. The agent labels them separately ### Security and Compliance #### Data Protection * **Delegated Access**: The agent acts strictly as the signed-in user and can do only what that user can do. There is no organization-wide background access * **Attribution**: Every change is recorded against the user who approved it, exactly as if they made it at `https://tasks.office.com` * **Credential Handling**: Tokens are held in Blockbrain's secured OAuth vault. Blockbrain staff never see user passwords, and disconnecting revokes access immediately #### Compliance Considerations * **GDPR Compliance**: Plan and task data processing follows GDPR and other relevant data protection requirements * **Task Data**: Tasks stay in Microsoft Planner and Microsoft To Do. The agent reads them on request and does not keep its own copy * **Audit Logging**: All MS Planner Agent activity is logged for compliance and reporting purposes * **Concurrency Safety**: Changes are guarded with Microsoft's standard concurrency checks, so a simultaneous edit in Planner is never silently overwritten #### Access Control * **User Permissions**: The agent inherits the authenticated user's Planner permissions, which follow Microsoft 365 group membership * **Approval Gates**: All ten write tools require user approval by default, on top of the agent's own confirm-before-writing workflow * **Group Scope**: `Group.Read.All` lets the agent see which groups a user belongs to. It does not grant the agent the ability to change groups or their membership {% hint style="warning" %} **Why the agent cannot post comments.** Planner has no comment endpoint of its own. A task's comments are a conversation thread on the plan's Microsoft 365 group, so reading them is covered by the group-read permission you already grant. Posting one would require write access to group conversations, which also carries write access to group mail and membership. That is a much broader grant than task management needs, so it was deliberately left out. The agent tells the user and offers to record the note in the task description instead. If your organization wants the agent to post comments, raise it with your Blockbrain contact so the wider permission stays a decision you make knowingly. {% endhint %} ### Next Steps After successful MS Planner Agent configuration: * **Tool Permissions**: Review the permission levels on the ten write tools, and on the two delete tools in particular * **User Training**: Show users the confirm-before-writing workflow, and the difference between plan tasks and personal tasks * **Group Membership**: Confirm the users who need a plan are members of the group that owns it, since that is what governs access ### Support and Resources For assistance with MS Planner Agent configuration: * **Blockbrain Support**: Contact your Customer Success Manager for feature-specific help * **Microsoft Documentation**: Reference the Microsoft Entra ID documentation for delegated permission and consent details * **Azure AD Troubleshooting**: Use Microsoft Entra ID sign-in logs for authentication diagnostics --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.blockbrain.ai/for-admins/agents/ms-planner-agent.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.