PowerShell

How to Use Get-MgUserToDoList Cmdlet in Graph PowerShell

The Get-MgUserToDoList cmdlet in Microsoft Graph PowerShell enables you to retrieve Microsoft To Do lists associated with a specific user. This cmdlet is useful for administrators and developers who want to manage or report on users' task lists, providing insights into task management across the organization.

Syntax

Get-MgUserToDoList -UserId <String> [-Top <Int32>] [-Filter <String>]

UserId (Required): The UPN (User Principal Name) or object ID of the user whose To Do lists are to be retrieved.
Top (Optional): Specifies the number of items to return.
Filter (Optional): An OData expression to filter the lists based on properties.

Example Usage

Example 1: Retrieve All To Do Lists for a User

Get-MgUserToDoList -UserId "jane.doe@contoso.com"

This example retrieves all To Do lists for the user Jane Doe.

Example 2: Retrieve a Specific Number of To Do Lists

Get-MgUserToDoList -UserId "john.smith@contoso.com" -Top 5

This command returns the top 5 To Do lists for John Smith. It is particularly useful when there are many lists but only a subset is required for review.

Example 3: Filter To Do Lists Based on Name

Get-MgUserToDoList -UserId "sam.jones@contoso.com" -Filter "displayName eq 'Work Tasks'"

This example uses the -Filter parameter to return a list named "Work Tasks" for Sam Jones. Filtering can be useful when looking for a specific task list among many others.

Cmdlet Tips

Use the Filter Parameter to Narrow Results: Instead of pulling all lists for a user, apply filters to target specific lists based on properties like displayName.
Combine with Other Graph PowerShell Cmdlets: You can use Get-MgUserToDoTask in conjunction with this cmdlet to retrieve tasks within each list, enabling detailed reporting on task completion or pending actions.

Use Cases

Automating Task Management: By integrating Get-MgUserToDoList into workflows, administrators can pull task list data for users and automate processes such as task reporting, monitoring overdue tasks, or generating performance reviews based on completed lists.
Task List Auditing: Organizations may want to audit how effectively teams use Microsoft To Do for task management. The Get-MgUserToDoList cmdlet can extract all task lists, enabling management to track whether project-related tasks are being captured and followed.
Delegation of Tasks: Suppose a user is on leave or has transitioned roles. You can use the Get-MgUserToDoList cmdlet to retrieve their task lists and reassign tasks to other team members, ensuring continuity of work.

Possible Errors and Solutions

Error 1: "InvalidUserId"

Cause: This error occurs when the provided UserId is invalid or does not exist in the directory.

Solution: Ensure that the -UserId parameter is set to a valid UPN or object ID for a user in the organization.

Error 2: "Request_UnsupportedQuery"

Cause: This may happen if an invalid or unsupported filter query is used with the -Filter parameter.

Solution: Verify that the filter query uses valid OData expressions. Refer to Microsoft's OData query documentation for supported operators and syntax.

Error 3: "AccessDenied"

Cause: This error occurs when the user executing the cmdlet does not have permission to retrieve the To Do lists of the specified user.

Solution: Ensure that the executing account has the necessary permissions (e.g., delegated or application permissions like Tasks.Read).

Conclusion

The Get-MgUserToDoList cmdlet is a powerful tool for managing task lists within an organization, providing a programmatic way to audit, report, or automate task management processes. With filtering capabilities and integration with other Microsoft Graph PowerShell cmdlets, administrators can enhance the efficiency of task handling for users.

Additional Resources:

Graph PowerShell Get-MgUserToDoList Cmdlet Documentation
Microsoft Graph PowerShell Module Documentation
Microsoft Graph API Documentation

Using Get-MgDirectoryRole in Graph PowerShell
Using Get-MgUserLicenseDetail in Graph PowerShell
Using Find-GraphMgCommand in Graph PowerShell
Connect to Microsoft 365 Using PowerShell
How to Create Bulk Users in Office 365 Using Graph PowerShell?
Create Microsoft 365 Group Using Microsoft Graph PowerShell
Block Microsoft 365 User Using Microsoft Graph PowerShell
Assign Microsoft 365 License Using Graph PowerShell
Microsoft 365 User Management Using Graph PowerShell
Checking Group Membership in Microsoft 365
Bulk Assign Microsoft 365 License
Find Inactive Users in Microsoft 365
Using Powershell Graph Search Query
Using Powershell Graph Filter Query
Using Where-Object In Graph PowerShell
Using Expand Property In Graph PowerShell
Using Select Object In Graph PowerShell
Using -Contains Operator In Graph PowerShell
Add User to Multiple Microsoft 365 Groups Using Graph PowerShell
Get Microsoft 365 User Location Using Graph PowerShell
Import Microsoft 365 Groups from CSV File Using Graph PowerShell
Microsoft 365 Group User Import Using Graph PowerShell