Walkthrough: Automating the Upgrade Process

  • Article

This walkthrough illustrates how you can upgrade data in a Microsoft Dynamics NAV solution by running it through an upgrade pipeline using Windows PowerShell.

You can upgrade the data in your existing Microsoft Dynamics NAV 2013 solution to Microsoft Dynamics NAV 2013 R2 by using the sample Windows PowerShell scripts that are included in Microsoft Dynamics NAV. You can use the automation of the data upgrade to upgrade a single database or multiple databases faster. For example, if you maintain multiple Microsoft Dynamics NAV databases because you support multiple customers with the same Microsoft Dynamics NAV application, you can reduce the time that you spend upgrading each database by using Windows PowerShell scripts. In that case, you can upgrade the application locally, and then use scripts to roll out the data upgrade of each database with a short time when each database is not available. You can combine this automated upgrade with a migration to multitenancy if this makes maintenance easier for you.

About this walkthrough

After completing this walkthrough, you will have a Microsoft Dynamics NAV 2013 R2 solution with upgraded data. The walkthrough uses the CRONUS International Ltd. demonstration database for Microsoft Dynamics NAV 2013 and Microsoft Dynamics NAV 2013 R2.

This walkthrough illustrates the following tasks:

  • Prepare the upgrade pipeline.

  • Upgrade the Microsoft Dynamics NAV 2013 production database.

  • Remove the upgrade pipeline.

Prerequisites

To complete this walkthrough, you need the following:

  • A backup of the database that you want to upgrade, such as NAV 2013 DB.bak.

    You will restore the backup into a database named NAV 2013 DB.

  • The latest version of the Microsoft Dynamics NAV 2013 R2 product media.

  • A Microsoft Dynamics NAV 2013 R2 partner license.

  • The equivalent of a Microsoft Dynamics NAV 2013 R2 customer license.

Preparing the Upgrade Pipeline

In order to automate the data upgrade process, you must prepare the application databases that the script uses as input during the data upgrade.

You create application databases for both the Microsoft Dynamics NAV 2013 database and the Microsoft Dynamics NAV 2013 R2 database. This uses the multitenant capabilities of Microsoft Dynamics NAV 2013 R2 by storing application tables in a separate database. When the application is stored in a dedicated database, the backup files are smaller and faster to handle during the upgrade. However, this does not mean that you migrate to a multitenant deployment architecture. When the upgrade is complete, the script will merge the application database with the business database again. For more information, see Separating Application Data from Business Data.

First, you must convert the Microsoft Dynamics NAV 2013 database. The application from this database is used by the first Microsoft Dynamics NAV Server instance in the data upgrade pipeline.

To convert the Microsoft Dynamics NAV 2013 database

  1. Restore the NAV 2013 DB.bak backup database to a database in SQL Server. In this walkthrough, the name of the restored Microsoft Dynamics NAV 2013 database is NAV 2013 DB.

  2. Install the Microsoft Dynamics NAV 2013 R2 demo installation option.

  3. Start the development environment with administrator privileges, and then import your partner license.

  4. Open the NAV 2013 DB database. When asked if you want to convert the database, choose the OK button.

  5. When the conversion process has completed, choose Tools, and then choose Options.

  6. In the Options window, change the value for the Prevent data loss from table changes option to No, and then choose the OK button.

  7. In Object Designer, select all objects, and then press F11 to compile all objects.

    The compilation will cause several errors. You must resolve the errors before you continue. For more information, see Converting a Microsoft Dynamics NAV 2013 Database.

  8. Import the Upgrade Toolkit Step 1 objects in the Upgrade700701.1.fob file on the Microsoft Dynamics NAV 2013 R2 product media.

If your application requires post-upgrade setup, you can use RapidStart Services for Microsoft Dynamics NAV to prepare the configuration of Microsoft Dynamics NAV 2013 R2 application functionality. The upgrade script can then import that data into all companies of the upgraded database. For example, you can add new source codes and register them in the Source Code Setup table, or add new number series to the newly added document types. For more information, see Set Up a Company With RapidStart Services for Microsoft Dynamics NAV and How to: Create a Configuration Package.

To make sure that the upgrade script imports the RapidStart package into every company of the database being upgraded, you must specify the path of the RapidStart package that you have prepared in the $NAVUpgrade_RapidStartPackageFile parameter of the Set-PartnerSettings.ps1 script before you start the upgrade.

Next, you extract the tables that define the Microsoft Dynamics NAV 2013 application to a dedicated application database.

