Converting a Database to Business Central Spring 2019 - Technical Upgrade
Note
If you're coming from version 13 or earlier, Business Central Spring 2019 (v14) is a required step to upgrade to the latest version of Business Central. However, mainstream support for version 14 ends in October 2023, and minor updates to the version are no longer available. New customers can't use version 14 in production, but only as a path for upgrading to latest version. Existing customers on version 14 remain supported by Microsoft as defined in the Fixed Lifecycle Policy.
All version 14 updates are compatible with any update version of Business Central 2024 release wave 1 and later release waves.
See print-friendly quick reference
This article describes how to convert a database from one of the following versions to the latest Business Central platform:
- Microsoft Dynamics NAV 2015
- Microsoft Dynamics NAV 2016
- Microsoft Dynamics NAV 2017
- Microsoft Dynamics NAV 2018
This article can also be used to update your current Business Central database to the latest cumulative update (CU) platform.
Overview
About technical upgrade and database conversion
Converting a database, which is often referred to as a technical upgrade, changes the database so that it works on the latest Business Central platform. The conversion updates the system tables of the old database to the new schema (data structure), and upgrades of all reports to support Report Viewer 2015. It provides you with the latest platform features and performance enhancements.
The process is slightly different when you have multitenant deployment compared to a single-tenant deployment. The steps that follow indicate the differences where applicable.
Important
Before you begin, read the article Important Information and Considerations for Before Upgrading. This article contains information about limitations in a technical upgrade, such as using V1 extensions or Dynamics 365 Sales integration.
If you are upgrading a single-tenant database to Business Central Cumulative Update 02, 03, 04, or 05, read Tenant synchronization issue with technical upgrade to Business Central Cumulative Updates 02–05 on the Business Central for Partners blog before starting the upgrade.
Tools
To complete the steps in the article, you will use the following tools:
Dynamics NAV Development Environment (the version that matches your old database and the new version)
Dynamics NAV Server Administration tool and/or Business Central Server Administration tool
SQL Server Management Studio
Task 1: (Dynamics NAV upgrade only) Preparation
Transition from the use of codeunit 1
With Business Central, codeunit 1 Application Management is no longer used and has been replaced. For more information, see Transitioning from Codeunit 1. To prepare for this change when doing a technical upgrade, do the following:
- If you have any custom code in codeunit 1, export the existing codeunit 1 as a .fob or .txt file.
- Go to Codeunit 1 Replacement, and make a .txt file that includes the replacement code for codeunit 1. You will use this file later.
Convert V1 extensions to V2 extensions
Business Central does not support V1 extensions. If you are updating a Dynamics NAV database that includes custom V1 extensions, and you want to continue to use them, you have to convert them to V2 extensions. For more information, see Converting Extensions V1 to Extensions V2.
V1 extensions that are produced by Microsoft (first-party extensions, publisher=Microsoft) are now available as V2 extensions on the Business Central installation media (DVD), so you do not have to convert these. If you want to keep the functionality provided and data collected by these V1 extensions, you will have to publish the V2 versions as part of the technical upgrade later in Task 4.
You will have to uninstall all V1 extension to successfully completes the technical upgrade.
Task 2: Preparing the Old Database
Before you convert the old database to Business Central, complete the following steps.
Make a copy of the old database or create full database backup.
For more information, see Create a Full Database Backup (SQL Server).
For single-tenant mode, uninstall all extensions. For multitenant mode, uninstall all V1 extensions.
You can do this from Extension Management page in the Dynamics NAV client or by using the Uninstall-NAVApp cmdlet of the Dynamics NAV Administration Shell.
To get a list of the extensions that are installed, run this command:
Get-NAVAppInfo -ServerInstance <ServerInstanceName> -Tenant <TenantID>For a single-tenant mode, set the
-Tenantparameter todefault. V1 extensions are indicated byExtensionType: CSIDE.For each extension, run this command to uninstall it:
Uninstall-NAVApp -ServerInstance <ServerInstanceName> -Name <Name> -Version <N.N.N.N>Alternately, to remove them all at once, you can run this command:
Get-NAVAppInfo -ServerInstance <ServerInstanceName> -Tenant default | % { Uninstall-NAVApp -ServerInstance <ServerInstanceName> -Name $_.Name -Version $_.Version }Unpublish extensions versions that you do not want to use in the upgraded database. This is optional and typically done for V1 extensions because they are no longer supported.
For example:
Unpublish-NAVApp -ServerInstance dynamicsnav110 -Name System -Version 11.0.12925.0Open the Dynamics NAV Development Environment that matches the Dynamics NAV or Business Central version of the old database, and then connect to the old application database.
For more information, see Open Databases.
In Object Designer, verify that all objects are compiled and no objects are locked.
For more information about compiling objects, see Compiling Objects.
If one or more objects are locked, the conversion process cannot update the database version number. As a result, the conversion does not complete. For more information, see Locking and Unlocking Objects.
On the Tools menu, choose Build Server Application Objects, and then choose the Yes button.
If any errors occur, they are shown in the Error List window. Make sure that you address all compilation errors before you continue.
Run the schema synchronization with validation to synchronize the database schema changes.
For more information, see Synchronizing the Tenant Database and Application Database.
Upload the Business Central Partner license to the database.
For more information, see Uploading a License File for a Specific Database.
Important
The license that you upload must be a developer license. During the conversion, the development environment will convert the report objects that are stored in the old database to the RDL format.
(Multitenant only) Dismount tenants.
Use the Dynamics NAV Server Administration tool or Dismount-NAVTenant cmdlet of the Dynamics NAV Administration Shell to dismount all tenants from the Dynamics NAV Server instance.
Dismount-NAVTenant -ServerInstance <serverinstance> -Tenant <tenantID>Stop the Dynamics NAV Server instance, and close the development environment.
You can use the Dynamics NAV Server Administration tool or Set-NAVServerInstance cmdlet of the Dynamics NAV Administration Shell.
To use the Set-NAVServerInstance cmdlet, run the following command:
Set-NAVServerInstance –ServerInstance <ServerInstanceName> -StopClear all records from the dbo.Server Instance and dbo.Debugger Breakpoint tables in the old application database in SQL Server.
Using SQL Server Management Studio, open and clear the dbo.Server Instance and dbo.Debugger Breakpoint tables of the old database. For example, you can run the following SQL query:
DELETE FROM [<My NAV Database Name>].[dbo].[Server Instance] DELETE FROM [<My NAV Database Name>].[dbo].[Debugger Breakpoint]Close all to connections to the database.
This includes but is not limited to Dynamics NAV client tools and SQL Server Management Studio.
Task 3: Run Technical Upgrade on the Old Database
Next, you will convert the old database so that it can be used with Business Central.
Tip
If you want to write a script that helps you convert databases, you can use the Invoke-NAVDatabaseConversion function in the Dynamics NAV Development Shell.
Important
Before you run the technical upgrade, delete any corrupt databases that are on the same SQL Server instance as the database that you intend to upgrade. Otherwise, when you run the database conversion, you will get the error "The Symbol Reference field on the Object Metadata table does not exist in the SQL Server table or view.".
If the database is on Azure SQL Database, add your user account to the dbmanager database role on the master database.
This membership is only required for converting the database, and can be removed afterwards. This step isn't required for Azure SQL Managed Instance.
Install Business Central.
Run the Business Central Setup, and install the following components as a minimum:
- Server
- SQL Server Database Components
- Administration Tool
- Dynamics NAV Development Environment
Important
For a multi-tenant installation, configure the Business Central Server instance to be a multi-tenant instance.
Note
If you want to install the local functionality for India, use the following link to get the files for that version, Business Central Spring 2019.
Run the newly installed Dynamics NAV Development Environment as an administrator.
If the Dynamics NAV Development Environment is already connected to the old application database, a dialog box about converting the database appears. Go to the next step.
Otherwise, connect to the old application database that you prepared in the previous task, and then go to the next step.
For more information, see Open Databases.
Important
If you do not run the development environment as an administrator, you will get an error and the conversion will be stopped.
In the dialog box that appears, read the instructions about converting the database carefully because this action cannot be reversed. When you are ready, choose the OK button, and then choose the OK button to confirm that you want to convert the database.
Dynamics NAV Development Environment will now convert the database. This includes an upgrade of system tables and reports.
When you are notified that the conversion was successful, choose the OK button.
If the database references any assemblies (such as client control add-ins) that are not included on the Business Central installation media (DVD), then add the assemblies to the Add-ins folder on Business Central Server.
For Business Central Server, the default path is the C:\Program Files\Microsoft Dynamics 365 Business Central\NNN\Service\Add-ins folder.
Connect a Business Central Server instance to the converted database.
Use the Business Central Server Administration tool or the Set-NAVServerConfiguration cmdlet to connect a Business Central Server instance to the converted database.
Important
The service account that is used by the Business Central Server instance must be a member of the db_owner role in the Dynamics NAV database on SQL Server or Azure SQL Database.
For more information, see Connect a Server Instance to a Database and Giving the account necessary database privileges in SQL Server.
Go to the development environment, and set it to use the Business Central Server instance that connects to the database.
For more information, see Change the Server Instance.
If upgrading from Dynamics NAV, import the codeunit 1 replacement text file you created earlier.
Compile all objects without table schema synchronizing (Synchronize Schema set to Later); you will do this later.
For more information, see Compiling Objects.
-
If any errors occur, they are shown in the Error List window. For help on resolving the errors, see the following:
You can find all objects which did not compile in the Object Designer window, by setting a field filter on the Compiled field.
Recompile V2 extensions that you uninstalled previously.
Use the Repair-NAVApp cmdlet of the Business Central Administration Shell to compile the published extensions to make sure they are work with the new platform.
For example, you can run the following command to recompile all extensions:
Get-NAVAppInfo -ServerInstance <ServerInstanceName> | Repair-NAVApp(Multitenant only) Mount the tenant.
Use the Mount-NAVTenant cmdlet.
Mount-NAVTenant -ServerInstance <serverinstance> -Tenant <tenantID> -DatabaseName <tenantdatabasename>-AllowAppDatabaseWriteis optional but is required for some post-upgrade tasks, like upgrading the control add-ins. When you are done upgrading, you can dismount and mount the tenant without this parameter as needed.
Note
If you are upgrading from an India (IN) Dynamics NAV 2016, you must perform below step:
On the Tools menu, choose Build Server Application Objects, and then choose the Yes option.
Run the schema synchronization with validation to complete the database conversion.
For more information, see Synchronizing the Tenant Database and Application Database.
Note
If you are upgrading from an India (IN) Dynamics NAV 2016, you must perform below step:
Run the Data Upgrade to complete the technical upgrade.
Delete the obsolete tables with Schema Synchronization as Force Mode.
Table Id Table Name 470 Job Queue 824 DO Payment Connection Details 825 DO Payment Connection Setup 826 DO Payment Setup 827 DO Payment Credit Card 828 DO Payment Credit Card Number 829 DO Payment Trans. Log Entry 830 DO Payment Card Type 1305 Mini Pages Mapping 1510 Notification Template 5150 Integration Page 5371 Service Connection Error 5372 Service Connection Status 8640 Config. Text Transformation
Task 4: Post-upgrade
Upgrade Javascript-based control add-ins to new versions.
The Business Central Server installation includes new versions of Microsoft-provided Javascript-based control add-ins, such as the Business Chart control add-in. If you application is using any of these add-ins, you must upgrade them to the new versions as follow:
Open the Business Central client.
Search for and open the Control Add-ins page.
Choose Actions > Control Add-in Resource > Import.
Locate and select the .zip file for the control add-in and choose Open.
The .zip files are located in the Add-ins folder of the Business Central Server installation. There is a sub-folder for each add-in. For example, the path to the Business Chart control add-in is
C:\Program Files\Microsoft Dynamics 365 Business Central\140\Service\Add-ins\BusinessChart\Microsoft.Dynamics.Nav.Client.BusinessChart.zip.After you have imported all the new control add-in versions, restart Web Server instance.
(Single tenant only) Install the V2 extensions that you uninstalled previously.
Use the Install-NAVApp cmdlet to compile the published extensions to make sure they are work with the new platform.
For each V2 extension, run the following command to install it:
Install-NAVApp -ServerInstance <ServerInstanceName> -Name <Name> -Version <N.N.N.N>(Dynamics NAV 2017 or 2018 upgrade only) If the old database used first-party V1 extensions (publisher Microsoft), then you should publish and install the corresponding V2 extensions that are found on the installation media (DVD). For example, Sales and Inventory Forecast and PayPal Payment Standards were available as V1 extensions. Now, they are available as V2 extensions.
Publish the system.app and test.app symbol files.
If you installed the AL Development Environment, you can find the symbol files where you installed the environment, which by default is C:\Program Files (x86)\Microsoft Dynamics 365 Business Central\NNN. Otherwise, you can find the files in the ModernDev folder on the installation media.
To publish the symbols, open the Business Central Administration Shell as an administrator, and run the following command for each of the symbol files:
Publish-NAVApp -ServerInstance <ServerInstanceName> -Path <SymbolFilePath> -PackageType SymbolsOnlyGenerate the application symbol references by using the finsql.exe file.
Open a command prompt as an administrator, change to the directory where the
finsql.exefile has been installed as part of Dynamics NAV Development Environment, and then run the following command:finsql.exe Command=generatesymbolreference, ServerName=<DatabaseServerName>\<DatabaseInstance>, Database="<MyDatabaseName>"Replace values for the
DatabaseandServerNamesettings to suit.If the application database contains test objects (ID 130000-139999), then make sure to exclude these objects when generating symbols. You can do this by using the
-Filterparameter and running the command twice:finsql.exe command=generatesymbolreference, ServerName=<DatabaseServerName>\<DatabaseInstance>, Database="<MyDatabaseName>, filter="Object ID=1..129999"finsql.exe command=generatesymbolreference, ServerName=<DatabaseServerName>\<DatabaseInstance>, Database="<MyDatabaseName>, filter="Object ID=140000..1999999999"Note
This command does not generate a file. It populates the Object Metadata table in the database.
When you run the command, the console returns to an empty command prompt, and does not display or provide any indication about the status of the run. However, the finsql.exe may still be running in the background. It can take several minutes for the run to complete, and the symbols will not be generated until such time. You can see whether the finsql.exe is still running by using Task Manager and looking on the Details tab for finsql.exe.
When the process ends, a file named navcommandresult.txt is saved to the Dynamics NAV Client connected to Business Central installation folder. If the command succeeded, the file will contain text like
[0] [06/12/17 14:36:17] The command completed successfully in '177' seconds.If the command failed, another file named naverrorlog.txt will be generated. This file contains details about the error(s) that occurred.For more information about generation symbols, see Running C/SIDE and AL Side-by-Side.
Configure the Enable loading application symbol references at server startup (EnableSymbolLoadingAtServerStartup) setting on the Business Central Server instance, and restart the instance.
For more information, see Configuring Business Central Server.
Publish the new V2 extension by running the Publish-NAVApp cmdlet for each extension:
Publish-NAVApp -ServerInstance <ServerInstanceName> -Path <ExtensionFileName>Synchronize the schema with the database by running the Sync-NAVApp cmdlet for each extension:
Sync-NAVApp -ServerInstance <ServerInstanceName> -Name <Name> -Version <N.N.N.N>For each V2 extension, run the following command to install it:
Install-NAVApp -ServerInstance <ServerInstanceName> -Name <Name> -Version <N.N.N.N>
(Dynamics NAV upgrade only) Transition the custom code in the old codeunit 1 to use the new system event implementation.
For more information, see Transitioning from Codeunit 1.
(Microsoft Dynamics NAV 2016 upgrade only) Modify C/AL code to ensure that the My Settings page works properly in the Business Central Web client.
For more information, see Resolving My Settings Page Implementation After a Database Conversion.
(Dynamics NAV upgrade only) Configure pages and reports included in the MenuSuite to be searchable in the Web client.
The MenuSuite is no longer used to control whether a page or report can be found in the search feature of the Web client. This is now determined by specific properties on the page and report objects. For more information, see Making Pages and Reports Searchable in Web client After an Upgrade.
Build the object search index to make objects able to be searched from Tell Me in the client. If you completed step 6, you can skip this step.
In the Tools menu of the Dynamics NAV Development Environment, select Build Object Search Index.
Upload the customer license to the converted database.
For more information, see Uploading a License File for a Specific Database.
You have now completed the conversion of the database to be accessed from Business Central. To test the converted database, you can connect it to the Business Central Server instance that is used by Dynamics NAV clients, and then open a client.
Note
If you are upgrading from an India (IN) Dynamics NAV 2016, you must perform steps defined in the Publish, Synchronize and Install the ‘IndiaUpgradeTables’ extension
Database and Windows collations
Starting from SQL Server 2008, SQL Server collations are fully aligned with the collations in Windows Server. If you upgrade to Business Central from Microsoft Dynamics NAV 2009, the step to convert the database includes upgrading the database from using SQL collations to using Windows collation. This collation change provides users with the most up-to-date and linguistically accurate cultural sorting conventions. For more information, see Collation and Unicode Support.
Related information
Upgrading the Application Code Upgrading the Data
Upgrading to Business Central