Technical upgrade to version 19

Use this process to upgrade any of the following versions to the Business Central 2021 release wave 2 platform (version 19). This process won't upgrade the application to the latest version.

  • Business Central 2021 release wave 1 (version 18)
  • Business Central 2020 release wave 2 (version 17)
  • Business Central 2020 release wave 1 (version 16)

Upgrade on customized Business Central application.

Before you begin

Review the information in this section before you start upgrading your deployment.

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.

Prepare new runtime packages

If a deployment uses extensions that are published as runtime packages, create new versions of runtime packages against the new platform and application. Although you could run Repair-NAVapp on the extensions instead, as described later in this article, this way isn't recommended. Using Repair-NAVapp can lead to problems with the extensions after upgrade.

For more information, see Creating Runtime Packages for Business Central On-Premises.

PowerShell variables used in tasks

Many of the steps in this article use PowerShell cmdlets, which require that you provide values for various parameters. To make it easier for copying or scripting in PowerShell, the steps use the following variables for parameter values. Replace the text between the " " with the correct values for your environment.

$OldBcServerInstance = "The name of the Business Central server instance for your previous version, for example: BC180"
$NewBcServerInstance = "The name of the Business Central server instance for version 19, for example: BC190"
$TenantId = "The ID of the tenant to be upgraded. If not using a multitenant server instance, set the variable to default, or omit -Tenant parameter."
$TenantDatabase = "The name of the Business Central tenant database to be upgraded, for example: Demo Database BC (19-0)" 
$ApplicationDatabase = "The name of the Business Central application database in a multitenant environment, for example: My BC App DB. For a single-tenant deployment, this is the same as $TenantDatabase." 
$DatabaseServer = "The SQL Server instance that hosts the databases. The value has the format server_name\instance_name, For example: localhost\BCDEMO"
$OldVersion = "The version number for the current System, Base, and Application extensions that you'll reinstall, for example: 18.1.24582.0"
$PartnerLicense = "The file path and name of the partner license"
$AddinsFolder = 'The file path to the Add-ins folder of version 19 server installation, for example, C:\Program Files\Microsoft Dynamics 365 Business Central\190\Service\Add-ins'
$CustomerLicense = "The file path and name of the customer license"

Task 1: Install version 19

  1. Choose a version 19 that's compatible with your current platform version.

    There are several updates for each Business Central version. The update of your current version must be compatible version 19 update that you want to upgrade to. For more information, see Dynamics 365 Business Central Upgrade Compatibility Matrix. If your solution, for example, is currently running 18.6, you can't upgrade to 19.0. You'll have to wait until 19.1 is available.

  2. Before you install version 19, it can be useful to create desktop shortcuts to the version 16.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 19.0 tools.

  3. Install version 19 components.

    You'll keep previous version installed for now. When you install version 19, you must either specify different port numbers for components (like the Business Central Server instance and web services) or stop the version 18.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.

  4. Copy Dynamics Online Connect add-in (upgrade from version 16 or earlier).

    The Dynamics Online Connect add-in was deprecated in version 17. As a result, it's been removed from the DVD and is no longer installed as part of the Business Central Server. However, for upgrade, the add-in might still be required for the old System Application. If the Business Central Server installation for your current version includes the Add-ins\Connect folder, then copy the Connect folder to the Add-ins folder of the version 19 server installation.

Task 2: Upgrade permission sets

Version 18 introduced the capability to define permissions sets as AL objects, instead of as data. Permissions sets as AL objects is now the default and recommended model for defining permissions. However for now, you can choose to use the legacy model, where permissions are defined and stored as data in the database. Whichever model you choose, there are permission set-related tasks you'll have to go through before and during upgrade.

For more information, see Upgrading Permissions Sets and Permissions.

Task 3: Prepare databases

