Performing the Migration

Migration is performed with the connect_migration.py script. We recommend that you perform the migration by following these steps:

  1. Run the script in dry-run execution mode. (No actual migration is performed in this execution mode.)

  2. Check the report and log files produced by the script. If there are any issues, analyze and fix them before running the script in production mode.

  3. Run the script in production execution mode.

  4. Check the report and log files produced by the script. If there are any issues, analyze and fix them.

  5. In BSS, check the orders created by the script. If there are any issues, analyze and fix them.

    Important: (for New Subscription Mode) After you fix those issues and the failed orders are processed, you must manually cancel the appropriate source subscriptions.

Parameters

The parameters of the script that you can use when performing the migration are in the tables.

Migration-specific Parameters

Parameter name Mandatory Description
--migrationmode Yes

The migration mode of the script. You must specify one of these values, depending on which migration mode you need:

  • new (for New Subscription Mode)

  • switch (for Switch Plan Mode)

To learn the preconditions and how migration is performed depending on the migration mode, see Supported Migration Modes.
--for-expiration-date No

With this parameter, you can migrate only those CloudBlue Commerce subscriptions whose Microsoft subscriptions have a specific expiration date.

To specify an expiration date, you must use the YYYY-MM-DD format and enclose that date in single quotes. For example: --for-expiration-date '2022-04-12'

Your CSV file specified in the source-data parameter must have the following columns:

  • OaCustomerId: The CloudBlue Commerce identifiers of customer accounts

  • OaSubscriptionId: The CloudBlue Commerce identifiers of source CloudBlue Commerce subscriptions

  • MsCommitmentEndDate: The expiration dates for the Microsoft subscriptions of the source CloudBlue Commerce subscriptions.

To learn how to prepare that CSV file, see Getting Microsoft 365 Subscription Expiration Dates.

Note: This parameter can be used only with the source-data parameter.
--skip-mca-check No

When started, for every customer account, the script checks whether the Microsoft Customer Agreement was accepted by the owner of that customer account. Each check may take up to several seconds as the script makes calls to the Microsoft APIs.

When specified, the script does not perform that check.

Important: You can use this parameter only for test runs. For example, you can specify it when you evaluate how the migration script works.

Warning: Do not use this parameter for actual migration.
--skip-nce-eligibility No

When started, the script checks whether every Microsoft 365 CSP license can be upgraded to a Microsoft 365 NCE license. Each check may take up to several seconds as the script makes calls to the Microsoft APIs.

When specified, the script does not perform that check.

Important: You can use this parameter only for test runs. For example, you can specify it when you evaluate how the migration script works.

Warning: Do not use this parameter for actual migration.
--threads No

The number of threads to be created for performing the collection and validation of migration data (from 0 to 16).

If not specified or specified with the 0 value, the script automatically determines how many threads it needs to create based on the number of CPU cores in your system.
--threads-l2 No

The number of threads to be created for migrating the source subscriptions of a customer account (from 0 to 8). If not specified, up to 4 threads are created per customer account being processed.

If specified with the 0 value, the script automatically determines how many threads it needs to create based on the number of CPU cores in your system.

For example, if your typical customer account has 5 source subscriptions, set this parameter to 5.

Note: The threads-l2 and threads-l3 parameters are the main parameters that affect the performance of migration. For example, if you set threads-l2 to 5 and threads-l3 to 20, up to 100 threads will be created for migrating source subscriptions and processing customer accounts with source subscriptions.

--threads-l3 No

The number of threads to be created for processing customer accounts with source subscriptions (from 0 to 96). If not specified, up to 16 threads are created.

If specified with the 0 value, the script automatically determines how many threads it needs to create based on the number of CPU cores in your system.

Note: The threads-l2 and threads-l3 parameters are the main parameters that affect the performance of migration. For example, if you set threads-l2 to 5 and threads-l3 to 20, up to 100 threads will be created for migrating source subscriptions and processing customer accounts with source subscriptions.

--timeout-order-process No

New Subscription Mode

When migrating a Microsoft 365 CSP subscription, the script creates a sales order for each Microsoft 365 CSP license included in that subscription. It then waits 600 seconds (the default timeout interval) for each sales order to be completed or fail as the processing of that sales order is performed on the CloudBlue Connect and Microsoft sides. If each sales order created for that subscription is completed within that timeout interval, the script creates a cancellation order for that subscription, and it is considered migrated. Otherwise, no cancellation order is created, and you must manually complete the migration of that Microsoft 365 CSP subscription.

With this parameter, you can redefine the default timeout interval of 600 seconds, depending on how long such sales orders are processed for your CloudBlue Commerce installation.

Switch Plan Mode

