Applies to: Exchange Server 2013, Exchange Online

Topic Last Modified: 2013-02-26

Use the New-MigrationBatch cmdlet to submit a new migration request for a batch of users. The cmdlet is used to move mailboxes in an Exchange on-premises organization, migrate on-premises mailboxes to Exchange Online (also called onboarding), or migrate Exchange Online mailboxes back to an on-premises Exchange organization (also called offboarding) in an Exchange hybrid deployment. You can also use this cmdlet to perform another type of onboarding migration, which is called an IMAP migration. In this type of migration, mailbox data is migrated from on-premises mailboxes on an IMAP server to Exchange Online mailboxes.

For information about the parameter sets in the Syntax section below, see Syntax.

Syntax


`New-MigrationBatch [-CSVData <Byte[]>] [-ExcludeFolders <MultiValuedProperty>] [-LargeItemLimit <Unlimited>] [-SourceEndpoint <MigrationEndpointIdParameter>] [-TargetDeliveryDomain <String>] <COMMON PARAMETERS>`


`New-MigrationBatch -CSVData <Byte[]> -Local <SwitchParameter> <COMMON PARAMETERS>`


`New-MigrationBatch -CSVData <Byte[]> [-LargeItemLimit <Unlimited>] [-TargetDeliveryDomain <String>] [-TargetEndpoint <MigrationEndpointIdParameter>] <COMMON PARAMETERS>`


COMMON PARAMETERS: -Name <String> [-AllowIncrementalSyncs <$true \| $false>] [-ArchiveOnly <SwitchParameter>] [-AutoComplete <SwitchParameter>] [-AutoRetryCount <Int32>] [-AutoStart <SwitchParameter>] [-BadItemLimit <Unlimited>] [-Confirm [<SwitchParameter>]] [-DisallowExistingUsers <SwitchParameter>] [-DomainController <Fqdn>] [-ForceNewMigration <SwitchParameter>] [-Locale <CultureInfo>] [-NotificationEmails <MultiValuedProperty>] [-Organization <OrganizationIdParameter>] [-PrimaryOnly <SwitchParameter>] [-SkipSteps <SkippableMigrationSteps[]>] [-TargetArchiveDatabases <String[]>] [-TargetDatabases <String[]>] [-TimeZone <ExTimeZoneValue>] [-WhatIf [<SwitchParameter>]]

COMMON PARAMETERS: -Name <String>
[-AllowIncrementalSyncs <$true | $false>] [-ArchiveOnly
<SwitchParameter>] [-AutoComplete <SwitchParameter>]
[-AutoRetryCount <Int32>] [-AutoStart
<SwitchParameter>] [-BadItemLimit <Unlimited>]
[-Confirm [<SwitchParameter>]] [-DisallowExistingUsers
<SwitchParameter>] [-DomainController <Fqdn>]
[-ForceNewMigration <SwitchParameter>] [-Locale
<CultureInfo>] [-NotificationEmails
<MultiValuedProperty>] [-Organization
<OrganizationIdParameter>] [-PrimaryOnly
<SwitchParameter>] [-SkipSteps
<SkippableMigrationSteps[]>] [-TargetArchiveDatabases
<String[]>] [-TargetDatabases <String[]>] [-TimeZone
<ExTimeZoneValue>] [-WhatIf [<SwitchParameter>]]

Examples

EXAMPLE 1

This example creates a migration batch for a local move, where the mailboxes in the specified CSV file are moved to a different mailbox database. This CSV file contains a single column with the email address for the mailboxes that will be moved. The header for this column must be named EmailAddress. The migration batch in this example must be started manually by using the Start-MigrationBatch cmdlet or the Exchange admin center. Alternatively, you can use the AutoStart parameter to start the migration batch automatically.

	Copy Code
New-MigrationBatch -Local -Name LocalMove1 -CSVData ([System.IO.File]::ReadAllBytes("C:\Users\Administrator\Desktop\LocalMove1.csv")) -TargetDatabases MBXDB2

	Copy Code
