Progeny Upgrade Guide

Progeny Upgrade Guide Page | 1 Contents Getting Started ...... 3 A note about Progeny Downloads and Updates ...... 3 Progeny Desktop Client Update/Upgrade ...... 3 Before Updating/Upgrading the Progeny Desktop Client ...... 3 Upgrading the Progeny Desktop between major versions (Ex. 9 to 10) ...... 4 Updating the Progeny Desktop between minor versions (Ex. 10.0.0.0 to 10.2.0.0) ...... 7 Licensing the desktop client ...... 9 Upgrading the Database ...... 10 Database Server Upgrade ...... 11 Upgrading the Database Server ...... 11 Changing the Database Service ...... 14 Web Server Upgrade ...... 18 Web Server Components and Installation Requirements ...... 18 ...... 18 Upgrade ...... 18 Progeny Web Application (ROOT.war file) ...... 22 Licensing and Configuring the Progeny Web Application ...... 27 Firewall Rules ...... 29 Contact Progeny Support ...... 32

Progeny Upgrade Guide Page | 2 Getting Started This documentation will assist with upgrading the major components of the Progeny application and provide basic options for customizing the installation. As always, Progeny Support is available to assist should users have any questions about the applications upgrade process or if your network has special/non-standard configurations that require additional consideration.

A note about Progeny Downloads and Updates Progeny does not ship physical media for its software. The installation and update files are delivered via digital download. Use the credentials from the introductory email along with hyperlinks from this document/hyperlinks from a Progeny representative to download the various components of Progeny. When updates are issued, Progeny will send an email notification containing a hyperlink to the update and release notes.

• Updates to the Progeny Desktop Client are provided in the form of a .exe file which is downloaded and run on the end user’s PC. • Progeny Desktop Client update notices will be sent to anyone on our email notification list. o To be added to the email notification list, please contact Progeny Support. o Updated versions are also available from the login screen of the Progeny Desktop client via the Acct Info... then the Update... button.

Progeny Desktop Client Update/Upgrade Before Updating/Upgrading the Progeny Desktop Client

When updating the Progeny desktop client to a newer version, ALL other desktop clients MUST be updated to the same version. Any desktop client that is not updated will not be able to log into the updated database until it has been updated to the same version as the others. Log into the desktop computer with a user account that has LOCAL ADMINISTRATIVE rights. Without LOCAL ADMINISTRATIVE rights, users will not be able to complete the installation of the Progeny desktop client.

BEFORE GOING ANY FURTHER - make sure to create a backup of all active databases. The conversion CANNOT BE REVERSED. From the database server, make manual backups of BOTH the database file and the transaction log file for each database that will be upgraded.

Before installing any of the Progeny software, verify the computer configuration meets the System Requirements.

To look up the computer’s configuration, use the following options based on the operating system version:

• Windows 10 – Type in the windows search bar, at the bottom left of the taskbar, System and choose System when it appears.

Progeny Upgrade Guide Page | 3 • Windows 8 - Hold down the Windows key and press X on the keyboard (WIN+X) and choose System from the menu that appears. • Windows 7 - Open Control Panel, click on System and Security and click System.

Once that is confirmed, then you can proceed to download the Progeny Desktop Client. NOTE: This requires your Customer Number. If you do not know this number, reach out to Progeny Support for assistance.

The Progeny Upgrade process requires downtime to be scheduled. All users must be notified ahead of time so that the proper downtime can be scheduled. The upgrade process usually takes around an hour, depending on your Progeny configuration. All users must be disconnected from the database and no- one will be able to log back into Progeny during this process.

Upgrading the Progeny Desktop between major versions (Ex. 9 to 10) 1. Double-click the new Progeny executable file to launch the installation wizard. 2. Click Next to proceed to the Software License Agreement.

Progeny Upgrade Guide Page | 4 3. Please take a moment to read the License Agreement. When ready to proceed, select the I accept the terms in the license agreement radio button and click Next.

4. Click Next to save Progeny to the default directory: :\Program Files (x86)\Progeny Software\Progeny 10:

Progeny Upgrade Guide Page | 5

5. Click Install to continue the installation process.

6. The installation process usually takes between 12 seconds to 1 minute, depending on the computer. When a successful confirmation message is displayed, click the Finish button to complete the installation and close the installer window.

Progeny Upgrade Guide Page | 6

7. You can then uninstall the older version of the desktop client from the computer.