When migrating a Microsoft 365 CSP subscription, the script creates a change order for that subscription. It then waits 600 seconds (the default timeout interval) for that change order to be completed or fail as the processing of that change order is performed on the CloudBlue Connect and Microsoft sides. If that change order is completed within that timeout interval, that subscription is considered migrated. Otherwise, that subscription is not considered as migrated, and you must manually complete the migration of that Microsoft 365 CSP subscription.

With this parameter, you can redefine the default timeout interval of 600 seconds, depending on how long such change orders are processed for your CloudBlue Commerce installation.

General Parameters

Parameter name Mandatory Description
--source-data Yes

  • The path to a CSV file that contains the identifiers of the subscriptions that you need to migrate. That file must have a column named OaSubscriptionId. In that column, you must specify the identifiers of those subscriptions. For example:

    subscription_ids.csv 

    OaSubscriptionId
1000098
1000099

  • The path to a CSV file that contains the identifiers of the customer accounts whose subscriptions you need to migrate. That file must have a column named OaCustomerId. In that column, you must specify the identifiers of those customer accounts. For example:

    customer_account_ids.csv 

    OaCustomerId
1000098
1000099

If you want the script to migrate only those CloudBlue Commerce subscriptions whose Microsoft subscriptions have a specific expiration date, you must:

  1. Use a CSV file where expiration dates are specified in the MsCommitmentEndDate column for the Microsoft subscriptions of the source CloudBlue Commerce subscriptions. To prepare that CSV file, follow the instructions in Getting Microsoft 365 Subscription Expiration Dates.

  2. Specify the expiration date you need in the for-expiration-date parameter when migrating subscriptions with the script, as described in Performing the Migration.

Note: The source-data, accounts, resellers, and subscriptions parameters are mutually exclusive. You must use only one of them when running the script.
--accounts Yes

The identifiers of the customer accounts whose subscriptions you need to migrate. These identifiers must be separated with commas and enclosed in single quotes. For example: '1000098,1000099'

Note: The source-data, accounts, resellers, and subscriptions parameters are mutually exclusive. You must use only one of them when running the script.
--resellers Yes

The identifiers of the reseller accounts whose direct customers have subscriptions intended for the migration. These identifiers must be separated with commas and enclosed in single quotes. For example: '1000098,1000099'

Note: The source-data, accounts, resellers, and subscriptions parameters are mutually exclusive. You must use only one of them when running the script.
--subscriptions Yes

The identifiers of the subscriptions you need to migrate. These identifiers must be separated with commas and enclosed in single quotes. For example: '1000098,1000099'

Note: The source-data, accounts, resellers, and subscriptions parameters are mutually exclusive. You must use only one of them when running the script.
--sourcemodel Yes

The type of the application whose subscriptions you need to migrate. You must specify one of these values, depending on which application is installed:

  • odin (for the Microsoft 365 application)

  • softcom (for the O365_APS2 application)
--connect-products Yes The path to a JSON configuration file that contains CloudBlue Connect product descriptions. You must specify the path to the file that you prepared in Preparing a JSON Configuration File with Target Product Descriptions. For example: connect_product_descriptions.json
--csp-nce-mapping Yes The path to a CSV configuration file that contains the mappings between Microsoft 365 CSP licenses and Microsoft 365 NCE licenses. You must specify the path to the file that you prepared in Preparing a CSV Configuration File with CSP to NCE License Mappings. For example: csp_to_nce_license_mappings.csv
--dry-run No

When specified, the script is run in dry-run execution mode. In this mode, the script performs checks and stores the results in report and log files. No actual actions are performed.

Important: We recommend that you first run the script in dry-run execution mode and check the report and log files produced by the script.
--verbose No When specified, the script writes more details to its log files.
--out-root-path No

The root directory for log and report files produced by the script.

By default, the script uses the directory where it is placed as the root directory.

Note: If the root directory that you specified does not exist, the script will create it.
--oa-api-user No The username of a user for connecting to the OSS and BSS XML-RPC APIs. You must specify it if HTTP authentication is turned on for the APIs.
--oa-api-user-password No The password of a user for connecting to the OSS and BSS XML-RPC APIs. You must specify it if HTTP authentication is turned on for the APIs.
-h No When specified, the script prints its parameters and their short description.

How To Run the Script

New Subscription Mode

To run the script, go to the respective directory on your cloud MN and execute this command:

python connect_migration.py migration --migrationmode new [OTHER PARAMETERS]

