Set-MgUserManagerByRef: How to Assign or Update Managers for Microsoft 365 Users

This guide explains how to use the Set-MgUserManagerByRef cmdlet in Microsoft Graph PowerShell to assign or update a manager for a user. Learn how to link a user to a manager with practical examples for single and bulk operations

Managing user relationships is crucial in Microsoft 365 (M365) environments. Assigning a manager to a user account can streamline workflows, enhance reporting, and improve organizational hierarchy tracking. The Set-MgUserManagerByRef cmdlet in Microsoft Graph PowerShell allows administrators to set or update the manager for a user. This article will guide you through the cmdlet's syntax, provide real-world usage examples, offer tips, outline common errors with solutions, and conclude with practical use cases.

Cmdlet Syntax

Set-MgUserManagerByRef -UserId <String> -BodyParameter <Hashtable>

• UserId: The ID or user principal name (UPN) of the user whose manager you're setting.
• BodyParameter: A hashtable containing the manager's information. The manager is identified by the directory object URL format.

Usage Examples

Example 1: Assign a Single Manager to a User

This example assigns a manager to a single user by specifying the UserId and manager-id.

$Manager = @{
    "@odata.id" = "https://graph.microsoft.com/v1.0/users/12345678-90ab-cdef-ghij-klmnopqrstuv"
}
Set-MgUserManagerByRef -UserId "john.doe@company.com" -BodyParameter $Manager

Example 2: Assign Managers to Multiple Users

In this scenario, we loop through multiple users and assign a manager using the Set-MgUserManagerByRef cmdlet.

$Manager = @{
    "@odata.id" = "https://graph.microsoft.com/v1.0/users/87654321-abcd-efgh-ijkl-mnopqrstuvwx"
}
$Users = @("user1@company.com", "user2@company.com", "user3@company.com")

foreach ($User in $Users) {
    Set-MgUserManagerByRef -UserId $User -BodyParameter $Manager
}

Example 3: Assign Managers via CSV Import

This example shows how to assign managers to users by importing the user details from a CSV file. The CSV should contain columns for UserPrincipalName and ManagerId.

CSV File Format

    UserPrincipalName,ManagerId
    user1@company.com,manager1-id
    user2@company.com,manager2-id

$CSVPath = "C:\\Managers.csv"
$Users = Import-Csv -Path $CSVPath

foreach ($User in $Users) {
    $Manager = @{
        "@odata.id" = "https://graph.microsoft.com/v1.0/users/$($User.ManagerId)"
    }
    Set-MgUserManagerByRef -UserId $User.UserPrincipalName -BodyParameter $Manager
}

Cmdlet Tips

• BodyParameter Formatting: Ensure the manager information is passed in the correct format as shown in the examples.The @odata.id key should be used to specify the manager, with the value being the URL path that includes the manager's object ID.
• Assigning the Same Manager: You can use a loop to assign the same manager to multiple users by creating a hashtable and passing it to the -BodyParameter for each user.
• CSV for Bulk Assignments: Using a CSV file is highly effective for bulk assignments, especially in larger organizations.

Use Cases

• Organizational Hierarchy Setup: Administrators often need to set up organizational hierarchies when onboarding users or when there are departmental changes. The Set-MgUserManagerByRef cmdlet allows admins to easily assign or update managers for users, ensuring that reporting structures remain accurate in the Microsoft 365 environment.
• Bulk Manager Assignments: When organizations merge or restructure, there is often a need to reassign managers to large numbers of users. Using the CSV import example, administrators can efficiently update managers for hundreds or thousands of users.
• Automating Onboarding Processes: Automating user provisioning processes is essential for efficient onboarding. As part of onboarding, new hires can automatically be assigned managers based on their department or role, streamlining the workflow.

Possible Errors and Solutions

Error 1: "Request_BadRequest: The reference to the manager is invalid."

Cause: This error occurs when the manager’s UserId is invalid or formatted incorrectly in the hashtable.

Solution: Double-check the manager-id in the @odata.id field to ensure it points to the correct directory object. Confirm the manager exists in your tenant.

Error 2: "User not found."

Cause: This occurs when the UserId provided for the target user is incorrect.

Solution: Ensure that the user principal name or user ID is correctly specified in the -UserId parameter. Use Get-MgUser to verify the user exists.

Frequently Asked Questions

1. What is Set-MgUserManagerByRef used for?

Set-MgUserManagerByRef is a Microsoft Graph PowerShell cmdlet used to assign or update the manager property for a user in Azure AD.

2. How can I assign a manager to a user?

Use the following script to set a manager for a user:

$Body = @{
    "@odata.id" = "https://graph.microsoft.com/v1.0/users/<ManagerObjectId>"
}
Set-MgUserManagerByRef -UserId "<UserObjectId>" -BodyParameter $Body

3. How can I verify if a manager is set for a user?

Use the Get-MgUserManager cmdlet to verify the manager:

Get-MgUserManager -UserId "<UserObjectId>"

4. What permissions are required to use Set-MgUserManagerByRef?

You need the User.ReadWrite.All or Directory.ReadWrite.All permission in Microsoft Graph PowerShell. Ensure appropriate permissions are granted in Azure AD.

Conclusion

The Set-MgUserManagerByRef cmdlet is a powerful tool for managing user-manager relationships in Microsoft 365. By properly formatting the BodyParameter and utilizing CSV imports for bulk assignments, administrators can efficiently manage organizational hierarchies. Whether you are setting managers for a few users or updating relationships across the organization, this cmdlet helps simplify the process.