# Microsoft Planner (/integrations/microsoft_planner)





{/* MANUAL-CONTENT-START:intro */}

Use [Microsoft Planner](https://www.microsoft.com/en-us/microsoft-365/planner) to manage tasks, plans, and buckets. Task details include checklists and references; use the actions below to read or update them.

{/* MANUAL-CONTENT-END */}

## OAuth scopes [#oauth-scopes]

Sim requests these scopes when someone connects a Microsoft Planner account. For a self-hosted deployment, register your own app with the provider using the settings below. See [Integrations and OAuth](/platform/self-hosting/integrations-oauth) for setup.

| Setting | Value |
| - | - |
| Redirect URI | `<NEXT_PUBLIC_APP_URL>/api/auth/oauth2/callback/microsoft-planner` |
| Environment variables | `MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET` |

| Scope | Description |
| - | - |
| `openid` | Standard authentication |
| `profile` | Access profile information |
| `email` | Access email address |
| `Group.ReadWrite.All` | Read and write all groups |
| `Group.Read.All` | Read all groups, memberships, and group content |
| `Tasks.ReadWrite` | Read and manage Planner tasks |
| `offline_access` | Access account when not using the application |

## Use the block [#usage-instructions]

Manage tasks, plans, buckets, and task details including checklists and references.

## Actions [#actions]

### Read Microsoft Planner Tasks [#read-microsoft-planner-tasks]

Read tasks from Microsoft Planner - get all user tasks or all tasks from a specific plan

<ReferenceDetails>
  #### Input [#input]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `planId` | string | No | The ID of the plan to get tasks from, if not provided gets all user tasks (e.g., "xqQg5FS2LkCe54tAMV\_v2ZgADW2J") |
  | `taskId` | string | No | The ID of the task to get (e.g., "pbT5K2OVkkO1M7r5bfsJ6JgAGD5m") |

  #### Output [#output]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether tasks were retrieved successfully |
  | `tasks` | array | Array of task objects with filtered properties |
  | `metadata` | object | Metadata including planId, userId, and planUrl |
  | ↳ `planId` | string | Plan ID |
  | ↳ `userId` | string | User ID |
  | ↳ `planUrl` | string | Microsoft Graph API URL for the plan |
</ReferenceDetails>

### Create Microsoft Planner Task [#create-microsoft-planner-task]

Create a new task in Microsoft Planner

<ReferenceDetails>
  #### Input [#input-1]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `planId` | string | Yes | The ID of the plan where the task will be created (e.g., "xqQg5FS2LkCe54tAMV\_v2ZgADW2J") |
  | `title` | string | Yes | The title of the task (e.g., "Review quarterly report") |
  | `dueDateTime` | string | No | The due date and time for the task in ISO 8601 format (e.g., "2025-03-15T17:00:00Z") |
  | `startDateTime` | string | No | The start date and time for the task in ISO 8601 format (e.g., "2025-03-10T09:00:00Z") |
  | `priority` | number | No | The priority of the task (0-10, where 0 is urgent and 10 is low) |
  | `percentComplete` | number | No | The percentage of task completion (0-100) |
  | `assigneeUserId` | string | No | The user ID to assign the task to (e.g., "e82f74c3-4d8a-4b5c-9f1e-2a6b8c9d0e3f") |
  | `bucketId` | string | No | The bucket ID to place the task in (e.g., "hsOf2dhOJkC6Fey9VjDg1JgAC9Rq") |
  | `appliedCategories` | string | No | Comma-separated category labels to apply to the task, e.g. "category1,category3" (up to category1-category25, plan-defined color labels) |

  #### Output [#output-1]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether the task was created successfully |
  | `task` | object | The created task object with all properties |
  | `metadata` | object | Metadata including planId, taskId, and taskUrl |
  | ↳ `planId` | string | Parent plan ID |
  | ↳ `taskId` | string | Created task ID |
  | ↳ `taskUrl` | string | Microsoft Graph API URL for the task |
</ReferenceDetails>

### Update Microsoft Planner Task [#update-microsoft-planner-task]

Update a task in Microsoft Planner

<ReferenceDetails>
  #### Input [#input-2]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `taskId` | string | Yes | The ID of the task to update (e.g., "pbT5K2OVkkO1M7r5bfsJ6JgAGD5m") |
  | `etag` | string | Yes | The ETag value from the task to update (If-Match header) |
  | `title` | string | No | The new title of the task (e.g., "Review quarterly report") |
  | `bucketId` | string | No | The bucket ID to move the task to (e.g., "hsOf2dhOJkC6Fey9VjDg1JgAC9Rq") |
  | `dueDateTime` | string | No | The due date and time for the task in ISO 8601 format (e.g., "2025-03-15T17:00:00Z") |
  | `startDateTime` | string | No | The start date and time for the task (ISO 8601 format) |
  | `percentComplete` | number | No | The percentage of task completion (0-100) |
  | `priority` | number | No | The priority of the task (0-10) |
  | `assigneeUserId` | string | No | The user ID to assign the task to (e.g., "e82f74c3-4d8a-4b5c-9f1e-2a6b8c9d0e3f") |
  | `appliedCategories` | string | No | Comma-separated category labels to apply to the task, e.g. "category1,category3" (up to category1-category25, plan-defined color labels) |

  #### Output [#output-2]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether the task was updated successfully |
  | `message` | string | Success message when task is updated |
  | `task` | object | The updated task object with all properties |
  | `taskId` | string | ID of the updated task |
  | `etag` | string | New ETag after update - use this for subsequent operations |
  | `metadata` | object | Metadata including taskId, planId, and taskUrl |
  | ↳ `taskId` | string | Updated task ID |
  | ↳ `planId` | string | Parent plan ID |
  | ↳ `taskUrl` | string | Microsoft Graph API URL for the task |
</ReferenceDetails>

### Delete Microsoft Planner Task [#delete-microsoft-planner-task]

Delete a task from Microsoft Planner

<ReferenceDetails>
  #### Input [#input-3]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `taskId` | string | Yes | The ID of the task to delete (e.g., "pbT5K2OVkkO1M7r5bfsJ6JgAGD5m") |
  | `etag` | string | Yes | The ETag value from the task to delete (If-Match header) |

  #### Output [#output-3]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether the task was deleted successfully |
  | `deleted` | boolean | Confirmation of deletion |
  | `metadata` | object | Additional metadata |
</ReferenceDetails>

### List Microsoft Planner Plans [#list-microsoft-planner-plans]

List all plans shared with the current user

<ReferenceDetails>
  #### Input [#input-4]

  | Parameter | Type | Required | Description |
  | - | - | - | - |

  #### Output [#output-4]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether plans were retrieved successfully |
  | `plans` | array | Array of plan objects shared with the current user |
  | `metadata` | object | Metadata including userId and count |
  | ↳ `count` | number | Number of plans returned |
  | ↳ `userId` | string | User ID |
</ReferenceDetails>

### Read Microsoft Planner Plan [#read-microsoft-planner-plan]

Get details of a specific Microsoft Planner plan

<ReferenceDetails>
  #### Input [#input-5]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `planId` | string | Yes | The ID of the plan to retrieve (e.g., "xqQg5FS2LkCe54tAMV\_v2ZgADW2J") |

  #### Output [#output-5]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether the plan was retrieved successfully |
  | `plan` | object | The plan object with all properties |
  | `metadata` | object | Metadata including planId and planUrl |
  | ↳ `planId` | string | Plan ID |
  | ↳ `planUrl` | string | Microsoft Graph API URL for the plan |
</ReferenceDetails>

### Create Microsoft Planner Plan [#create-microsoft-planner-plan]

Create a new Microsoft Planner plan owned by a Microsoft 365 group

<ReferenceDetails>
  #### Input [#input-6]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `groupId` | string | Yes | The ID of the Microsoft 365 group that will own the plan (e.g., "ebf3b108-5234-4e22-b93d-656d7dae5874"). The current user must be a member of this group. |
  | `title` | string | Yes | The title of the plan |

  #### Output [#output-6]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether the plan was created successfully |
  | `plan` | object | The created plan object with all properties |
  | `metadata` | object | Metadata including planId and groupId |
  | ↳ `planId` | string | Created plan ID |
  | ↳ `groupId` | string | Owning Microsoft 365 group ID |
</ReferenceDetails>

### Update Microsoft Planner Plan [#update-microsoft-planner-plan]

Rename a Microsoft Planner plan

<ReferenceDetails>
  #### Input [#input-7]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `planId` | string | Yes | The ID of the plan to update (e.g., "xqQg5FS2LkCe54tAMV\_v2ZgADW2J") |
  | `etag` | string | Yes | The ETag value from the plan to update (If-Match header) |
  | `title` | string | Yes | The new title of the plan |

  #### Output [#output-7]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether the plan was updated successfully |
  | `plan` | object | The updated plan object with all properties |
  | `metadata` | object | Metadata including planId |
  | ↳ `planId` | string | Updated plan ID |
</ReferenceDetails>

### Get Microsoft Planner Plan Details [#get-microsoft-planner-plan-details]

Get detailed information about a plan including category descriptions and sharing

<ReferenceDetails>
  #### Input [#input-8]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `planId` | string | Yes | The ID of the plan (e.g., "xqQg5FS2LkCe54tAMV\_v2ZgADW2J") |

  #### Output [#output-8]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether the plan details were retrieved successfully |
  | `planDetails` | object | The plan details including categoryDescriptions and sharedWith |
  | `etag` | string | The ETag value for this plan details resource |
  | `metadata` | object | Metadata including planId |
  | ↳ `planId` | string | Plan ID |
</ReferenceDetails>

### Update Microsoft Planner Plan Details [#update-microsoft-planner-plan-details]

Update a plan's category (color label) descriptions and shared-with user list in Microsoft Planner

<ReferenceDetails>
  #### Input [#input-9]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `planId` | string | Yes | The ID of the plan (e.g., "xqQg5FS2LkCe54tAMV\_v2ZgADW2J") |
  | `etag` | string | Yes | The ETag value from the plan details to update (If-Match header) |
  | `categoryDescriptions` | object | No | Category label names as a JSON object, e.g. \{"category1": "Blocked", "category2": "At Risk"}. Set a value to null to clear a label. |
  | `sharedWith` | object | No | User IDs to share the plan with as a JSON object, e.g. \{"\<user-id>": true}. Set a value to false to unshare. |

  #### Output [#output-9]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether the plan details were updated successfully |
  | `planDetails` | object | The updated plan details object with categoryDescriptions and sharedWith |
  | `metadata` | object | Metadata including planId |
  | ↳ `planId` | string | Plan ID |
</ReferenceDetails>

### Delete Microsoft Planner Plan [#delete-microsoft-planner-plan]

Delete a Microsoft Planner plan

<ReferenceDetails>
  #### Input [#input-10]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `planId` | string | Yes | The ID of the plan to delete (e.g., "xqQg5FS2LkCe54tAMV\_v2ZgADW2J") |
  | `etag` | string | Yes | The ETag value from the plan to delete (If-Match header) |

  #### Output [#output-10]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether the plan was deleted successfully |
  | `deleted` | boolean | Confirmation of deletion |
  | `metadata` | object | Additional metadata |
</ReferenceDetails>

### List Microsoft Planner Buckets [#list-microsoft-planner-buckets]

List all buckets in a Microsoft Planner plan

<ReferenceDetails>
  #### Input [#input-11]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `planId` | string | Yes | The ID of the plan (e.g., "xqQg5FS2LkCe54tAMV\_v2ZgADW2J") |

  #### Output [#output-11]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether buckets were retrieved successfully |
  | `buckets` | array | Array of bucket objects |
  | `metadata` | object | Metadata including planId and count |
  | ↳ `planId` | string | Plan ID |
  | ↳ `count` | number | Number of buckets returned |
</ReferenceDetails>

### Read Microsoft Planner Bucket [#read-microsoft-planner-bucket]

Get details of a specific bucket

<ReferenceDetails>
  #### Input [#input-12]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `bucketId` | string | Yes | The ID of the bucket to retrieve (e.g., "hsOf2dhOJkC6Fey9VjDg1JgAC9Rq") |

  #### Output [#output-12]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether the bucket was retrieved successfully |
  | `bucket` | object | The bucket object with all properties |
  | `metadata` | object | Metadata including bucketId and planId |
  | ↳ `bucketId` | string | Bucket ID |
  | ↳ `planId` | string | Parent plan ID |
</ReferenceDetails>

### Create Microsoft Planner Bucket [#create-microsoft-planner-bucket]

Create a new bucket in a Microsoft Planner plan

<ReferenceDetails>
  #### Input [#input-13]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `planId` | string | Yes | The ID of the plan where the bucket will be created (e.g., "xqQg5FS2LkCe54tAMV\_v2ZgADW2J") |
  | `name` | string | Yes | The name of the bucket |

  #### Output [#output-13]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether the bucket was created successfully |
  | `bucket` | object | The created bucket object with all properties |
  | `metadata` | object | Metadata including bucketId and planId |
  | ↳ `bucketId` | string | Created bucket ID |
  | ↳ `planId` | string | Parent plan ID |
</ReferenceDetails>

### Update Microsoft Planner Bucket [#update-microsoft-planner-bucket]

Update a bucket in Microsoft Planner

<ReferenceDetails>
  #### Input [#input-14]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `bucketId` | string | Yes | The ID of the bucket to update (e.g., "hsOf2dhOJkC6Fey9VjDg1JgAC9Rq") |
  | `name` | string | No | The new name of the bucket |
  | `etag` | string | Yes | The ETag value from the bucket to update (If-Match header) |

  #### Output [#output-14]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether the bucket was updated successfully |
  | `bucket` | object | The updated bucket object with all properties |
  | `metadata` | object | Metadata including bucketId and planId |
  | ↳ `bucketId` | string | Updated bucket ID |
  | ↳ `planId` | string | Parent plan ID |
</ReferenceDetails>

### Delete Microsoft Planner Bucket [#delete-microsoft-planner-bucket]

Delete a bucket from Microsoft Planner

<ReferenceDetails>
  #### Input [#input-15]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `bucketId` | string | Yes | The ID of the bucket to delete (e.g., "hsOf2dhOJkC6Fey9VjDg1JgAC9Rq") |
  | `etag` | string | Yes | The ETag value from the bucket to delete (If-Match header) |

  #### Output [#output-15]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether the bucket was deleted successfully |
  | `deleted` | boolean | Confirmation of deletion |
  | `metadata` | object | Additional metadata |
</ReferenceDetails>

### Get Microsoft Planner Task Details [#get-microsoft-planner-task-details]

Get detailed information about a task including checklist and references

<ReferenceDetails>
  #### Input [#input-16]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `taskId` | string | Yes | The ID of the task (e.g., "pbT5K2OVkkO1M7r5bfsJ6JgAGD5m") |

  #### Output [#output-16]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether the task details were retrieved successfully |
  | `taskDetails` | object | The task details including description, checklist, and references |
  | `etag` | string | The ETag value for this task details - use this for update operations |
  | `metadata` | object | Metadata including taskId |
  | ↳ `taskId` | string | Task ID |
</ReferenceDetails>

### Update Microsoft Planner Task Details [#update-microsoft-planner-task-details]

Update task details including description, checklist items, and references in Microsoft Planner

<ReferenceDetails>
  #### Input [#input-17]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `taskId` | string | Yes | The ID of the task (e.g., "pbT5K2OVkkO1M7r5bfsJ6JgAGD5m") |
  | `etag` | string | Yes | The ETag value from the task details to update (If-Match header) |
  | `description` | string | No | The description of the task |
  | `checklist` | object | No | Checklist items as a JSON object |
  | `references` | object | No | References as a JSON object |
  | `previewType` | string | No | Preview type: automatic, noPreview, checklist, description, or reference |

  #### Output [#output-17]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether the task details were updated successfully |
  | `taskDetails` | object | The updated task details object with all properties |
  | `metadata` | object | Metadata including taskId |
  | ↳ `taskId` | string | Task ID |
</ReferenceDetails>