Chat now with support
Chat with Support

Binary Tree Migrator Pro for Exchange 20.10.1 - User Guide

1. Introduction 2. Creating and Managing Forests 3. Managing Exchange Pro Workers 4. Managing Configuration Settings 5. Mailboxes View 6. Mailbox Jobs View 7. Blackout Times View 8. Migration Summary View 9. Migration Schedule View 10. Migration Metrics View 11. Migrating Delegation Rights 12. Public Folders View 13. Public Folder Jobs View 14. Content Analysis View 15. The User Portal 16. Troubleshooting Third Party Components Appendixes

Appendix C:  Diagnostic and Operational Report Scripts

Migrator Pro for Exchange uses PowerShell as a platform to extend the product and provide external functionality that can be integrated with other applications and services. Migrator Pro for Exchange's PowerShell scripts let you:

  • Diagnose connection and configuration problems
  • Extract operational reports in .csv format
  • Customize and extend the migration pipeline functionality
  • Trigger auto-migrations outside of the Migrator Pro for Exchange Admin Portal
  • Export and import group information between disconnected forests

The Migrator Pro for Exchange Diagnostic scripts are installed in C:\Program Files\Binary Tree\Scripts\E2E\Diagnostic, and include:

  • Get-BTForest.ps1
  • Test-ExchangePowerShellHost.ps1

The Migrator Pro for Exchange Operational Report scripts are installed in C:\Program Files\Binary Tree\Scripts\E2E\Report), and include:

  • Get-BTMigrationReport.ps1
  • Get-BTBlackoutReport.ps1
  • Get-BTThroughputReport.ps1

Diagnostic Report Scripts

  • Get-BTForest.ps1 : Used to quickly scan a forest, validate credentials and access via Active Directory.

PowerShell Command:
.\get-btforest.ps1 –<parameter>

  • Test-ExchangePowerShellHost.ps1 : Used to validate the PowerShell host connection in the forest using specified credentials. This is a thorough diagnostic tool to aid in configuring the environment for initial Exchange / PowerShell / Migrator Pro for Exchange usage.

PowerShell Command:
.\test-exchangepowershellhost.ps1 –<parameter>

Operational Report Scripts

  • Get-BTMigrationReport.ps1 : Provides reports on the Mailbox Jobs, and the migrations which have been completed. These reports can be displayed on the screen or output to a CSV file.

PowerShell Command:
.\get-btmigrationreport.ps1 –<parameter>

  • Get-BTBlackoutReport.ps1 : Provides reports on the blackouts which have been defined in Migrator Pro for Exchange. These reports can be displayed on the screen or output to a CSV file.

PowerShell Command:
.\get-btblackoutreport.ps1 –<parameter>

  • Get-BTThroughputReport.ps1 : Provides reports on the Throughput results for completed migrations. These reports can be displayed on the screen or output to a CSV file.

PowerShell Command:
.\get-btthroughputreport.ps1 –<parameter>

Executing Diagnostic and Operational Report Scripts

To execute a script:

  1. Open the Windows PowerShell command prompt.

  1. Navigate to the location of the scripts.

  1. Enter the name of the script and provide any additional parameters.  For example:
    .\Get-BTMigrationReport.ps1 –archive –csv c:\migrationreport.csv

The –csv parameter lets you output a report to a new .csv file on the local drive:

You can use the -? parameter to get additional information on the script and available parameters:

Appendix D:  Migration Processing Scripts

The Migration Processing Scripts include these MCP scripts:

  • Confirm-ScheduleMigration.ps1
  • Confirm-BeginMigration.ps1
  • Confirm-EndMigration.ps1

Enabling Migration Customization Scripts

Perform the following steps to enable the migration scripts to be called from Migrator Pro for Exchange.

  1. Click Settings in the main toolbar.
  2. Click the Scripts tab. The script settings are displayed.

  1. Check Enable External Scripts.
  2. Set the Scripts Folder location. For example, c:\contoso\scripts\ps\
  3. Enter the script file name for the Migration Script you want to be called.  For example: In the End Migration Script field, enter Confirm-EndMigration.ps1

