Migrate subscriptions to new commerce experience using the batch migration tool (BAM)

Artikkeli
10/28/2024

You can efficiently migrate large numbers of subscriptions into the new commerce experience (NCE) using the batch migration tool (BAM).

(You can also migrate batches of subscriptions using the Migration API from .NET SDK version 3.0.1).

Important

As of June 2023, the latest Partner Center .NET SDK release 3.4.0 is now archived. You can download the SDK release from GitHub, along with a readme file that contains useful information.

Partners are encouraged to continue to use the Partner Center REST APIs.

The BAM tool:

Supports high quality, repeatable, customizable batch migrations.
Uses Excel to manage migration edits
Requires no code
Can be downloaded using the sample code at GitHub.

Batch migration tool capabilities

Using the BAM tool, you can:

Retrieve a list of all customers for a tenant.
Retrieve customer legacy subscriptions in a .csv file.
Prepare am exported .csv file for migration, and edit subscriptions (such as changes to seat count, term, and billing cycle) during migration.
Upload an updated subscription .csv file into the tool, after which the tool executes the migration requests.
Review the status of migration requests.
Download all the NCE subscriptions for all of the list of customers in the input file.

Prerequisites

The .NET 6.0 SDK is required to use the BAM tool.

SDK and sample code

For details and resources regarding SDK releases, and sample app code that you can use to access the BAM tool:

Use the BAM tool

Note

For detailed instructions, see Step-by-step flow of migrating a batch.

To load the workflow options for batch migration, use the following steps:

Run the BAM tool, and at the command prompt, enter ncebulkmigration [app ID] {UPN ID].

This stage allows the partner to:

Export a list of customers.
Export legacy subscriptions with migration eligibility.
Upload subscriptions to be migrated.
Export the migration status of batches already uploaded for migration.
Export a list of new commerce experience subscriptions.

Account authentication

The BAM tool isn't configured for multitenant apps. When completing authentication, use the AppID of an app with single tenant configuration.

Microsoft is evaluating options for enabling the batch migration for multitenant applications.

Export a list of customers

To export a list of customers, use the following steps:

Run the BAM tool and enter command 1.

The exported list of customers is saved to the output file of the BAM tool's folders.

View exported customers in the file customers.csv.

For each customer under a partner tenant ID, you can view:

Customer tenant ID
Customer domain
Customer company name

Access subscriptions for select customers

You can remove rows of customers from the downloaded customers.csv file whose subscriptions you don't want to export in the next file download. The customers who remain in the file are validated for migration eligibility during the next step in the BAM tool's work flow.

Save the updated customers.csv file in the input folder so you can execute the next step of receiving subscriptions for the specified customers.
- The input folder has two nested folders, migrations and subscriptions.
- Don't place customers.csv in the nested folders. Keep it in the input folder.

To export subscriptions with migration eligibility, use the following steps:

Run the BAM tool and enter command 2.

The tool runs and indicates that subscriptions are being validated for eligibility. After export is complete, the list of subscriptions for the specified customers is available in the output folder as subscriptions.csv, which provides a list of all legacy subscriptions (both active and suspended) for the customers previously specified.

The following fields can be viewed for each subscription:

Partner tenant ID
vIndirect Reseller PartnerID*
Customer Name
Customer Tenant ID
Legacy Subscription ID
Legacy Subscription Name
Legacy Product Name
Expiration Date
Migration Eligible (True or False)
Current Term
Current Billing Plan
urrent Seat Count
Start New Term (post migration in NCE)
Term (post migration in NCE)
Billing Plan (post migration in NCE)
Seat Counts (post migration in NCE)
Add On (True or False)
Base Subscription (if an add-on)
Migration Ineligibility Reason (if subscription isn't eligible for migration)

Determine the subscriptions to migrate

Using the preceding fields, you can filter the exported list of subscriptions to determine which subscriptions you want to migrate to NCE in a batch. For example, you might filter migration batches based on product type or to a particular indirect reseller.

Partners can remove subscriptions from the .csv batch they do not want migrated.

We recommend exporting no more than 200 subscriptions per batch. (See Migrate more than 200 subscriptions later in this article if you need to migrate more.)

The next step is to specify how subscriptions are migrated. Partners decide which properties to apply to the migration.

You can overwrite the following fields in rows for subscriptions you want to migrate:

Start New Term
Term
Billing Plan
Seat Counts

The preceding fields represent the instructions or attributes that the NCE subscription adheres to post-migration. The default values for these fields are the values of the legacy subscriptions being migrated. If no changes are made to a field, the corresponding NCE subscription has the same value as the legacy subscription it migrated from. For example, if a legacy subscription being migrated has a Current Seat Count of two, and no changes are made to the Seat Count field, the NCE subscription will have a seat count of two after migration.

To start a subscription with a new term in NCE, use the following step:

Change the Start New Term flag from FALSE to TRUE.

Don't change values outside of the following columns:
- Start New Term
- Term
- Billing Plan
- Seat Count

Upload a batch for migration

Save the updated subscriptions.csv file in the subscriptions folder that is nested in the input folder. Each file saved in the subscriptions folder represents a batch to migrate.

After a file from the subscriptions folder is processed and executed for migration, the BAM tool moves that file into the nested processed folder. You don't need to manually move files into the processed folder. The BAM tool ingores files in the processed folder since they are already processed.

To upload migrations, use the following step:

At the command prompt, run the BAM tool and select option 3, upload migrations, after which:
- The BAM tool reads batch files from the subscriptions folder and executes migration requests.
- The console window indicates that migration requests are being processed.
  
  A file for each batch containing the migration IDs is exported and is available in the migrations folder that is nested in the output folder.
  - Exported files are labeled [batchID].csv.
  - [batchID].csv has the same fields as the input subscriptions.csv file, but with two more columns: Batch ID and Migration ID.
  - Batch ID is the same for every subscription in the file, indicating that these subscriptions belong to the same batch or set of migration requests that were processed together.
  - The Batch ID is also reflected in the name of the .csv file: [batchID].csv.

Check migration status

If a migration is successful, its migration status is Completed.

If a migration is unsuccessful, its migration status is Failed, and you can view the reason for the failure.

A Migration ID is unique to each subscription that is migrated, so you can use Migration ID to track migration status.

An NCE Subscription ID is also populated upon successful migration.

To retrieve a refreshed status file for a batch, use the following step:

Copy or save the exported [batchID].csv file from the output/migrations folder to the input/migrations folder.

Doing so enables the tool to read which batches' status is requested and prepare reports to export.

Status files aren't updated automatically. To retrieve updated statuses, a new request must be made each time.

To retrieve updated migration statuses, use the following step:

Run the BAM tool and enter command 4.

The BAM tool runs and indicates that it's looking up migration status and is exporting status to the migrationstatus folder. The names of the exported migration status files represent the batch ID of subscriptions contained in the .csv files.

The [batchID].csv file exported to the migrationstatus folder provides updated statuses for processed migration requests. If more than one batch is represented in the file, use the Batch ID column to filter to access statuses of requests in a particular batch.

Export a list of new commerce experience subscriptions

To export NCE subscriptions, use the following step:

Run the BAM tool and enter command 5.

The exported list is saved in the output folder. This step isn't required for migration, but you can use it to organize NCE subscriptions for different customers.

Migrate more than 200 subscriptions

If you want to migrate more than 200 subscriptions (which is the maximum recommended batch size), you can upload multiple batches into the BAM tool. You can organize folders by various fields to reduce the size of the files that you want to upload to be migrated:

Indirect reseller
Product name
Subscription name
Other criteria

Batch files that exceed the maximum recommended size of 200 subscriptions can be broken up into separate .csv files.

Upload multiple files

You can upload multiple files into the BAM tool at once. The tool reads migration requests one batch file at a time until it finishes processing all the files in the input directory.

The BAM tool reads batches one-by-one and calls the Create Migration API on each subscription individually.

You don't need to wait for one batch file to finish executing to add more batch files to the input directory.

Rate limits and throttling

To execute command 2 (retrieving subscriptions for customers and validating those subscriptions for migration), the BAM tool calls the Validate Migration API. The rate limit of the Validate Migration API is 450 calls per partner + customer combination in five minutes. With this rate limit and the current latency of the Validate Migration API, most partners won't experience throttling when you run the BAM tool. Partners can upate the concurrency limits to ensure that throttling doesn't occur.

However, if an issue does occur, you can keep track of which customer's subscriptions weren't pulled and validated. A separate .csv titled failedCustomers.csv appears in the output folder of the tool if the customer's subscriptions can't be pulled or if there are other validation issues. You can retry pulling and validating subscriptions for those customers again.