Start-MigrationBatch -Identity LocalMove1

EXAMPLE 2

This example creates a migration batch for a cross-forest enterprise move, where the mailboxes for the mail users specified in the CSV file are moved to a different forest. A new migration endpoint is created, which identifies the domain where the mailboxes are currently located. The endpoint is used to create the migration batch. Then the migration batch is started with the Start-MigrationBatch cmdlet. Note that cross-forest moves are initiated from the target forest, which is the forest that you want to move the mailboxes to.

	Copy Code
$Credentials = Get-Credential

	Copy Code
$MigrationEndpointSource = New-MigrationEndpoint -ExchangeRemoteMove -Name Forest1Endpoint -Autodiscover -EmailAddress administrator@forest1.contoso.com -Credentials $Credentials

	Copy Code
$CrossForestBatch = New-MigrationBatch -Name CrossForestBatch1 -SourceEndpoint $MigrationEndpointSource.Identity -TargetDeliveryDomain forest2.contoso.com -TargetDatabases MBXDB1 -CSVData ([System.IO.File]::ReadAllBytes("C:\Users\Administrator\Desktop\CrossForestBatch1.csv"))

Copy Code

$CrossForestBatch = New-MigrationBatch -Name CrossForestBatch1 -SourceEndpoint $MigrationEndpointSource.Identity -TargetDeliveryDomain forest2.contoso.com -TargetDatabases MBXDB1 -CSVData ([System.IO.File]::ReadAllBytes("C:\Users\Administrator\Desktop\CrossForestBatch1.csv"))

	Copy Code
Start-MigrationBatch -Identity $CrossForestBatch.Identity

EXAMPLE 3

This example creates a migration batch for an onboarding remote move migration from an on-premises Exchange organization to Exchange Online. The syntax is similar to that of a cross-forest move, but it's initiated from the Exchange Online organization. A new migration endpoint is created, which points to the on-premises organization as the source location of the mailboxes that will be migrated. This endpoint is used to create the migration batch. Then the migration batch is started with the Start-MigrationBatch cmdlet.

	Copy Code
$Credentials = Get-Credential

	Copy Code
$MigrationEndpointOnPrem = New-MigrationEndpoint -ExchangeRemoteMove -Name OnpremEndpoint -Autodiscover -EmailAddress administrator@onprem.contoso.com -Credentials $Credentials

	Copy Code
$OnboardingBatch = New-MigrationBatch -Name RemoteOnBoarding1 -SourceEndpoint $MigrationEndpointOnprem.Identity -TargetDeliveryDomain cloud.contoso.com -CSVData ([System.IO.File]::ReadAllBytes("C:\Users\Administrator\Desktop\RemoteOnBoarding1.csv"))

Copy Code

$OnboardingBatch = New-MigrationBatch -Name RemoteOnBoarding1 -SourceEndpoint $MigrationEndpointOnprem.Identity -TargetDeliveryDomain cloud.contoso.com -CSVData ([System.IO.File]::ReadAllBytes("C:\Users\Administrator\Desktop\RemoteOnBoarding1.csv"))

	Copy Code
Start-MigrationBatch -Identity $OnboardingBatch.Identity

EXAMPLE 4

This example creates a migration batch for an offboarding remote move migration from Exchange Online to an on-premises Exchange organization. Like an onboarding remote move, it's initiated from the Exchange Online organization. First a Migration Endpoint is created that contains information about how to connect to the on-premises organization. The endpoint is used as the TargetEndpoint when creating the migration batch, which is then started with the Start-MigrationBatch cmdlet. The TargetDatabases parameter specifies multiple on-premises databases that the migration service can select as the target database to move the mailbox to.

	Copy Code
$Credentials = Get-Credential

	Copy Code
$MigrationEndpointOnPrem = New-MigrationEndpoint -ExchangeRemoteMove -Name OnpremEndpoint -Autodiscover -EmailAddress administrator@onprem.contoso.com -Credentials $Credentials

	Copy Code