Here are some examples tailored to various scenarios:

  • Run the script in dry-run execution mode for the Microsoft 365 application:

    python connect_migration.py migration --migrationmode new --dry-run --source-data subscription_ids.csv --sourcemodel odin --connect-products connect_product_descriptions.json --csp-nce-mapping csp_to_nce_license_mappings.csv

  • Run the script in production execution mode for the Microsoft 365 application:

    python connect_migration.py migration --migrationmode new --source-data subscription_ids.csv --sourcemodel odin --connect-products connect_product_descriptions.json --csp-nce-mapping csp_to_nce_license_mappings.csv

  • Run the script in dry-run execution mode for the O365_APS2 application:

    python connect_migration.py migration --migrationmode new --dry-run --source-data subscription_ids.csv --sourcemodel softcom --connect-products connect_product_descriptions.json --csp-nce-mapping csp_to_nce_license_mappings.csv

  • Run the script in production execution mode for the O365_APS2 application:

    python connect_migration.py migration --migrationmode new --source-data subscription_ids.csv --sourcemodel softcom --connect-products connect_product_descriptions.json --csp-nce-mapping csp_to_nce_license_mappings.csv

Plan Switch Mode

To run the script, go to the respective directory on your cloud MN and execute this command:

python connect_migration.py migration --migrationmode switch [OTHER PARAMETERS]

Here are some examples tailored to various scenarios:

  • Run the script in dry-run execution mode for the Microsoft 365 application:

    python connect_migration.py migration --migrationmode switch --dry-run --source-data subscription_ids.csv --sourcemodel odin --connect-products connect_product_descriptions.json --csp-nce-mapping csp_to_nce_license_mappings.csv

  • Run the script in production execution mode for the Microsoft 365 application:

    python connect_migration.py migration --migrationmode switch --source-data subscription_ids.csv --sourcemodel odin --connect-products connect_product_descriptions.json --csp-nce-mapping csp_to_nce_license_mappings.csv

  • Run the script in dry-run execution mode for the O365_APS2 application:

    python connect_migration.py migration --migrationmode switch --dry-run --source-data subscription_ids.csv --sourcemodel softcom --connect-products connect_product_descriptions.json --csp-nce-mapping csp_to_nce_license_mappings.csv

  • Run the script in production execution mode for the O365_APS2 application:

    python connect_migration.py migration --migrationmode switch --source-data subscription_ids.csv --sourcemodel softcom --connect-products connect_product_descriptions.json --csp-nce-mapping csp_to_nce_license_mappings.csv

Script Output

After each run, the script outputs migration statistics and the location of its log and report files to your console. For example:

...
Report for subscription #1000122   : ............................. outresult/m365_20220413T134952/subscriptions/subs_C1000048_1000122.csv

Errors data to file                : .......................................................... outresult/m365_20220413T134952/errors.csv
Warnings data to file              : ........................................................ outresult/m365_20220413T134952/warnings.csv
Results migrated subscriptions     : ................................................. outresult/m365_20220413T134952/migrate_results.csv
Failed migrated subscriptions      : ............................................ outresult/m365_20220413T134952/fail_migrate_results.csv
Successful migrated subscriptions  : ......................................... outresult/m365_20220413T134952/success_migrate_results.csv
Log file name                      : ........................................................................... migration_2022-04-13.log
##############################################################
### dry-run mode                                           ###
##############################################################

Statistics:
---------------------------------------------------------------
preparation phase
---------------------------------------------------------------
connect products (configured and available) ................ 1
customers total ............................................ 5
customers ready for migration .............................. 0
customers with errors ...................................... 5
customers with warnings .................................... 3
subscriptions total ........................................ 10
subscriptions prepared for migration  ...................... 0
subscriptions with errors .................................. 10
subscriptions with warnings ................................ 0
---------------------------------------------------------------
migration phase
---------------------------------------------------------------
customers migrated to connect .............................. dry-run mode
subscriptions migrated to connect .......................... dry-run mode
subscriptions with migration errors ........................ dry-run mode
---------------------------------------------------------------

Done.
...

Log and Report Files

  • The script writes log records to files named migration_<YYYY-MM-DD>.log. Log records are appended to the same log file for each day.

  • After each run, the script generates these reports:

    • outresult/m365_<TIMESTAMP>/subscriptions/subs_C<CUSTOMER_ACCOUNT_ID>_<SOURCE_SUBSCRIPTION_ID>.csv contains detailed information about a subscription of a customer account.

    • outresult/m365_<TIMESTAMP>/errors.csv contains information about subscriptions whose processing completed with errors.

    • outresult/m365_<TIMESTAMP>/warnings.csv contains information about subscriptions whose processing completed with warnings.

    • outresult/m365_<TIMESTAMP>/migrate_results.csv contains information about all subscriptions.

    • outresult/m365_<TIMESTAMP>/fail_migrate_results.csv contains information about failed subscriptions.

    • outresult/m365_<TIMESTAMP>/success_migrate_results.csv contains information about successfully migrated subscriptions.

      Note: After you run the script in dry-run execution mode, it will write the identifiers of subscriptions that are ready for migration in a report file named outresult/m365_<TIMESTAMP>/success_migrate_results.csv. You can then use that file as an input file when running the script in production execution mode.

© 2022 Ingram Micro, Inc. All Rights Reserved. Privacy Policy, Terms of Use and Legal