Commands › Exchange Online

New-MigrationBatch

Exchange Online ExchangeOnlineManagement New-*

Submit a new migration request for a batch of users.

Quick start script

# New-MigrationBatch — quick start (serv365.ai)
# 1. Connect (app-only shown; interactive: omit the certificate parameters)
Connect-ExchangeOnline -CertificateThumbprint $thumb -AppId $appId -Organization $org

# 2. Capture the current state first — you cannot roll back what you never recorded
$before = Get-MigrationBatch
$before | Format-List

# 3. Make the change (dry run first)
New-MigrationBatch -UserIds <MultiValuedProperty> -Users <MultiValuedProperty> -Analyze <SwitchParameter> -WhatIf
New-MigrationBatch -UserIds <MultiValuedProperty> -Users <MultiValuedProperty> -Analyze <SwitchParameter>

# 4. Verify and diff
$after = Get-MigrationBatch
Compare-Object ($before | Out-String) ($after | Out-String)

Syntax — 18 parameter sets

Abch

New-MigrationBatch -Name <String> -CSVData <Byte[]> [-AllowIncrementalSyncs <System.Boolean>]
 [-AllowUnknownColumnsInCsv <Boolean>]
 [-AutoComplete]
 [-AutoRetryCount <System.Int32>]
 [-AutoStart]
 [-CompleteAfter <System.DateTime>]
 [-Confirm]
 [-DomainController <Fqdn>]
 [-Locale <CultureInfo>]
 [-NotificationEmails <MultiValuedProperty>]
 [-ReportInterval <System.TimeSpan>]
 [-SkipReports]
 [-SkipSteps <SkippableMigrationSteps[]>]
 [-StartAfter <System.DateTime>]
 [-TargetDatabases <MultiValuedProperty>]
 [-TimeZone <ExTimeZoneValue>]
 [-WhatIf]
 [<CommonParameters>]

Analysis

New-MigrationBatch -Name <String> -CSVData <Byte[]> [-Analyze]
 [-AllowUnknownColumnsInCSV <Boolean>]
 [-AutoComplete]
 [-AutoStart]
 [-CompleteAfter <System.DateTime>]
 [-Confirm]
 [-Daily]
 [-ExcludeFolders <MultiValuedProperty>]
 [-IncludeFolders <MultiValuedProperty>]
 [-NotificationEmails <MultiValuedProperty>]
 [-Partition <MailboxIdParameter>]
 [-ReportInterval <System.TimeSpan>]
 [-SkipDetails]
 [-SkipReports]
 [-SourceEndpoint <MigrationEndpointIdParameter>]
 [-StartAfter <System.DateTime>]
 [-TimeZone <ExTimeZoneValue>]
 [-WhatIf]
 [<CommonParameters>]

FolderMove

New-MigrationBatch -Name <String> -CSVData <Byte[]>
 [-AllowUnknownColumnsInCSV <Boolean>]
 [-AutoComplete]
 [-AutoStart]
 [-BadItemLimit <Unlimited>]
 [-CompleteAfter <System.DateTime>]
 [-Confirm]
 [-LargeItemLimit <Unlimited>]
 [-MoveOptions <MultiValuedProperty>]
 [-NotificationEmails <MultiValuedProperty>]
 [-Partition <MailboxIdParameter>]
 [-ReportInterval <System.TimeSpan>]
 [-SkipReports]
 [-StartAfter <System.DateTime>]
 [-TimeZone <ExTimeZoneValue>]
 [-WhatIf]
 [<CommonParameters>]

GoogleResourceOnboarding

New-MigrationBatch -Name <String> -CSVData <Byte[]>
 [-AdoptPreexisting]
 [-AllowUnknownColumnsInCSV <Boolean>]
 [-AutoComplete]
 [-AutoStart]
 [-CompleteAfter <DateTim>]
 [-Confirm]
 [-GoogleResource]
 [-NotificationEmails <MultiValuedProperty>]
 [-Partition <MailboxIdParameter>]
 [-RemoveOnCopy]
 [-ReportInterval <TimeSpan>]
 [-SkipDelegates]
 [-SkipMerging <MultiValuedProperty>]
 [-SkipProvisioning]
 [-SkipReports]
 [-SourceEndpoint <MigrationEndpointIdParameter>]
 [-StartAfter <DateTime>]
 [-TimeZone <ExTimeZoneValue>]
 [-WhatIf]
 [<CommonParameters>]

14 more parameter sets — see the parameter table below.

Parameters (75)

