Using Get-MgUserManager with Set-MgUserManagerByRef: Manage Microsoft 365 User Managers

Managing reporting relationships in Microsoft 365 is essential for maintaining organizational efficiency. By pairing Get-MgUserManager and Set-MgUserManagerByRef, administrators can retrieve detailed information about a user’s manager and update it programmatically. This article provides an updated script and detailed guidance on how to use these cmdlets effectively.

The Get-MgUserManager cmdlet retrieves the Object ID of a user's manager, which can then be used with Get-MgUser to obtain detailed manager information. The Set-MgUserManagerByRef cmdlet allows administrators to update a user's manager by specifying the manager's Object ID in the required format. Together, these cmdlets streamline the process of managing reporting hierarchies in Microsoft 365.

Usage Example: Retrieving and Updating a User’s Manager

Here’s the updated script to retrieve detailed manager information and update it:


# Step 1: Retrieve the current manager's details for a user
$userId = "john.doe@company.com"  # Replace with the user's UPN or ObjectId

try {
    $managerId = (Get-MgUserManager -UserId $userId).Id
    if ($managerId) {
        # Fetch detailed manager information
        $manager = Get-MgUser -UserId $managerId -Property "Id, DisplayName, UserPrincipalName, Mail"
        Write-Output "Current Manager for $userId:"
        Write-Output "Manager ID: $($manager.Id)"
        Write-Output "Manager Display Name: $($manager.DisplayName)"
        Write-Output "Manager UPN: $($manager.UserPrincipalName)"
        Write-Output "Manager Email: $($manager.Mail)"
    } else {
        Write-Output "No manager assigned for $userId."
    }
} catch {
    Write-Error "Failed to retrieve manager details: $_"
}

# Step 2: Update the manager for the user
$newManagerId = "12345678-90ab-cdef-ghij-klmnopqrstuv"  # Replace with the new manager's Object ID
$managerReference = @{
    "@odata.id" = "https://graph.microsoft.com/v1.0/users/$newManagerId"
}

try {
    Set-MgUserManagerByRef -UserId $userId -BodyParameter $managerReference
    Write-Output "Manager updated successfully for $userId."
} catch {
    Write-Error "Failed to update manager: $_"
}

Cmdlet Tips

Retrieve Manager Details: Use Get-MgUser to fetch detailed information about the manager after obtaining the Object ID.

Assign Managers by UPN: Find the Object ID of a new manager using their UPN:

$newManager = Get-MgUser -Filter "userPrincipalName eq 'manager.name@company.com'"
$newManagerId = $newManager.Id

Format the Manager Reference Correctly: Ensure the @odata.id field uses the correct Graph API URL for the manager’s Object ID:
```
$managerReference = @{
    "@odata.id" = "https://graph.microsoft.com/v1.0/users/$newManagerId"
}
```

Bulk Updates: Update managers for multiple users in bulk:

$users = @("user1@company.com", "user2@company.com")
foreach ($user in $users) {
    Set-MgUserManagerByRef -UserId $user -BodyParameter $managerReference
}

Verify permissions: Ensure the account or app executing these commands has User.ReadWrite.All and Directory.ReadWrite.All permissions.

Use Cases

Onboarding New Employees: Assign managers to new hires automatically during their onboarding process based on their department or team.
Organizational Restructuring: Efficiently update managers during leadership changes or departmental reorganizations.
Auditing Reporting Structures: Retrieve and review current reporting hierarchies for compliance and accuracy.
Automating Workflows: Ensure accurate manager assignments to improve workflows in tools like Power Automate or Viva Insights.
Role-Based Access Management: Align reporting relationships to enforce role-based access controls (RBAC) for resources and applications.
Offboarding and Reassignments: Reassign direct reports of offboarded employees to a new manager to maintain operational continuity.

Possible Errors & Solutions

Error Message	Cause	Solution
Manager Not Found	No manager assigned or invalid user ID	Verify the user's ID and handle missing managers gracefully in your script.
Access Denied	Insufficient permissions	Assign `User.ReadWrite.All` and `Directory.ReadWrite.All` permissions.
Invalid DirectoryObjectId	Incorrect or non-existent manager Object ID	Verify the manager’s Object ID using `Get-MgUser`.
Too Many Requests	API throttling due to bulk updates	Implement a delay between requests or use batch processing for updates.
Invalid @odata.id	Incorrect format in `@odata.id`	Ensure the manager reference uses the correct URL format.

Conclusion

Pairing Get-MgUserManager and Set-MgUserManagerByRef provides administrators with a powerful way to manage user-manager relationships in Microsoft 365. By retrieving and updating manager assignments programmatically, you can streamline HR processes, ensure accurate reporting hierarchies, and enhance workflow efficiency across your organization.

This cmdlet combination simplifies organizational updates, ensuring seamless collaboration and compliance with changing business needs.