$OffboardingBatch = New-MigrationBatch -Name RemoteOffBoarding1 -TargetEndpoint $MigrationEndpointOnprem.Identity -TargetDeliveryDomain onprem.contoso.com -TargetDatabases @(MBXDB01,MBXDB02,MBXDB03) -CSVData ([System.IO.File]::ReadAllBytes("C:\Users\Administrator\Desktop\RemoteOffBoarding1.csv"))

Copy Code

$OffboardingBatch = New-MigrationBatch -Name RemoteOffBoarding1 -TargetEndpoint $MigrationEndpointOnprem.Identity -TargetDeliveryDomain onprem.contoso.com -TargetDatabases @(MBXDB01,MBXDB02,MBXDB03) -CSVData ([System.IO.File]::ReadAllBytes("C:\Users\Administrator\Desktop\RemoteOffBoarding1.csv"))

	Copy Code
Start-MigrationBatch -Identity $OffboardingBatch.Identity

EXAMPLE 5

This example creates a migration batch for the cutover Exchange migration CutoverBatch that's automatically started. The example uses the Test-MigrationServerAvailability cmdlet to obtain and test the connection settings to the on-premises Exchange server, and then uses those connection settings to create a migration endpoint. The endpoint is then used to create the migration batch. This example also includes the optional TimeZone parameter.

	Copy Code
$credentials = Get-Credential

	Copy Code
$TSMA = Test-MigrationServerAvailability -ExchangeOutlookAnywhere -Autodiscover -EmailAddress administrator@contoso.com -Credentials $credentials

	Copy Code
$SourceEndpoint = New-MigrationEndpoint -ExchangeOutlookAnywhere -Name SourceEndpoint -ConnectionSettings $TSMA.ConnectionSettings

	Copy Code
New-MigrationBatch -Name CutoverBatch -SourceEndpoint $SourceEndpoint.Identity -TimeZone "Pacific Standard Time" -AutoStart

EXAMPLE 6

This example creates and starts a migration batch for a staged Exchange migration. The example uses the New-MigrationEndpoint cmdlet to create a migration endpoint for the on-premises Exchange server, and then uses that endpoint to create the migration batch. The migration batch is started with the Start-MigrationBatch cmdlet.

	Copy Code
$Credentials = Get-Credential

	Copy Code
$MigrationEndpoint = New-MigrationEndpoint -ExchangeOutlookAnywhere -Name ContosoEndpoint -Autodiscover -EmailAddress administrator@contoso.com -Credentials $Credentials

	Copy Code
$StagedBatch1 = New-MigrationBatch -Name StagedBatch1 -SourceEndpoint $MigrationEndpoint.Identity -CSVData ([System.IO.File]::ReadAllBytes("C:\Users\Administrator\Desktop\StagedBatch1.csv"))

	Copy Code
Start-MigrationBatch -Identity $StagedBatch1.Identity

EXAMPLE 7

This example creates a migration endpoint for the connection settings to the IMAP server. Then an IMAP migration batch is created that uses the CSV migration file IMAPmigration_1.csv and excludes the contents of the Deleted Items and Junk Email folders. This migration batch is pending until it's started with the Start-MigrationBatch cmdlet.

	Copy Code
New-MigrationEndpoint -IMAP -Name IMAPEndpoint1 -RemoteServer imap.contoso.com -Port 993

	Copy Code
New-MigrationBatch -Name IMAPbatch1 -CSVData ([System.IO.File]::ReadAllBytes("C:\Users\Administrator\Desktop\IMAPmigration_1.csv")) -SourceEndpoint IMAPEndpoint1 -ExcludeFolders "Deleted Items","Junk Email"

Copy Code

New-MigrationBatch -Name IMAPbatch1 -CSVData ([System.IO.File]::ReadAllBytes("C:\Users\Administrator\Desktop\IMAPmigration_1.csv")) -SourceEndpoint IMAPEndpoint1 -ExcludeFolders "Deleted Items","Junk Email"

