Upgrade PI Integrator for Business Analytics

You can upgrade to PI Integrator for Business Analytics 2020 R2 SP2 Patch 1 from the following versions:

• 2020 R2 SP1

• 2020 R2 SP2

Interim upgrades

For versions prior to 2020 R2 SP1, you must first upgrade to PI Integrator for Business Analytics 2020 R2 SP1.

• There is no direct upgrade path from PI Integrator for Business Analytics 2020 R2 Patch 2 and earlier to PI Integrator for Business Analytics 2020 R2 SP2 Patch 1.

For versions prior to 2020, you must first upgrade to PI Integrator for Business Analytics 2020.

• There is no direct upgrade path from PI Integrator for Business Analytics 2018 R2 SP2 and earlier to PI Integrator for Business Analytics 2020 R2 SP1 or later.

• Download the PI Integrator for Business Analytics 2020 SQL Utility which contains the script that upgrades the databases.

For versions prior to 2018 R2, you must first upgrade to PI Integrator for Business Analytics 2018 R2.

• If you are upgrading to PI Integrator for Business Analytics 2018 R2 as an intermediate version, and PI Integrator for Business Analytics was running against PI AF Server 2014 or earlier, then you must upgrade to PI AF 2015 or later before continuing. If not, your existing PI Integrator for Business Analytics users will not be automatically converted to PI AF identities. For more information, see User access permissions.

• If you have multiple pre-2018 1.x instances of PI Integrator installed to the same PI AF server, you must upgrade all instances to 2020 or later (2.x). If you upgrade some, but not all instances to 2.x, your 1.x views may fail to publish after the upgrade.

• If the user account used to upgrade to PI Integrator for Business Analytics 2018 R2 has a db_accessadmin database role membership on the PIIntegratorDB, PIIntegratorLogs, and PIIntegratorStats databases, the user account must also have SELECT, UPDATE, and ALTER privileges on the PIIntegratorStats database. If the user account is not granted permissions for the upgrade, then you must manually update the databases before you upgrade.

Upgrade preparation

Before upgrading:

• Verify that the specified Windows service account runs PI Integrator for Business Analytics in the Domain\User format. If the service account uses the User Principal Name (UPN) format (account@domain.com), the upgrade will fail. You will need to manually revert the service account in services.msc to the Domain\User format and then proceed with the upgrade.

• Ensure that you have local admin privileges on the computer where you are installing PI Integrator for Business Analytics.

• Ensure that the user account used to upgrade the software has sysadmin privileges on the SQL Server where you are upgrading the PI Integrator databases. Note that the SQL schema upgrade is required only for certain upgrade paths as mentioned in the above Interim Upgrades section. See What are the supported upgrade paths for PI Integrator for Business Analytics and PI Integrator for Microsoft Azure?

The following permissions are required to upgrade the PI Integrator's backend SQL databases.

• If the user account is not granted the required privileges, then a user who has sysadmin privileges, typically a database administrator, must manually upgrade the SQL databases. Upgrade the SQL databases first, before PI Integrator for Business Analytics.

• After you install the SQL databases, add the user account that will upgrade PI Integrator for Business Analytics as a login on SQL Server. The user upgrading the PI Integrator for Business Analytics must have the following permissions:

1. db_accessadmin database role membership on the PIIntegratorDB, PIIntegratorStats, and PIIntegratorLogs databases

2. SELECT permissions on the PIIntegratorStats database

Note: During the upgrade, you will not be able to specify a new PI AF Server or SQL Server.

• If the application impersonation security setting is on during installation, and your PI Integrator for Business Analytics is installed in a one-way domain trust environment, run the identity migration tool in the same domain as your PI Integrator for Business Analytics users, prior to upgrade. See How to run the Identity Migration Tool for more information.

Upgrade procedure

PI Integrator for Business Analytics installs executable files. If any views are running when the upgrade begins, or are scheduled to run while the upgrade is taking place, PI Integrator for Business Analytics stops or postpones the jobs before it begins upgrading the executable files. Once the upgrade is complete, it restarts the jobs or resumes running the jobs.

