Edit

Technical Upgrade to Dynamics 365 Business Central 2019 Wave 2

  • Article

Use this process when you have a code customized Business Central application (version 14) that you want to upgrade to the Business Central 2019 release wave 2 platform (version 15). This process won't upgrade the application to the latest version. You'll convert the entire application from C/AL to an AL base application extension.

Upgrade on customized Business Central application.

Single-tenant and multitenant deployments

The process for upgrading is similar for a single-tenant and multitenant deployment. However, there are some inherent differences. With a single-tenant deployment, the application code and business data are in the same database. In a multitenant deployment, application code is in a separate database (the application database) than the business data (tenant). In the procedures that follow, for a single-tenant deployment, consider references to the application database and tenant database as the same database. Steps are marked as Single-tenant only or Multitenant only where applicable.

Prerequisites

  1. Upgrade to Business Central Spring 2019 (version 14).

    There are several updates for version 14. When upgrading from Business Central Fall 2018 (version 13) or Dynamics NAV, upgrade to the latest version 14 update that has a compatible version 15 update. For more information, see Dynamics 365 Business Central Upgrade Compatibility Matrix.

    If your solution is already on version 14, then you don't have to upgrade to the latest version 15 update.

    To download the latest update, go to Released Cumulative Updates for Microsoft Dynamics 365 Business Central Spring 2019 Update on-premises.

    For information, see Upgrading to Dynamics 365 Business Central On-Premises.

  2. Disable data encryption.

    If the current server instance uses data encryption, disable it. You can enable it again after upgrading.

    For more information, see Managing Encryption and Encryption Keys.

    Instead of disabling encryption, you can export the current encryption key, which you'll then import after upgrade. However, we recommend disabling encryption before upgrading.

Task 1: Install Dynamics 365 Business Central 2019 release wave 2 (version 15.0)

  1. Before you install version 15, it can be useful to create desktop shortcuts to the version 14.0 tools, such as the Business Central Server Administration tool, Business Central Administration Shell, and Dynamics NAV Development Shell because the Start menu items for these tools will be replaced with the version 15.0 tools.

  2. Install all components of Business Central 2019 release wave 2 (version 15).

    If you didn't uninstall version 14.0, then you must either specify different port numbers for components during installation or stop the version 14.0 Business Central Server instance before you run the installation. Otherwise, you'll get an error that the Business Central Server failed to install.

    For more information, see Installing Business Central Using Setup.

  3. Copy the version 14 CodeViewer add-in to the version 15.0 server installation.

    1. Find the CodeViewer folder in the Add-ins folder of the version 14 RoleTailored client installation. By default, the folder path is C:\Program Files (x86)\Microsoft Dynamics 365 Business Central\140\RoleTailored Client\Add-ins.

    2. Copy the folder to the Add-ins folder of the version 15 server installation. By default, the folder path is C:\Program Files\Microsoft Dynamics 365 Business Central\150\Service\Add-ins. Replace the existing folder and files, if any.

    CodeViewer is no longer used in version 15. But it's required because of references that exist in the converted application. If you omit this step, you might get compilation errors later.

Task 2: Convert your application from C/AL to AL

Convert your solution from C/AL code to AL code. For more information, see Code Conversion from C/AL to AL.

Task 3: Prepare the application database for technical upgrade

  1. Make backup of the database.

  2. Make sure that you have the extension packages for all published extensions.

    You'll need these packages later to publish and install the extensions again.

  3. Uninstall all extensions from the old tenants.

    Run the Business Central Administration Shell for version 14.0 as an administrator. To uninstall an extension, you use the Uninstall-NAVApp cmdlet. For example, together with the Get-NAVAppInfo cmdlet, you can uninstall all extensions with a single command:

    Get-NAVAppInfo -ServerInstance <BC14 server instance> -Tenant <tenant ID> | % { Uninstall-NAVApp -ServerInstance <BC14 server instance> -Name $_.Name -Version $_.Version -Tenant <tenant ID>}

    If you have a single tenant deployment, you can omit the -Tenant parameter and value.

  4. Unpublish all extensions from the application server instance.

    To unpublish extensions, use the Unpublish-NAVAPP cmdlet. Together with the Get-NAVAppInfo cmdlet, you can uninstall all extensions from the tenant using a single command:

    Get-NAVAppInfo -ServerInstance <BC14 server instance> | % { Unpublish-NAVApp -ServerInstance <BC14 server instance> -Name $_.Name -Version $_.Version }

  5. Unpublish all system, test, and application symbols.

    To unpublish symbols, use the Unpublish-NAVAPP cmdlet. You can unpublish all symbols by using the Get-NAVAppInfo cmdlet with the -SymbolsOnly switch as follows:

    Get-NAVAppInfo -ServerInstance <BC14 server instance> -SymbolsOnly | % { Unpublish-NAVApp -ServerInstance <BC14 server instance> -Name $_.Name -Version $_.Version }

    What are symbols?

  6. (Multitenant only) Dismount the tenants from the application server instance.

    To dismount a tenant, use the Dismount-NAVTenant cmdlet:

    Dismount-NAVTenant -ServerInstance <BC14 server instance> -Tenant <tenant ID>

  7. Stop the server instance.

    Stop-NAVServerInstance -ServerInstance <BC14 server instance>