Detailed Description

Use the New-MigrationBatch cmdlet to create a migration batch to migrate mailboxes and mailbox data in one of the following migration scenarios.

Moves in on-premises Exchange organizations

Local move: A local move is where you move mailboxes from one mailbox database to another. A local move occurs within a single forest. For more information, see Example 1.
Cross-forest enterprise move: In a cross-forest enterprise move, mailboxes are moved to a different forest. Cross-forest moves are initiated either from the target forest, which is the forest that you want to move the mailboxes to, or from the source forest, which is the forest that currently hosts the mailboxes. For more information, see Example 2.

Onboarding and offboarding in Exchange Online

Onboarding remote move migration: In a hybrid deployment, you can move mailboxes from an on-premises Exchange organization to Exchange Online. This is also known as an onboarding remote move migration because you on-board mailboxes to Exchange Online. For more information, see Example 3.
Offboarding remote move migration: You can also perform an offboarding remote move migration, where you migrate Exchange Online mailboxes to your on-premises Exchange organization. For more information, see Example 4.

Note:

Both onboarding and offboarding remote move migrations are initiated from your Exchange Online organization.
Cutover Exchange migration: This is another type of onboarding migration and is used to migrate all mailboxes in an on-premises Exchange organization to Exchange Online. You can migrate a maximum of 1,000 Microsoft Exchange Server 2003, Exchange Server 2007, or Exchange Server 2010 mailboxes using a cutover migration. Mailboxes will be automatically provisioned in Exchange Online when you perform a cutover Exchange migration. For more information, see Example 5.
Staged Exchange migration: You can also migrate a subset of mailboxes from an on-premises Exchange organization to Exchange Online. This is another type of onboarding migration. You can migrate only Exchange 2003 and Exchange 2007 mailboxes using a staged Exchange migration. Migrating Exchange 2010 and Exchange 2013 mailboxes isn't supported using a staged migration. Prior to running a staged migration, you have to use directory synchronization or some other method to provision mail users in your Exchange Online organization. For more information, see Example 6.
IMAP migration: This onboarding migration type migrates mailbox data from an IMAP server (including Exchange) to Exchange Online. For an IMAP migration, you must first provision mailboxes in Exchange Online before you can migrate mailbox data. For more information, see Example 7.

Note:
Both onboarding and offboarding remote move migrations are initiated from your Exchange Online organization.

You need to be assigned permissions before you can run this cmdlet. Although all parameters for this cmdlet are listed in this topic, you may not have access to some parameters if they're not included in the permissions assigned to you. To see what permissions you need, see the "Mailbox Move and Migration Permissions" section in the Recipients Permissions topic.

Parameters

Parameter Required Type Description

Local

Required

System.Management.Automation.SwitchParameter

The Local parameter specifies a local move, where mailboxes are moved to a different mailbox database within the same forest.

Name

Required

System.String

The Name parameter specifies an identifying name for the migration batch.

AllowIncrementalSyncs

Optional

System.Boolean

The AllowIncrementalSyncs parameter specifies whether to allow incremental synchronization. During incremental synchronization, the source and target mailboxes are synchronized. This means that any new messages sent to the source mailbox are copied to the corresponding target mailbox. This occurs every 24 hours.

You can use one of the following values for this parameter:

$true Enables incremental synchronization; this is the default value.
$false Prevents incremental synchronizations. If you use this value, the migration batch will go into Stopped state after initial synchronization is complete. To complete a migration batch for local moves, cross-forest moves, or remote move migrations, you have to enable incremental synchronization by using the Set-MigrationBatch cmdlet.

ArchiveOnly

Optional

System.Management.Automation.SwitchParameter

The ArchiveOnly parameter specifies whether to migrate only the archive mailboxes from the source to the target destination for the users specified in the migration batch. Primary mailboxes aren't migrated when this parameter is used. This parameter can only be used for local moves and remote move migrations.

