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

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

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

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.

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

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.

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

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.

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 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

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.

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