Ephesoft Transact 2019.1 Upgrade Guide – Single-Server – for Linux

Overview

This document provides information on how to install Ephesoft Transact 2019.1 in the following environment:

  • Environment — single-server
  • Operating system — Linux
  • Installation type — upgrade

The following tasks describe how to upgrade to Ephesoft Transact 2019.1:

# Installation Task General Scope of Activity
1 Complete the Prerequisites Check Prepare for installation by gathering installation resources and verifying that the environment is supported.
2 Run the Ephesoft Transact Installer:

  • Normal upgrade
  • Silent upgrade
Run the Ephesoft Transact installer in the command line interface. For silent upgrade, provide required configurations in the config.properties file.
3 Install the Ephesoft Transact License (if required) Obtain and install the license if upgrading from Ephesoft Transact versions prior to 4.5.0.0.
4 Install the Ephesoft Transact 2019.1 Hotfix Download and install the 2019.1 hotfix.
5 Start the Ephesoft Transact Service Launch the Ephesoft Transact service.
6 Launch Ephesoft Transact 2019.1 Access the Ephesoft Transact app in a browser.

Upgrade Process

1. Complete the Prerequisites Check

  • Upgrade any necessary hardware or software on the current servers. Refer to the System Requirements and Platform Support for additional information.
  • Complete all in-flight batches. All the batch instances need to be in the Finished state for the reporting jobs to run successfully after the upgrade.
  • Perform a complete backup of the databases (ephesoft, report and report_archive databases).
  • Back up all batch classes (export from Batch Class Management).
  • Back up the Ephesoft SharedFolders directory.
  • Run all reports and ensure they are complete and in sync.
  • Document the Tomcat memory settings (if changed from default) so that they can be restored after the upgrade. For additional information, please refer to the following article: Configuring Tomcat Memory Settings.
  • Verify registry information with the following command:
    /etc/.java/.systemPrefs/com/ephesoft/license/core/annotation
  • The path for sharedFolderDir must match the SharedFolders path currently being used by Ephesoft Transact.
  • The server.xml and registry database entries must match before starting an upgrade. Check the registry settings to ensure proper configuration for the database upgrade.
  • Edit the SelectedDb entry in the registry to reflect the correct database type.
  • Enter the number in the Value data field in the registry setting to match the database type number.The database options are as follows:
    • MariaDB Server (MySQL compatible)
    • Oracle Database Server
  • If installing with Oracle Database 11g, confirm that the time zone is set for your local area before running the Transact installer.
  • For a normal upgrade, make sure you are connected to the internet. Some software will need to be updated or installed from the OS repository during the Ephesoft Transact installation.
  • Run the installation script with super-user permissions (use the root user), otherwise, an error message will be displayed, and the script will exit.

Note: Ephesoft recommends testing any software upgrade with an existing application before moving the upgrade into production. This is an essential approach to the success of the upgrade process. This approach is particularly important if the software being upgraded is integrated with any other applications, systems, or workflows.

2. Run the Ephesoft Transact Installer

Normal Upgrade to Transact 2019.1

1. Download the Ephesoft Transact installer and save it on your Linux machine.

2. Unzip the Ephesoft Transact installer by navigating to the folder containing the .zip file and running the unzip command.

3. To install Ephesoft Transact, you need super-user permissions.

3.1. Run the sudo su root command.
3.2. Use the chmod -R 777 * command.

Note: If the installation process is started without obtaining the super-user permissions, one of the following messages will be displayed depending on the OS:

  • “Permission Denied”
  • “Please run Ephesoft installation script with super user permissions”

4. To start the installation process, use the ./install command. Then, select n as we are not using silent installer.

5. Follow the prompts to complete the upgrade as shown in the image below.

5.1. Confirm you want to upgrade to Ephesoft Transact 2019.1 by selecting y.
5.2. Stop the Ephesoft service on all nodes if it is running.
    Note: Ephesoft Transact server needs to be stopped for the upgrade installation.
5.3. Execute the database patch. The database patch is mandatory for a single-server installation. In case of multi-node installation, the database patch must be run only on the first server, and the option can be selected for all remaining servers in the cluster.

Note: If you select n for a single server, the installation process will continue, however, there could be errors when running database queries.

Important: When upgrading to the latest version of Ephesoft Transact, the Certs, lib, and META-INF folders along with other critical configuration and license files are saved in the back-up directory for future reference. Refer to the image below:

