M365 PowerShell

Using New-MgBookingBusinessStaffMember in Graph PowerShell

The New-MgBookingBusinessStaffMember cmdlet allows you to add staff members to a Microsoft Bookings business. This cmdlet is a powerful tool for managing the staff in your organization, enabling you to assign roles, set working hours, and decide whether or not to send email notifications to the staff members being added. In this article, we will explore the syntax, usage examples, tips, common errors, and practical use cases to make your implementation smoother.

Cmdlet Syntax

New-MgBookingBusinessStaffMember -BusinessId  -BodyParameter  []

-BusinessId: The unique identifier for the Microsoft Bookings business.
-BodyParameter: A hashtable containing the properties for the new staff member(s).

Usage Examples

Example 1: Adding a Single Staff Member

$staffMember = @{
    displayName = "John Doe"
    emailAddress = "john.doe@contoso.com"
    role = "administrator"
    isEmailNotificationEnabled = $false
    workingHours = @(
        @{
            day = "monday"
            timeSlots = @(
                @{
                    startTime = "09:00:00"
                    endTime = "17:00:00"
                }
            )
        }
        @{
            day = "wednesday"
            timeSlots = @(
                @{
                    startTime = "09:00:00"
                    endTime = "17:00:00"
                }
            )
        }
        @{
            day = "friday"
            timeSlots = @(
                @{
                    startTime = "09:00:00"
                    endTime = "17:00:00"
                }
            )
        }
    )
}

New-MgBookingBusinessStaffMember -BusinessId "your-business-id" -BodyParameter $staffMember

This command adds a single staff member as an administrator with simple working hours and no email notifications.

Example 2: Adding Multiple Staff Members

$staffMembers = @(
    @{
        displayName = "Jane Smith"
        emailAddress = "jane.smith@contoso.com"
        role = "scheduler"
        isEmailNotificationEnabled = $true
        workingHours = @(
            @{
                day = "tuesday"
                timeSlots = @(
                    @{
                        startTime = "10:00:00"
                        endTime = "18:00:00"
                    }
                )
            }
            @{
                day = "thursday"
                timeSlots = @(
                    @{
                        startTime = "10:00:00"
                        endTime = "18:00:00"
                    }
                )
            }
        )
    }
    @{
        displayName = "Mark Taylor"
        emailAddress = "mark.taylor@contoso.com"
        role = "viewer"
        isEmailNotificationEnabled = $false
        workingHours = @(
            @{
                day = "monday"
                timeSlots = @(
                    @{
                        startTime = "09:00:00"
                        endTime = "17:00:00"
                    }
                )
            }
            @{
                day = "wednesday"
                timeSlots = @(
                    @{
                        startTime = "09:00:00"
                        endTime = "17:00:00"
                    }
                )
            }
        )
    }
)

New-MgBookingBusinessStaffMember -BusinessId "your-business-id" -BodyParameter $staffMembers

You can also add multiple staff members in a single command by passing an array of staff member objects.

Example 3: Bulk Import Staff Members from a CSV

For larger organizations, you might want to add staff members in bulk from a CSV file. Here’s how you can do it.

CSV Structure:

displayName,emailAddress,role,isEmailNotificationEnabled,workingHours
Alice Green,alice.green@contoso.com,guest,false,"monday:09:00-17:00,friday:09:00-17:00"
Bob Brown,bob.brown@contoso.com,administrator,true,"tuesday:08:00-16:00,thursday:08:00-16:00"

PowerShell Script:

$csvData = Import-Csv -Path "C:\path\to\staffMembers.csv"
$staffMembers = @()

foreach ($row in $csvData) {
    $workingHoursArray = @()
    $workingHours = $row.workingHours -split ","
    
    foreach ($slot in $workingHours) {
        $day, $times = $slot -split ":"
        $startTime, $endTime = $times -split "-"
        $workingHoursArray += @{
            day = $day
            timeSlots = @(
                @{
                    startTime = $startTime
                    endTime = $endTime
                }
            )
        }
    }
    
    $staffMembers += @{
        displayName = $row.displayName
        emailAddress = $row.emailAddress
        role = $row.role
        isEmailNotificationEnabled = [bool]::Parse($row.isEmailNotificationEnabled)
        workingHours = $workingHoursArray
    }
}

New-MgBookingBusinessStaffMember -BusinessId "your-business-id" -BodyParameter $staffMembers

Cmdlet Tips

Role Assignment: Assign roles based on the staff member's responsibilities. For example, an administrator has full control, a scheduler manages bookings, a viewer can only see appointments, and a guest is typically an external member with limited access.
Email Notifications: The isEmailNotificationEnabled flag controls whether an email is sent to the staff member. Use $false to suppress notifications if you need to silently add members.
Working Hours: Simplify the working hours to avoid confusion. Use a maximum of three days to make the script manageable.

Common Errors & Solutions

Error: "Invalid role value"

Cause: The role value provided does not match the acceptable values.

Solution: Ensure the role is one of the following: "administrator", "scheduler", "viewer", "guest".

Error: "The request is malformed"

Cause: The -BodyParameter hashtable is not properly formatted.

Solution: Double-check the structure of your hashtable, ensuring all properties follow the conventions laid out in the Microsoft documentation.

Error: "Invalid time format"

Cause: The time format in working hours is incorrect.

Solution: Use the 24-hour time format (e.g., "09:00:00" for 9 AM and "17:00:00" for 5 PM).

Use Cases

Onboarding New Staff: When onboarding new employees, you can use this cmdlet to quickly add them to the Microsoft Bookings business, assigning appropriate roles and working hours.
Seasonal Staff Management: For businesses that hire temporary or seasonal staff, this cmdlet allows easy addition and removal of staff members, streamlining the management process.
Bulk Updates: If you need to make bulk updates to your staff, such as during a reorganization or departmental shift, the bulk import option via CSV simplifies the process, reducing manual work.

Conclusion

The New-MgBookingBusinessStaffMember cmdlet is a versatile tool for managing staff in Microsoft Bookings. By following the conventions for constructing the -BodyParameter, you can avoid common pitfalls and ensure your staff members are added smoothly. Whether you're adding a single staff member or importing them in bulk, this cmdlet provides the flexibility needed to efficiently manage your organization’s booking staff.

Additional Resources:

Graph PowerShell New-MgBookingBusinessStaffMember 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