Edit

Upgrading the Data to Business Central: Multitenant Deployment

  • Article

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.

See print-friendly quick reference

This article describes the tasks required for upgrading data to the latest Business Central in a multitenant deployment.

About Data Upgrade

In this scenario, you already have an upgraded application that is mounted on a Business Central Server. You will then mount the old tenants on the server instance and perform the 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.

Important

Before you begin, read the article Important Information and Considerations for Before Upgrading. This article contains information about limitations and things that might require you to perform extra tasks before you upgrade, such as the use of extensions V1 and the deprecation of codeunit 1.

Prerequisites

Before you start the upgrade tasks, make sure you have 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 Business Central 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.

  2. (Upgrading from Dynamics NAV only) Custom V1 extensions used in Dynamics NAV have been converted to V2 extensions.

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

  3. Business Central has been installed with the upgraded application and upgrade toolkit.

    As a minimum, you must install the following components:

    • Business Central Server instance connected to the application database.

    • Dynamics NAV Development Environment for Business Central

    • AL Development Environment

      This installs the required system and test symbols for V2 extensions.

    • Business Central Server Administration tool (optional)

    • Business Central Web Server components (not required for upgrade).

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

  4. Permission sets (except SUPER) and permissions have been exported from the old tenant database.

    • When upgrading from Dynamics NAV

      To export permission sets and permissions, you run running XMLPort 9171 and 9172.

      It is important that you exclude the SUPER permission set when running XMLPort 9171. You can do this by adding the filter Role ID is <>SUPER.

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

    • When upgrading from an earlier version of Business Central

      In the client, search for and open the Permission Sets page, select the user-defined permission sets that you want to keep, and then choose Export Permission Sets.

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

    For more information, see Export and Import Encryption Keys.

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.

Prepare the tenant database for data upgrade

You perform these tasks on each tenant that you want to upgrade.

  1. Backup the tenant database.

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

  2. (Dynamics NAV upgrade only) Uninstall all V1 extensions.

    Make sure that all V1 extensions are uninstalled. Open the Dynamics NAV Administration Shell that matches to old database, and run these commands:

    1. To get a list of the V1 extensions that are installed, run this command:
    Get-NAVAppInfo -ServerInstance <OldServerInstanceName> -Tenant <TenantID>

    V1 extensions are indicated by CSIDE in the Extension Type column. 2. For each extension, run the Uninstall-NAVApp cmdlet to uninstall it:

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

  3. Dismount the tenant.

    Before you upgrade the tenant, you must dismount it from the old server instance. To dismount the tenant, run the Dismount-NAVTenant cmdlet:

    Dismount-NAVTenant -ServerInstance <OldServerInstanceName> -Tenant <TenantID>

Run the data upgrade on the tenant

You perform these tasks on each tenant that you want to upgrade.

  1. Mount the tenant.

    Mount the tenant on the new Business Central Server instance that connects to the newly application database. To mount the tenant, use the Mount-NAVTenant cmdlet:

    Mount-NAVTenant -ServerInstance <ServerInstanceName> -DatabaseName <Database name> -DatabaseServer <server\instance> -Tenant <TenantID> -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.

    Synchronize the tenant database schema with validation by running the Sync-NAVTenant cmdlet from the Business Central Administration Shell.

    Sync-NAVTenant -ServerInstance <ServerInstanceName> -Tenant <TenantID>

    When completed, the tenant should have the status OperationalDataUpgradePending or, if there are published extensions with newer versions than on the tenant, OperationalSyncPending. To verify this, run the following cmdlet:

    Get-NAVTenant -ServerInstance <ServerInstanceName> -tenant default -ForceRefresh

  3. If there are published extensions with newer versions than on the tenant, synchronize all published extensions with the tenant database.

    Synchronize the schema with the database by running the Sync-NAVApp cmdlet for each extension version:

    Sync-NAVApp -ServerInstance <ServerInstanceName> -Name <Name> -Version <N.N.N.N> -Tenant <TenantID>

    Or, to synchronize all published extensions using one command:

    Get-NAVAppInfo -ServerInstance <ServerInstanceName> -Tenant <TenantID> | % { Sync-NAVApp -ServerInstance <ServerInstanceName> -Name $_.Name -Version $_.Version }

    When completed, the tenant should have the status OperationalDataUpgradePending.

  4. Run the data upgrade.

    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. It will also upgrade the published extensions.

    1. Open the Business Central Administration Shell as an administrator, and then run Start-NavDataUpgrade cmdlet as follows:
    Start-NavDataUpgrade -ServerInstance <ServerInstanceName> -Tenant <TenantID> -FunctionExecutionMode Serial -ContinueOnError

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

    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 with the -SkipCompanyIntitialization parameter.

    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.

    1. Check for and resolve upgrade errors.

      Run the following command to get a list of any errors that have occurred:

      Get-NAVDataUpgrade ServerInstanceName> -ErrorOnly

      Resolve the errors before going to the next step.

  5. Install extensions on the tenant.

    Install the desired extensions on the tenant by running the Install-NAVApp cmdlet:

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

Post-upgrade tasks

  1. Import permission sets and permissions

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

    • For upgrade from Dynamics NAV:

      1. Open table 2000000004 Permission Sets in the client, and delete all permission sets except SUPER.

        Note

        You are only required to delete those permission sets that also included in the permission sets XML file that you will import. Because if you try to import a permission set with the same name as on already in the database, you will get an error.

      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.

    • For upgrade from an earlier Business Central version:

      1. In the client, search for and open the Permission Sets page.
      2. Delete all user-defined permissions.
      3. Choose Import Permission Sets, then select the permissions set file that you exported previously.

  2. Import encryption keys.

    For more information, see Exporting and Importing Encryption Keys.

  3. (Optional) Update Web Server instance configuration file

    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.

    • If the old deployment used a web.config file, then you have to manually change the settings in the navsetting.json file that is used on the new Business Central Web Server instance.

    • If you upgraded from Business Central October 2018, you can replace the navsettings.json file on the new Business Central Web Server instance with the old file. However, as of Business Central April 2019, the following settings are now configured under a root element called ApplicationIdSettings instead of the root element NAVWebSettings.

      • AndroidPrivacy
      • AndroidSoftwareLicenseTerms
      • AndroidThirdPartyNotice
      • BaseHelpUrl
      • BaseSettingsSectionName
      • CommunityLink
      • FeedbackLink
      • IosPrivacy
      • IosSoftwareLicenseTerms
      • IosThirdPartyNotice
      • KeyboardShortcutsLink
      • PrivacyLink
      • LegalLink
      • SignInHelpLink

      If the old navsettings.json file uses any of these settings, then you will have to move them from the NAVWebSettings element to the ApplicationIdSettings element.

    For more information about the navsettings.json file, see Configuring Business Central Web Server Instances.

  4. Upload the customer license.

    For more information, see Uploading the License File

See Also

Upgrading the Application Code
Upgrading to Business Central