All configurations files are automatically transferred to the newly upgraded application. The only exception is the log4j.xml file (<Ephesoft Installation Directory>/Application), which needs to be updated manually.

Silent Upgrade to Transact 2019.1

1. Download the Ephesoft Transact installer and save it on your Linux machine.

2. Unzip the Transact installer by navigating to the folder containing the .zip file and running the unzip command.

3. To install Ephesoft Transact, you need super-user permissions.

3.1. Run the sudo su root command.

3.2. Use the chmod -R 777 * command.

4. Open the config.properties file located in the Response-Files folder in any text editor by running the vi or vim or nano command. Alternatively, you can use WinSCP to connect to your Linux server and open the file in any UI text editor application.

5. Edit the values for the parameters in config.properties to reflect the required configuration for the upgrade. If using the vi editor, run the i command to enter the insert mode to edit the content.

All available parameters are explained in the config.properties file and also described in the Silent Installation Guide.

Important:

  • Incorrect entries in the config.properties file can cause installation failure.
  • Make sure to configure the following two parameters correctly as per the table below:
Configurable Property Description
input_database_patch_enable This parameter is used to define whether to run the database patch:

n – do not run the database patch

y – run the database patch

The database patch is mandatory for a single-server installation. In case of a multi-node installation, the database patch is run only on the first server, and the n option can be selected for all remaining servers in the cluster.

If you select n for a single server, the installation process will continue, however, there could be errors when running database queries.

input_upgrade_application This parameter is used to define whether the application is being upgraded from an older version. In this case, select y.

6. Save the updated config.properties file without changing its name in the Response-Files folder. If using vi editor, press ESC to exit from the insert mode and use the :wq command to save and close the file.

7. Navigate to the folder with the unzipped Ephesoft Transact installer and start the silent installation process by running the ./install -silentinstall -product command.

All required details will be picked up by the installer from the config.properties files.

Important: When upgrading to the latest version of Ephesoft Transact, the Certs, lib, and META-INF folders along with other critical configuration and license files are saved in the back-up directory for future reference. Refer to the image below:

All configurations files are automatically transferred to the newly upgraded application. The only exception is the log4j.xml file (<Ephesoft Installation Directory>/Application), which needs to be updated manually.

3. Install the Ephesoft Transact License

If upgrading from previous versions of Ephesoft Transact, you may be required to get a new license. For Ephesoft Transact releases prior to 4.5.0.0, it is mandatory to obtain a new license. For upgrades from Transact 4.5.5.0, we recommend obtaining a new license as there are screen enhancements that were included in version 2019.1.

To obtain a new license, follow the steps below:

1. Navigate to /opt/Ephesoft/Dependencies/licensing and send the details.properties file to licenses@ephesoft.com for all nodes that make up environment.

Be sure to note that your installation is a Linux installation and advise the Ephesoft licensing team of the number of CPU cores for all nodes with Ephesoft Transact on them that make up the environment. If you are not sure how many CPU cores your server has, type nproc in the terminal and it will give you the number of cores as an output.

2. The Ephesoft licensing team will send you a file named ephesoft.lic. Save it to the following folder: /opt/Ephesoft/Dependencies/license-util/ephesoft-license-installer/

3. Navigate to the folder /opt/Ephesoft/Dependencies/license-util/ephesoft-license-installer, and run the ./install-license.sh file to install the Ephesoft Transact license.

Important: You need to have super-user permissions to install the Ephesoft Transact license.

The license is installed.

4. Install the Ephesoft Transact 2019.1 Hotfix

Once Ephesoft Transact is installed and licensed, you need to install the Transact 2019.1 hotfix, which includes important updates and improvements. Note that this hotfix MUST be installed to ensure proper Ephesoft Transact functionality.

To install the hotfix:

1. Download the 2019.1_Fix_Pack.zip file, save it to a temporary location and unzip it.

2. Copy the extracted dcma-batch-*, dcma-util-*, dcma-recostar-*, gxt-core-*, gxt-review-validate-* JAR files to the <Ephesoft Installation Directory>\Application\WEB-INF\lib\HOT-FIXES directory.

3. Back up the existing reviewValidate and bm folders present in the <Ephesoft Installation Directory>\Application\ directory.

4. Copy the extracted reviewValidate and bm folders to the <Ephesoft Installation Directory>\Application\ directory.

For more information, refer to Ephesoft Transact 2019.1 Hotfix.

5. Start the Ephesoft Transact Service

Start the Ephesoft Transact service by running the service ephesoft start command.

