Using Get-MgGroupPlannerPlan in Graph PowerShell

Cmdlet Syntax

Get-MgGroupPlannerPlan -GroupId <String> [-ExpandProperty <String[]>] [-Property <String[]>]

• GroupId: Specifies the ID of the group whose Planner plans are to be retrieved.
• ExpandProperty: Expands related entities inline.
• Property: Selects specific properties to be returned.

Usage Examples

Retrieve All Planner Plans for a Group

This command retrieves all Planner plans associated with the specified group.

$groupId = "d7b14b9a-6d4b-4a1c-bd74-67c6c4aaf2ed"
Get-MgGroupPlannerPlan -GroupId $groupId

Retrieve Specific Properties of Planner Plans

This command retrieves the specified properties of all Planner plans associated with the specified group.

$groupId = "d7b14b9a-6d4b-4a1c-bd74-67c6c4aaf2ed"
Get-MgGroupPlannerPlan -GroupId $groupId -Property "id", "title", "owner"

Filter Plans by Title

This command retrieves all Planner plans for a group and filters them to return only those with titles containing "Project".

$groupId = "d7b14b9a-6d4b-4a1c-bd74-67c6c4aaf2ed"
$plans = Get-MgGroupPlannerPlan -GroupId $groupId
$filteredPlans = $plans | Where-Object { $_.title -like "*Project*" }
$filteredPlans

Export Planner Plans for a Group to CSV

Connect-MgGraph -Scopes "Group.Read.All", "Planner.Read.All"
$GroupId = "d7b14b9a-6d4b-4a1c-bd74-67c6c4aaf2ed"
$ExportPath = "C:\Reports\GroupPlannerPlans.csv"
Get-MgGroupPlannerPlan -GroupId $GroupId -Property "id,title,owner,createdDateTime" |
Select-Object Id, Title, Owner, CreatedDateTime |
Export-Csv -Path $ExportPath -NoTypeInformation
Write-Host "Planner plans exported to $ExportPath"

                    

What this script does

This script retrieves Planner plans associated with a specific Microsoft 365 Group and exports the plan details to a CSV file.

Why this example is useful

This is useful for documenting Planner usage, auditing group-linked plans, and preparing Planner inventory reports before migration, cleanup, or governance reviews.

Cmdlet Tips

• Permissions: Ensure you have the necessary permissions to access Planner plans. Typically, this requires Group.ReadWrite.All permissions.
• Property Selection: Use the -Property parameter to limit the properties returned and improve performance.
• Related Entities: To retrieve related entities such as buckets or tasks, use the appropriate cmdlets (e.g., Get-MgPlannerBucket, Get-MgPlannerTask) with the plan ID.

Use Cases

• Project Management: Retrieve all Planner plans for a team to monitor project progress and ensure tasks are on track.
• Reporting: Automate the generation of reports that include details about Planner plans.
• Integration: Integrate Planner plan retrieval into other automation scripts for a seamless workflow.

Frequently Asked Questions

• Can I retrieve all Planner plans across the organization?

Yes, you can loop through all Microsoft 365 Groups using Get-MgGroup and then call Get-MgGroupPlannerPlan for each group. This is useful for generating a tenant-wide Planner inventory report.

• Why does Get-MgGroupPlannerPlan return an empty result?

This usually occurs if the group doesn’t have any associated Planner plans or if the authenticated account lacks the required Group.Read.All or Group.ReadWrite.All permissions.

• How can I retrieve plan details such as title or owner directly?

Use the -ExpandProperty parameter with Get-MgGroupPlannerPlan to include nested details like the plan title, owner, and creation date in a single command.

• Can I export Planner plan details to a CSV file?

Absolutely. You can pipe the results to Select-Object to choose the properties you need, then export them using Export-Csv for easy reporting

• What permissions are required to use Get-MgGroupPlannerPlan?

You typically need Planner and group read permissions, such as:

Connect-MgGraph -Scopes "Group.Read.All", "Planner.Read.All"

Use write permissions only when your script needs to modify Planner or group data.

• Does Get-MgGroupPlannerPlan return tasks inside a plan?

No. Get-MgGroupPlannerPlan retrieves the Planner plans connected to a group. To retrieve tasks, first get the plan ID, then use task-related Planner cmdlets such as Get-MgPlannerTask.

Get-MgPlannerTask -Filter "planId eq 'PLAN-ID-HERE'"

Possible Errors & Solutions

# Example of retry logic
    $retryCount = 0
    $maxRetries = 5
    $groupId = "d7b14b9a-6d4b-4a1c-bd74-67c6c4aaf2ed"
    do {
    try {
       $plans = Get-MgGroupPlannerPlan -GroupId $groupId
       break
    } catch {
       $retryCount++
       Start-Sleep -Seconds ([math]::Pow(2, $retryCount))
    }
    } while ($retryCount -lt $maxRetries)
                                    
    if (-not $plans) {
        Write-Error "Failed to retrieve Planner plans after $maxRetries retries"
    }

Conclusion

The Get-MgGroupPlannerPlan cmdlet is a powerful tool for retrieving Microsoft Planner plans associated with a specific group using the Microsoft Graph PowerShell module. By understanding its syntax, parameters, and usage, you can effectively manage and automate tasks related to Planner plans. Remember to handle possible errors appropriately to ensure smooth execution of your scripts.

Additional Resources

Related Articles: