Upgrading the Data to Business Central: Single-Tenant Deployment

See print-friendly quick reference

This topic describes the tasks required for upgrading the data of a Dynamics NAV database to Business Central in a single-tenant deployment.

About Data Upgrade

You use data conversion tools provided with Business Central to convert the old data with the old version’s table and field structure, so that it functions together with the new version’s table and field structure. Mainly, only table objects and table data are modified during the data upgrade process. Other objects, such as pages, reports, codeunits, and XMLports are upgraded as part of the application code upgrade process.

The data upgrade process described in this article leads you through the database conversion (technical upgrade) and then the upgrade of the actual data, which is achieved by using the upgrade toolkit/upgrade codeunits.

Prerequisites

Before you start the upgrade tasks, make sure you meet the following prerequisites:

  1. Your computer uses the same codepage as the data that will be upgraded.

    If you use conflicting codepages, some characters will not display in captions, and you might not be able to access the upgraded database. This is because Dynamics NAV must remove incorrect metadata characters to complete the data upgrade. In this case, after upgrade, you must open the database in the development environment on a computer with the relevant codepage and compile all objects. This adds the missing characters again.

    Optionally, you can export the captions before the upgrade. For more information, see How to: Add Translated Strings for Conflicting Text Encoding Formats.

  2. Custom V1 extensions used in the old deployment have been converted to V2 extensions.

    For more information, see Converting Extensions V1 to Extensions V2.

  3. You have upgraded the application code, and have the FOB files that contain the upgraded application code and upgrade toolkit. The upgrade toolkit includes upgrade codeunits for handling the data upgrade. The upgrade toolkit can be in the same FOB file as the application code or in a separate FOB file.

    For more information about upgrading the application code, see Upgrading the Application Code.

    For W1 versions, you can find the default upgrade toolkit objects in the UpgradeToolKit\Data Conversion Tools folder on the Business Central installation media (DVD). Choose the FOB that matches the Dynamics NAV version from which you are upgrading:

    Version FOB Remarks
    Microsoft Dynamics NAV 2013 Upgrade7001100.FOB This file can be found on the Microsoft Dynamics NAV 2018 Cumulative Update 2 installation media (DVD). It is not available with later cumulative updates.
    Microsoft Dynamics NAV 2013 R2 Upgrade7101100.FOB and Upgrade710HF1100.FOB This file can be found on the Microsoft Dynamics NAV 2018 Cumulative Update 2 installation media (DVD). It is not available with later cumulative updates.
    Microsoft Dynamics NAV 2015 Upgrade8001300.FOB
    Microsoft Dynamics NAV 2016 Upgrade9001300.FOB
    Microsoft Dynamics NAV 2017 Upgrade10001300.FOB
    Microsoft Dynamics NAV 2018 Upgrade11001300.FOB

    For local versions, you will find the upgrade toolkit objects in the UpgradeToolKit\Local Objects folder. The files follow the same naming convention except they include the 2-letter local version, such as Upgrade11001300.DK.fob for Denmark or Upgrade11001300.DE.fob for Germany.

  4. You have exported the permission sets (except SUPER) and permissions as XML files from the old database.

    To exclude the SUPER permission set when running XMLPort 9171, add the filter Role ID is <>SUPER.

    For more information, see Exporting and Importing Permission Sets and Permissions.

  5. If the old deployment uses data encryption, you have exported the encryption key file that it used for the data encryption.

    For more information, see How to: Export and Import Encryption Keys.

  6. (Optional) Make a copy of the configuration file (web.config or navsettings.json) for all Business Central Web Server instances in the old deployment.

  7. Business Central has been installed.

    As a minimum, you must install the following components:

    • Server
    • SQL Server Components
    • Business Central Web Server components

    • Dynamics NAV Development Environment

    • AL Development Environment
    • (optionally) Business Central Server Administration tool

    For more information, see Installing Business Central Using Setup.

Note

If the old Dynamics NAV application uses Payment Services for Microsoft Dynamics ERP, be aware that this was discontinued in Microsoft Dynamics NAV 2017. This means that most of the objects that are associated with this feature will be deleted during the upgrade. Some objects you will have to manually delete.

Task 1: Create a full SQL backup of the old database on SQL Server

Create a full backup of the old database in the SQL Server. Alternatively, you can make a copy of the old database and perform the upgrade tasks on the copy.

For more information, see Create a Full Database Backup (SQL Server).

Task 2 Uninstall all extensions in old database

Open the Dynamics NAV Administration Shell that matches to old database, and run these commands:

  1. To get a list of the extensions that are installed, run this command:

    Get-NAVAppInfo -ServerInstance <ServerInstanceName> -Tenant default
    

    Replace <ServerInstanceName> with the name of the Dynamics NAV Server instance that the database connects to.

  2. For each extension, run this command to uninstall it:

    Uninstall-NAVApp -ServerInstance <ServerInstanceName> -Name <Name> -Version <N.N.N.N>
    

    Replace <ServerInstanceName> with the name of the Dynamics NAV Server instance that the database connects to.

    Replace <Name> and <N.N.N.N> with the name and version of the Extension V1 as it appeared in the previous step.

    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 }
    

Task 3: Upload the Business Central partner license to the old database

By using the Dynamics NAV Development Environment that matches the old database, upload the Business Central license to the database.

For more information, see [Uploading a License File for a Specific Database.

Task 4: Delete all objects except tables from the old database

In the development environment version that matches the database, open the old database, open Object Designer, select all objects except tables, and then choose Delete.

You can also use the DeleteObjects command of the finsql.exe.

Task 5: Clear server instance and debugger breakpoint records from old database

Clear all records from the dbo.Server Instance and dbo.Debugger Breakpoint tables in the database in SQL Server.

  1. Make sure that you stop the old server instance, and close any tools that connect to the database, such as the Dynamics NAV Administration Tool and development environment.

  2. 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]
    

Task 6: Convert the old database to the Business Central format

If the database is on Azure SQL Database, you must first add your user account to the dbmanager database role on master database. This membership is only required for converting the database, and can be removed afterwards.

To convert the old database to the Business Central format, open the old database in the new Dynamics NAV Development Environment for Business Central, and follow the conversion instructions.

For more information about how to open a database, see Open a Database.

Important

Do not run schema synchronization at this time. Choose to run it later.

Task 7: Import the upgraded application objects

Using Dynamics NAV Development Environment for Business Central, import the application objects that you want in the database. This includes the application objects FOB file (from the application code upgrade) and the upgrade toolkit objects FOB file.

  1. Import the application objects FOB file first, and then import the upgrade toolkit FOB file.

    For more information, see Importing Objects.

  2. IMPORTANT When prompted about table synchronization, set the Synchronize Schema option to Later.

  3. When you import the FOB file, if you experience metadata conflicts, the Import Worksheet windows appears.

    Review the Worksheet page. For more information, see Import Worksheet.

    Choose Replace All, and then OK to continue.

Task 8: Connect a Business Central Server instance to the converted database

You use the Business Central Server Administration tool or Set-NAVServerConfiguration cmdlet in the Business Central Administration Shell to connect a Business Central Server instance to the converted database.

The service account that is used by the Business Central Server instance must be a member of the db_owner role in the Business Central database on SQL Server or Azure SQL Database.

For more information, see Connecting a Server Instance to a Database and Giving the account necessary database privileges in SQL Server.

Important

When upgrading a large database, you should increase the SQL Command Timeout setting for the Business Central Server instance, to avoid timeouts during schema synchronization. The default setting is 30 minutes.

Task 9: Compile all objects

  1. In the Dynamics NAV Development Environment, set it to use the server instance that connects to the database.

    For more information, see Changing the Server Instance.

  2. Use the Dynamics NAV Development Environment or finsql.exe to compile all objects. This includes the imported application objects, data tables, and system tables.

    Important

    Choose to run schema synchronization later. For example, in Object Designer, choose Tools, choose Compile, set the Synchronize Schema option to Later, and then choose OK. For more information, see Compiling Objects.

  3. (Microsoft Dynamics NAV 2016 and earlier only) If you get errors on the following table objects, use the Object Designer to delete the objects because they are no longer used.

    • Table 470 Job Queue (replaced by the Task Scheduler)
    • Table 824 DO Payment Connection Details
    • Table 825 DO Payment Connection Setup
    • Table 827 DO Payment Credit Card
    • Table 828 DO Payment Credit Card Number
    • Table 829 DO Payment Trans. Log Entry
    • Table 1510 Notification Template

    When you delete a table object, in the Delete confirmation dialog box that appears, set the Synchronize Schema option to Force.

    Important

    In this step, it is very important that you do not use the Sync. Schema For All Tables option from the Tools menu.

  4. (Microsoft Dynamics NAV 2016 and earlier only) If the old database includes test runner codeunits, you will get errors on these codeunits that the OnBeforeTestRun and OnAfterTestRun trigger signatures are not valid. To fix these issues, you change the signature of the OnBeforeTestRun and OnAfterTestRun triggers to include the TestPermission parameter.

    For more information, see Resolving OnBeforeTestRun and OnAfterTestRun Trigger Errors When Converting a Database.

    The triggers for codeunit 130400 CAL Test Runner and 130402 CAL Command Line Test Runner will be updated for you during the data upgrade.

Task 10: Increase the application version of the database

If you are upgrading from Microsoft Dynamics NAV 2018, you must increase the application version that is assigned to the database.

Use the Set-NAVApplication cmdlet of the Business Central Administration Shell to increase the application version number of the database from its current version.

To see the current version, use the following command:

Get-NAVApplication -ServerInstance <ServerInstanceName> 

To change the version, use the following command:

Set-NAVApplication -ServerInstance <ServerInstanceName> -ApplicationVersion <N.N.N.N> -Force

For example, if the old version was 11.0.24279.0, then you could change the version to 13.0.24279.0.

Task 11: Run the schema synchronization on the imported objects

Synchronize the database schema with validation.

For example, run the Sync-NAVTenant cmdlet from the Business Central Administration Shell.

Sync-NAVTenant -ServerInstance <ServerInstanceName>

For more information, see Synchronizing the Tenant Database and Application Database.

Task 12: Run the data upgrade process

A data upgrade runs the upgrade toolkit objects, such as upgrade codeunits and upgrade tables, to migrate business data from the old table structure to the new table structure. You can start the data upgrade from the Dynamics NAV Development Environment or Business Central Administration Shell.

Note

In the last phase of data upgrade, all companies will be initialized by running codeunit 2 Company Initialization. This is done automatically. If you want to skip company initialization, then use the Start-NavDataUpgrade cmdlet and set the -SkipCompanyIntitialization parameter.

Open the Business Central Administration Shell as an administrator, and then run Start-NavDataUpgrade cmdlet as follows:

Start-NavDataUpgrade -ServerInstance <ServerInstanceName>  

Replace <ServerInstanceName> with the name of the Business Central Server instance that is connected to the database.

To view the progress of the data upgrade, you can run Get-NavDataUpgrade cmdlet with the –Progress switch.

The data upgrade process runs CheckPreconditions and Upgrade functions in the upgrade codeunits. If any of the preconditions are not met or an upgrade function fails, you must correct the error and resume the data upgrade process. If CheckPreconditions and Upgrade functions are executed successfully, codeunit 2 is automatically run to initialize all companies in the database unless you set the -SkipCompanyIntitialization parameter.

Task 13: Import upgraded permission sets and permissions

Import the permission sets and permissions XML files that you exported from the old database as follows:

  1. Delete all permission sets in the database except the SUPER permission set.

    In Object Designer, run page 9802 Permission Sets, and then delete the permission sets except SUPER.

  2. Run XMLport 9171 and XMLport 9172 to import the permission sets and permission XML files.

    For more information, see How to: Export and Import Permission Sets and Permissions.

Task 14: Import Data Encryption Key (Optional)

If you want to use data encryption as before, you must import the data encryption key file that was exported previously.

For more information, see Exporting and Importing Encryption Keys.

Task 15: Set the language of the customer database

In the Dynamics NAV Development Environment, choose Tools, choose Language, and then select the language of the original customer database.

Task 16: Register client control add-ins

The database is now fully upgraded and is ready for use. However, Business Central includes the following client control add-ins.

  • Microsoft.Dynamics.Nav.Client.BusinessChart
  • Microsoft.Dynamics.Nav.Client.DynamicsOnlineConnect
  • Microsoft.Dynamics.Nav.Client.FlowIntegration
  • Microsoft.Dynamics.Nav.Client.OAuthIntegration
  • Microsoft.Dynamics.Nav.Client.PageReady
  • Microsoft.Dynamics.Nav.Client.PingPong
  • Microsoft.Dynamics.Nav.Client.PowerBIManagement
  • Microsoft.Dynamics.Nav.Client.RoleCenterSelector
  • Microsoft.Dynamics.Nav.Client.SocialListening
  • Microsoft.Dynamics.Nav.Client.TimelineVisualization
  • Microsoft.Dynamics.Nav.Client.VideoPlayer
  • Microsoft.Dynamics.Nav.Client.WebPageViewer

To use these add-ins, they must be registered in table 2000000069 Client Add-in. Depending on the version that you upgraded from, all the add-ins might not be registered after the upgrade process. You can register missing control add-ins in the Control Add-ins page in the client. The assemblies (.dlls) for these add-ins are in subfolders to the Add-ins folder of the Business Central Server installation, which by default is C:\Program Files\Microsoft Dynamics 365 Business Central\130\Service\Add-ins. For more information, see How to: Register a Windows Client Control Add-in.

Task 17: Update the Web Server instance configuration file (navsettings.json)

If you have installed the Business Central Web Server, populate the navsettings.json file for the Business Central Web Server instance with the settings of the old web.config file or navsettings.json.

For more information, see Configuring Business Central Web Server Instances.

Task 18: Delete the upgrade objects

At this point, you have upgraded the database to Business Central. Now, you can delete the upgrade codeunits and upgrade table objects that you imported in task 9. This task is recommended but not required.

When you delete tables, on the Delete dialog box, set the Synchronize Schema option to Force.

Task 19: Publish and install/upgrade extensions

Complete this task if you are upgrading from a Microsoft Dynamics NAV 2018 deployment that uses V2 extensions or a Denmark (DK) version of Microsoft Dynamics NAV 2017 or earlier.

The Business Central installation media (DVD) includes several new versions of Microsoft extensions (that is, extensions that have Microsoft as the publisher). If your old deployment uses these extensions, you have to upgrade the current versions to the new versions.

In addition, other extensions used in the old deployment that you still want to use must be repaired to work on the new platform.

Important

If you are upgrading from a Denmark (DK) version of Dynamics NAV 2017 or earlier, you must publish and install the following extensions to get the local functionality:

Name Extension package
Payroll Data Import Definitions (DK) ImportDKPayroll.app
Payment and Reconciliation Formats (DK) FIK.app
Tax File Formats (DK) VATReportsDK.app
  1. To get list of the extensions currently published on the application, run the following command from the Business Central Administration Shell:

    Get-NAVAppinfo -ServerInstance <ServerInstanceName>
    
  2. Publish the system.app and test.app symbol files.

    If you installed the AL Development Environment, you can find the symbol files where your installed the environment, which by default is C:\Program Files (x86)\Microsoft Dynamics 365 Business Central\130. 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 SymbolsOnly
    
  3. Generate the application symbol references by using the finsql.exe file as follows:

    1. Make sure that Enable loading application symbol references at server startup (EnableSymbolLoadingAtServerStartup) is set on the Business Central Server instance.

      For more information, see Configuring Business Central Server.

    2. Open a command prompt as an administrator, change to the directory where the finsql.exe file has been installed as part of Dynamics NAV Development Environment, and then run the following command:

      finsql.exe Command=generatesymbolreference, Database="<MyDatabaseName>", ServerName=<DatabaseServerName>\<DatabaseInstance>
      

      Replace values for the Database and ServerName settings to suit.

      Note

      This command does not generate a file. It populates the Object Metadata table in the database.

    3. 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.

  4. Upgrade the Microsoft extensions that were published in the old deployment to new versions.

    The new versions are found in the \Extensions folder of the installation media. To upgrade to the new extension versions, follow these steps from the Business Central Administration Shell for each extension:

    1. Publish the new extension version by running the Publish-NAVApp cmdlet:

      Publish-NAVApp -ServerInstance <ServerInstanceName> -Path <ExtensionFileName> 
      
    2. Synchronize the schema with the database by running the Sync-NAVApp cmdlet:

      Sync-NAVApp -ServerInstance <ServerInstanceName> -Name <Name> -Version <N.N.N.N>
      
    3. Upgrade the data of the extensions by running the Start-NAVAppDataUpgrade cmdlet:

      Start-NAVAppDataUpgrade -ServerInstance <ServerInstanceName> -Name <Name> -Version <N.N.N.N>
      

      Apart from upgrading the data, this command will install the new extension version. For more information about publishing extensions, see Publish and Install an Extension.

  5. Repair, synchronize, and install other published extension versions that you still want to use, but have not been upgraded to new versions.

    For each extension, complete the following steps from the Business Central Administration Shell:

    1. Compile the extension to make it work with the new platform by running the Repair-NAVApp cmdlet.

      Repair-NAVApp -ServerInstance <ServerInstanceName> -Name <Extension Name> -Version <N.N.N.N>
      
    2. Synchronize the schema with the database by running the Sync-NAVApp cmdlet:

      Sync-NAVApp -ServerInstance <ServerInstanceName> -Name <Name> -Version <N.N.N.N>
      
    3. Install the extension by running the Install-NAVApp cmdlet:

      Install-NAVApp -ServerInstance <ServerInstanceName> -Name <Name> -Version <N.N.N.N>
      
  6. (Optional) Unpublish unused extension versions by running the Unpublish-NAVApp:

    Unpublish-NAVApp -ServerInstance <ServerInstanceName> -Name <Name> -Version <N.N.N.N>
    

See Also

Upgrading the Application Code
Upgrading to Business Central