Ultimate Guide for Using Get-MgUserDirectReport Cmdlet

Managing user hierarchies within an organization is crucial for ensuring smooth workflows, effective delegation, and accurate reporting structures.

The Get-MgUserDirectReport cmdlet, part of the Microsoft Graph PowerShell module, allows administrators to retrieve a list of users who report to a specific manager. This guide will take you through its use, from setting up Graph PowerShell to practical examples and best practices.

Who Are Microsoft 365 User Direct Reports?

In Microsoft 365, direct reports are users who are assigned a manager within the organization’s directory. These reporting relationships are essential for:

• Workflows & Approvals: Automating leave approvals, project escalations, and other business processes.
• HR & Organizational Management: Keeping reporting structures up to date.
• Access Control: Implementing permissions based on hierarchies.

For example, if Sam Admin is the manager of three employees, these employees are his direct reports in Microsoft Entra ID (formerly Azure AD).

Why Use Get-MgUserDirectReport?

The Get-MgUserDirectReport cmdletsimplifies the process of retrieving direct reports for a given manager. It is useful for:

• AuditingEnsuring reporting structures are accurate.
• AutomationFetching user details for HR or IT workflows.
• IntegrationCombining with other cmdlets to create automated reports.

Instead of manually checking user details in the Microsoft 365 Admin Center, this cmdlet allows for efficient data retrieval through scripting.

Setting Up Microsoft Graph PowerShell

Before usingGet-MgUserDirectReport,you need to install and configure Microsoft Graph PowerShell.

1. Install the Module

Install Microsoft Graph PowerShell using the following command:

Install-Module Microsoft.Graph -Scope CurrentUser

2. Connect to Microsoft Graph

Establish a connection with the required permissions:

Connect-MgGraph -Scopes "User.Read.All"

Authenticate using admin credentials when prompted.

3. Disconnect After Use

Always disconnect your session after completing tasks to maintain security:

Disconnect-MgGraph

Exploring the Get-MgUserDirectReport Cmdlet

TheGet-MgUserDirectReport cmdletis used to retrieve a list of users who directly report to a specific user (i.e., their manager).

Cmdlet Syntax

Get-MgUserDirectReport -UserId <String> [<CommonParameters>]

• -UserId: The unique identifier (UPN or ObjectId) of the user whose direct reports you want to retrieve.

Practical Examples of Get-MgUserDirectReport

1. Retrieve Direct Reports of a Specific User

To get the direct reports of a user with User Principal Name (UPN) samadmin@7xh7fj.onmicrosoft.com:

Get-MgUserDirectReport -UserId samadmin@7xh7fj.onmicrosoft.com

This command will return a list of user IDs representing the employees who report to Sam Admin.

2. Retrieve Detailed Info of the Direct Reports of a Specific User

While Get-MgUserDirectReport only provides basic information (such as Object IDs), you can use it alongside Get-MgUser to fetch additional details:

# Retrieve the direct reports of the user

$directReports = Get-MgUserDirectReport -UserId "samadmin@7xh7fj.onmicrosoft.com"

# Check if any direct reports are returned
if ($directReports.Count -gt 0) {
# Loop through each direct report and retrieve full user details
$directReports | ForEach-Object {
$userId = $_.Id
                                                                        
$user = Get-MgUser -UserId $userId
[PSCustomObject]@{
DisplayName = $user.DisplayName
JobTitle = $user.JobTitle
}
} | Format-Table -AutoSize
} else {
Write-Host "No direct reports found for the specified user."
}

How This Script Works

1. Retrieves all direct reports of Sam Admin using Get-MgUserDirectReport.
2. Loops through each user ID and fetches their details (such asDisplay Name and Job Title ) using Get-MgUser.
3. Displays the results in a neatly formatted table.

Best Practices for Using Get-MgUserDirectReport

1. Verify User Accounts Before Querying

Ensure the specified user has direct reports configured in Microsoft 365. Use Get-MgUser to validate the user before running queries:

Get-MgUser -UserId "samadmin@7xh7fj.onmicrosoft.com"

2. Automate Reporting

The Get-MgUserDirectReport with Power Automate or scheduled PowerShell tasks to generate monthly or weekly reports.

3. Handle Errors Gracefully

Some users may not have direct reports. Use error handling to avoid script failures:

try {
$directReports = Get-MgUserDirectReport -UserId "samadmin@7xh7fj.onmicrosoft.com"
} catch {
Write-Host "Error retrieving direct reports: $_"
}

4. Use -WhatIf for Testing

Before running scripts on live environments, test them using -WhatIf:

Get-MgUserDirectReport -UserId "samadmin@7xh7fj.onmicrosoft.com" -WhatIf

Conclusion

The Get-MgUserDirectReport cmdletis an invaluable tool for Microsoft 365 administrators, enabling efficient retrieval of reporting structures. Whether you’re auditing manager relationships, generating organizational reports, or integrating data into workflows, this cmdlet simplifies the process.

By following best practices and combining Get-MgUserDirectReport with other Microsoft Graph PowerShell cmdlets, you can automate user hierarchy management and improve administrative efficiency.

Start using Get-MgUserDirectReporttoday to gain better visibility into your organization’s reporting structures!