Parameter	Type	Required	What it controls
-UserIds	MultiValuedProperty	yes	The UserIds parameter specifies the users that you want to copy from an existing migration batch (for example, if a previous migration was partially successful). You identify a user by email address or by their Guid...
-Users	MultiValuedProperty	yes	The Users parameter specifies the users that you want to copy from an existing migration batch (for example, if a previous migration was partially successful). You identify the users by using the Get-MigrationUser...
-Analyze	SwitchParameter	yes	This parameter is available only in the cloud-based service.
-ConnectionLogicalId	String	yes	This parameter is available only in the cloud-based service.
-CSVData	Byte[]	yes	The CSVData parameter specifies the CSV file that contains information about the user mailboxes to be moved or migrated. The required attributes in the header row of the CSV file vary depending on the type of...
-Local	SwitchParameter	yes	This parameter is available only in on-premises Exchange.
-ManagedGmailTeams	SwitchParameter	yes	This parameter is available only in the cloud-based service.
-Name	String	yes	The Name parameter specifies an unique name for the migration batch on each system (Exchange On-premises or Exchange Online). The maximum length is 64 characters. If the value contains spaces, enclose the value in...
-SlackPublicDataConnector	SwitchParameter	yes	This parameter is available only in the cloud-based service.
-SlackWorkspaceId	String	yes	This parameter is available only in the cloud-based service.
-SourcePublicFolderDatabase	DatabaseIdParameter	yes	This parameter is available only in on-premises Exchange.
-AdoptPreexisting	SwitchParameter		This parameter is available only in the cloud-based service.
-AllowIncrementalSyncs	Boolean		This parameter is available only in on-premises Exchange.
-AllowUnknownColumnsInCsv	Boolean		The AllowUnknownColumnsInCsv parameter specifies whether to allow extra columns in the CSV file that aren't used by migration. Valid values are:
-ArchiveDomain	String		This parameter is available only in the cloud-based service.
-ArchiveOnly	SwitchParameter		The ArchiveOnly switch specifies that only archive mailboxes are migrated for the users in the migration batch (primary mailboxes aren't migrated). You don't need to specify a value with this switch.
-AutoComplete	SwitchParameter		The AutoComplete switch forces the finalization of the individual mailboxes as soon as the mailbox has completed initial synchronization. You don't need to specify a value with this switch.
-AutoProvisioning	SwitchParameter		This parameter is available only in the cloud-based service.
-AutoRetryCount	Int32		This parameter is available only in on-premises Exchange.
-AutoStart	SwitchParameter		The AutoStart switch immediately starts the processing of the new migration batch. You don't need to specify a value with this switch.
-AvoidMergeOverlap	SwitchParameter		This parameter is available only in the cloud-based service.
-BadItemLimit	Unlimited		This parameter is available only in on-premises Exchange.
-CompleteAfter	DateTime		This parameter is functional only in the cloud-based service.
-Confirm	SwitchParameter		The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on whether the cmdlet requires confirmation before proceeding.
-ContentFilter	String		This parameter is available only in the cloud-based service for IMAP migration and Google Workspace migration.
-ContentFilterLanguage	CultureInfo		This parameter is available only in the cloud-based service for IMAP migration and Google Workspace migration.
-DataFusion	SwitchParameter		This parameter is available only in the cloud-based service.
-Daily	SwitchParameter		This parameter is available only in the cloud-based service.
-DisableOnCopy	SwitchParameter		The DisableOnCopy switch disables the original migration job item for a user if you're copying users from an existing batch to a new batch by using the UserIds or Users parameters. You don't need to specify a value...
-DisallowExistingUsers	SwitchParameter		This parameter is available only in on-premises Exchange.
-DomainController	Fqdn		This parameter is available only in on-premises Exchange.
-ExcludeDumpsters	SwitchParameter		This parameter is available only in the cloud-based service.
-ExcludeFolders	MultiValuedProperty		This parameter is available only in the cloud-based service.
-ForwardingDisposition	GmailForwardingDisposition		This parameter is available only in the cloud-based service.
-GoogleResource	SwitchParameter	yes	The GoogleResource switch specifies that this is a Google Resource migration batch. You don't need to specify a value with this switch.
-IncludeFolders	MultiValuedProperty		This parameter is available only in the cloud-based service.
-IncludeOtherContacts	SwitchParameter		This parameter is available only in the cloud-based service.
-LargeItemLimit	Unlimited		This parameter is available only in on-premises Exchange.
-Locale	CultureInfo		This parameter is available only in on-premises Exchange.
-MigrateTasks	SwitchParameter		This parameter is available only in the cloud-based service.
-MoveOptions	MultiValuedProperty		The MoveOptions parameter specifies the stages of the migration that you want to skip for debugging purposes. Don't use this parameter unless you're directed to do so by Microsoft Customer Service and Support or...
-NotificationEmails	MultiValuedProperty		The NotificationEmails parameter specifies one or more email addresses that migration status reports are sent to. Specify the value as a string array, and separate multiple email addresses with commas.
-Partition	MailboxIdParameter		This parameter is available only in the cloud-based service.
-PrimaryOnly	SwitchParameter		The PrimaryOnly switch specifies that only primary mailboxes are migrated for the users in the migration batch that also have archive mailboxes (archive mailboxes aren't migrated). You don't need to specify a value...
-PublicFolderToUnifiedGroup	SwitchParameter	yes	This parameter is functional only in the cloud-based service.
-RemoveOnCopy	SwitchParameter		This parameter is available only in the cloud-based service.
-RenamePrimaryCalendar	SwitchParameter		This parameter is available only in the cloud-based service.
-ReportInterval	TimeSpan		The ReportInterval parameter specifies how frequently emailed reports should be sent to the email addresses listed within NotificationEmails.
-Restore	SwitchParameter		This parameter is available only in the cloud-based service.
-SimplifiedSwitchOver	SwitchParameter		This parameter is available only in the cloud-based service.
-SkipCalendar	SwitchParameter		This parameter is available only in the cloud-based service.
-SkipContacts	SwitchParameter		This parameter is available only in the cloud-based service.
-SkipDelegates	SwitchParameter		This parameter is available only in the cloud-based service.
-SkipDetails	SwitchParameter		This parameter is available only in the cloud-based service.
-SkipMail	SwitchParameter		This parameter is available only in the cloud-based service.
-SkipMerging	MultiValuedProperty		The SkipMerging parameter specifies the stages of the migration that you want to skip for debugging purposes. Don't use this parameter unless you're directed to do so by Microsoft Customer Service and Support or...
-SkipMoving	MultiValuedProperty		This parameter is replaced by the MoveOptions parameter.
-SkipProvisioning	SwitchParameter		This parameter is available only in the cloud-based service.
-SkipReports	SwitchParameter		The SkipReports switch specifies that you want to skip automatic reporting for the migration. You don't need to specify a value with this switch.
-SkipRules	SwitchParameter		This parameter is available only in the cloud-based service.
-SkipSteps	SkippableMigrationSteps[]		This parameter is available only in on-premises Exchange.
-SourceEndpoint	MigrationEndpointIdParameter		The SourceEndpoint parameter specifies the migration endpoint to use for the source of the migration batch. You create the migration endpoint by using the New-MigrationEndpoint cmdlet. You can use any value that...
-SourcePFPrimaryMailboxGuid	Guid		This parameter is available only in the cloud-based service.
-StagedRollOutGroupId	String		This parameter is available only in the cloud-based service.
-StartAfter	DateTime		The StartAfter parameter specifies a delay before the data migration for the users within the batch is started. The migration is prepared, but the actual data migration for the user doesn't start until the date/time...
-TargetArchiveDatabases	MultiValuedProperty		The TargetArchiveDatabases parameter specifies the database where the archive mailboxes specified in the migration batch are migrated to. You can use any value that uniquely identifies the database. For example:
-TargetDatabases	MultiValuedProperty		The TargetDatabases parameter specifies the identity of the database that you're moving mailboxes to. You can use any value that uniquely identifies the database. For example:
-TargetDeliveryDomain	String		The TargetDeliveryDomain parameter specifies the FQDN of the external email address created in the source forest for the mail-enabled user when the migration batch is complete.
-TargetEndpoint	MigrationEndpointIdParameter		The TargetEndpoint parameter specifies the migration endpoint to use for the destination of the migration batch. You create the migration endpoint by using the New-MigrationEndpoint cmdlet. You can use any value that...
-TimeZone	ExTimeZoneValue		The TimeZone parameter specifies the time zone of the administrator who submits the migration batch.
-WhatIf	SwitchParameter		The WhatIf switch shows what the command does without making any changes. You don't need to specify a value with this switch.
-WorkflowControlFlags	MigrationWorkflowControlFlags		The WorkflowControlFlags parameter specifies advanced controls for the steps that are performed in the migration. Valid values are:
-WorkflowTemplate	String		The WorkflowTemplate parameter specifies the name of an expert migration template to use for the migration batch. Don't use this parameter unless you're directed to do so by Microsoft Customer Service and Support or...
-WorkloadType	RequestWorkloadType		This parameter is available only in on-premises Exchange.
-XMLData	Byte[]		This parameter is available only in the cloud-based service.

Reference facts derived from Microsoft documentation, © Microsoft, licensed CC BY 4.0; restructured with original guidance by serv365.ai.