Technical Upgrade to Dynamics 365 Business Central 2019 Wave 2

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 will not upgrade the application to the latest version. With this process, you will 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 the very similar for a single-tenant and multitenant deployment. However, there are some inherent differences because with a single-tenant deployment, the application and business data are included in the same database, while with 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. If you are upgrading from Business Central Fall 2018 (version 13) or Dynamics NAV, we recommend that you upgrade to the latest update for version 14 that has a compatible update for version 15. If your solution is already on version 14, then you do not have to upgrade to the latest version 15 update. For more information, see Dynamics 365 Business Central Upgrade Compatibility Matrix.

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

    For information about how to perform the upgrade, see Upgrading to Dynamics 365 Business Central On-Premises.

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 will be replaced with the version 15.0 tools.

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

    If you did not uninstall version 14.0, then you must either specify different port numbers for components (like the Business Central Server instance and web services) during installation, or you must stop the version 14.0 Business Central Server instance before you run the installation. Otherwise, you will 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.

    Copy the CodeViewer folder from the Add-ins folder of the Business Central version 14 RoleTailored client installation (C:\Program Files (x86)\Microsoft Dynamics 365 Business Central\140\RoleTailored Client\Add-ins) to the Add-ins folder of the Business Central 150 Server installation (C:\Program Files\Microsoft Dynamics 365 Business Central\150\Service\Add-ins). Replace the existing folder and files, if any.

    In version 15.0 CodeViewer is no longer used, but it is 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 access to the extension packages for all published extensions.

    You will need these 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 with the -SymbolsOnly switch.

    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 to convert it from the version 14.0 platform to the version 15.0 platform. The conversion updates the system tables of the database to the new schema (data structure) and provides the latest platform features and performance enhancements.

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

  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           :
    

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. 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 will mount the tenant automatically. For more information, see Connecting a Server Instance to a Database.

  1. 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 this after upgrade if needed.

  2. 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 will publish extensions to the version 15.0 server instance. Publishing an extension adds the extension to the application database that is mounted on the server instance, making it available for installing on tenants later. Publishing 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, which by default 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

In this task, you update the schema of tenant database schema with schema of changes in system objects and application objects. In this step, you will synchronize the tenant to the to your custom base application extension and test library extension (if any). With this operation, the extensions will take ownership of the tables in the SQL database.

If you have a multitenant deployment, perform 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 should be able to open the application in the client.

  5. Synchronize and install the test library extension, 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

With this task, you configure the version 15 server so that the Microsoft and 3rd party extensions that were installed in the version 14 deployment can be reinstalled. You will do this by configuring the DestinationAppsForMigration parameter of the serve 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 3rd 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 extensions.

    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 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:

    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 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\150\Service\Add-ins\BusinessChart\Microsoft.Dynamics.Nav.Client.BusinessChart.zip.

    5. After you have 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.

See Also

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