Updating the Progeny Desktop between minor versions (Ex. 10.0.0.0 to 10.2.0.0) 1. Double-click the new Progeny executable file to launch the installation wizard. 2. Click Yes to confirm upgrading.

Progeny Upgrade Guide Page | 7 3. Click Next to proceed with the update process.

4. The update process usually takes between 12 to 30 seconds, depending on the computer. When a successful confirmation message is displayed, click the Finish button to complete the update of the installation file and close the installer window.

Progeny Upgrade Guide Page | 8

Licensing the desktop client When upgrading Progeny, you will have to re-license the upgraded version because each major version has its own specific settings for storing the license information.

1. Launch the Progeny application from the desktop:

2. When attempting to log in to the database, the Progeny Registration window will appear. Input the License ID for your institution. 3. Click Verify.

Progeny Upgrade Guide Page | 9 4. Click OK.

For the Progeny client and web software to be licensed, a connection to and from the Progeny Licensing Server must be allowed: gls.progenygenetics.com

As mentioned above, be sure to back up the database file as well as the log file before continuing to update the database. This is important in case we will have to revert the database due to unforeseen issues.

Upgrading the Database 1. During the licensing of the desktop client, while trying to log into a database, you will then see another window pop up right afterward. Click OK on the Confirm Database Maintenance window to confirm the upgrade maintenance on the database. All users will need to be disconnected from the database to complete the database upgrade.

Progeny Upgrade Guide Page | 10

2. Click Start on the Database Conversion Progress window to begin the conversion.

Depending on the size of your database, this conversion process can take several minutes. Please do not cancel, stop, kill, or otherwise interrupt the process until it is complete. This could possibly cause database corruption. 3. Once the conversion is completed successfully, you will then be logged into the database.

Database Server Upgrade Upgrading the Database Server This upgrade is only necessary if you are utilizing Progeny 8 or 9 Server. This will upgrade to Progeny 10 Server. If you already have Progeny 10 Server installed, you do not need to upgrade the Database Server and you should skip this section.

Upgrading the Progeny Database Server application is a straightforward process which should take no more than 10 minutes. First, download the Progeny 10 Server installation file and run the installer:

http://www.progenygenetics.com/software/server/current.html

1. Double-click the executable to launch the installation wizard.

Progeny Upgrade Guide Page | 11 2. Click Next to proceed to the Software License Agreement.

3. Please take a moment to read the License Agreement. When ready to proceed, select the I accept the terms in the license agreement radio button and click Next.

Progeny Upgrade Guide Page | 12 4. Click Next to save the Progeny Server to the default directory C:\Program Files (x86)\Progeny Software\Progeny 10\Server:

5. Click Install to continue the installation process.

Progeny Upgrade Guide Page | 13 6. The installation process usually takes between 12 seconds to 1 minute, depending on the computer. When a successful confirmation message is displayed, click the Finish button to complete the installation and close the installer window.

Changing the Database Service If you have upgraded the Progeny Server application, you will need to update the database services to use the new Progeny 10 Server Configuration Utility service. If you did not upgrade the Server application, skip this section.

1. Launch the Progeny 10 Server Configuration Utility:

2. Double-click on SQL Anywhere 17:

Progeny Upgrade Guide Page | 14 3. Click the Services tab:

4. For each database service name, right-click and choose Stop to stop the service from running.

5. After all database services are stopped, double-click each service name to open the Service Properties window, then click on the Configuration tab, click the Browse button to point to the new dbsrv17.exe path instead of the older dbsrv12.exe or dbsrv11.exe. The default location is C:\Program Files (x86)\Progeny Software\Progeny 10\Server\BIN64\dbsrv17.exe

Progeny Upgrade Guide Page | 15 Old Configuration:

Progeny Upgrade Guide Page | 16 New Configuration:

6. Click OK to save the changes. Make sure to apply this change to all database services. 7. All database services can now be started by right-clicking on the service name and selecting, Start.

8. You can then uninstall the old Progeny Server from the computer.

Progeny Upgrade Guide Page | 17 Web Server Upgrade Web Server Components and Installation Requirements The Progeny Web Server consists of the following components:

• Java Runtime Version 8 • Apache Tomcat 9 • Progeny Web Application (ROOT.war file)

For web browser system requirements, see the System Requirements. Java We recommend using the latest version of Java that is available for your server to take advantage of security fixes and performance improvements. If you are using Java version 7 or older, you MUST upgrade to Java 8.