To export the Microsoft Dynamics NAV 2013 application tables to the App1 application database

  1. Open the Microsoft Dynamics NAV 2013 R2 Administration Shell.

    Important

    You must run the program as administrator. Also, you must make sure that scripting is enabled on the computer.

    For more information, see Microsoft Dynamics NAV Windows PowerShell Cmdlets.

  2. To export the application tables from the converted Microsoft Dynamics NAV 2013 database, type the following command:

    Export-NAVApplication –DatabaseServer localhost\NAVDEMO –DatabaseName 'NAV 2013 DB' –DestinationDatabaseName 'App1' -Force

    This extracts the application tables from the Microsoft Dynamics NAV 2013 database to a new database, App1.

Next, you prepare the application database that is used by the third Microsoft Dynamics NAV Server instance in the data upgrade pipeline.

To export the Microsoft Dynamics NAV 2013 R2 application tables to the App3 application database

  1. In the development environment, and open the Microsoft Dynamics NAV 2013 R2 demonstration database, Demo Database NAV (7-1).

  2. Make sure that you have the relevant permissions, permission sets, profiles, client control add-ins, and web services configured. For example, you can import them from your Microsoft Dynamics NAV 2013 database. These tables will be exported to the third application database that is used in the upgrade process.

    To verify that the data is set up correctly, run the following pages from Object Designer:

    Page ID Name

    810

    Web Services

    9171

    Profile List

    9802

    Permission Sets

    9803

    Permissions

    9820

    Control Add-Ins

    You can use the actions that are available in each window to update the data if necessary. For example, the following client control add-ins are available from the Microsoft Dynamics NAV 2013 R2 product media:

    • Microsoft.Dynamics.Nav.Client.BusinessChart

    • Microsoft.Dynamics.Nav.Client.PageReady

    • Microsoft.Dynamics.Nav.Client.PingPong

    • Microsoft.Dynamics.Nav.Client.VideoPlayer

  3. To export the application tables from the Microsoft Dynamics NAV 2013 R2 database, in the Microsoft Dynamics NAV 2013 R2 Administration Shell, type the following command:

    Export-NAVApplication –DatabaseServer localhost\NAVDEMO –DatabaseName ' Demo Database NAV (7-1)' –DestinationDatabaseName 'App3' -Force

    This extracts the application tables from the Microsoft Dynamics NAV 2013 database to a new database, App3.

Next, you prepare the application database that is used by the second Microsoft Dynamics NAV Server instance in the data upgrade pipeline. This application database must contain all Upgrade Toolkit objects.

To export the Microsoft Dynamics NAV 2013 R2 application tables to the App2 application database

  1. Return to the development environment, and open the Microsoft Dynamics NAV 2013 R2 demonstration database, Demo Database NAV (7-1).

  2. Import the Upgrade Toolkit Step 1 objects in the Upgrade700701.1.fob file on the Microsoft Dynamics NAV 2013 R2 product media.

  3. Import the Upgrade Toolkit Step 2 objects in the Upgrade700701.2.fob file on the Microsoft Dynamics NAV 2013 R2 product media.

    Next, you create a new application database that is based on the Microsoft Dynamics NAV 2013 R2 database but includes the Upgrade Toolkit objects.

  4. In the Microsoft Dynamics NAV 2013 R2 Administration Shell, type the following command:

    Export-NAVApplication –DatabaseServer localhost\NAVDEMO –DatabaseName ' Demo Database NAV (7-1)' –DestinationDatabaseName 'App2' -Force

You have created three application databases. You must create backups of the databases so that you can use them in the automated upgrade process. Use SQL Server Management Studio to create backups of the App1, App2, and App3 databases.

As a result of this procedure, you have three backups of databases as described in the following table.

File name Description

App1.bak

Contains the application tables from the converted Microsoft Dynamics NAV 2013 database and the Upgrade Toolkit Step 1 objects.

App2.bak

Contains the application tables from the Microsoft Dynamics NAV 2013 R2 database with your customizations, the Upgrade Toolkit Step 1 objects, and the Upgrade Toolkit Step 2 objects.

App3.bak

Contains the application tables from the Microsoft Dynamics NAV 2013 R2 database with your customizations.

This application database must contain the configuration data for permissions, permission sets, web services and client control add-ins that the fully upgraded database must contain.

You have prepared the databases that you use during the upgrade process. This concludes the work that you must do in the Microsoft Dynamics NAV development environment. The following section illustrates how the rest of the upgrade process runs.

Upgrade Microsoft Dynamics NAV 2013 Databases in a Windows PowerShell Pipeline