If you prefer, you can manually stop any running jobs. However, you will need to restart the jobs once the upgrade is completed.

1. Download the PI Integrator for Business Analytics setup kit from the AVEVA Customer Portal Products page.

2. Right-click the setup executable and click Run as Administrator to launch the installation wizard.

   The Self-Extracting Executable window opens.

3. Specify the extraction path for the installer and click OK.

   The Welcome to the PI Integrator for Business Analytics Setup window opens, listing the separate modules included with the installation. The installation wizard upgrades each module or ensures that the correct version of the module already exists on your system.

4. Click OK.

   The Welcome to the PI Integrator for Business Analytics Installation window opens.

5. Click Next.

   The Logon Information window opens.

6. Specify the Password for the Windows service account that runs the PI Integrator for Business Analytics services.

7. Click Next.

   The Port and TLS Certificate Configuration window opens.

8. Enter a valid available port number in the Enter a port number field and click Validate Port.

   The PI Integrator for Business Analytics user interface uses this port to connect with the PI Integrator Framework service component.

   Tip: If you use port 443, you can omit this port number when you specify the URL for PI Integrator for Business Analytics.

9. Choose a TLS certificate from one of the following sources:

   • (Recommended) TLS certificate from a certificate authority. Choose Import certificate and click Select Certificate to choose a certificate that has been issued by a certificate authority and imported to the machine where PI Integrator for Business Analytics is being installed.

   • Self-signed certificate that is generated during the installation. This is the default.

   Note: If you choose this option, users logging in from remote machines may see a security warning message. To avoid this warning for self-signed certificates, the certificate must be explicitly trusted on the client machine. See the workaround in the Knowledge Base article Certificate error returned when navigating to a PI Vision or PI Web API web site using a self-signed certificate.

10. In the PI Integrator Worker Nodes window, click the arrow and select the number of worker nodes you want to install, and then click Next.

    The Ready to Install the Application window opens.

    Note: Each worker node requires additional CPU and RAM.

    Note: If you encounter an error, ensure that the port is not in use and open.

11. Click Next.

    If you have view, the Back up Existing Views window opens. Otherwise, skip to step 13.

12. Click Take Backup.

    This step takes a backup of your existing view configuration from the AF configuration database. If the backup completes successfully, this dialog lists the status of the backup, as well as a link to the backup file in the %PIHOME%\dat directory.

    If an error occurs, an error message will appear. Click OK to close the error dialog.

    At this point you can either:

    • Resolve the error and click Take Backup.

    • Manually take a backup in PI System Explorer. To do this:

      • On the machine where the PI Integrator for Business Analytics is installed, locate the %PIHOME64\Integrators\BA\CAST.UI.WindowsService.exe.config file.

      • Open the configuration file and note the value of the InstancePath key.

      • In PI System Explorer, navigate to the element indicated by the InstancePath element.

      • Expand the element using the arrow to the left to expose the Views element.

      • Right-click the Views element and select Export to File.

      • Select the options Included Referenced Objects and Include Security Strings. Note the backup file location.

      • Click OK.

    • Proceed without taking a backup (not recommended).

13. The PI View Deprecated Verification step requires you to acknowledge that the PI View target is deprecated. All existing views using the PI View target will be disabled from publishing after the installation.

    • (Recommended) There is a scan available to detect any views on your system that use the PI View target. If the scan completes successfully, there will be a list of the view names for detected views, as well as a link to the exported list file in the %PIHOME%\dat directory. You can use this scan to identify PI View views that can be deleted or migrated to the Microsoft SQL Server target as an alternative. For instructions on how to migrate views using the PI View target to Microsoft SQL Server, see Migrate PI View target to Microsoft SQL Server target.

      • If an error occurs during the scan, an error message will appear. Click OK to close the error dialog.

      • If the scan succeeds but the list fails to be exported, please manually take note of the view names.

        Click the acknowledgement checkbox to continue the installation. Click Next.

        The Ready to Install Application window opens.

14. Click Install.

    The Updating System window opens showing the progress of the installation.

15. When you finish installation, the Installation Complete window appears. Click Close.