Perform the Java update before continuing to upgrade Apache Tomcat.

NOTE: Ensure that the 64-bit version of Java is installed. Progeny is NOT compatible with the 32-bit version.

Apache Tomcat Upgrade This upgrade is only necessary if you are utilizing Apache Tomcat 8 or earlier. This will upgrade to Apache Tomcat 9. If you already have Apache Tomcat 9 installed, you do not need to upgrade Apache Tomcat and you should skip this section.

Be sure to back up the entire directory of Apache Tomcat 8, or whichever version you are upgrading from, before continuing to upgrade to version 9. The default directory that should be backed up is "C:\Program Files\Apache Software Foundation\Tomcat 8.0"

1. The first step is to stop the currently running service of Apache Tomcat if it is running. This can be done by using Windows Task Manager. The service name is Tomcat8.exe with the description of Commons Daemon Service Runner. 2. Once complete, launch the Apache Tomcat Setup (.exe) for the new Tomcat 9. Click through the Apache Tomcat Setup welcome and licensing pages. On the Choose Components page, click the + (expansion button) next to the Tomcat item to reveal these additional options. Check only the Service Startup option and uncheck everything else.

Progeny Upgrade Guide Page | 18

3. On the Apache Tomcat Setup: Configuration Options window, configure the following:

Option Description

Server Shutdown Port -1 (Default)

HTTP/1.1 Connector Port Use port 80 if possible. Port 8080 works if 80 is unavailable.

AJP/1.3 Connector Port 8009 (Default)

Windows Service Name Tomcat9 (Default)

Progeny Upgrade Guide Page | 19 Once the desired modifications are made, click Next:

If necessary, you can use the same ports that were being used in Tomcat 8 if they are different from the above ports. These can be found in the server.xml file in the old Tomcat directory: C:\Program Files\Apache Software Foundation\Tomcat 8.0\conf\server.xml

4. Define the file path where the Java Virtual Machine is located. For this reason, Java should be installed first. The Tomcat installation will automatically identify the best-possible Java Runtime location available. After the appropriate Java location is detected, click Next:

Progeny Upgrade Guide Page | 20 5. On the Choose Install Location dialog box, define the installation directory. The default location is C:\Program Files\Apache Software Foundation\Tomcat 9.0 for ease of management. Click Install to continue:

Progeny Upgrade Guide Page | 21 6. When the installation process has completed, deselect the Run Apache Tomcat and Show Readme checkboxes and click Finish:

Progeny Web Application (ROOT.war file) FOR THE NEWLY INSTALLED APACHE TOMCAT When Apache Tomcat is installed, a default ROOT folder is automatically created with the default Tomcat settings. This will be deleted and replaced with the Progeny Web application (ROOT.war file). Follow the next section in this guide for instructions on how to replace the default ROOT folder with the Progeny ROOT.war file before starting the Apache Tomcat service.

To download this file, access the Progeny 10 Web Update here: http://www.progenygenetics.com/updates/web

The ROOT. war file must be the same version as the version of Progeny that you will be utilizing. The version is not shown in the file, so you will have to contact Progeny Support to confirm you have the same ROOT.war version as your Progeny Database. The above link is for the latest version of the ROOT.war file.

1. Select DOWNLOAD WEB 10.X.X.X. 2. A new page is displayed, input the Customer Number, and click Continue. 3. Click Download (make a note of where the file is downloaded).

Progeny Upgrade Guide Page | 22 Depending on the network/computer settings, the ROOT.war file may download as ROOT.zip - if this happens, simply change the extension to .war (disregard the warning that may pop up saying the file may become unusable):

4. If you are downloading the new ROOT on the FHQ/DMZ server, copy all custom logos and images from the old Tomcat ROOT folder unto the desktop so that it can be copied back into the new ROOT folder. Usually, the default folder for custom logos and images are in C:\Program Files\Apache Software Foundation\Tomcat 8.0\webapps\ROOT\png This is only applicable if you use custom logos and images. 5. Open Windows Explorer and navigate to the Apache Tomcat installation directory C:\Progeny Files\Apache Software Foundation\Tomcat 9.0\ and open the ‘webapps’ folder. 6. Delete the existing ROOT folder. 7. Copy and paste the ROOT.war that was just downloaded into the same C:\Program Files\Apache Software Foundation\Tomcat 9.0\webapps folder. 8. Navigate to the Apache Tomcat installation directory C:\Program Files\Apache Software Foundation\Tomcat 9.0 and open the ‘bin’ folder. Double-click to open ‘Tomcat9w.exe’. 9. On the Java tab, check the Use default checkbox to automatically use the default Java. Also, clear out the values that are entered in the Initial memory pool and Maximum memory pool.