Failures designed to halt the migration can be expressed as thrown exceptions or as calls to Write-Error in the confirmation scripts. Both the Schedule and Begin confirmations can halt the migration by failing in this manner. The End confirmation cannot cause the migration to fail if the mailbox is already complete, but it can cause a warning to be reported.

Because the confirmation script runs in a non UI environment, calls in PowerShell such as Write-Host will cause faults and should not be used. Write-Error, Write-Warning, and Write-Verbose are acceptable to use, since they write to specific pipelines which are redirected in PowerShell.

Migration Customization Scripts

If enabled, the Migration Customization scripts are called by the MCP during mailbox migrations. These scripts are installed to C:\Program Files\Binary Tree\Scripts\E2E\Extension; however, they are not usually run manually from the PowerShell console.  The files in the Extension folder are not removed during an uninstall.

Confirm-ScheduleMigration.ps1

This script is called when a mailbox has been scheduled for migration, and can be used to perform any custom actions prior to submitting the mailbox to Exchange.

<add key="Confirm-ScheduleMigration" value="$null"/>

The MCP will not execute any custom scripts for the Schedule Migration step of a mailbox.  This is the default entry in the MCP configuration file.

<add key="Confirm-ScheduleMigration" value="Confirm-ScheduleMigration.ps1"/>

The MCP will execute the Confirm-ScheduleMigration.ps1 script located in the defined script folder for the Schedule Migration step of a mailbox.

<add key="Confirm-ScheduleMigration" value=""/>

The MCP will execute the default script (named Confirm-ScheduleMigration.ps1 in this example) located in the defined script folder during the Schedule Migration step of a mailbox. 

<add key="Confirm-ScheduleMigration" value="MyCmdlet"/>

The MCP will execute the specified cmdlet during the Schedule Migration step of a mailbox. 

Confirm-BeginMigration.ps1

This script is called before a mailbox is migrated, and can be used to perform any prep-work necessary prior to the submission of the mailbox to Exchange.

<add key="Confirm-BeginMigration" value="Confirm-BeginMigration.ps1"/>

The same values listed above for the Confirm-ScheduleMigration script can be used for the Confirm-BeginMigration script.

Confirm-EndMigration.ps1

This script is called after a mailbox is migrated, and can be used to perform any post-processing work necessary after the mailbox has been migrated by Exchange.  Note however that this script is only called if the migration job is Completed or CompletedWithWarning.

<add key="Confirm-EndMigration" value="Confirm-EndMigration.ps1"/>

The same values listed above for the Confirm-ScheduleMigration script can be used for the Confirm-EndMigration script.

Script Parameters

All scripts include the following parameters:

  • $SourceCredential: The source forest PS credentials defined in Migrator Pro for Exchange settings
  • $SourceForest: Source forest name
  • $SourceServer: Source server FQDN
  • $SourceDatabase: Source database DN
  • $SourceMailbox: Source mailbox DN
  • $TargetCredential: The target forest PS credentials defined in Migrator Pro for Exchange settings
  • $TargetForest: Target forest name
  • $TargetServer: Target server FQDN
  • $TargetDatabase: Target database DN
  • $TargetMailbox: Target mailbox DN (not mandatory for the Confirm-BeginMigration.ps1 script)
  • $Status: Current job status string
  • $ControllingForest: optional, not used

 

Appendix E:  E2E Mailbox Job Importer

The Binary Tree Migrator Pro for Exchange Mailbox Job Importer utility is installed as part of Migrator Pro for Exchange.  The Binary Tree Migrator Pro for Exchange Job Importer allows you import a CSV schedule file of mailbox migration jobs from a command line. A CSV file can also be used to update existing mailbox migration job values. A CSV cancel file can be used to cancel mailbox migration jobs.

