How to generate a CSV file for CodeTwo migration tools with PowerShell

Problem:

You would like to prepare a CSV file using PowerShell to import matched source and target mailbox pairs into CodeTwo migration tools.

Solution:

To generate a CSV file containing the information required for mailbox migration, download, configure and run one of the provided PowerShell scripts that best suits your migration scenario.

• CSV file structure
• PowerShell scripts for generating a CSV file for migration
  • Migration between Microsoft 365 (Exchange Online) tenants
  • Migration from Microsoft 365 (Exchange Online) to on-premises Exchange
  • Migration from on-premises Exchange to Microsoft 365 (Exchange Online)
  • Migration between on-premises Exchange servers
• How to run a PowerShell Script

CSV file structure

The CSV file must contain the following data:

The CSV file must also include relevant information about source and target mailbox types (Primary or Archive) in the Source Mailbox Type and Target Mailbox Type fields. This information is generated automatically, based on the settings you use when configuring a script, as shown in the next section.

Optionally, the CSV may contain the DisplayName property as well.

Our program will also recognize column headings if they are used in the file, and CSV files generated using our scripts will contain such headings. To learn more about using a CSV file for migration, watch our video guide or read the appropriate sections in the CodeTwo Office 365 Migration user’s manual or the CodeTwo Exchange Migration user’s manual.

PowerShell scripts for generating a CSV file for migration

PowerShell scripts are available for the following migration scenarios:

• Migration between Microsoft 365 (Exchange Online) tenants
• Migration from Microsoft 365 (Exchange Online) to on-premises Exchange
• Migration from on-premises Exchange to Microsoft 365 (Exchange Online)
• Migration between on-premises Exchange servers

Before you run a script, it must be configured. The details are provided individually for each of the scripts.

Migration between Microsoft 365 (Exchange Online) tenants

This script will generate a CSV file containing the following fields: Source Email, Source ID, Display Name, Source Mailbox Type, Target Mailbox Type, Target Email, Target ID.

Download script

To use the script, open it in a text editor, such as Notepad, and enter the following information in the configuration of script section:

• $SourceUPN – User Principal Name of the account you are going to use to sign in to the source server.
• $TargetUPN – User Principal Name of the account you are going to use to sign in to the target server.
• $migrations – by default, you don't need to modify the 4 code snippets in this section in any way. However, if you want to cross-migrate primary mailboxes to archive mailboxes and vice versa (after choosing Migrate primary and archive mailboxes option in this step of the migration job wizard), you need to:
  • comment the first two snippets by adding # at the beginning of each line to disable them (Fig. 1., item 1).
  • then uncomment the last two snippets by removing the # at the beginning of each line to enable them (Fig. 1., item 2).

  
  Fig. 1. The script settings modified to let you complete cross-migration (primary to archive and vice versa).

• $ItemsPerFile – the maximum number of rows (entries) in the generated CSV file.

Accounts used to sign in to Exchange Online must have the Global Administrator role assigned.

When this information is entered, save changes to the script and close the editor. You can now run the script.

Migration from Exchange Online (Microsoft 365) to on-premises Exchange

This script will generate a CSV file containing the following fields: Source Email, Source ID, Display Name, Source Mailbox Type, Target Mailbox Type, Target Email, Target ID.

Download script

To use the script, open it in a text editor, such as Notepad, and enter the following information in the configuration of script section:

• $SourceUPN – User Principal Name of the account you are going to use to sign in to the source server.
• $TargetUri – here, you need to replace Your.Target.Exchange.Server.Full.Name with the Fully Qualified Domain Name (FQDN) of your target Exchange server, e.g. http://exchange.my-company.com/powershell/.
  If necessary, change http to https as well.
• $TargetAuthentication – target server authentication method, Basic or Kerberos.
• $migrations – by default, you don't need to modify the 4 code snippets in this section in any way. However, if you want to cross-migrate primary mailboxes to archive mailboxes and vice versa (after choosing Migrate primary and archive mailboxes option in this step of the migration job wizard), you need to:
  • comment the first two snippets by adding # at the beginning of each line to disable them (see Fig. 1., item 1).
  • then uncomment the last two snippets by removing the # at the beginning of each line to enable them (see Fig. 1., item 2).
