Invoke-CalendarEventMigration
This cmdlet is only available in the cloud-based service.
Use the Invoke-CalendarEventMigration cmdlet to change the time zone of a meeting or appointment.
For information about the parameter sets in the Syntax section below, see Exchange cmdlet syntax.
Syntax
TimeZoneMigration (Default)
Invoke-CalendarEventMigration
[-Identity] <MailboxIdParameter>
-FromWindowsTimeZoneId <string>
-ToWindowsTimeZoneId <string>
-QueryWindowInDays <int>
[-QueryStartDate <DateTime>]
[-Force]
[-PreviewOnly]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Description
When a new time zone is released, affected Outlook users need to update their scheduled events to use the new time zone. The Invoke-CalendarEventMigration cmdlet allows IT administrators to automate the calendar event migration by creating a script that loops through affected users. Invoke-CalendarEventMigration operates on one mailbox at a time and migrates meetings from one time zone to another while keeping the same local time. For example, a meeting at 9 AM Pacific Standard Time is migrated to 9 AM British Columbia Standard Time.
The initial release supports single instance meetings and appointments only. Support for recurring meetings and appointments will be delivered in the next version. You can safely rerun the cmdlet when support for recurring events is added.
Only meetings where the mailbox is the organizer are migrated. Meetings where the mailbox is an attendee must be migrated by the organizer, either manually or by running the cmdlet on the organizer's mailbox. Migrated meetings generate a meeting update message for attendees, so their calendars reflect the time zone change.
Only events in the default Calendar folder are migrated. Events in secondary calendars are not migrated.
You can safely rerun after a timeout or when additional features are added.
The cmdlet does not change the mailbox time zone, which is the time zone used to display the calendar and schedule new events. To change the mailbox time zone, use Set-MailboxRegionalConfiguration.
You need to be assigned permissions before you can run this cmdlet. Although this topic lists all parameters for the cmdlet, you might not have access to some parameters if they're not included in the permissions assigned to you. To find the permissions required to run any cmdlet or parameter in your organization, see Find the permissions required to run any Exchange cmdlet.
Examples
Example 1
Invoke-CalendarEventMigration user1@contoso.com -FromWindowsTimeZoneId "Pacific Standard Time" -ToWindowsTimeZoneId "British Columbia Standard Time" -QueryStartDate 2026-11-01 -QueryWindowInDays 365 -Confirm:$false
This example migrates single instance meetings and appointments on User1's primary calendar from Pacific Standard Time to British Columbia Standard Time. Only events between November 1, 2026 and November 1, 2027 are migrated.
Example 2
$mailboxes = @(
"user1@contoso.com"
"user2@contoso.com"
"shared@contoso.com"
)
foreach ($mailbox in $mailboxes) {
Set-MailboxRegionalConfiguration -Identity $mailbox -TimeZone "British Columbia Standard Time"
Invoke-CalendarEventMigration -Identity $mailbox `
-FromWindowsTimeZoneId "Pacific Standard Time" `
-ToWindowsTimeZoneId "British Columbia Standard Time" `
-QueryStartDate 2026-11-01 -QueryWindowInDays 365 -Confirm:$false
}
This example migrates affected mailboxes User1, User2, and Shared to British Columbia Standard Time. Each mailbox time zone is updated to British Columbia Standard Time and single instance meetings and appointments are migrated from Pacific Standard Time to British Columbia Standard Time. Only events between November 1, 2026 and November 1, 2027 are migrated.
Parameters
-Confirm
Applicable: Exchange Online
Prompts you for confirmation before running the cmdlet.
Parameter properties
| Type: | System.Management.Automation.SwitchParameter |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | cf |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Force
Applicable: Exchange Online
Sets whether the migration is allowed when the source and destination time zones have different current local times. This check helps prevent accidentally moving meetings to a new time. Use -Force to bypass the check.
Parameter properties
| Type: | System.Management.Automation.SwitchParameter |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
TimeZoneMigration
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-FromWindowsTimeZoneId
Applicable: Exchange Online
The time zone currently on events that need to be migrated. Events scheduled in other time zones will not be migrated.
Run Get-TimeZone -ListAvailable | FT -Property Id to see the list of supported time zones.
Parameter properties
| Type: | System.String |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
TimeZoneMigration
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Identity
Applicable: Exchange Online
The Identity parameter specifies the mailbox of the current meeting organizer. You can use any value that uniquely identifies the mailbox. For example:
- Name
- Alias
- Distinguished name (DN)
- Canonical DN
- Domain\Username
- Email address
- GUID
- LegacyExchangeDN
- SamAccountName
- User ID or user principal name (UPN)
Parameter properties
| Type: | MailboxIdParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 1 |
| Mandatory: | True |
| Value from pipeline: | True |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-PreviewOnly
Applicable: Exchange Online
When used, shows matching events that would be migrated without updating them.
Parameter properties
| Type: | System.Management.Automation.SwitchParameter |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
TimeZoneMigration
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-QueryStartDate
Applicable: Exchange Online
The start date for the query window. The cmdlet operates on events within the query window. Events before this date will not be migrated. If -QueryStartDate is not provided, the current time is used.
Parameter properties
| Type: | DateTime |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-QueryWindowInDays
Applicable: Exchange Online
The length in days for the query window. The cmdlet operates on events within the query window. Events beyond the query window will not be migrated. Valid values are between 1 (1 day) and 1825 (5 years), inclusive.
Parameter properties
| Type: | System.Int32 |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
TimeZoneMigration
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-ToWindowsTimeZoneId
Applicable: Exchange Online
The time zone that events will be migrated to.
Run Get-TimeZone -ListAvailable | FT -Property Id to see the list of supported time zones.
Parameter properties
| Type: | System.String |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
TimeZoneMigration
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-WhatIf
Applicable: Exchange Online
Runs the command in a mode that only reports what would happen without performing the actions.
Parameter properties
| Type: | System.Management.Automation.SwitchParameter |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | wi |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.