Progeny Upgrade Guide Page | 23 10. Click OK to save the changes once completed. 11. If you were using a Progeny 10 database, copy and paste the progenyConfig folder from the old Tomcat 8 folder into the Tomcat 9 folder. The default location is C:\Program Files\Apache Software Foundation\Tomcat 8.0\progenyConfig. This process copies the Derby configuration from Tomcat 8 into Tomcat 9, which carries over the database connection, licensing, FHQ configurations, and other derby settings. If you do not see a progenyConfig folder in Tomcat 8, most likely you were using a version of Progeny older than 10, so you can skip this step because this folder will automatically be created for you.

12. If you were using an SSL certificate for Tomcat 8, you will need to ensure the same parameters that were configured in the server.xml and web.xml files are also transferred over. Copying the server and web files will NOT be sufficient as there are some changes in the way Tomcat 8 and Tomcat 9 is configured to read those files. Review the server.xml and web.xml file from Tomcat 8 and compare with Tomcat 9. Copy and paste any custom parameters into the new server.xml and web.xml. The default location for both of these files is C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf\

13. Be sure to transfer/copy any customization. The most common customizations that are implemented in Apache Tomcat 9 are as follows:

server.xml

Custom Redirect Port

Custom SSL Connector Port

web.xml Custom HTTPS Redirect RPC Request Enscription RPCRequests RPC Requests /*

Progeny Upgrade Guide Page | 24 GET POST Encrypt all RPC request data destined for server CONFIDENTIAL

14. Start the Apache Tomcat 9 service via Windows Task Manager or the Services program. 15. When the service starts, within the ‘webapps’ folder, a new ROOT folder will automatically be created. Tomcat recognizes .war files as application packages and will automatically deploy it as an application folder – this may take a few minutes as the WAR file needs to fully unpack the new ‘ROOT’ folder.

16. Copy your logo files that have been placed on the desktop into the new ROOT folder within the same location as it was stored in the old ROOT folder. This location is commonly in C:\Program Files\Apache Software Foundation\Tomcat 9.0\webapps\ROOT\png. This is only applicable if you use custom logos and images.

FOR THE EXISTING APACHE TOMCAT Be sure to back up the entire directory of the ROOT folder. This default directory is "C:\Program Files\Apache Software Foundation\Tomcat 9.0\webapps\ROOT". This is important because we may need to transfer logos and other files into the new ROOT folder.

The new ROOT. war file must be the same version as the version of Progeny that you will be utilizing. The version is not shown in the file, so you will have to contact Progeny Support to confirm you have the same ROOT.war version as your Progeny Database. The link below is for the latest version of the ROOT.war file.

To download the latest ROOT.war file, access the Progeny 10 Web Update here: http://www.progenygenetics.com/updates/web

1. Select DOWNLOAD WEB 10.X.X.X. 2. A new page is displayed, input the Customer Number, and click Continue. 3. Click Download (make a note of where the file is downloaded).

Depending on the network/computer settings, the ROOT.war file may download as ROOT.zip - if this happens, simply change the extension to .war (disregard the warning that may pop up saying the file may become unusable):

4. Make sure to end the task for the running Tomcat service. This can be done in Windows Task Manager. 5. Open Windows Explorer and navigate to the Apache Tomcat installation directory C:\Progeny Files\Apache Software Foundation\Tomcat 9.0\ and open the ‘webapps’ folder.

Progeny Upgrade Guide Page | 25 6. If you are downloading the new ROOT on the FHQ/DMZ server, make sure to copy all custom logos and images from the old Tomcat ROOT folder unto the desktop so that it can be copied back into the new ROOT folder. Usually, the default folder for custom logos and images are in C:\Program Files\Apache Software Foundation\Tomcat 9.0\webapps\ROOT\png This is only applicable if you use custom logos and images. 7. Delete the existing ROOT folder and the ROOT.war file. 8. Copy and paste the ROOT.war that was just downloaded into the same C:\Program Files\Apache Software Foundation\Tomcat 9.0\webapps folder. 9. Navigate to the Apache Tomcat installation directory C:\Program Files\Apache Software Foundation\Tomcat 9.0 and open the ‘bin’ folder. Double-click to open ‘Tomcat9w.exe’. 10. On the Java tab, check the Use default checkbox to automatically use the default Java. Also, clear out the values that are entered in the Initial memory pool and Maximum memory pool.

11. Click OK to save the changes once completed. 12. Start the Apache Tomcat 9 service via Windows Task Manager or the Services program. 13. When the service starts, within the ‘webapps’ folder, a new ROOT folder will automatically be created. Tomcat recognizes .war files as application packages and will automatically deploy it as an application folder – this may take a few minutes as the WAR file needs to fully unpack the new ‘ROOT’ folder.

Progeny Upgrade Guide Page | 26 14. Copy your logo files that have been placed on the desktop into the new ROOT folder within the same location as it was stored in the old ROOT folder. This location is commonly in C:\Program Files\Apache Software Foundation\Tomcat 9.0\webapps\ROOT\png. This is only applicable if you use custom logos and images. Licensing and Configuring the Progeny Web Application FOR THE NEWLY INSTALLED APACHE TOMCAT 1. Open a web browser and navigate to either http://localhost OR http://localhost:8080, depending on which port Apache Tomcat was configured with earlier in the installation. 2. The page will then re-direct and append the configuration string below:

/CONFIG?id=162d2827-d57f-45c3-b385-49060d087fa0&UTYPE=INTERNAL

The completed configuration URL will appear like http://localhost/CONFIG?id=162d2827-d57f-45c3-b385-49060d087fa0&UTYPE=INTERNAL

Your IT may have configured a custom URL instead of the default above. Confirm with your IT team or Progeny Administrator.

If the setup to this point has been successful, a login page like the following should display.

Progeny Upgrade Guide Page | 27

If this login page does not display, please review the installation steps or contact Progeny Support for assistance.

3. Standard user credentials will not work on this page. To access this configuration page, log in with the following credentials:

Username: config Password: internal

This password may have been changed by your organization.

Progeny Upgrade Guide Page | 28 4. Once logged in, you will see the Progeny Configuration. Click the Update button for the web application to make the necessary steps to update the configuration of the derby service.

5. Navigate to either http://localhost OR http://localhost:8080, depending on how Apache Tomcat was configured earlier in the installation, and confirm you are able to login to Progeny. You may need to repeat step 4 for another configuration update.

Firewall Rules FOR NEWLY UPGRADED APACHE TOMCAT AND/OR PROGENY SERVER Firewall rules are created to allow a computer to send traffic to or receive traffic from specific services, programs, computers, or users. For Progeny to work properly, Inbound firewall rules need to be added for dbsrv17.exe and Tomcat9.exe. If you upgraded both from an earlier version, you will then need to update the firewall rules for the updated versions. If you did not upgrade either the Database Server or Apache Tomcat, you can skip these steps.

Progeny Database Rule 1. Open Windows Firewall with Advanced Security:

2. Select Inbound Rules.

3. Search for the rule called Progeny Database – Sybase SQL Central and double-click it to edit the rule properties. The rule name may be different, based on how it was named initially.

Progeny Upgrade Guide Page | 29 4. The current Firewall rule should be pointing to the old dbsrv12.exe path. To update it, click on the Programs and Services tab then click Browse to find the newly updated program path C:\Program Files (x86)\Progeny Software\Progeny 10\Server\BIN64\dbsrv17.exe and select it, then click OK.

Progeny Web Rule 1. Within the same Windows Firewall program, search for the rule called Progeny Web – Apache Tomcat and double-click it to edit the rule properties. The rule name may be different, based on how it was named initially. 2. The current Firewall rule should be pointing to the old Tomcat8.exe path. To update it, click on the Programs and Services tab then click Browse to find the newly updated program path C:\Program Files\Apache Software Foundation\Tomcat 9.0\bin\Tomcat9.exe and select it,

Progeny Upgrade Guide Page | 30 then click OK.

The Progeny Web Server should now be fully operational – Congratulations!

Progeny Upgrade Guide Page | 31 Contact Progeny Support For assistance with your Progeny software, please contact Progeny Support:

Online: Learning Center and Live Chat Email: [email protected] Phone: (800) 776-4369 Monday – Thursday: 8:00 AM – 7:00 PM Eastern Time Friday 8:00 AM – 5:00 PM Eastern Time Mailing Address: Progeny Genetics, LLC 190 Congress Park Drive, Suite 140 Delray Beach, Florida 33445

Progeny Upgrade Guide Page | 32