Migration jobs that are in AutoSuspended or BlackoutSuspended state (only if Suspend When Ready to Complete flag was set) can be modified. For these jobs, only the Do Not Complete Before Date, Do Not Start Before Date, Migration Group, and Priority fields will be updated.

The Auto license 0365 users and Default Usage Location settings in the Tenant Forest General Settings are used by the Migrator Pro for Exchange Job Importer when scheduling mailbox migration to Office 365.

CSV Schedule File Format

The CSV schedule file of mailbox migration jobs must meet the following requirements:

  • The file should not contain headers.
  • No values can be blank except for the Do Not Start Before Date, Do Not Complete Before Date, Communication Language, Migration Group and Blackout Profile.
  • All columns must be included.

The CSV schedule file must include these columns:

Col

Field

Example

Req'd?

Description

1

 

User Principal Name (UPN)

eprouser@contoso.com

Yes

User Principal Name of desired mailbox.

Matched Against: CMTEUP_PersonADData.userPrincipalName

2

 

Target Forest Name

contoso.com

Yes

Name of target forest.

Matched Against: CMTEUP_Forests.ForestName

3

 

Target delivery domain

root1.contoso.com

Yes

Name of target domain for mailbox.

Saved To: CMTEUP_Job.param_TargetDeliveryDomain

4

 

Target Mailbox Database Name

primarymailbox1

No

Name of target mailbox database.  Leave blank if target is an O365 forest.

Matched Against: CMTEUP_ServerDatabase.ServerDatabaseName

5

 

Do not start before date

10/15/2016 09:00AM

No

The time to start the migration, if not immediately.  If specified, must be a valid date/time string.

Saved To: CMTEUP_Job.DoNotStartBefore

6

 

Suspend when ready to complete

"true" or "false"

Yes

Whether migration should be suspended before cutover.

Saved To: CMTEUP_Job.param_SuspendWhenReadyToComplete

7

 

Bad Item Limit

10

No

Number of bad mailbox items to allow before migration is failed. Must be a valid number >= 0.

Saved To: CMTEUP_Job.param_BadItemLimit

8

 

Large Item Limit

75

No

Number of large mailbox items to allow before migration is failed. Must be a valid number >= 0.

Saved To: CMTEUP_Job.param_LargeItemLimit

9

 

Ignore Rule Limit Errors

"true" or "false"

Yes

Whether mailbox rules should be moved to target.

Saved To: CMTEUP_Job.param_IgnoreRuleLimitErrors

10

 

Do not complete before date

10/15/2016 09:00AM

No

When to complete the migration. If specified, must be a valid date/time string AND Suspend when ready to complete must be "true."

Saved To: CMTEUP_Job.param_SuspendWhenReadyToComplete

11

 

Communication Language

0 or "en" or "English"

No

Number or name of a valid culture. Must match a culture using CMTEUP_Culture. CultureName, CMTEUP_Cuture.Culture-Display Name or CMTEUP_Culture.Cul- tureID.  Also, when specified, CMTEUP_UserMailbox.CultureIDLocked=1 is set to prevent updates to this value from the Migrator Pro for Exchange rationalization process.

Saved To: CMTEUP_UserMailbox.CultureID

12

 

Migration Group

MyMigrationGroup1

No

Name of a migration group.  Will either match an existing group on CMTEUP_MigrationGroups.MigrationGroupName, or create a new group if no match can be found.

Saved To: CMTEUP_UserMailbox.MigrationGroupID

13

 

Priority

5

No

Relative priority used to schedule the mailbox migration.  Must be a number between 1 and 100.  If not specified, a default priority of 10 is used. This setting does not apply to migrations to Office 365.

Saved To: CMTEUP_UserMailbox.Priority

14

 

Blackout Profile

MyBlackoutProfile1

No

The name of a Blackout profile to use.  This will either match an existing profile on CMTEUP_Blackout Profiles.BlackoutProfileName or create a new profile if no match can be found.  If not specified, the default blackout profile will be assigned.

Saved To: CMTEUP_UserMailbox.BlackoutProfileID