You can open the catalina.out file in the /opt/Ephesoft/JavaAppServer/logs/ folder to track the service start-up process. For that, run the following command: tail -f catalina.out (the screenshot below shows extracts from the log file).

6. Launch Ephesoft Transact 2019.1

Open your browser and access the application using the following URL:

http://<server name>:<port number>/dcma/home.html.

If any connection error or warning is received, you will need to open the firewall ports to connect to Ephesoft Transact.

Figure 1. Ephesoft Transact Home Page

Clicking on the Administrator or Operator icon will take you to the login screen. The username is ephesoft and the password is demo.

Note: If you installed Ephesoft Transact with the Active Directory, use the username and password provided for AD.

Figure 2. Ephesoft Transact Login Dialogue

Once you have authenticated, you have completed the installation and configuration with your choice of database and authentication type.

Appendix

Custom Script Support

A customer or Ephesoft can develop any customization using custom scripts for Ephesoft Transact 2019.1.

Ephesoft provides support only for custom scripts developed by Ephesoft for the appropriate version of Ephesoft Transact.

Ephesoft does not provide support for such scripts in subsequent releases.

If you have custom scripts developed by someone other than the Ephesoft, please make sure to test these scripts, as we do not provide support unless otherwise agreed.

Before upgrading to Ephesoft Transact 2019.1, Ephesoft highly recommends testing any custom scripts in a test or development environment before upgrading your production environment.

If you need any assistance with custom script creation, upgrading your environment(s) or a consulting session, please contact your Ephesoft Sales Manager.

API Support

API calls that are deprecated will be noted in the release notes for each version of Ephesoft Transact. Please check the release notes before installing any upgrade.

Troubleshooting

  • If the Ephesoft Transact installer stops with an error during any step of the installation process, please send the following files to Ephesoft Support at tickets@ephesoft.com and include the distribution and version of Linux on which you are installing.

/var/log/install-ephesoft.log

/etc/Ephesoft/ephesoft.conf (only root user has access to this folder; if the file does not exist, send only the first file)

  • If you do not have root or sudo permissions on the server, please contact your system administrator for permissions and/or instructions.
  • If installing the SharedFolders directory on a remote server/NAS/SAN, please advise your system administrator to mount the share locally to your server and use the path they provide during the installation. Contact support for assistance if you run into issues. Persistent mount of the share on the local server will be necessary for Ephesoft Transact to function.

Notes:
Although Ephesoft Transact may support other Ubuntu and RHEL based distributions, we have not tested them all. Please contact support at tickets@ephesoft.com before attempting an installation so that we can advise you of any changes that may need to be made during the installation process.

In Ubuntu, Ephesoft Transact installation will turn the firewall (ufw) on after install. At the end of the installation, if you want ufw turned off, please remember to turn it off again with the command sudo ufw disable.

When shutting down the Ephesoft Transact service in Ubuntu, use the command sudo /opt/Ephesoft/JavaAppServer/bin/shutdown.sh.

After installing Ephesoft Transact and before running the application for the first time, run the following commands (dos2unix is installed by Ephesoft):

sudo dos2unix /opt/Ephesoft/JavaAppServer/conf/*

sudo dos2unix /opt/Ephesoft/JavaAppServer/bin/*

Post-Upgrade Health Check

Use WinMerge to compare settings from [backed up pre-upgrade] and [post-upgrade] META-INF config *.properties files and config *.xml files.

Download WinMerge from the following location: http://winmerge.org/

Expect new line items in the config files if upgrading to a new version of Ephesoft Transact.

Adjust customized settings as found.

Examples of lines you would not change would be completely new config lines that exist in new config files but not in old ones. These configuration files are primarily the *.properties files that are found in:

<Ephesoft Installation Directory>:\Ephesoft\Application\WEB-INF\classes\META-INF\

An example of acceptable differences between files would be changes to paths of the database, SharedFolder, or computer names (if you moved these parts of the environment to various locations).

An example of a configuration that may have changed is the imagemagick.properties file, which contains different compression settings for TIF and PDF files. If these were previously changed from the default values, they may have reverted back to the default settings.

In some config files, such as user-connectivity properties, config entries that used to have separate lines for LDAP and AD may have consolidated config lines that are now used for both. In these cases, careful consideration should be made before making changes.

For clustered environments, closely check the workflow and reporting properties files against the backup files for consistency across cron expressions.

Restore any custom Tomcat memory settings.