You can use the TargetArchiveDatabases parameter to specify the database to migrate the archive mailboxes to. You can also specify the target archive database in the CSV file. If you don't specify the target archive database, the cmdlet uses the automatic mailbox distribution logic to select the database.

AutoComplete

Optional

System.Management.Automation.SwitchParameter

The AutoComplete parameter specifies whether to force the finalization of the individual mailboxes in a migration batch when the initial synchronization for a mailbox is successfully completed. Alternatively, you have to run the Complete-MigrationBatch cmdlet to finalize a migration batch. This parameter can only be used for local moves and remote move migrations.

This parameter will force the individual mailboxes to be finalized as soon as the mailbox has completed initial synchronization.

Important:
If you're migrating mailboxes from Exchange Online to an on-premises Exchange Server 2007 organization, you must include the AutoComplete parameter. This parameter is required because offboarding cloud-based mailboxes to an Exchange 2007 organization is performed offline, and mailboxes in the migration batch must be finalized after the initial synchronization is successfully completed.

AutoRetryCount

Optional

System.Int32

The AutoRetryCount parameter specifies the number of attempts to restart the migration batch to migrate mailboxes that encountered errors.

AutoStart

Optional

System.Management.Automation.SwitchParameter

The AutoStart parameter specifies whether to immediately start the processing of the new migration batch. If you don't use the AutoStart parameter, you have to manually start the migration batch by using the Start-MigrationBatch cmdlet.

BadItemLimit

Optional

Microsoft.Exchange.Data.Unlimited

The BadItemLimit parameter specifies the number of bad items to skip if the migration request encounters corruption in the mailbox. Use 0 to not skip bad items. The valid input range for this parameter is from 0 through 2147483647 and the value unlimited. The default value is 0. We recommend that you keep the default value 0 and only change the BadItemLimit parameter value if the move or migration fails.

Confirm

Optional

System.Management.Automation.SwitchParameter

The Confirm switch causes the command to pause processing and requires you to acknowledge what the command will do before processing continues. You don't have to specify a value with the Confirm switch.

CSVData

Optional

System.Byte[]

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 migration. Use the following format for the value of this parameter: ([System.IO.File]::ReadAllBytes(<path of the CSV migration file>)). The following is an example: CSVData:([System.IO.File]::ReadAllBytes("C:\Users\Administrator\Desktop\MigrationBatch_1.csv"))

DisallowExistingUsers

Optional

System.Management.Automation.SwitchParameter

The DisallowExistingUsers parameter specifies whether to prevent the migration of mailboxes that are currently being migrated in a different migration batch. A validation warning is displayed for any pre-existing mailbox in the target destination.

DomainController

Optional

Microsoft.Exchange.Data.Fqdn

The DomainController parameter specifies the fully qualified domain name (FQDN) of the domain controller that writes this configuration change to Active Directory.

In the cloud-based service, this parameter is reserved for internal Microsoft use.

ExcludeFolders

Optional

Microsoft.Exchange.Data.MultiValuedProperty

For an IMAP migration, the ExcludeFolders parameter specifies mailbox folders that you don't want to migrate from the on-premises messaging system to the cloud-based mailboxes. Use folder names relative to the IMAP root on the on-premises mail server. Specify the value as a string array and separate multiple folder names with commas.

This parameter is available only in the cloud-based service. It isn't available for on-premises deployments.

ForceNewMigration

Optional

System.Management.Automation.SwitchParameter

The ForceNewMigration parameter causes the migration process to create a subscription for any mailbox in the migration batch that was previously migrated in a different migration batch. Existing subscriptions for mailboxes in the migration batch are deleted.

LargeItemLimit

Optional

Microsoft.Exchange.Data.Unlimited

The LargeItemLimit parameter specifies the number of large items in each mailbox in the migration batch that will be skipped. When the number of large items exceeds this value, the migration for the mailbox fails.

The default value is 0, which means that the migration fails if the mailbox contains any large items.