Task 4: Convert the version 14.0 application database to the version 15.0 platform

This task runs a technical upgrade on the application database. A technical upgrade converts the database from the version 14.0 platform to the version 15.0 platform. This conversion updates the system tables of the database to the new schema (data structure). It also provides the latest platform features and performance enhancements.

  1. If the database is on Azure SQL Database, you may get 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.

  1. Start Business Central Administration Shell for version 15.0 as an administrator.

    For more information, see Run Business Central Administration Shell.

  2. Run the Invoke-NAVApplicationDatabaseConversion cmdlet to start the conversion:

    Invoke-NAVApplicationDatabaseConversion -DatabaseServer <database server>\<database instance> -DatabaseName "<BC14 database name>"

    When completed, a message like the following displays in the console:

    DatabaseServer      : .\BCDEMO
DatabaseName        : Demo Database BC (14-0)
DatabaseCredentials :
DatabaseLocation    :
Collation           :

Note

When the database is on Azure SQL Database, you may get the following error:

SQL Server: Execution Timeout Expired. The timeout period elapsed prior to completion of the operation or the server is not responding. The statement has been terminated.

If you do, scale up the database resources in Azure SQL, then run the Invoke-NAVApplicationDatabaseConversion cmdlet again. If the conversion is successful, you can then scale it back down to its original setting and continue the upgrade.

Task 5: Connect and configure the version 15 server instance

When you installed version 15 in Task 1, a version 15 Business Central Server instance was created. In this task, you change server configuration settings that are required to complete the upgrade. Some of the changes are only required for version 14 to version 15.0 upgrade and can be reverted after you complete the upgrade.

  1. 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 Manage Instance.

  2. Set the server instance to connect to the application database.

    Set-NAVServerConfiguration -ServerInstance <BC15 server instance> -KeyName DatabaseName -KeyValue "<BC14 database name>"

    In a single tenant deployment, this command mounts the tenant automatically. For more information, see Connecting a Server Instance to a Database.

  3. Disable task scheduler on the server instance for purposes of upgrade.

    Set-NavServerConfiguration -ServerInstance <BC15 server instance> -KeyName "EnableTaskScheduler" -KeyValue false

    Be sure to re-enable task scheduler after upgrade if needed.

  4. Restart the server instance.

    Restart-NAVServerInstance -ServerInstance <BC15 server instance>

Task 6: Publish system symbols, base application, and test library extensions

In this task, you'll publish extensions to the version 15.0 server instance. Publishing adds the extension to the application database that is mounted on the server instance. The extension is then available for installing on tenants later. It updates internal tables, compiles the components of the extension behind-the-scenes, and builds the necessary metadata objects that are used at runtime.

The steps in this task continue to use the Business Central Administration Shell for version 15.0 that you started in the previous task.

  1. Publish the system symbols extension for version 15.

    The symbols extension contains the required platform symbols that the base application depends on. The symbols extension package is called System.app. You find it where the AL Development Environment is installed. The default installation path is C:\Program Files (x86)\Microsoft Dynamics 365 Business Central\150\AL Development Environment.

    Publish-NAVApp -ServerInstance <BC15 server instance> -Path "<path to the System.app file>" -PackageType SymbolsOnly

  2. Publish the custom base application extension that you created in Task 2.

    Publish-NAVApp -ServerInstance <BC15 server instance> -Path "<path to the base application extension package file>"

  3. Publish the test library extension if you created one in Task 2.

    Publish-NAVApp -ServerInstance <BC15 server instance> -Path "<path to the test library extension package file>"

Task 7: Synchronize tenant and synchronize/install base application and test library extensions

This task updates the tenant database schema with schema changes in system objects and application objects. You'll synchronize the tenant to the custom base application and test library extension (if any). When you synchronize the tenant, extensions take ownership of the tables in the SQL Database.

