Migrate to Business Central Online from Business Central On-premises

The end-to-end process is described here. In this article, we talk about background information and things to take into consideration.

The migration from Business Central on-premises is in two separate steps:

  • Data replication

    This step starts when you run the Set up Cloud Migration assisted setup guide in Business Central online. At the end of the process, you have a copy of the on-premises data in the relevant environment in Business Central online so that you can verify if the migration went well or not. The migration task has the status Upgrade Pending in the Cloud Migration Management page, and you can rerun the migration multiple times if you want to.

    For example, you've run the assisted setup guide from a test company in a sandbox environment because you worry that many extensions might be problematic. Once the data has been replicated to the sandbox environment, you can use the troubleshooting tools in the Business Central administration center, for example.

  • Data upgrade

    This step starts when you choose the Run Data Upgrade Now action in the Cloud Migration Management page in Business Central online for the specific environment.

Once you have chosen this action, both the Run Migration Now and the Run Data Upgrade Now action can no longer be used for this company in the environment. If the upgrade has failed, an automatic point-in-time restore is run to revert the tenant to the point before upgrade. You can then fix the errors and try the upgrade again. Alternatively, you can start the cloud migration in another environment, or you can restore the current environment from a backup from a point in time before the data upgrade. Or, delete all companies in the current environment and start the migration again.

If you want to migrate more companies, disable the migration, and start the setup again. Or, use the Select Companies to Migrate action from Cloud Migration Management page.

Companies and data

The cloud migration capabilities are optimized to migrate data in batches of up to 10 companies. However, a Business Central on-premises or Dynamics NAV database often includes more companies. In some cases, the database contains several hundred companies.

In such cases, here are our recommendations for how to manage the migration:

  • Break the migration into batches.

  • If the companies include large data sets, break the migration into smaller batches.

    For example, you're migrating 10 companies, but two companies include 50 GB each plus 30-GB shared data. In this example, we recommend that you migrate each of the large companies individually.

  • Be mindful of any extensions that might complicate the migration as described in the Migrate data from extensions section.

  • Check that the company names are valid. For more information, see Company names in the Troubleshooting article.

  • When moving many companies, use Cloud Migration APIs.

    For more information, go to Cloud Migration API Overview. Find samples in the BC Tech GitHUb repo.

Migrate data from extensions

It's highly recommended that you test the impact of any extension in a sandbox environment before you install the extensions in your Business Central production environment to help avoid any data failures or unintended consequences.


The migration from Business Central on-premises is in two separate steps, which gives you better options to test the migration in a sandbox environment before you migrate to the final production environment.

In order to support data migration, tables and table extensions must specify if data from that table must be migrated or not. By default, the ReplicateData property is set to Yes so that, by default, any extension that is installed in the Business Central online environment will have all its tables migrated.

In certain circumstances, you may not want to migrate all data. Here are a few examples:

  • The extension is installed in the Business Central online environment but not in the Business Central on-premises solution

    In this case, Business Central will attempt to migrate the data but show a warning. Since the extension isn't installed on-premises, any table related to that extension table won't migrate, and warning notifications will appear in the cloud migration status page.

    If you own the extension, we recommend that you set the ReplicateData property to No on the extension tables. If you don't, and if you want data to migrate, install the extension in both Business Central online and your on-premises solution. If you don't want data to migrate, uninstall the extension from the Business Central online environment.

  • The extension references a base table

    This can cause your base table to appear empty when you view data in your Business Central online tenant. If that happens, uninstall the extension from your Business Central online tenant, and then run the cloud migration process again.

    Business Central will insert the default values and records into the table extensions automatically. If there any problems, you can use the Repair Companion Table Records action on the Cloud Migration Management page to insert the missing table extension records.


Use the Cloud Migration Management page to verify that data migrated correctly. For example, an extension extends a table in the base application. In SQL Server, the table doesn't contain the data from the base app table for some reason. In this example, the Cloud Migration Management page shows the table as not migrated, and the page that renders the table is blank. The solution is to verify on-premises that the table with the table extension contains the same count of records as the table for the base app table.

For more information, see FAQ about Migrating to Business Central Online from On-Premises Solutions and Troubleshooting Cloud Migration.

Data that isn't migrated

During the data migration process, Business Central doesn't migrate most system tables, users, and permissions.


Currently, record links are not migrated because the links are associated with a user ID, and we do not migrate users from the on-premises environment to the online tenant. You can choose to upvote this feature suggestion.

Upgrading to a new version of Business Central

If you upgrade to a new version of Business Central on-premises, including a cumulative update, then you must update the extensions as well. Depending on your on-premises solution, your Business Central online environment contains different extensions for the cloud migration. For more information, see Business Central Cloud Migration Extensions.

See also

Run the assisted setup guide
Migration On-premises Data to Business Central online
ReplicateData Property
Intelligent Insights with Business Central Online
Migrate Legacy Help to the Dynamics 365 Business Central Format
Upgrading from Dynamics NAV to Business Central Online
Important Information and Considerations for Before Upgrading to Dynamics 365 Business Central Spring 2019