{"title":"Custom migration from any SQL source","url":"https://jonas-paprotka.de/docs/dev-itpro/administration/cloud-migration-custom-migration/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/cloud-migration-custom-migration, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/cloud-migration-custom-migration","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Learn how to set up and run custom migrations from any SQL-based source to Business Central online, including no-code options and custom migration apps.","date":"2026-05-29","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Custom migration from any SQL source","slug":"custom-migration-from-any-sql-source","at":0,"chars":17352},{"level":2,"title":"Determine your migration approach","slug":"determine-your-migration-approach","at":202,"chars":1214},{"level":2,"title":"No-code custom migration from any SQL source","slug":"no-code-custom-migration-from-any-sql-source","at":1416,"chars":4944},{"level":3,"title":"Table mapping types","slug":"table-mapping-types","at":2031,"chars":1219},{"level":3,"title":"Prerequisites","slug":"prerequisites","at":3250,"chars":482},{"level":3,"title":"Run a no-code custom migration","slug":"run-a-no-code-custom-migration","at":3732,"chars":2628},{"level":2,"title":"Create your own migration tool","slug":"create-your-own-migration-tool","at":6360,"chars":8023},{"level":3,"title":"Implementation overview","slug":"implementation-overview","at":6647,"chars":546},{"level":3,"title":"Interfaces to implement","slug":"interfaces-to-implement","at":7193,"chars":1563},{"level":4,"title":"Custom Migration Provider interface","slug":"custom-migration-provider-interface","at":7221,"chars":904},{"level":4,"title":"Custom Migration Table Mapping interface","slug":"custom-migration-table-mapping-interface","at":8125,"chars":631},{"level":3,"title":"Table mapping structure","slug":"table-mapping-structure","at":8756,"chars":714},{"level":3,"title":"Company table requirement","slug":"company-table-requirement","at":9470,"chars":333},{"level":3,"title":"Implementation example","slug":"implementation-example","at":9803,"chars":3075},{"level":4,"title":"Step 1: Extend the enum","slug":"step-1-extend-the-enum","at":9921,"chars":431},{"level":4,"title":"Step 2: Implement the provider codeunit","slug":"step-2-implement-the-provider-codeunit","at":10352,"chars":2526},{"level":3,"title":"Best practices","slug":"best-practices","at":12878,"chars":714},{"level":3,"title":"Working implementations for reference","slug":"working-implementations-for-reference","at":13592,"chars":791},{"level":2,"title":"Extend the Business Central 14 reimplementation","slug":"extend-the-business-central-14-reimplementation","at":14383,"chars":2581},{"level":3,"title":"Extension patterns","slug":"extension-patterns","at":15492,"chars":653},{"level":3,"title":"Disable standard modules","slug":"disable-standard-modules","at":16145,"chars":819},{"level":2,"title":"Related information","slug":"related-information","at":16964,"chars":388}],"text":"# Custom migration from any SQL source\nCustom migrations let you migrate data from any SQL-based source to a Business Central environment. This article explains how to set up and run custom migrations.\n## Determine your migration approach\nThere are three ways to run a custom migration, depending on your source system and requirements:\nApproach|What gets migrated|When to use\n#no-code-custom-migration-from-any-sql-source|Only the tables you manually select|Small number of tables, testing, or post-migration additions\nFull custom migration app<#create-your-own-migration-tool>|Only what your app defines|Migrating from non-Business Central systems where you need full control\n#extend-the-business-central-14-reimplementation|Standard Business Central data plus your custom tables|Business Central 14 on-premises to Business Central online with custom tables to migrate\n> TIP\n> If you're migrating from Business Central 14 on-premises and only need to add a few custom tables, extending the Business Central 14 reimplementation is the fastest path. You get all standard data migration for free and only write code for your custom entities.\n> TIP\n> Even if you're not migrating from Business Central, the Business Central 14 reimplementation app<migrate-bc14-reimplementation> is a useful reference. Study its patterns for buffer tables, phased execution, and error handling when building your own custom migration.\n## No-code custom migration from any SQL source\nFor specific scenarios, you need to migrate only a small number of individual tables to a cloud environment. For example:\n You're migrating some additional tables to a company that has previously migrated.\n You want to test performance in a sandbox environment using large tables with real data from your on-premises database before committing to a full migration.\nNo-code custom migration is highly controlled. You select exactly which tables to copy, and nothing else is migrated. This approach lets you migrate individual tables manually without writing any code.\n### Table mapping types\nTo set up a no-code custom migration scenario, you create one or more table mappings. A table mapping defines how data moves from your source database to Business Central online. Each mapping specifies a source table, a destination table, and settings that control how the data is copied.\nWhen you create a table mapping, you also choose the mapping type, which determines when the data is copied:\nMapping type|When data is copied|Use for\nReplication|During data replication runs|Most tables - this is the standard way to move data\nSetup|During the assisted setup guide, before companies are created|Small configuration tables needed to configure the migration itself\nUse Replication for most tables. Use Setup only for small tables that your migration logic needs to read during the assisted setup guide - for example, a table that lists which companies to create. Setup mappings run before companies exist in the cloud, so keep them minimal to avoid slowing down the assisted setup guide.\n> NOTE\n> Setup mappings are for advanced scenarios only. The standard Business Central, Dynamics GP, and Dynamics SL migration tools don't use them. Most custom migrations only need Replication mappings.\n### Prerequisites\nThe source database must contain a table with company names. The table can have any name, but it must contain the following fields:\n|Field|Type|Notes|\n|Name|nvarchar(30)|Primary key|\n|`Display Name`|nvarchar(250)||\nIf this table doesn't exist, create it using a SQL script before running the migration.\n> NOTE\n> System tables that are inaccessible by AL code can't be migrated. This limitation applies to all migration tools built on the cloud migration platform.\n### Run a no-code custom migration\n1. Sign in to Business Central online<https://businesscentral.dynamics.com> and open the environment you want to migrate data to.\n1. Search for and open the Cloud Migration Management page.\n1. Select Enable/Disable Custom Migration to enable custom migration. A message confirms the setting is enabled.\n1. Select Manage table mappings to open the Custom Migration Table Mappings page.\n1. Select Add Table Mapping and configure the mapping:\n  Mapping Type - Select Replication for data moved during replication or Setup for data needed during assisted setup.\n  Data per-company - Enable if the table contains company-specific data.\n  Company name - Specify the company name, or enable All companies to apply to all migrated companies.\n  Preserve cloud data - Enable to keep existing cloud data (recommended for per-database tables).\n  Source: Table name - Enter the SQL table name from the source database.\n  Target: Table name - Use the assist-edit to select the Business Central table you want to migrate data into. This field identifies the logical table and auto-populates the destination table name.\n  Target: Destination table name - The physical SQL table name in the cloud database. This field is auto-populated when you select a target table, but you can edit it manually if the source table name doesn't match the standard Business Central naming convention.\n1. Repeat the previous step for each table you want to migrate.\n1. Select the Setup cloud migration action to run the Cloud Migration Setup assisted setup guide.\n1. Read the information on the page and provided links. If you consent, switch on I accept warning & privacy notice, and then select Next to continue.\n1. Set the Product field to Custom Migration, and then select Next.\n1. On the Configure custom cloud migration page, verify the SQL table names. For no-code migrations, the defaults are usually correct:\n  Replication Mappings SQL Table Name - The table storing replication mappings (default: `Replication Table Mapping$<app-id>`).\n  Setup Mappings SQL Table Name - The table storing setup mappings (default: `Migration Setup Table Mapping$<app-id>`).\n  Companies SQL Table Name - The table in your source database containing company names (default: Company).\n1. Enter the connection string for your on-premises database.\n1. Select the companies to migrate.\n1. Complete the assisted setup guide, then select Run data replication to start the migration.\n> TIP\n> You can export your table mappings and import them into another tenant. On the Custom Migration Table Mappings page, use the Export and Import actions.\n## Create your own migration tool\nDevelopers can create their own apps to migrate from any SQL-based source to Business Central online using the existing migration tooling. A custom migration app defines the table mappings and setup data needed to migrate data from the source database.\n### Implementation overview\nCustom migration apps extend the Intelligent Cloud Base app published by Microsoft. The migration framework uses two interfaces that your app must implement:\n `\"Custom Migration Provider\"` - Defines the migration provider metadata and table mapping setup logic.\n `\"Custom Migration Table Mapping\"` - Defines where table mappings are stored and the company table name.\nYour app registers itself by extending enum 4010 `\"Custom Migration Provider\"`, which makes it available in the cloud migration assisted setup guide.\n### Interfaces to implement\n#### Custom Migration Provider interface\nThe `\"Custom Migration Provider\"` interface requires implementing the following procedures:\nProcedure|Description\n`GetDisplayName(): Text[250]`|Returns the display name shown in the Cloud Migration Setup assisted setup guide.\n`GetDescription(): Text`|Returns a description of the migration type.\n`GetAppId(): Guid`|Returns the app ID of your migration app.\n`SetupReplicationTableMappings()`|Registers the table mappings used during data replication. Called after companies are created online.\n`SetupMigrationSetupTableMappings()`|Registers table mappings needed during the setup phase, before companies are created. Use for per-database tables only.\n`GetDemoDataType(): Enum \"Company Demo Data Type\"`|Returns the demo data type for new companies. Common values: `\"Production - Setup Data Only\"` (populates setup data) or `\"Create New - No Data\"` (empty company).\n#### Custom Migration Table Mapping interface\nThe `\"Custom Migration Table Mapping\"` interface requires implementing the following procedures:\nProcedure|Description\n`GetReplicationTableMappingName(): Text`|Returns the SQL table name that stores replication mappings.\n`GetMigrationSetupTableMappingName(): Text`|Returns the SQL table name that stores setup table mappings.\n`GetCompaniesTableName(): Text`|Returns the name of the company table in the source database.\n`ShowConfigureMigrationTablesMappingStep(): Boolean`|Returns true to show the table mapping configuration step in the assisted setup guide. Default should be false.\n### Table mapping structure\nTable mappings define how data moves from source to destination. Both `Replication Table Mapping` (table 40034) and `Migration Setup Table Mapping` (table 40033) use the same structure:\nField|Type|Description\n`Source Sql Table Name`|Text[128]|The exact SQL table name in the source database.\n`Destination Sql Table Name`|Text[128]|The exact SQL table name in the cloud environment.\n`Company Name`|Text[30]|The company name. Leave blank for per-database tables.\n`Table Name`|Text[128]|A friendly name for the table (for example, \"Customer\").\n`Preserve Cloud Data`|Boolean|If true, existing cloud data isn't overwritten. Set to true for per-database tables, false for per-company tables.\n### Company table requirement\nThe source database must contain a table with company information. The table can have any name, but it must contain these fields:\n|Field|Type|Notes|\n|Name|nvarchar(30)|Primary key|\n|`Display Name`|nvarchar(250)||\nCreate this table using a SQL script in the source database before running the migration.\n### Implementation example\nThe following example shows the minimum code needed to create a custom migration provider.\n#### Step 1: Extend the enum\n```al\nenumextension 50100 \"My Migration Provider Ext\" extends \"Custom Migration Provider\"\n{\n    value(50100; \"My Custom Migration\")\n    {\n        Caption = 'My Custom Migration'; // Display name shown in assisted setup guide\n        Implementation = \"Custom Migration Provider\" = \"My Migration Provider\",\n                         \"Custom Migration Table Mapping\" = \"My Migration Provider\";\n    }\n}\n```\n#### Step 2: Implement the provider codeunit\n```al\ncodeunit 50100 \"My Migration Provider\" implements \"Custom Migration Provider\", \"Custom Migration Table Mapping\"\n{\n    procedure GetDisplayName(): Text[250]\n    begin\n        exit('My Custom Migration');\n    end;\n\n    procedure GetDescription(): Text\n    begin\n        exit('Migrates data from my source system to Business Central online.');\n    end;\n\n    procedure GetAppId(): Guid\n    begin\n        exit('00001111-aaaa-2222-bbbb-3333cccc4444'); // Your app ID\n    end;\n\n    procedure SetupReplicationTableMappings()\n    var\n        HybridCloudManagement: Codeunit \"Hybrid Cloud Management\";\n    begin\n        // Map source tables to destination tables in Business Central online by table ID\n        // Called after companies are created online\n        HybridCloudManagement.CreateReplicationMapping(\n            CompanyName(),\n            Database::\"Source Table Name\",  // Source table to migrate\n            Database::\"Target Table Name\"   // Destination table in Business Central online\n        );\n    end;\n\n    procedure SetupMigrationSetupTableMappings()\n    var\n        HybridCloudManagement: Codeunit \"Hybrid Cloud Management\";\n    begin\n        // Register per-database tables needed during setup\n        // Called before companies are created - use sparingly\n        // Example (uncomment if needed):\n        // HybridCloudManagement.CreateMigrationSetupMapping(\n        //     '',  // Empty company name for per-database tables\n        //     Database::\"Migration Config\",  // Small config table\n        //     Database::\"Migration Config\"\n        // );\n    end;\n\n    procedure GetDemoDataType(): Enum \"Company Demo Data Type\"\n    begin\n        exit(Enum::\"Company Demo Data Type\"::\"Production - Setup Data Only\");\n    end;\n\n    // Custom Migration Table Mapping interface\n    procedure GetReplicationTableMappingName(): Text\n    var\n        CustomMigrationProvider: Codeunit \"Custom Migration Provider\";\n    begin\n        exit(CustomMigrationProvider.GetReplicationTableMappingName());\n    end;\n\n    procedure GetMigrationSetupTableMappingName(): Text\n    var\n        CustomMigrationProvider: Codeunit \"Custom Migration Provider\";\n    begin\n        exit(CustomMigrationProvider.GetMigrationSetupTableMappingName());\n    end;\n\n    procedure GetCompaniesTableName(): Text\n    begin\n        exit('Company'); // Or your custom company table name\n    end;\n\n    procedure ShowConfigureMigrationTablesMappingStep(): Boolean\n    begin\n        exit(false);\n    end;\n}\n```\n### Best practices\n Setup table mappings run before companies exist: Only use `SetupMigrationSetupTableMappings()` for per-database tables. Per-company data must be registered through `SetupReplicationTableMappings()`, which runs after companies are created.\n Use buffer tables for data transformation: If you need to transform data during migration, replicate to buffer tables first, then process the data into the target tables.\n Provide integration events: Add events like OnBeforeMigrate and OnAfterMigrate to allow extensions to customize the migration behavior.\n Preserve cloud data for per-database tables: Set `Preserve Cloud Data` to true for per-database tables to avoid overwriting existing cloud data.\n### Working implementations for reference\nUse these examples as templates for your own custom migration app. Study the patterns, copy the code structure, and adapt it to your source system. You don't need to take a dependency on these apps - they're meant to illustrate how to build a migration from scratch.\n BC14 Item Category Migration Example<https://github.com/microsoft/BCTech/tree/master/samples/CloudMigration/BC14ItemCategoryMigrationExample> on GitHub - A simple example showing the basic structure for migrating a single entity.\n Business Central 14 Reimplementation app - A complete implementation that migrates master data, setup data, and transactions. Use this app as a reference for building comprehensive migrations with buffer tables, phased execution, and error handling.\n## Extend the Business Central 14 reimplementation\n[This article is prerelease documentation and is subject to change.]\n> IMPORTANT\n > This is a preview feature.\n > Preview features aren't meant for production use and might have restricted functionality. These features are subject to supplemental terms of use<https://go.microsoft.com/fwlink/?linkid=2189520>, and are available before an official release so that customers can get early access and provide feedback.\nThe Business Central 14 reimplementation app provides an extensible architecture for migrations that require data transformation. Instead of building a custom migration from scratch, you can extend the Business Central 14 reimplementation to add migrators for custom tables while getting all standard Business Central data migration for free.\nYour extension must declare a dependency on HybridBC14 in your app.json. The Business Central 14 reimplementation app handles all standard Business Central entities (customers, vendors, items, G/L accounts, and more). You only need to create migrators for custom tables that aren't already covered.\n### Extension patterns\nThe Business Central 14 reimplementation supports three extension patterns:\nPattern|Use case\nAdd fields to existing entities|Carry extra fields on Customer, Item, etc. alongside standard migration\nAdd new entities|Migrate your own custom tables that aren't part of standard Business Central\nAdd post-migration logic|Run validations or actions after migration completes\nFor detailed implementation guidance, working code samples, and best practices, see Extending the BC14 Reimplementation Tool<https://github.com/microsoft/BCTech/blob/master/samples/CloudMigration/BC14ReimplementationToolExtendingSample/Extending.md> on GitHub.\n### Disable standard modules\nThe Business Central 14 reimplementation includes per-company settings that let you disable standard migrators. This is useful when you want to use the Business Central 14 reimplementation framework and tooling but only migrate your custom tables.\nTo disable standard modules:\n1. Open the BC14 Migration Configuration page.\n2. In the Modules section, clear the checkboxes for modules you don't want to migrate:\n  General Ledger - Disables G/L Account and related ledger migration\n  Receivables - Disables Customer migration\n  Payables - Disables Vendor migration\n  Inventory - Disables Item migration\n3. Your custom migrators (which return true from `IsEnabled()`) still run.\n> NOTE\n> Module settings are locked after migration starts. Configure them before running your first replication.\n## Related information\n Migrate on-premises data to Business Central online<migrate-data>\n Business Central 14 reimplementation tool<migrate-bc14-reimplementation>\n Extending the BC14 Reimplementation Tool<https://github.com/microsoft/BCTech/blob/master/samples/CloudMigration/BC14ReimplementationToolExtendingSample/Extending.md> on GitHub\n cloudmigrationapi/cloud-migration-api-overview"}