Migrate subscriptions to new commerce experience in batches using the BAM tool


The New commerce experiences for license-based services include many new capabilities and are available to all Cloud Solution Provider (CSPs). For more information, see New commerce experience for license-based services.

The batch migration (BAM) tool described in this article can be downloaded using the sample code via GitHub. You can also batch migrate using the Migration API from the .NET SDK version 3.0.1.

As a partner, you can now migrate subscriptions in batches using a console app tool, the batch migration (BAM) tool. Using the BAM tool, you can efficiently migrate to and adopt the new commerce experience (NCE).

SDK release information

For details and resources regarding SDK releases and the sample app code where partners can access the BAM tool:

Tool introduction

To help you efficiently migrate large quantities of subscriptions into NCE using the BAM tool:

  • Partners can download the BAM tool using the sample code via GitHub

  • The BAM tool supports high quality, repeatable, customizable batch migrations.

  • Uses Excel to manage migration edits.

  • Requires no code.

Experience summary

Using the BAM tool, you can:

  • Retrieve the list of all customers for a specific tenant.

  • Retrieve customer legacy subscriptions in a .csv file.

  • Prepare the exported .csv file for migration and edit subscriptions (like changes to seat counts, 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.

Software prerequisites

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

Installation and account authentication


Currently, the batch migration (BAM) tool is not configured for multitenant apps. When completing authentication, use an AppID of an app with single tenant configuration. Microsoft is evaluating options for enabling the batch migration for a multi tenant applications.

Load the .NET console app

To load the workflow options for batch migration, at the command prompt enter ncebulkmigration [app ID] {UPN ID]

Review the NCE migration instructions for additional details.

From this stage in the application flow, you can:

  • Export the list of customers.
  • Export legacy subscriptions with migration eligibility.
  • Upload subscriptions to be migrated.
  • Export the migration status of batches that have already been uploaded for migration.
  • Export a list of New commerce experience subscriptions.

Filter by customer

To export a list of customers, enter the 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, and customer company name.

Access subscriptions for select customers

In the downloaded customers.csv file, you can remove rows of customers 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 to 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, run the BAM tool and enter command 2. The tool will indicate 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.

subscriptions.csv 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

  • Indirect 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

  • Current Seat Count

  • Start New Term (post migration in NCE)

  • Term (post migration in NCE)

  • Billing Plan (post migration in NCE)

  • Seat Count (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 which subscriptions will be migrated and how

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 to migrate subscriptions of a specific product type or subscriptions under a particular indirect reseller in a batch.

After you have filtered and selected subscriptions, delete any subscriptions that aren't selected for the batch from the .csv file. Doing so prevents unintended migrations.

We recommend a maximum of 200 subscriptions per batch.

The next step is to specify how subscriptions are to be migrated (for example, like-to-like, or with updated start new term, billing frequency, term duration or seat count attributes).

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

  • Start New Term

  • Term

  • Billing Plan

  • Seat Count

The preceding fields represent the instructions or attributes that the NCE subscription will adhere 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.

For a subscription to start a new term in NCE, change the Start New Term flag from FALSE to TRUE. Don't change values outside of the Start New Term, Term, Billing Plan, and Seat Count columns.

Submitting a batch for migration

After you've specified how a batch is to migrate (that is, after you have filtered subscriptions for migration and have updated NCE values, if desired), 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 has been processed for migration, the BAM tool moves that file into the nested processed folder, indicating that migration requests for that batch have been executed. You don't need to manually move files into the processed folder. Files in the processed folder aren't read by the BAM tool to execute migration because they've already been processed.

Next, at the command prompt, run the BAM tool and select option 3, upload migrations. The BAM tool will start reading batch files from the subscriptions folder and executing migration requests. The console window will indicate that the migration requests are being processed. A file for each batch containing the migration IDs is exported and will be 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.

Checking migration status

If the 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, copy or save the exported [batchID].csv file (which is exported to the migrations folder nested in output) to the migrations folder (which is nested in the input folder). Doing so enables the tool to read which batches' status has been 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, run the BAM tool and enter command 4. The BAM tool will indicate that it's looking up migration status and that a file has been exported to the migrationstatus folder. The names of the exported migration status files represent the batch ID of subscriptions contained in the CSVs.

The [batchID].csv file exported to the migrationstatus folder provides updated statuses for migration requests that have been processed. 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.

Exporting a list of new commerce experience subscriptions

To export NCE subscriptions, 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.

Key Scenarios

In the case a user wants to migrate more than 200 subscriptions (the maximum batch size recommendation), multiple batches can be uploaded into the BAM tool. Users can organize folders by a variety of fields to reduce the size of the files they would like to upload to be migrated; users may organize subscriptions to be migrated by indirect reseller, product name, subscription name, and more. If a batch file, which the user has organized, exceeds the maximum recommendation of 200 subscriptions, users may separate one .csv into multiple by effectively copying over subscriptions to new files to maintain the 200 subscription maximum of each batch. For example, if a user would like to migrate 425 subscriptions, this can be split into three separate files (two files can each contain 200 subscriptions and the last one can contain 25).

Multiple files can be uploaded into the batch tool at once; the tool will read migration requests one batch file and a time and will automatically begin reading in other batch files saved to the input directory (in the case multiple batches have been added). The tool will read in batches one-by-one and call the Create Migration API on each subscription individually. Users would not need to wait for one batch file to be finished executing to add additional 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, we don't anticipate that you'll experience throttling when you run the BAM tool. Also, the tool has 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. If a customer’s subscriptions can't be pulled or there are issues while validating subscriptions, a separate .csv titled failedCustomers.csv appears in the output folder of the tool. You can retry pulling/validating subscriptions for those customers again.