In this task, you prepare the application and tenant databases for the upgrade.

  1. Make backup of the database.
  1. 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.

  2. (Single-tenant only) Uninstall all extensions from the old tenants.

    Run the Business Central Administration Shell for the previous version, like 18, as an administrator. For more information, see Run Business Central Administration Shell.

    Use the Uninstall-NAVApp cmdlet to uninstall an extension. For example, together with the Get-NAVAppInfo cmdlet, you can uninstall all extensions with a single command:

    Get-NAVAppInfo -ServerInstance $OldBcServerInstance  | % { Uninstall-NAVApp -ServerInstance $OldBcServerInstance -Name $_.Name -Version $_.Version }
    
  3. 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 $OldBcServerInstance  -SymbolsOnly | % { Unpublish-NAVApp -ServerInstance $OldBcServerInstance -Name $_.Name -Version $_.Version }
    

    What are symbols?

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

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

    Dismount-NAVTenant -ServerInstance $OldBcServerInstance -Tenant $TenantId
    
  5. Stop the server instance.

    Stop-NAVServerInstance -ServerInstance $OldBcServerInstance
    

Task 4: Convert application database to version 19

This task runs a technical upgrade on the application database. A technical upgrade converts the current database to the version 19.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.

Important

The conversion does not modify the application objects, but it will remove any modifications that you have made to system tables. After the conversion you will no longer be able to use it with current version.

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

    For more information, see Run Business Central Administration Shell.

  2. Run the Invoke-NAVApplicationDatabaseConversion cmdlet to start the conversion. In a multitenant deployment, run this cmdlet against the application database.

    Invoke-NAVApplicationDatabaseConversion -DatabaseServer $DatabaseServer -DatabaseName $ApplicationDatabase
    

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

    DatabaseServer      : .\BCDEMO
    DatabaseName        : Demo Database BC (18-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: Configure version 19 server

When you installed version 19 in Task 1, a version 19 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 the upgrade and can be reverted after you complete the upgrade.

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

    Set-NAVServerConfiguration -ServerInstance $NewBcServerInstance -KeyName DatabaseName -KeyValue $ApplicationDatabase
    

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

  2. If you want to use permission sets defined as data, set the UserPermissionSetsFromExtensions setting to false.

    Set-NavServerConfiguration -ServerInstance $NewBcServerInstance -KeyName "UsePermissionSetsFromExtensions" -KeyValue false
    
  3. Disable task scheduler on the server instance for purposes of upgrade.

    Set-NavServerConfiguration -ServerInstance $NewBcServerInstance -KeyName "EnableTaskScheduler" -KeyValue false
    

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

  4. Restart the server instance.

    Restart-NAVServerInstance -ServerInstance $NewBcServerInstance
    

Task 6: Import Business Central partner license

If you've gotten a new Business Central partner license, make sure that it has been uploaded to the database. To upload the license, use the Import-NAVServerLicense cmdlet:

Import-NAVServerLicense -ServerInstance $NewBcServerInstance -LicenseFile $PartnerLicense

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

Task 7: Recompile published extensions

Compile all published extensions against the new platform.

Important

Don't do this step on extensions published as runtime packages. Create new versions of the runtime packages instead. For more information, see Creating Runtime Packages for Business Central On-Premises.

  1. To compile an extension, use the Repair-NAVApp cmdlet, For example:

    Repair-NAVApp -ServerInstance $NewBcServerInstance -Name $ExtName -Version $ExtVersion
    

    To compile all published extensions at once, you can use this command:

    Get-NAVAppInfo -ServerInstance $NewBcServerInstance | Repair-NAVApp  
    
  2. If errors occur for any of the extensions, especially the system application or base application, you'll have to fix them before proceeding.

    For more information, see Fixing compilation errors for technical upgrade.

    In most cases, fixing these errors require you to create new versions of the extensions, which you'll have to publish and upgrade.

  3. Restart the server instance.

    Restart-NAVServerInstance -ServerInstance $NewBcServerInstance
    

Task 8: Synchronize tenant

  1. (Multitenant only) Mount the tenant to the new Business Central Server instance.

    You'll have to do this step and the next for each tenant. For more information, see Mount or Dismount a Tenant.

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

    Mount-NAVTenant -ServerInstance $NewBcServerInstance -DatabaseName $TenantDatabase -DatabaseServer $DatabaseServer -Tenant $TenantId -AllowAppDatabaseWrite
    

    Important

    You must use the same tenant ID for the tenant that was used in the old deployment; otherwise you'll 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.

    For upgrade, set the -AllowAppDatabaseWrite parameter. After upgrade, you can dismount and mount the tenant again without the parameter if needed.

  2. Synchronize the tenant.

    Use the Sync-NAVTenant cmdlet:

    Sync-NAVTenant -ServerInstance $NewBcServerInstance -Tenant $TenantId -Mode Sync
    

    For a single-tenant deployment, you can either set the $TenantId to default or omit the -Tenant $TenantId parameter. For more information about syncing, see Synchronizing the Tenant Database and Application Database.

  3. If you published new extension versions, like for system application and base application, synchronize the new versions with the tenant. Sychronize the extensions in order of dependency, for example:

    Sync-NAVApp -ServerInstance $NewBcServerInstance -Name "System Application" -Version "<version>" -Tenant $TenantId
    
    Sync-NAVApp -ServerInstance $NewBcServerInstance -Name "Base Application" -Version "<version>" -Tenant $TenantId
    

Task 9: Upgrade new extension versions

In this task, you upgrade the tenant to any new extension versions that you created during Task 7 to fix compilation errors, like for the system application and base application. Use the Start-NAVAppDataUgrade cmdlet, for example:

Start-NAVAppDataUpgrade -ServerInstance $NewBcServerInstance -Name "System Application"-Version "<version>" -Tenant $TenantId
Start-NAVAppDataUpgrade -ServerInstance $NewBcServerInstance -Name "Base Application"-Version "<version>" -Tenant $TenantId 

This step installs the new versions on the tenant.

Task 10: Reinstall extensions (single-tenant only)

In this task, you reinstall the same extensions that were installed on the tenant before, unless you've published new versions.

To install an extension, you use the Install-NAVApp cmdlet. For example:

  1. If your solution uses the System Application, install this first.

    Install-NAVApp -ServerInstance $NewBcServerInstance -Name "System Application" -Version $OldVersion
    

    Replace <extension version> with the exact version of the published System Application.

  2. Install the Base Application.

    Install-NAVApp -ServerInstance $NewBcServerInstance -Name "Base Application" -Version $OldVersion
    

    Replace <extension version> with the exact version of the published System Application.

  3. Install the Application extension.

    Install-NAVApp -ServerInstance $NewBcServerInstance -Name "Application" -Version $OldVersion
    

    Replace <extension version> with the exact version of the published Application extension.

    For more information about the Application extension, see The Microsoft_Application.app File.

  4. Install other extensions, including Microsoft and third-party extensions.

    Install-NAVApp -ServerInstance $NewBcServerInstance -Name $ExtName -Version $ExtVersion
    

At this point, your solution has been updated to the latest platform.

Task 11: Upgrade control add-ins

The Business Central Server installation includes new versions of the Microsoft-provided Javascript-based control add-ins, like Microsoft.Dynamics.Nav.Client.BusinessChart, Microsoft.Dynamics.Nav.Client.VideoPlayer, and more. If your solution uses any of these control add-ins, upgrade them to the latest version.

To upgrade the control add-ins from the client, 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\190\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.

Alternatively, you can use the Set-NAVAddin cmdlet of the Business Central Administration Shell. For example, the following commands update the control add-ins installed by default. Modify the commands to suit:

Set-NAVAddIn -ServerInstance $NewBcServerInstance -AddinName 'Microsoft.Dynamics.Nav.Client.BusinessChart' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $AddinsFolder 'BusinessChart\Microsoft.Dynamics.Nav.Client.BusinessChart.zip')
Set-NAVAddIn -ServerInstance $NewBcServerInstance -AddinName 'Microsoft.Dynamics.Nav.Client.FlowIntegration' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $AddinsFolder 'FlowIntegration\Microsoft.Dynamics.Nav.Client.FlowIntegration.zip')
Set-NAVAddIn -ServerInstance $NewBcServerInstance -AddinName 'Microsoft.Dynamics.Nav.Client.OAuthIntegration' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $AddinsFolder 'OAuthIntegration\Microsoft.Dynamics.Nav.Client.OAuthIntegration.zip')
Set-NAVAddIn -ServerInstance $NewBcServerInstance -AddinName 'Microsoft.Dynamics.Nav.Client.PageReady' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $AddinsFolder 'PageReady\Microsoft.Dynamics.Nav.Client.PageReady.zip')
Set-NAVAddIn -ServerInstance $NewBcServerInstance -AddinName 'Microsoft.Dynamics.Nav.Client.PowerBIManagement' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $AddinsFolder 'PowerBIManagement\Microsoft.Dynamics.Nav.Client.PowerBIManagement.zip')
Set-NAVAddIn -ServerInstance $NewBcServerInstance -AddinName 'Microsoft.Dynamics.Nav.Client.RoleCenterSelector' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $AddinsFolder 'RoleCenterSelector\Microsoft.Dynamics.Nav.Client.RoleCenterSelector.zip')
Set-NAVAddIn -ServerInstance $NewBcServerInstance -AddinName 'Microsoft.Dynamics.Nav.Client.SatisfactionSurvey' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $AddinsFolder 'SatisfactionSurvey\Microsoft.Dynamics.Nav.Client.SatisfactionSurvey.zip')
Set-NAVAddIn -ServerInstance $NewBcServerInstance -AddinName 'Microsoft.Dynamics.Nav.Client.VideoPlayer' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $AddinsFolder 'VideoPlayer\Microsoft.Dynamics.Nav.Client.VideoPlayer.zip')
Set-NAVAddIn -ServerInstance $NewBcServerInstance -AddinName 'Microsoft.Dynamics.Nav.Client.WebPageViewer' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $AddinsFolder 'WebPageViewer\Microsoft.Dynamics.Nav.Client.WebPageViewer.zip')
Set-NAVAddIn -ServerInstance $NewBcServerInstance -AddinName 'Microsoft.Dynamics.Nav.Client.WelcomeWizard' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $AddinsFolder 'WelcomeWizard\Microsoft.Dynamics.Nav.Client.WelcomeWizard.zip')

