Transact

⌘K
  1. Home
  2. Transact
  3. Install and Upgrade
  4. Transact 2020.1.02
  5. Linux Upgrade Guide 2020.1.02

Linux Upgrade Guide 2020.1.02

Introduction

This document describes how to upgrade Ephesoft Transact 2020.1.02 in the following environments:

  • Environments — single or multi-server
  • Operating system — Red Hat Enterprise Linux (RHEL) 7.5 or 7.6

Note: Ephesoft Transact 2020.1.02 is only supported for these Linux distributions. Do not run the yum update command, as this updates RHEL to an unsupported version. Refer to How to Update to a Previous Version of RHEL for more information.

  • Installation types — normal or silent

Upgrade Overview

The process of upgrading to Ephesoft Transact 2020.1.02 follows this general sequence of tasks.

Installation Task General Scope of Activity
Prerequisites Prepare to upgrade by gathering the required resources and verifying that the environment and databases are supported.
Prepare the Server for Upgrade Perform these steps to prepare the server for the upgrade installer.
Download and Run the Ephesoft Transact Installer Run the Ephesoft Transact installer in the command line interface.

For a silent upgrade, provide the required configurations in the config.properties file.

Select Normal or Silent Upgrade Determine if you are performing a normal or silent upgrade and follow the steps for your selected option.
License and Launch Ephesoft Transact 2020.1.02 Perform these steps to complete the upgrade for Ephesoft Transact 2020.1.02.

Prerequisites

Perform these steps for a successful software upgrade and startup:

  1. Determine if you need to perform a single-server or multi-server upgrade.

Important: Steps unique to a multi-server environment upgrade are identified where applicable.

  1. Verify that the existing installation of Ephesoft Transact is supported for direct upgrade to Ephesoft Transact 2020.1.02
    • If the system is currently running Ephesoft Transact version 2020.1 or above, your system is supported for a direct upgrade to Ephesoft Transact 2020.1.02.
    • If the system is currently running a release prior to Ephesoft Transact 2020.1, you will need to upgrade to version 2020.1 before upgrading to Ephesoft Transact 2020.1.02.

Important: If you are required to perform an intermediate upgrade, then you must launch the Ephesoft Transact 2020.1 service before upgrading to version 2020.1.02 or the upgrade process will fail.

  1. Verify that your database version is supported. Refer to Platform Configuration and Third-Party Integrations for additional information.

Important: If you are upgrading to Ephesoft Transact 2020.1.02 with an existing version of MariaDB or MySQL database engine, refer to Install and Migrate to MariaDB for Linux before proceeding any further with the upgrade.

  1. Verify that internet connectivity is available for this upgrade.
nm-online

Note: The installation will be interrupted if an internet connection is unavailable, as some software requires updates or installation from the operating system’s repository.

  1. Verify that you have super-user (root) permissions. If you are not a super-user, execute the following command to gain super-user permissions.
sudo su root

Important: The installation script must be run with super-user permissions, or an error will occur, and the script will exit.

  1. Verify that SharedFolders is accessible on the server undergoing upgrade.

User Instructions

Prepare the Server for Upgrade

Perform these steps to prepare the server for an upgrade to Ephesoft Transact 2020.1.02:

  1. Complete all in-flight batches. All batch instances must be in the Finished state for the upgrade to be successful.
  2. Perform a complete backup of the following:
    • Ephesoft, Report, and Report_Archive databases
    • Batch classes
    • Ephesoft SharedFolders directory
  1. Run all reports and ensure they are complete and in sync.
  2. If the Apache Tomcat memory settings were changed from the default, take note of your current configuration to restore after upgrading. Refer to Configuring Tomcat Memory Settings for additional information.
  3. Verify registry information with the following command:
/etc/.java/.systemPrefs/com/Ephesoft/license/core/annotation
  1. Ensure the following paths and settings are properly configured:
    • Check that the path for sharedFolderDir matches the SharedFolders path currently being used by Ephesoft Transact.
    • Check the registry settings to ensure that the DB Names and IP Address in Apache Tomcat’s server.xml and registry database entries match. If there are any changes in the database information you will need to edit the appropriate settings in the server.xml and registry database to reflect those changes.
    • Edit the SelectedDb entry in the registry to reflect the correct database type.
    • Edit the number in the Value data field in the registry settings to match the database.
      • Select 1 for MariaDB Server(MySQL compatible).
      • Select 2 for Oracle Database Server.