For an on-premises Exchange organization, the size limit is defined by the target mailbox database. In Exchange Online, items up to 35 megabytes (MB) are migrated.

Locale

Optional

System.Globalization.CultureInfo

The Locale parameter specifies the language for the organization.

In the cloud-based service, this parameter is reserved for internal Microsoft use.

NotificationEmails

Optional

Microsoft.Exchange.Data.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.

If you don't use this parameter, the status report isn't sent.

Organization

Optional

Microsoft.Exchange.Configuration.Tasks.OrganizationIdParameter

The Organization parameter is reserved for internal Microsoft use.

PrimaryOnly

Optional

System.Management.Automation.SwitchParameter

The PrimaryOnly parameter specifies that only the primary mailboxes are migrated from the source destination to the target organization for the users specified in the migration batch. Archive mailboxes aren't migrated when this parameter is used.

This parameter can only be used for local moves and remote move migrations.

SkipSteps

Optional

Microsoft.Exchange.Data.Storage.Management.SkippableMigrationSteps[]

The SkipSteps parameter allows you to skip the step of setting the target email address on the source mailbox. This prevents mail from being forwarded from the original mailbox to the new mailbox that was migrated to the target destination. Use one of the following values with this parameter:

SettingTargetAddress
None

This parameter is only enforced for migration batches for a staged Exchange migration.

SourceEndpoint

Optional

Microsoft.Exchange.Management.Migration.MigrationEndpointIdParameter

The SourceEndpoint parameter specifies the name of the migration endpoint for the current location of the mailboxes specified in the migration batch. The migration endpoint specified by this parameter contains the connection settings that will be used by the migration process to connect to the server where the mailboxes specified in the migration batch are located.

TargetArchiveDatabases

Optional

System.String[]

The TargetArchiveDatabases parameter specifies the database where the archive mailboxes specified in the migration batch will be migrated to.

This parameter can only be used for local moves and remote move migrations.

TargetDatabases

Optional

System.String[]

The TargetDatabases parameter specifies the identity of the database that you're moving mailboxes to. You can use the following values:

Database GUID
Database name

If you don't specify the TargetDatabases parameter for a local move, the cmdlet uses the automatic mailbox distribution logic to select the database.

You can also specify multiple databases for the value of this parameter. The migration service will select one as the target database to move the mailbox to. For example: -TargetDatabases @(MBXDB01,MBXDB02,MBXDB03)

This parameter can only be used for local moves and remote move migrations.

TargetDeliveryDomain

Optional

System.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. This parameter is required when creating remote move onboarding and remote offboarding migration batches.

TargetEndpoint

Optional

Microsoft.Exchange.Management.Migration.MigrationEndpointIdParameter

The TargetEndpoint parameter specifies the name of the migration endpoint for the destination where the mailboxes specified in the migration batch will be moved or migrated to. The migration endpoint specified by this parameter contains the connection settings that will be used by the migration process to connect to the server where the mailboxes will be moved.

TimeZone

Optional

Microsoft.Exchange.Data.Storage.Management.ExTimeZoneValue

The TimeZone parameter specifies the time zone of the administrator who submits the migration batch. Use a valid Windows time zone name.

You can use Windows PowerShell to retrieve time zone names from the registry, for example:

	Copy Code
Get-ChildItem "HKLM:\Software\Microsoft\Windows NT\CurrentVersion\Time zones" \| Format-List pschildname

WhatIf

Optional

System.Management.Automation.SwitchParameter

The WhatIf switch instructs the command to simulate the actions that it would take on the object. By using the WhatIf switch, you can view what changes would occur without having to apply any of those changes. You don't have to specify a value with the WhatIf switch.

Input Types

To see the input types that this cmdlet accepts, see Cmdlet Input and Output Types. If the Input Type field for a cmdlet is blank, the cmdlet doesn’t accept input data.

Return Types

To see the return types, which are also known as output types, that this cmdlet accepts, see Cmdlet Input and Output Types. If the Output Type field is blank, the cmdlet doesn’t return data.