If you have a multitenant deployment, run these steps for each tenant (replacing <tenant ID> with the appropriate tenant ID).

  1. (Multitenant only) Mount the tenant to the version 15 server instance.

    To mount the tenant, use the Mount-NAVTenant cmdlet:

    Mount-NAVTenant -ServerInstance <BC15 server instance> -DatabaseName "<BC14 database name>" -DatabaseServer <database server>\<database instance> -Tenant <tenant ID> -AllowAppDatabaseWrite

    Important

    You must use the same tenant ID for the tenant that was used in the old deployment; otherwise you will get an error when mounting or syncing the tenant. If you want to use a different ID for the tenant, you can either use the -AlternateId parameter now or after upgrading, dismount the tenant, then mount it again using the new ID and the OverwriteTenantIdInDatabase parameter.

    Note

    For upgrade, we recommend that you use the -AllowAppDatabaseWrite parameter. After upgrade, you can dismount and mount the tenant again without the parameter if needed.

  2. Synchronize the tenant to the system objects.

    Use the Sync-NAVTenant cmdlet:

    Sync-NAVTenant -ServerInstance <BC15 server instance> -Tenant <tenant ID> -Mode Sync

    With a single-tenant deployment, you can omit the -Tenant parameter and value.

    At this stage, the tenant state is Operational.

  3. Synchronize the tenant to the base application extension (Base Application).

    Use the Sync-NAVApp cmdlet:

    Sync-NAVApp -ServerInstance <BC15 server instance> -Name "Base Application" -Version <extension version> -tenant <tenant ID>

    With this step, the base app takes ownership of the database tables. When completed, in SQL Server, the table names will be suffixed with the base app extension ID.

  4. Install custom base application extension on the tenant.

    To install the extension, you use the Install-NAVApp cmdlet.

    Install-NAVApp -ServerInstance <BC15 server instance> -Name "Base Application" -Version <extension version>

    At this point, the base application is upgraded to the version 15 platform and is operational. You can open the application in the client.

  5. Synchronize and install the test library extension.

    This step is like what you did for the custom base application in steps 3 and 4.

Task 8: Configure the version 15 server instance for migrating extensions

In this task, you configure the version 15 server so that the Microsoft and third-party extensions that were installed in the version 14 deployment can be reinstalled. You'll configure the DestinationAppsForMigration parameter of the server instance with information about the custom base application and test library. Specifically, you need the appId, name, and publisher assigned to these extensions. With the DestinationAppsForMigration parameter set, when you publish the Microsoft and third-party extensions, the server instance will automatically modify the manifest of the extensions to include the dependency on the base application and test library extension, allowing them to be published.

  1. Get the appId, name, and publisher of the custom base application and test library.

    Get-NAVAppInfo -ServerInstance <BC15 server instance>

  2. Set the DestinationAppsForMigration parameter for the server instance configuration to include the information about the custom base application and test library (if used). For example:

    Set-NAVServerConfiguration -ServerInstance <BC15 server instance> -KeyName "DestinationAppsForMigration" -KeyValue '[{"appId":"437dbf0e-84ff-417a-965d-ed2bb9650972", "name":"Base Application", "publisher": "Microsoft"},{"appId":"<test library extension app ID>", "name":"<test library extension name>", "publisher": "<test library publisher>"}]'

  3. Restart the server instance.

Task 9: Publish, synchronize, and install extensions on the tenants

Now, you can install the Microsoft and 3rd-party extensions that were installed on the tenant before the upgrade.

  1. Publish the old extension versions.

    Publish-NAVApp -ServerInstance <BC15 server instance> -Path "<path to extension package file>"

    You only need to do this step once.

  2. Synchronize the extension.

    Sync-NAVApp -ServerInstance <BC15 server instance> -Name "<extension name>" -Version <extension version> -tenant <tenant ID>

  3. Install the extension:

    Install-NAVApp -ServerInstance <BC15 server instance> -Name "<extension name>" -Version <extension version> -tenant <tenant ID>

  4. Repeat steps 2 and 3 for each extension and on each tenant.

Now, your application is fully upgraded to the version 15 platform.

Task 10: Post-upgrade

  1. Upgrade Javascript-based control add-ins to new versions.

    The Business Central Server installation includes new versions of the following Microsoft-provided Javascript-based control add-ins that must be upgraded.

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

    To upgrade the control add-ons, do the following steps:

    1. Open the Business Central client.

    2. Search for and open the Control Add-ins page.

    3. Choose Actions > Control Add-in Resource > Import.

    4. 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's a subfolder for each add-in. For example, the path to the Business Chart control add-in is C:\Program Files\Microsoft Dynamics 365 Business Central\150\Service\Add-ins\BusinessChart\Microsoft.Dynamics.Nav.Client.BusinessChart.zip.

    5. After you've imported all the new control add-in versions, restart Business Central Server instance.

  2. Enable task scheduler on the server instance.

  3. (Multitenant only) For tenants other than the tenant that you use for administration purposes, if you mounted the tenants using the -AllowAppDatabaseWrite parameter, dismount the tenants, then mount them again without using the -AllowAppDatabaseWrite parameter.

  4. If you want to use data encryption as before, enable it.

    For more information, see Managing Encryption and Encryption Keys.

    Optionally, if you exported the encryption key instead of disabling encryption earlier, import the encryption key file to enable encryption.

See Also

Upgrading the Data
Upgrading to Business Central
Business Central 14.X to 15.X compatibility matrix