New-MgUserCalendarEvent: Create Events Using Graph PowerShell

This guide demonstrates how to use the New-MgUserCalendarEvent cmdlet in Microsoft Graph PowerShell to create calendar events for users. Learn how to specify event details, invite attendees, and set reminders with practical examples.

The New-MgUserCalendarEvent cmdlet is a powerful tool within the Microsoft Graph PowerShell module that allows administrators to create calendar events for individual users. This cmdlet is particularly useful in scenarios where automation of personal schedules, centralized event management, and remote workforce support are necessary.

Note: You need a calendar ID to work with this cmdlet. Use Get-MgUserCalendar to get the calendar ID.

Cmdlet Syntax

New-MgUserCalendarEvent -UserId <String> -BodyParameter <IMicrosoftGraphEvent>

• -UserId <String>: The unique identifier or UPN (User Principal Name) of the user whose calendar you are targeting.
• -BodyParameter <IMicrosoftGraphEvent>: The event details, including the subject, start time, end time, location, attendees, etc., are passed in the form of a hashtable.

Usage Examples

Example 1: Creating an Offline Meeting

This example creates a meeting scheduled in a physical location (e.g., a conference room).

$eventDetails = @{
    subject = "Project Kickoff Meeting"
    start = @{
        dateTime = "2024-08-20T10:00:00"
        timeZone = "Pacific Standard Time"
    }
    end = @{
        dateTime = "2024-08-20T11:00:00"
        timeZone = "Pacific Standard Time"
    }
    location = @{
        displayName = "Conference Room 1"
    }
    attendees = @(
        @{
            emailAddress = @{
                address = "john.doe@domain.com"
            }
            type = "Required"
        }
    )
}

New-MgUserCalendarEvent -UserId "user@domain.com" -BodyParameter $eventDetails

Example 2: Creating an Online Meeting

This example creates an online meeting using Microsoft Teams.

$eventDetails = @{
    subject = "Weekly Sync"
    start = @{
        dateTime = "2024-08-21T14:00:00"
        timeZone = "Pacific Standard Time"
    }
    end = @{
        dateTime = "2024-08-21T15:00:00"
        timeZone = "Pacific Standard Time"
    }
    location = @{
        displayName = "Online"
    }
    isOnlineMeeting = $true
    onlineMeetingProvider = "teamsForBusiness"
    attendees = @(
        @{
            emailAddress = @{
                address = "team.member@domain.com"
            }
            type = "Required"
        }
    )
}

New-MgUserCalendarEvent -UserId "user@domain.com" -BodyParameter $eventDetails

Cmdlet Tips

• Use Descriptive Subjects: When creating events, ensure that the subject is clear and descriptive, making it easier for users to understand the purpose of the meeting at a glance.
• Time Zone Accuracy: Always specify the correct time zone to avoid scheduling conflicts, especially when dealing with remote teams across different regions.
• Check Permissions: Ensure that the user running the cmdlet has the necessary permissions (Calendars.ReadWrite or Calendars.ReadWrite.Shared) to access and modify the target user's calendar.

Possible Errors & Solutions

Error 1: Unauthorized Access

Error Message: Access is denied. Check credentials and permissions.

Cause: The user executing the cmdlet does not have sufficient permissions.

Solution: Verify that the user has the required permissions (Calendars.ReadWrite or Calendars.ReadWrite.Shared). If necessary, delegate the appropriate permissions in Azure AD.

Error 2: Invalid Time Zone

Error Message: The specified time zone is invalid.

Cause: The timeZone parameter is incorrectly specified.

Solution: Use a valid time zone identifier (e.g., Pacific Standard Time, Eastern Standard Time) from the IANA time zone database.

Error 3: Invalid Attendee Format

Error Message: The attendee email format is incorrect.

Cause: The email address of an attendee is not in the correct format or is missing.

Solution: Ensure that all attendee email addresses are valid and correctly formatted within the hashtable.

Use Cases