Task 12: Install upgraded permissions sets

In this task, you install the custom permission sets that you upgraded earlier in this procedure. The steps depend on whether you've decided to use permission sets as AL objects or as data.

For permission sets as AL objects

  1. Publish the extension or extensions that include the permission sets.
  2. Sync the extensions with the tenant.
  3. Install the extensions on the tenant.

For permission sets as data in XML

  1. Set the UserPermissionSetsFromExtensions setting of the Business Central Server instance to false.

    Set-NavServerConfiguration -ServerInstance $NewBcServerInstance -KeyName "UsePermissionSetsFromExtensions" -KeyValue false
    
  2. Restart the serve instance.

  3. Open the Business Central Web client.

  4. Search for and open the Permission Sets page.

  5. Select Import Permission Sets, and follow the instructions to import the XML file.

For more information, see To export and import a permission set.

Post-upgrade tasks

  1. Enable task scheduler on the server instance.

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

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

  4. Import the customer license.

    Import the customer license by using the Import-NAVServerLicense cmdlet, as you did with the partner license. You'll have to restart the server instance afterwards.

    Import-NAVServerLicense -ServerInstance $NewBcServerInstance -LicenseFile $CustomerLicense
    Restart-NAVServerInstance -ServerInstance $NewBcServerInstance
    

See also

Upgrading to Business Central
Business Central Compatibility matrix