In this section, you use the databases that you prepared in the previous section in an automated upgrade process. This process uses the Microsoft Dynamics NAV Windows PowerShell cmdlets and sample scripts. In addition to the databases that you already prepared, the upgrade process takes as input the database that you want to upgrade. For example, when you upgrade a customer database, you can use these scripts to make the data upgrade faster and simpler. Also, if you maintain multiple Microsoft Dynamics NAV deployments with the same application, in this section you are upgrading one of those deployments at the customer site. This section is repeatable.

To help you keep track of which components are used for what, we recommend that you set up a folder structure such as the following:

  • Upgrade

    • Databases

    • Licenses

    • Logs

    • Upgrade Script

To prepare the computer where you run the upgrade

  1. Copy the App1.bak, App2.bak, and App3.bak backup files that you created in the previous section into the Databases folder.

  2. Back up the database that you want to upgrade to a file such as NAV2013Production.bak, and then move the backup file to the Databases folder.

  3. Copy your Microsoft Dynamics NAV 2013 R2 partner license and customer license to the Licenses folder.

  4. Copy the Microsoft Dynamics NAV 2013 R2 sample upgrade scripts from the Microsoft Dynamics NAV 2013 R2 product media to the Upgrade Script folder.

    On the product media, the sample upgrade scripts are in the Upgrade folder under the WindowsPowerShellScripts folder. For more information, see Sample Windows PowerShell Scripts for Microsoft Dynamics NAV Administration.

    Important

    To run the data upgrade scripts, you must have a default instance of Microsoft Dynamics NAV Server and the Microsoft Dynamics NAV Server Administration tool running on the same machine. You can install these components by choosing the Custom option in Microsoft Dynamics NAV 2013 R2 Setup. You can skip this step if Demo version of Microsoft Dynamics NAV 2013 R2 is already installed on this machine.

You have prepared the computer where you will run the upgrade. Next, you specify which settings to apply to the upgrade script, and you run the script to upgrade the Microsoft Dynamics NAV 2013 database.

To upgrade the Microsoft Dynamics NAV 2013 database

  1. Start the Windows PowerShell ISE with administrator privileges.

  2. Open the Set-PartnerSettings.ps1 cmdlet, which is stored in the Upgrade Script folder on your computer.

    This scripted cmdlet sets values for the parameters that the cmdlets and scripts in the upgrade pipeline use. These values are specific to your deployment. In the script, parameters are commented out with a #TODO clause. You must remove the comments and sent the relevant values.

  3. Choose Edit, choose Replace in Script, and then, in the Replace window, specify that you want to replace # TODO: with blank space.

    This removes the comments from the parameters so that you can specify the relevant values and run the cmdlet.

  4. Change the relevant parameter values to match your deployment environment. This includes specifying the three backup files of the application databases, the various ports on the Microsoft Dynamics NAV Server instance that is created during the upgrade, the instance of SQL Server and the Microsoft Dynamics NAV Server instance, and other configuration settings. The Set-PartnerSettings.ps1 script contains a thorough description of the required parameters.

    Important

    You must also specify a name for the database that you want to upgrade and a tenant ID for it. This is because the upgrade process uses the multitenant capabilities on Microsoft Dynamics NAV and temporarily mounts the database that is being upgraded as a tenant against the specified Microsoft Dynamics NAV Server instance. If you only upgrade one database, you can leave the tenant ID as default.

  5. Save your changes.

    Next, you run the upgrade process.

  6. Open the Example.ps1 script, which is stored in the Upgrade Script folder on your computer, and then import Microsoft Dynamics NAV cmdlets by running the following command in the Windows PowerShell ISE:

    Import-Module C:\Program Files\Microsoft Dynamics NAV\71\Service\NavAdminTool.ps1

  7. Press F5 to run the script.

    This upgrades the specified database based on the parameter values that you specified. The last step of the upgrade script merges the App3 application database with the upgrade database so that you again have a single database.

When the upgrade finishes, you must change the Microsoft Dynamics NAV Server instance to access the upgraded database and restart the service. For more information, see How to: Configure a Microsoft Dynamics NAV Server Instance. This completes the upgrade of this Microsoft Dynamics NAV deployment.

See Also

Tasks

How to: Configure a Microsoft Dynamics NAV Server Instance

Concepts

Automating the Upgrade Process using Sample Windows PowerShell Scripts
Sample Windows PowerShell Scripts for Microsoft Dynamics NAV Administration

Other Resources

Upgrading to Microsoft Dynamics NAV 2013 R2