An example of a valid row in the CSV schedule file looks like:

Test03102@dom1.epro.dom,targetForest.dom,TargetDeliveryDomain.dom,Mailbox Database 12345678,03-25-2014 04:12 pm,true,0,0,true,04-01-2014 05:52 pm,en-US,Group1,10,Profile 1

CSV Cancel File Format

The CSV cancel file used to cancel mailbox migration jobs must meet the following requirements:

  • The file should not contain headers.
  • The file must include column 1: User Principal Name (UPN).

An example of a valid row in the CSV cancel file looks like:

Test03102@dom1.epro.dom

To convert an Excel document to a CSV text file:

  1. Open your Excel file.
  2. Remove any existing header rows.
  3. Format all cells as text by selecting all columns and then right-click > Format Cells > Text.
  4. Save the document as a CSV.

Importing the CSV Schedule File of Mailbox Migration Jobs

To schedule or reschedule mailbox migration jobs by importing the CSV schedule file in the command prompt:

  1. Open a command prompt.
  2. Run C:\Program Files\Binary Tree\Exchange Pro\bin>BinaryTree.E2E.JobImporter /s [CSV schedule file].

  1. The schedule file is validated and saved to the database. If an error is encountered, no jobs are saved.

To review and correct import errors:

  1. Errors will be displayed below the import command in the command prompt window.

  1. Optionally, you can run C:\Program Files\Binary Tree\Exchange Pro\bin>BinaryTree.E2E.JobImporter [CSV schedule file] > OutputReport.txt to generate a text file containing the errors.
  2. Correct the errors in the CSV schedule file and attempt the import again. Optionally, you can validate the CSV schedule file without importing (see steps below).

To validate the CSV schedule file without importing:

  1. In the command prompt, run C:\Program Files\Binary Tree\Exchange Pro\bin>BinaryTree.E2E.JobImporter /v [CSV schedule file]
  2. The number of valid rows and rows with errors are displayed. The CSV schedule file is not imported.

To view the Help file:

  1. In the command prompt, run C:\Program Files\Binary Tree\Exchange Pro\bin>BinaryTree.E2E.JobImporter /? or /help
  2. The help message is displayed.

Cancelling Mailbox Migration Jobs using the CSV Cancel File

Mailbox migrations jobs can be cancelled using a CSV cancel file that contains a list of UPNs associated with migration jobs.

To cancel mailbox migration jobs by importing the CSV cancel file in the command prompt:

  1. Open a command prompt.
  2. Run C:\Program Files\Binary Tree\Exchange Pro\bin>BinaryTree.E2E.JobImporter /c [CSV cancel file].
  3. The migration jobs for the UPNs are cancelled.

Usage Summary

BinaryTree.E2E.JobImporter [[/s <schedule file>] | [/v <schedule file>] | [/c <cancel file>]] [/?] or [/help]

/s <file> : Schedule (or re-schedule) mailboxes for migration. See JobImporter-ReadMe.txt for details on the format of <schedule file>.

/v <file> : Validate the contents of <schedule file>. Any errors found are reported, but no migration jobs are scheduled.

/c <file> : Cancel mailbox migrations for the list of UPNS found in <cancel file>.

/? or /help : Display this help message.

Appendix F:  E2E Public Folder Job Importer

The Binary Tree Migrator Pro for Exchange Public Folder Job Importer utility is installed as part of Migrator Pro for Exchange.  The utility will create a job for each row of the input file. If a job already exists with the same source server name and folder path and same target server name and folder path, the information from the input file will update the existing job instead of creating a new one.

If the user elects to add subfolders for a given row, only subfolders that do not have a job will be added. The utility will not update subfolder job settings based on a parent job.

When the utility creates a job and the user does not specify a value for an optional field, the utility will use the same default as the Add folders to migration queue dialog.

CSV File Format (Scheduling New Jobs and Rescheduling Existing Jobs)

Col

Field

Example

Req'd?

Description

1

 

Source folder path

\TestFolder

