netTerrain 9.5 Upgrade Guide

Document Code. GN_D_nT9-11 Last revision: 07/28/2022

© 2022 Graphical Networks LLC. All rights reserved.

Graphical Networks and netTerrain are registered trademarks of Graphical Networks LLC. Other product names mentioned in this manual may be trademarks or registered trademarks of their respective companies and are hereby acknowledged.
If rash, irritation, redness, or swelling develops, discontinue reading. Safety goggles may be required during use. Do not eat this guide, it’s not yummy. This disclaimer is not intended as legal advice. For that, better call Saul.

Image: Crystal Caves, Iceland.

Graphical Networks LLC
Telephone: +1-240-912-6223
Fax: +1-240-912-6339 (for the upgrade purchase order, you know)

1 Introduction

1.1 Who should use it

This guide is intended for a netTerrain administrator who will be upgrading an existing installation of the netTerrain application server and database. If you are the administrator, we are sorry.

1.2 Assumptions

This guide assumes that the administrator has knowledge of the following:

• SQL Server administration, including login/security management, backup and restore procedures
• Overall knowledge of server administration procedures (installing, uninstalling and managing application settings and similar fun stuff)
• A general sense of how to operate a mouse, press buttons and pour coffee (lots of it)

1.3 Files required for the upgrade process

To perform the upgrade, you should have a netTerrain upgrade patch file that will be executed on the application server. This will most likely be delivered as a zip file that will be unzipped before execution. After the executable has been run, a second file will be available on the application server. This is a .SQL file that will be used to upgrade the netTerrain database. If you do not have such a file, ask your manager to renew the netTerrain maintenance. Our accountant will appreciate it.

2 System Requirements

2.1 Server requirements

The upgrade patch will support installations of netTerrain where the application server runs on either the same or on a separate physical or virtual server as the database.

2.1.1 Database Server requirements

netTerrain 9.5 will support any prior deployments of the netTerrain database running on any Operating System and virtual environment that supports SQL Server 2012, 2014, 2016 or 2019.

2.1.2 application server requirements

The netTerrain 9.5 application server can run on any operating system and virtual environment that supports IIS 8.0 or higher. The .NET framework version 4.7.1 is also required. If your .NET version is lower than that the installer will alert you to the issue and you need to cancel the process and install .NET 4.7.1 before proceeding.

3 Upgrade Process

3.1 Backup

3.1.1 Application server backup

Before proceeding with the upgrade, the application server should be backed up. The best practice would be to stop the IIS server service and backup the netTerrain folder to an alternate location. Then restart the IIS service, after the backup has completed.

The typical location of the netTerrain application folder for Windows is C:\ProgramData\Graphical Networks\netTerrain\vis.

3.1.2 Database backup

The SQL server production database that is used by netTerrain should be fully backed up before upgrading the database, unless you feel like living on the edge. In all fairness, in the entire history of Graphical Networks we do not recall an instance of database corruption due to an upgrade attempt, but still, back it up!

The netTerrain database is called GNCORE by default. In addition, it is recommended that a database restore test be performed to ensure the database backup will restore properly. You should consult with your SQL server database administrator (DBA) on how the backup and restore test should be performed. If you are the lucky SQL server admin and don’t know how to do this, google it.

3.1.3 netTerrain versions prior to version 8.5

Customers can upgrade versions of netTerrain prior to 8.5 all the way down to version 6.0 (or even older following a manual process). In any case, customers only require one executable file to run the upgrade process, however for versions prior to 8.5, customers will get a different installer than the default installer.

Normally we should know which upgrade file to provide to you, but if for whatever reason you ran the default installer and your version of netTerrain is older than 8.5 you may see the following warning message:

If you see this warning, you must exit the upgrade process and request the upgrade file that works for versions prior to 8.5.

3.2 Upgrading the application server

To begin the upgrade process, unzip the provided netTerrain software (if it’s zipped, of course). Then, run the executable. You will see a beautiful splash screen like the one below.

netTerrain upgrade splash screen

Next, simply follow the prompts during the installation. In case you ran a prior upgrade patch of netTerrain, the current patch will show the following warning prior to uninstalling the old files and continuing with the upgrade of your system.

It should only take a few minutes to complete this part of the process.

Upgrade progress

3.2.1 Web.config file update

Once the installation process has completed, edit the new web.config file that is typically found on C:\ProgramData\Graphical Networks\netTerrain\vis.

The database connection string in this file will need to be updated. Open the web.config file that was backed up in the beginning of this upgrade process. Find the connection string section (depicted below) and copy the data to the new web.config file. In addition to the web.config file, there is a settings file in that same folder that contains many additional useful settings to personalize your netTerrain deployment. Refer to the full installation guide to review these additional options.

<connectionString>
    <add name="NetTerrain" providerName="System.Data.SqlClient" 
    connectionString="Data Source=.;Initial Catalog=GNCORE5;uid=vis;pwd=vis909303;"/>
</connectionString>

netTerrain web.config connection string section

Please note that if your web.config connection string uses a Trusted_Connection you will need to update your application pool Identity to match the “Connect As” user found in your IIS application.

<connectionString>
    <add name="NetTerrain" providerName="System.Data.SqlClient" 
    connectionString="Data Source=WIN-1H649C8332N;Initial Catalog=GNCORE;Trusted_Connection=yes;"/>
</connectionString>

netTerrain web.config connection string section

Application “Connect As” user and Application pool Identity must match

Don’t change any other settings on the web.config file just yet, in case an error occurs. Changing too many things complicates a potential trouble shooting situation. Once the upgrade works, you can make any additional changes you need.

3.3 Upgrading the Database

The database is upgraded with a SQL script that will be run against the netTerrain database. This script is typically called netTerrain_Database_Patch_Script_6.0-9.5.xxx.sql and is usually found under C:\ProgramData\Graphical Networks\netTerrain\vis\patch.

Take this script and a pack of chips and Red Bull (or a White Flat coffee) to bribe your always busy DBA into executing this script against the netTerrain database. Your DBA may need to review the contents of that script and may even ask questions about what it does. Have fun.

Attention!

If you want to be extra safe, ensure a full backup has been taken from the netTerrain database and the backup file tested for restoration prior to applying this script.

3.3.1 For DBAs: running the database upgrade script

To execute the script against the database, follow these steps:

1) Open the upgrade script file. As mentioned above, it will have some cryptic name like netTerrain_Database_Patch_Script_6.0-9.5.xxx.sql

2) Copy the contents to a new query in SQL Server Management Studio (SSMS). Sometimes, your system recognizes the .SQL extension and will open it directly in SSMS. If that’s the case, good for you.

3) Make sure the query points to the netTerrain database before running this script to ensure this script will be executed against the correct database. Otherwise you may be attempting to patch grandma’s grocery list database.

4) Parse the script to ensure consistency. If any errors appear, you will have to contact Graphical Networks tech support (email support@graphicalnetworks.com and/or enter a ticket in the Graphical Networks customer portal).

5) Once the script parsed successfully, execute it. This process may take over a minute, depending on the database server hardware specifications.

SSMS database patch process

After script execution, warning messages can be ignored as long as the final result of the execution is successful and a green checkbox is displayed in SSMS. If there are error messages though, please contact Graphical Networks support.

SSMS database patch success

A successful execution will show a green check mark on SSMS, as depicted below.

3.4 C++ Redistributable

When netTerrain was originally installed on your server, a version of the Microsoft C++ redistributable application had to be installed on the netTerrain application server as well. You may have to install a newer version of it (version 2015).

The installer file can be found in this location after running the upgrade script: C:\Program Files (x86)\Graphical Networks\netTerrain\patch\vcredist2015_x86.exe

Run the executable and follow the prompts.

Microsoft C++ redistribution file

If you get an error or some warning that this is already installed then you are good.

3.5 Testing the system after the upgrade

Login to the netTerrain server via a web browser. Your login screen should show you that you are on version 9.5 already.

netTerrain v9.5 login splash screen

After logging in, click on Help->About and review the netTerrain versions. It should now read something like the image below:

netTerrain version

Attention!

Make sure the netTerrain database version depicted in the full build version above, coincides with the database version depicted next to the database. In the example above, both database versions 9.5 coincide. If you see any discrepancy, chances are you did not run the database script.

Next, navigate your project using the hierarchy browser or by double clicking and drilling down into project diagrams. Ensure navigation is working as expected. You can also check out other functions such as the ability to edit devices and adding new devices.

netTerrain 9.5 GUI

And remember, if anything does not seem to be working properly, please contact support@graphicalnetworks.com or enter a ticket on the support portal. You can access the portal from https://graphicalnetworks.com/support-center/. Call us, we don’t bite!