Important: If the upgrade to Ephesoft Transact 2020.1.02 requires a database migration or database version upgrade, these changes must be made prior to starting the upgrade process. Refer to Platform Configurations and Third-Party Integrations for supported versions and Install and Migrate to MariaDB for additional instructions.

Note: We recommend testing any software upgrade with an existing application before moving the upgrade into production if the software being upgraded is integrated with any other applications, systems, or workflows.

  1. Stop Ephesoft Transact running as a service using the following command:
service ephesoft stop.

Figure 1: Stop Ephesoft Transact Service

  1. Ensure that the target installation drive has enough space for the installation files. You may require up to 8GB of space.

Download and Run the Ephesoft Transact Installer

Perform these steps to upgrade to Ephesoft Transact 2020.1.02:

  1. Refer to the Downloads page for information on how to obtain the Ephesoft Transact installer.
  2. Unzip the Ephesoft Transact installer by navigating to the folder containing the ZIP file and execute the following command:
unzip Ephesoft_Transact_2020.1.02_Linux.zip

If unzip is not installed, use the following command:

sudo yum install unzip

Figure 3: Execute the unzip command

  1. Run the following command to make the files executable:
chmod 777 install install-helper uninstall.

This is illustrated in Figure 3, below.

Figure 4: Execute the cmod 777 Command

  1. Run the following command to start the installation process:
./install

Figure 5: Execute the ./install Command

Important: If the Ephesoft Transact installer stops during any step of the upgrade process, contact Ephesoft Support at tickets@ephesoft.com and provide the following files and details:

    • Your distribution and version of Linux.
    • var/log/install-ephesoft.log
    • /etc/Ephesoft/Ephesoft.conf
      • Only the root user has access to this folder. If the file does not exist, send only the first file.
  1. You will be prompted to decide if you want to install Ephesoft Transact as a silent installer (figure 5).
    • If you are performing a normal upgrade, select n and proceed to Normal Upgrade.
    • If you are performing a silent upgrade, select y and proceed to Silent Upgrade.

Figure 6: Silent or Normal Installation

Normal Upgrade

  1. The following screen will display while the installer checks the internet connection. Press y to confirm that you want to upgrade to Ephesoft Transact 2020.1.02.

Figure 7: Upgrade to Ephesoft Transact 2020.1.02

  1. You will be prompted to forcefully stop the Ephesoft Transact service if it is running. Press y to stop the Ephesoft Transact service on all nodes. The upgrade process cannot proceed if the Ephesoft Transact server is running.

Important: The following steps vary depending on a single or multi-server installation. Carefully read the steps below before proceeding further.

  1. The following screen displays:

Figure 8: Database Patch

    • For a single-server upgrade, press y to run the database patch. The database patch is mandatory for a single-server upgrade, or if you are upgrading the first server in a multi-server installation.
    • For a multi-server upgrade, the database patch is only required for the first server in the node. Press n for subsequent server upgrades.

Important: If you run the database patch on a second or subsequent server in a multi-server installation, you may corrupt the existing database.

  1. If Tesseract (an OCR engine) was not installed with the previous installation, the following screen will display:
    • Select n to decline to install Tesseract. Tesseract is optional, and not required for Ephesoft Transact to function properly.

Figure 9: Install Tesseract

    • Select y to install Tesseract.
  1. The installer will begin upgrading sources. This may take some time.
  2. The installer will prompt for registration information. This information is used to assist in the generation of your license for Ephesoft Transact. Provide the registration details.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-331.png

Figure 10: Registration Information

Note: The following screen will display after the installer saves critical configurations, license files, and folders in the back-up directory for future reference. The only exception is the log4j.xml file, which needs to be updated manually.

Figure 11: Ephesoft Transact Upgrade Complete

  1. Update the log4j.xml file. The old log4j.xml can be found at /opt/Ephesoft/Application-backup-<previous-version>/log4j.xml.
  2. Copy the old log4j.xml and replace the new log4j.xml with the old one at /opt/Ephesoft/Application/log4j.xml.
  3. The upgrade is complete. Proceed to License and Launch Ephesoft Transact 2020.1.02.

