Update from 9.6 to 10.0 MS Windows

1. Introduction

Warning

These instructions are only applicable for updating the Key Survey application v.9.6 to v10.0

Every step described in this document should be performed in the listed order.
Do not skip any upgrade steps. If any item is not clear or throws an error, ask your point of contact at FORM for additional details.

2. Update the Application.

In this section, 'DB' and 'APP' acronyms are used to indicate the database server and the application server, respectively

The General Key Survey application update includes the following steps:

• application files update;

• config files update;

• database update.

In most cases, application files can be updated to a new build in one step skipping any intermediate versions.

3. Update procedure

PowerShell scripts that should be executed during the upgrade are not signed.

Therefore, please check Windows PowerShell execution policy on the application server, see more details at https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-5.1.
To complete the upgrade, the policy should be temporarily set to ‘Unrestricted’.

1.Stop Tomcat Service and IIS if it is used as proxy for the application.

2. Update Key Survey application files. Perform the following steps on the APP host.

The instructions below assume that application is installed in the default c:\hosting\keysurvey-standalone folder.
If you have custom application installation directory, adjust described paths accordingly.

If you have custom settings in config files located in 'c:\hosting\keysurveystandalone\conf', 'c:\hosting\keysurvey-standalone\bin' or other Tomcat configs, you will need to copy those changes from backup files to configuration files installed during the upgrade.
Do not copy old version files from the backup.

a. Rename c:\hosting\keysurvey-standalone folder into c:\hosting\keysurveystandalone.old

b. Extract keysurvey_app\keysurvey-standalone.zip from Key Survey upgrade archive into c:\hosting directory.

If you receive an error “Path too long” while copying the files, you can try using a third-party archiver (for instance 7-zip)

c. Copy the web.config file (if it exists in your installation) from the back up directory c:\hosting\keysurvey-standalone.old\keysurvey\app\ to c:\hosting\keysurveystandalone\keysurvey\app\

d. Edit 'c:\hosting\keysurvey-standalone\conf\tomcat-users.xml' file and change default login credentials to application system pages. You can also copy those credentials from backup file in file 'c:\hosting\keysurvey-standalone.old\conf\tomcat-users.xml'

<user username="admin" password="password" 
roles="keysurveyadmin"/>

e. Copy the contents from the c:\hosting\keysurvey-standalone.old\keysurvey\user-data to c:\hosting\keysurvey-standalone\keysurvey\user-data.

f. Edit c:\hosting\keysurvey-standalone\keysurvey\config.properties file and change all parameter values according to your system. You can copy the values for all previously existing parameters from the config.properties file from the backup c:\hosting\keysurvey-standalone.old\keysurvey\ folder.

Skip the following parameters, those will be updated at the end of the update process

DB_LOGIN.DM=<oracle_dm_your_db_login>

DB_PASSWORD.DM=<oracle_dm_your_db_password>

DB_CONNECTION.DM=jdbc:oracle:thin:@<oracle_your_db_host>:1521:<oracle_you_db_SID>

g. Copy application.yml file from the back up directory c:\hosting\keysurveystandalone.old\keysurvey\ to c:\hosting\keysurvey-standalone\keysurvey\ overwriting the existing one.

h. It is recommended to update current Java 11 to the latest build. If you do not need to update Java, you can skip this step. Below you will find an example of OpenJDK installation, where https://download.java.net/java/GA/jdk11/9/GPL/openjdk-11.0.2_windows-x64_bin.zip build is used. Replace links and version number with the Java build you are using:

• Extract jdk-11.0.2 folder from the archive to C:\Program Files\Java, so new Java folder on the app server is C:\Program Files\Java\jdk-11.0.2

• Click Start/Windows button, search for System environment variable and click ‘Edit the system environment variables’;

• Go to ‘Advanced’ tab and click ‘Environment Variables’ button;

• Find ‘JAVA_HOME’ in System Variables section and click Edit;

• Update ‘Variable Value’ box with the path where Java 11 is installed (for example C:\Program Files\Java\jdk-11.0.2) and save your changes.

i. Run 'c:\hosting\keysurvey-standalone\bin\tomcat9w.exe' and go to Java tab. Make sure Java Virtual Machine path points to Java 11. For example: C:\Program Files\Java\jdk11.0.2\bin\server\jvm.dll

3. Database update.

No errors should appear while running the scripts.

If you encounter any error, stop the upgrade process and forward error details to your point of contact at FORM for investigation.

If your application is installed into custom directory, replace c:\hosting\ paths according to your system in the following files:

• keysurvey-standalone\bin\setenv.bat

• keysurvey-standalone\bin\start_hook.ps1

a. Back up your Key Survey database;

b. Make sure there are no active connections to this DB.

c. Create a copy of your existing database with new name - <oracle_dm_your_db_login>.

Notes:

• <oracle_dm_your_db_login> is the placeholder that should be replaced with new DB name;

• <oracle_dm_your_db_login> should not conflict with any other existing DB names on the same server;

• Make sure you have enough space on the server to create a copy of the Database;

• A separate <oracle_dm_your_db_login> user should be created for this new DB with full access to it;

• As a result, you should have two DBs on the server with different names, <oracle_your_db_login> and <oracle_dm_your_db_login>

To complete the Database upgrade, perform the following steps on the APP server.

d. Edit c:\hosting\keysurvey-standalone\keysurvey\config.properties file and specify new DB Login credentials and connection string in the following parameters:

DB_LOGIN.DM=<oracle_dm_your_db_login>

DB_PASSWORD.DM=<oracle_dm_your_db_password>

DB_CONNECTION.DM=jdbc:oracle:thin:@<oracle_your_db_host>:1521:<oracle_you_db_SID>

e. Run PowerShell as administrator

f. Go to 'c:\hosting\keysurvey-standalone\bin' directory and run start_hook.ps1 script.

The script output should be the following: “Liquibase Update Successful”.

4. Start Tomcat Service and IIS if it is used as proxy for the application.