• Automation of Personal Schedules:
• Personal Assistants: Automating recurring personal events, reminders, or appointments for high-level executives or employees.
• HR Processes: Scheduling onboarding meetings, training sessions, or 1-on-1 reviews directly in employees' calendars.
• Centralized Event Management:
• Admin Roles: IT administrators can automate calendar entries such as setting up password reset reminders, security training, or other compliance-related tasks.
• Event Management: Automatically add events to specific users’ calendars based on external triggers like booking systems, CRM updates, or project management tools.
• Remote Workforce Support: For remote employees, schedule personal check-ins, performance reviews, or wellness checks directly into their calendars to ensure these events aren't missed.
• System Notifications: Automatically create calendar events based on system alerts (e.g., if a server requires maintenance, schedule an admin to check it).

New-MgEvent Vs.New-MgCalendarEvent

Let’s break down the difference between New-MgUserEvent and New-MgUserCalendarEvent.

New-MgUserEvent:

• Purpose: This cmdlet is used to create a new event directly in the default calendar of a specific user. The user is identified by their UserId.
• Usage Context: When you want to add an event directly to a user's default calendar without specifying a particular calendar.
• Usage Example: New-MgUserEvent -UserId "user@domain.com" -BodyParameter $params

New-MgUserCalendarEvent:

• Purpose: This cmdlet is used to create a new event in a specific calendar of a user. You must provide the UserId and the CalendarId of the specific calendar where you want the event to be added.
• Usage Context: When the user has multiple calendars, and you want to add an event to a specific one, not just the default calendar.
• Usage Example: New-MgUserCalendarEvent -UserId "user@domain.com" -CalendarId "AAMkAGI2TAAA=" -BodyParameter $params

When to Use Which:

• Use New-MgUserEvent when you are certain the event should be added to the user's default calendar.
• Use New-MgUserCalendarEvent when the event should go into a specific calendar other than the default one.

Frequently Asked Questions

1. What is New-MgUserCalendarEvent used for?

New-MgUserCalendarEvent is a Microsoft Graph PowerShell cmdlet used to create events in a user’s calendar, including specifying event details, setting reminders, and inviting attendees.

2. How can I create a simple calendar event for a user?

Use the following script to create a basic event:

$Body = @{
subject = "Team Meeting"
start = @{
        dateTime = "2023-11-10T10:00:00"
        timeZone = "UTC"
        }
        end = @{
        dateTime = "2023-11-10T11:00:00"
        timeZone = "UTC"
        }
        attendees = @(
             @{
                emailAddress = @{ address = "attendee@domain.com" }
                type = "required"
             }
            )
        }
New-MgUserCalendarEvent -UserId "<UserPrincipalName>" -BodyParameter $Body
                            

3. Can I create a recurring event using this cmdlet?

Yes, use the recurrence property to define the recurrence pattern. Example:

$Body = @{
subject = "Weekly Sync"
start = @{
        dateTime = "2023-11-10T10:00:00"
        timeZone = "UTC"
        }
end = @{
        dateTime = "2023-11-10T11:00:00"
        timeZone = "UTC"
}
attendees = @(
        @{
        emailAddress = @{ address = "attendee@domain.com" }
        type = "required"
        }
     )
recurrence = @{
    pattern = @{
            type = "weekly"
            interval = 1
            daysOfWeek = @("Monday")
        }
    range = @{
            type = "endDate"
            startDate = "2023-11-10"
            endDate = "2023-12-10"
            }
         }
    }
New-MgUserCalendarEvent -UserId "" -BodyParameter $Body
                            

4. 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-MgUserCalendarEvent cmdlet, while seemingly niche, offers significant value in scenarios requiring individual user calendar management. Whether it's for automating personal schedules, centralizing event management, supporting remote teams, or integrating with system notifications, this cmdlet enhances operational efficiency and ensures that important events are never overlooked.

By understanding its potential use cases, common errors, and proper implementation, administrators can leverage the New-MgUserCalendarEvent cmdlet to streamline processes and improve user experience within their organization.

Additional Resources:

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

Related Articles:

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