Using New-MgUserEvent in Graph PowerShell

This guide explains how to use the New-MgUserEvent cmdlet in Microsoft Graph PowerShell to create calendar events for a user. Learn how to schedule meetings and include attendees with practical examples.

The New-MgUserEvent cmdlet allows you to create calendar events for a specific user in Microsoft 365. You can schedule various events from simple offline meetings to virtual meetings hosted via Microsoft Teams. The cmdlet leverages the -BodyParameter for inputting event details in a hashtable format. Following Microsoft's documentation conventions for this hashtable is crucial to avoid running into errors.

Cmdlet Syntax

New-MgUserEvent -UserId <String> -BodyParameter <Hashtable>

• UserId: The unique identifier or user principal name (UPN) of the user for whom you are creating the event.
• BodyParameter: A hashtable that contains all details of the event such as subject, start time, end time, location, and attendees.

Usage Examples

1. Creating an Offline Meeting

This example demonstrates how to create an offline meeting, specifying a physical location and inviting attendees.

$params = @{
    subject = "Team Sync-up Meeting"
    start = @{
        dateTime = "2024-09-10T10:00:00"
        timeZone = "Pacific Standard Time"
    }
    end = @{
        dateTime = "2024-09-10T11:00:00"
        timeZone = "Pacific Standard Time"
    }
    location = @{
        displayName = "Conference Room A"
    }
    attendees = @(
        @{
            emailAddress = @{
                address = "john.doe@contoso.com"
                name = "John Doe"
            }
            type = "required"
        }
        @{
            emailAddress = @{
                address = "jane.smith@contoso.com"
                name = "Jane Smith"
            }
            type = "required"
        }
    )
}

New-MgUserEvent -UserId "alex.wilson@contoso.com" -BodyParameter $params

2. Creating an Online Meeting with Microsoft Teams

This example sets up a virtual meeting, automatically generating an online Microsoft Teams link.

$params = @{
    subject = "Project Kick-off Meeting"
    start = @{
        dateTime = "2024-09-15T14:00:00"
        timeZone = "Eastern Standard Time"
    }
    end = @{
        dateTime = "2024-09-15T15:30:00"
        timeZone = "Eastern Standard Time"
    }
    isOnlineMeeting = $true
    onlineMeetingProvider = "teamsForBusiness"
    attendees = @(
        @{
            emailAddress = @{
                address = "sarah.lee@contoso.com"
                name = "Sarah Lee"
            }
            type = "required"
        }
    )
}

New-MgUserEvent -UserId "michael.king@contoso.com" -BodyParameter $params

Cmdlet Tips

• Adhere to Hashtable Conventions: The BodyParameter requires precise formatting, especially for dateTime, attendees, and location fields. Improper formatting may cause errors, so ensure consistency with Microsoft's documentation.
• Time Zone Sensitivity: Always specify the correct time zone to avoid scheduling issues across regions. If no time zone is specified, the system defaults to the user's configured time zone.
• Online Meeting Provider: To schedule an online meeting, the onlineMeetingProvider field should be set to "teamsForBusiness" for Microsoft Teams. Make sure isOnlineMeeting = $true is also included.

Possible Errors & Solutions

Error: Invalid Start/End Date Format

Cause: The date and time format provided for the start or end field may be incorrect.

Solution: Ensure that the date is in the correct ISO 8601 format (e.g., "2024-09-10T10:00:00") and that the time zone is specified accurately. Example:

start = @{
    dateTime = "2024-09-10T10:00:00"
    timeZone = "Pacific Standard Time"
}

Error: Online Meeting Not Created

Cause: The onlineMeetingProvider field is either missing or incorrectly set.

Solution: Ensure that isOnlineMeeting = $true is set and that the correct value for onlineMeetingProvider is used. For Microsoft Teams, it should be "teamsForBusiness".

isOnlineMeeting = $true
onlineMeetingProvider = "teamsForBusiness"

Use Cases

• Team Meetings: Schedule regular offline or online meetings, manage attendees, and define specific time zones for cross-regional teams.
• Project Planning: For project kick-offs, create recurring meetings with predefined time slots and meeting invites.
• Calendar Management: Automate the process of scheduling meetings on behalf of users within your organization, reducing manual scheduling overhead.
• Syncing with External Partners: Invite external partners by email, ensuring seamless collaboration via Microsoft Teams for virtual meetings.

Frequently Asked Questions

1. What is New-MgUserEvent used for?

New-MgUserEvent is a Microsoft Graph PowerShell cmdlet used to create new calendar events in a user’s mailbox, such as meetings or appointments.

2. How can I verify that the event was created?

Retrieve events using the Get-MgUserEvent cmdlet and filter by subject or date:

Get-MgUserEvent -UserId "<UserPrincipalName>" -Filter "subject eq 'Project Kickoff Meeting'"

3. What permissions are required to create calendar events?

You need the Calendars.ReadWrite permission in Microsoft Graph PowerShell. Ensure these permissions are granted in Azure AD.

Conclusion

The New-MgUserEvent cmdlet is a powerful tool for scheduling offline and online meetings in Microsoft 365. Its flexibility to handle both physical and virtual meetings makes it a core feature for automating calendar management. By following proper hashtable conventions and being mindful of parameters like time zones, event types, and attendee information, you can ensure smooth execution of this cmdlet. Leverage this cmdlet to simplify scheduling and focus on boosting productivity across your teams.

Additional Resources:

Graph PowerShell New-MgUserEvent Cmdlet Documentation
Microsoft Graph PowerShell Module Documentation
Microsoft Graph API Documentation