Silent Upgrade

  1. Open the config.properties file located in the Response-Files folder. To do so, open a text editor and run one of the following commands:
    • vi config.properties
    • vim config.properties
    • nano config.properties

Figure 12: vi config.properties Command

Note: You can also use WinSCP to connect to your Linux server and open the file in any UI text editor application.

Edit the values for the parameters in config.properties to reflect the required configuration for the upgrade. If using vi editor, run the i command to enter insert mode and edit the content. See the table on configurable properties below for explanations of important parameters.

Figure 13: Edit config.properties File

Important: The upgrade may fail if any of the following settings in config.properties file are incorrect.

Configurable Property Description
input_database_patch_enable Select one of the following options depending on your server environment:

  1. For a single-server upgrade, press y to run the database patch. The database patch is mandatory for a single-server upgrade, or if you are upgrading the first server in a multi-server installation.
  2. For a multi-server upgrade, the database patch is only required for the first server in the node. Press n for subsequent server upgrades.
input_upgrade_application Select y to upgrade Ephesoft Transact from an older version.
  1. Save the updated config.properties file to the same name in the Response-Files folder. If using vi editor, press the ESC key to exit insert mode and use the :wq command to save and close the file.
  2. Navigate to the folder with the unzipped Ephesoft Transact installer and start the silent installation process by running the following command:
./install -silentinstall -product

Figure 14: Start the Silent Installation

  1. The installer will pick up all the required details from the config.properties files.

Note: When upgrading to the latest version of Ephesoft Transact, critical configurations, license files, and the Certs, lib, and META-INF folders are saved in the back-up directory for future reference.

Figure 15: Back-up Directory

  1. All configurations files are automatically transferred to the newly upgraded application. The only exception is the log4j.xml file, which needs to be updated manually.
  2. The old log4j.xml can be found at /opt/Ephesoft/Application-backup-<previous-version>/log4j.xml.
  3. Copy the old log4j.xml and replace with the new log4j.xml at /opt/Ephesoft/Application/log4j.xml.
  4. The silent upgrade is complete. Proceed to License and Launch Ephesoft Transact 2020.1.02.

License and Launch Ephesoft Transact 2020.1.02

To complete the upgrade, refer to Licensing Requirements.

Important: Ephesoft recommends restarting the service after your license registry is updated.

  1. Compare the post-upgrade properties files against the pre-upgrade properties files. You must match the configuration settings of the post-upgrade property files to the pre-upgrade property files.

Note: The upgrade installer creates a backup folder to store the pre-upgrade configuration settings and components.

  • Use the diff command to compare and merge the pre-upgrade configurations into the post-upgrade configurations. Original configuration files are backed up on the same server. Navigate to the folder where Ephesoft Transact was installed and find the backup folder of your previously installed version of Ephesoft Transact to get access to your prior configurations, files, and settings. Properties, file settings, or components that are unique to each deployment can include the following:
    • Computer names
    • Database paths
    • HTTPS (as applicable)
    • ImageMagick (as applicable)
    • JavaAppServer
    • Keystore location
    • Registry
    • Single Sign-On (SSO)
    • User connectivity for Microsoft Active Directory, Apache Tomcat, or LDAP

Refer to Folders where Customer-specific Data is Stored for additional information.

  • If you are upgrading from a version prior to 4.5.0.0, you will need a new license for 2020.1.02.

Figure 16: diff Command to Compare Configurations

  1. Start the Ephesoft Transact service by running the following command:
service ephesoft start

You can track the service start-up process by opening the catalina.out file in the /opt/Ephesoft/JavaAppServer/logs/ folder and running the following command:

tail -f catalina.out

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-338.png

Figure 16: Start Ephesoft Transact

  1. Open a web browser and enter the following Ephesoft Transact URL: http://<servername>:<portnumber>/dcma/home.html. The default port number is 8080. Allow time for the background configuration processes to complete. The initial startup may require several minutes.

Important: If you receive an error or connection warning, you will need to open the firewall ports to connect to Ephesoft Transact.

  1. The Ephesoft Transact 2020.1.02 home page displays. Select Administrator or Operator to log in.

Figure 17: Ephesoft Transact Home Screen

  1. Enter the username and password. The default username is ephesoft, and the default password is demo.

Figure 18: Login Screen

Note: The system may require additional time to complete the initial login.

Conclusion

This completes the upgrade process.