• $ItemsPerFile – the maximum number of rows (entries) in the generated CSV file.

The account used to sign in to Exchange Online must have the Global Administrator role assigned. In case of on-premises Exchange, the account must be a member of the Organization Management role group.

When this information is entered, save changes to the script and close the editor. You can now run the script.

Migration from on-premises Exchange to Exchange Online (Microsoft 365)

This script will create a CSV file containing the following fields: Source Email, Source ID, Display Name, Source Mailbox Type, Target Mailbox Type, Target Email, Target ID.

Download script

To use the script, open it in a text editor, such as Notepad, and enter the following information in the configuration of script section:

• $SourceUri – here, you need to replace Your.Source.Exchange.Server.Full.Name with the Fully Qualified Domain Name (FQDN) of your source Exchange server, e.g. http://exchange.my-company.com/powershell/.
  If necessary, change http to https as well.
• $SourceAuthentication – source server authentication method, Basic or Kerberos.
• $TargetUPN – User Principal Name of the account you are going to use to sign in to the target server.
• $migrations – by default, you don't need to modify the 4 code snippets in this section in any way. However, if you want to cross-migrate primary mailboxes to archive mailboxes and vice versa (after choosing Migrate primary and archive mailboxes option in this step of the migration job wizard), you need to:
  • comment the first two snippets by adding # at the beginning of each line to disable them (see Fig. 1., item 1).
  • then uncomment the last two snippets by removing the # at the beginning of each line to enable them (see Fig. 1., item 2).
• $ItemsPerFile – the maximum number of rows (entries) in the generated CSV file.

The account used to sign in to on-premises Exchange must be a member of the Organization Management role group. In case of Exchange Online, the account must be assigned the Global Administrator role.

When this information is entered, save changes to the script and close the editor. You can now run the script.

Migration between on-premises Exchange servers

This script will create a CSV file containing the following fields: Source Email, Source ID, Display Name, Source Mailbox Type, Target Mailbox Type, Target Email, Target ID.

Download script

To use the script, open it in a text editor, such as Notepad, and enter the following information in the configuration of script section:

• $SourceUri – here, you need to replace Your.Source.Exchange.Server.Full.Name with the Fully Qualified Domain Name (FQDN) of your source Exchange server, e.g. http://exchange.my-company.com/powershell/.
  If necessary, change http to https as well.
• $SourceAuthentication – source server authentication method, Basic or Kerberos.
• $TargetUri – see the explanations for $SourceUri, but this time use the FQDN of your target Exchange server.
• $TargetAuthentication – target server authentication method, Basic or Kerberos.
• $migrations – by default, you don't need to modify the 4 code snippets in this section in any way. However, if you want to cross-migrate primary mailboxes to archive mailboxes and vice versa (after choosing Migrate primary and archive mailboxes option in this step of the migration job wizard), you need to:
  • comment the first two snippets by adding # at the beginning of each line to disable them (see Fig. 1., item 1).
  • then uncomment the last two snippets by removing the # at the beginning of each line to enable them (see Fig. 1., item 2).
• $ItemsPerFile – the maximum number of rows (entries) in the generated CSV file.

Accounts used to sign in to on-premises Exchange must be members of the Organization Management role group.

When this information is entered, save changes to the script and close the editor. You can now run the script.

How to run a PowerShell script

Follow the instructions below to run a PowerShell script that will generate a CSV file containing the source and target mailbox information required for successful migration:

1. Download a PowerShell script file.
2. Open the script in a text editor, such as Notepad.
3. Find the section of the script that starts with:

# =================== configuration of script ===============================

4. Enter the required information in this section of the script, save changes and close the editor. Details regarding the information required by each of the scripts are provided in their descriptions above.
5. Run  PowerShell.
6. In PowerShell, navigate to the folder where the script is located.
7. Type .\ and press Tab until the name of your script is displayed and press Enter to run it.
8. The output CSV file will be saved in the same folder as the script.

The generated CSV file will look similar to the one shown in Fig. 2.

Fig. 2. A CSV file generated using one of the scripts provided in this article.