Yes

Path of job’s source folder.

Matched Against: CMTEUP_PublicFolder.FolderPath

2

 

Source folder server name

ExchgPro-EX10-1

Yes

Server name where job’s source folder resides.

Matched Against: CMTEUP_Server.ServerName

3

 

Target folder parent path

\

Yes

Path of target’s parent folder.

Matched Against: CMTEUP_PublicFolder.FolderPath

4

 

Target folder server name

QA-ExchgPro-EX10-1

Yes

Server name where job’s target folder resides.

Matched Against: CMTEUP_Server.ServerName

5

 

Target public folder mailbox UPN

pfmbx@qa-epro.dom

Only for Exchg 2013+

UPN of mailbox where target public folder will reside.

Matched Against: CMTEUP_PersonADData.userPrincipalName

6

 

Add or Modify subfolder jobs

True / False

No

Specifies if importer should add or modify jobs for subfolders. Defaults to “true.”

 

7

 

Sync Seconds

30

No

Sets interval for sync job. If value is 0 or omitted, job will run only once.

Saved To: CMTEUP_PublicFolderJob.SyncSeconds

8

 

Scheduled Start Date

10-25-2016 4:12 pm

No

Scheduled start date for the job. If omitted, then defaults to current time.

Saved To: CMTEUP_PublicFolderJob.ScheduledStart

Example valid lines:

\TestFolder,ExchgPro-EX10-1,\,QA-ExchgPro-EX10-1,,true,0,3-25-2015 04:12 pm

\TestFolder,ExchgPro-EX10-1,\,QA-ExchgPro-EX13-1,pfmailbox@qa-epro.dom,true,0,3-25-2015 04:12 pm

CSV File Format (Cancelling existing jobs)

Col

Field

Example

Req'd?

Description

1

 

Source folder path

\TestFolder

Yes

Path of job’s source folder.

Matched Against: CMTEUP_PublicFolder.FolderPath

2

 

Source folder server name

ExchgPro-EX10-1

Yes

Name of server where job’s source folder resides.

Matched Against: CMTEUP_Server.ServerName

3

 

Target folder parent path

\

Yes

Path of target’s parent folder.

Matched Against: CMTEUP_PublicFolder.FolderPath

4

 

Target folder server name

QA-ExchgPro-EX10-1

Yes

Name of server where job’s target folder resides.

Matched Against: CMTEUP_Server.ServerName

5

 

Target public folder mailbox UPN

pfmailbox@ExchgPro.dom

Only for Exchg 2013+

UPN of mailbox where target public folder will reside.

Matched Against: CMTEUP_PersonADData.userPrincipalNam

6

 

Cancel subfolder jobs

True / False

No

Specifies if importer should cancel jobs for subfolders. Defaults to “true.”

 

Example valid lines:

\TestFolder,ExchgPro-EX10-1,\,QA-ExchgPro-EX10-1,,true

\TestFolder,ExchgPro-EX10-1,\,QA-ExchgPro-EX13-1,pfmailbox@ExchgPro.dom,true

Command Line

Available command line switches:

BinaryTree.E2E.PFJobImporter [[/s <schedule file>] | [/v <schedule file>] | [/c <cancel file>]] [/? or /help]

  • /s <file>: Schedule (or re-schedule) public folders for migration.
  • /v <file>: Validate the contents of <schedule file>. Any errors found are reported, but no migration jobs are scheduled.
  • /c <file>: Cancel public folder migrations for the list of folders found in <cancel file>.
  • /? or /help: Display this help message.

Example command line for scheduling (or re-scheduling) a set of public folder jobs:

BinaryTree.E2E.PFJobImporter.exe /s jobfile.csv

Sample output:

Example command line for cancelling a set of public folder jobs:

BinaryTree.E2E.PFJobImporter.exe /c jobfile.csv

Sample output:

Example command line for validating a set of public folder jobs:

BinaryTree.E2E.PFJobImporter.exe /v jobfile.csv

Sample output:

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating