1. Home
  2. Transact
  3. Install and Upgrade
  4. Transact 2019.2
  5. Install and Upgrade – Single and Multi-Server
  6. Upgrading on Windows Single and Multi-Server
  7. Upgrade to Ephesoft Transact 2019.2 – Single and Multi-Server

Upgrade to Ephesoft Transact 2019.2 – Single and Multi-Server


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

  • Environment types — single and multi-server*
  • Operating System — Windows®

Upgrade Overview

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

Installation Task General Scope of Activity
Prerequisites Prepare for upgrade by gathering the required resources and confirming that Ephesoft Transact 2019.2 supports the target environment.
Prepare the Server for Upgrade Perform these steps to prepare the server for the upgrade Install Wizard.
Obtain and Launch the Install Wizard Package Launch and use the Windows Command Prompt to start the upgrade Install Wizard.
Service Pack Installation This service pack must be installed immediately after completing the Install Wizard upgrade. This service pack was created shortly after the initial launch of 2019.2 and addresses issues that were raised by customers through support.
License and Launch Ephesoft Transact 2019.2 Perform these steps to complete the upgrade for Ephesoft Transact 2019.2.


Perform these steps for a successful software upgrade and startup:

  1. Verify that the existing installation of Ephesoft Transact is supported for upgrade to Ephesoft Transact 2019.2.
    • If the system is currently running Ephesoft Transact versions–2019.1, the upgrade Install Wizard supports direct upgrade to Ephesoft Transact 2019.2.
    • If the system is currently running a release prior to Ephesoft Transact, you must first upgrade to version before upgrading to Ephesoft Transact 2019.2.

Important: If you must perform an intermediate upgrade before upgrading to Ephesoft Transact 2019.2, then you must start the Ephesoft Transact service at least once after upgrading to version This step is required to complete the intermediate upgrade process. If you do not start the service during the intermediate upgrade, and then attempt to upgrade to version 2019.2, the upgrade process will not be successful.

  1. Verify that Ephesoft Transact 2019.2 is supported on your operating system. Refer to the following resources for additional information: Ephesoft Transact 2019.2 — Platform Configuration and Third-Party Integrations
  2. Use the document cited above to confirm and verify that your database version is supported.

Important: If upgrading to Ephesoft Transact 2019.2 with an existing MariaDB or MySQL database, refer to the following document before proceeding any further with this upgrade: Install and Migrate MariaDB or MySQL for Windows

  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 accordingly throughout this document.

User Instructions

Prepare the Server for Upgrade

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

  1. Stop Ephesoft Transact, whether running as an application or service.

a. If you are running Ephesoft Transact as an application, close the Command Prompt in which Ephesoft Transact is running. Open the Windows Task Manager and use the End Task command to terminate the following two processes:

      • soffice.exe
      • soffice.bin

b. To stop Ephesoft Transact when running as a service, perform these steps:

      • In the Windows Control Panel, browse to Services | Desktop App.
      • Right click the Services utility and run as administrator. The Services (Local) screen displays. Scroll down to EphesoftTransact.

Figure 1: Sample Illustration of the Windows Services Utility

      • If the EphesoftTransact service is running, right-click EphesoftTransact, and click Stop. The service stops.
      • Close the Windows Service Control utility.
  1. Close all open files inside the existing Ephesoft installation directory.
  2. Ensure that the target Windows installation drive has sufficient space for extraction of the installer setup file and the backup files that the installer will create. Depending on the size of the existing Ephesoft Transact instance, you may require up to 8GB of space.
  3. Log onto the Windows system and disable (turn off) the user access control (UAC).

Important: This is a temporary setting, and you may re-enable UAC after completing the installation later in this document.

    • From the Windows Start menu, browse to the User Access Control or UAC. The Windows Control Panel displays the link. Click this link to display the page.

Figure 2: Change User Account Control settings in Windows Control Panel

The User Account Control Settings screen displays.

Figure 3: User Account Control Settings

a. If the security setting is closer to the Always notify part of the scale, adjust this setting to the lowest position (i.e., Never notify) as shown in figure 3. The system prompts the user to confirm this setting.
b. Accept the changes.

  1. Disable the IPv6 network protocol on this server. This control is available in the Windows network settings.

a. Select Control Panel > Network and Internet > Ethernet.

b. From the Ethernet screen, click Change adapter options. A new screen displays one or more networks.

Figure 4: Network Connections Example

c. Right-click the network on which to disable the IPv6 and click Properties from the pop-up menu.

Figure 5: Click Properties to Change IPv6 Settings

The Ethernet Properties screen displays.

Figure 6: Ethernet Properties Settings

d. Clear the Internet Protocol Version 6 (TCP/IPv6) check box.

Figure 7: Disable the Internet Protocol Version 6 (TCP/IPv6) Setting

e. Click OK to save changes. The system returns you to the Ethernet page. Close the Windows Control Panel.

  1. If you are using a Windows service account to run the Ephesoft Transact service in the current environment, and you want to use that same account after the upgrade, confirm that you have that account’s credentials (username and password) before starting the upgrade procedure.

You are now ready to obtain and launch the Install Wizard.

Obtain and Launch the Install Wizard Package

Perform these steps to launch the Ephesoft Transact Install Wizard:

  1. Contact Ephesoft for access to the Install Wizard package.
  2. Download the Ephesoft Transact 2019.2 Install Wizard as instructed by Ephesoft. This is a zipped file with the following filename: WINDOWS_Ephesoft_Transact_2019.2_xxx

Note: The xxx is an Ephesoft build number that is subject to change.

  1. Extract all contents of the zip file to a temporary location. To extract the file, right-click the file, and from the pop-up menu, click Extract All.

Figure 8: Click Extract All …

Important: You must extract all elements of the installer package. The following figure illustrates the contents of the extracted installer package:

Figure 9: Installer Package Contents

  1. Open the Windows Command Prompt as an Administrator. Navigate to the directory where you extracted the installer zip file, then execute the following command to download the Windows installer package:
    msiexec.exe /i Ephesoft_2019.2.msi

The following screen displays:

Figure 10: Security Warning

  1. Click Run to continue launching the Ephesoft Install Wizard. The Ephesoft Transact 2019.2 Setup screen displays.
  2. Click Next.

Figure 11: The Ephesoft Transact 2019.2 Setup Screen

The End-User License Agreement displays.

Figure 12: End-User License Agreement


  1. Read the end-user license agreement, select the check box to accept the terms, and click Next to continue.

Note: If your Ephesoft Transact environment previously used an instance of MariaDB that was installed inside the Ephesoft Transact installation folder structure, the following screen displays:

Figure 13: Bundled MariaDB Installation Not Supported

  1. If you have already installed a standalone instance of MariaDB and migrated the Ephesoft Transact databases to the new instance, check the check box and click Next.
  2. If you have not performed those tasks, click Cancel to exit the Install Wizard.You must install or migrate the MariaDB database prior to completing the upgrade Install Wizard for Ephesoft Transact 2019.2. Refer to the following document for additional information: Install and Migrate MariaDB or MySQL for Windows.

Important: If you proceed past this step without migrating your Ephesoft Transact database to a standalone instance of MariaDB installed outside of the Ephesoft Transact installation area, your Ephesoft Transact databases will be lost.

The Ephesoft Prerequisites Check displays.

Figure 14: Ephesoft Prerequisites Check

Note: The Install Wizard may take several minutes to perform these prerequisite checks. If a warning displays in the above screen, click Details for more information.

The following is an example of this type of message:

“JAVA_HOME environment variable is already defined. This will get modified during Transact installation. If you do not want this to happen, please cancel the installation.”

  1. Click Next when the prerequisites check is acceptable. Continue to .NET Framework 4.5.2 Installation.

.NET Framework 4.5.2 Installation

Ephesoft Transact performs a check to verify that the .NET Framework 4.5.2 is installed.

Figure 15: .NET Framework 4.5.2 Installation

The following factors enable or disable the Next button:

  • If the .NET Framework 4.5.2 is installed on the system, the Next button is enabled.
  • If .NET Framework 4.5.2 is not installed on the system, the Next button is disabled. A Download button displays in this case. Follow these steps:

a. Click Download and go to the appropriate link.

b. Download and install the .NET 4.5.2 Framework.

c. Once you have completed the installation of .NET 4.5.2 Framework, continue to step 11.

  1. Click Next. The upgrade Install Wizard performs a check of Microsoft® Visual C++ Redistributables.

Figure 16: Ephesoft Prerequisites Installation

Important: If your system has newer versions of the Visual C++ redistributables, the Ephesoft Transact installer may fail. Perform the following steps:

1.  Uninstall the newer version of the library.
2.  Run the Ephesoft Transact installer.
3.  Install the newer version of the library.

Refer to the list of Visual C++ redistributables shown in Figure 16 for the required versions of these files.

Note: The Install Wizard may display the following message: “Transact prerequisites are being installed in the background.” Allow time for the background configuration processes to complete.

  1. When the Setup Successful message displays, click Close. Continue to Define Log On Settings.

Define Log On Settings

The upgrade Install Wizard prompts you to choose the account to use with the Ephesoft Transact Server. Perform the steps below.

Figure 17: Log On Credentials and Account Selection

  1. In most cases, users select Local System Account. To use another existing account, select This Account, and note the following information:

a. Use this option with a service account that has access to the SharedFolders component located on another network server.

b.Enter the username and password for a local Windows server account that already exists for this function.

  1. Click Next. The Ephesoft Upgrade Installation screen displays.

Figure 18: Ephesoft Upgrade Installation Dialog for Database Changes

  1. The following steps vary depending on a single or multi-server upgrade.
    • If upgrading a single-server environment, or if you are upgrading the first server in a multi-server environment, check the Apply database changes check box.
    • If upgrading the second (third, fourth, etc.) server in a multi-server environment, uncheck the Apply database changes check box.

For additional information on multi-server environments, refer to the following section in this procedure: Multi-Server Upgrade.

  1. Click Next.

The Install Wizard will check if you have enough disk space for the upgrade installation. If your server does not have enough space, the following message may display:

Figure 19: Disk Space Warning

If you see this message, click Cancel to exit the Install Wizard. Clear the appropriate amount of disk space and restart the Install Wizard.

The Database Backup screen displays.

Figure 20: Database Backup Screen

  1. Select the check box if you have backed up the database and click Next.

Note: A message displays if Ephesoft Transact files or folders are in use:

Figure 21: Setup Dialog to Close Open Files/Folders

If you see this message, close any open files or folders in the Ephesoft Transact installation area, then click OK to return to the previous Install Wizard screen and click Next.

If you receive no warnings, the installer is ready to perform the upgrade. Continue to Run and Finish the Install Wizard.

Run and Finish the Install Wizard

The Ready to Install screen displays after you have completed the database backup.

Note: If needed, click Back to adjust your configurations in previous screens.

  1. Click Install.

Figure 22: Ready to Install Screen

A Status bar displays the installation’s progress.

Figure 23: Status Bar of the Install Wizard Progress

Once the upgrade installation is completed, the Post-Installation Instructions screen displays.

Figure 24: Post-Installation Instructions and License Information

  1. Read the post-installation instructions and perform the necessary tasks, then click Next. The following screen displays to confirm that the installation is complete.

Figure 25: Ephesoft Transact 2019.2 Setup is Complete Screen

You have the option to restart the system once you close the Install Wizard.

Note: Ephesoft recommends restarting the system after finishing the upgrade.

  1. Click Finish.
  2. When the upgrade installation is complete, re-enable User Access Control (UAC) on this server.

Important: This was a temporary setting required when running the Install Wizard in a previous task. This procedure re-activates UAC after installation.

a. From the Windows Start menu, select the User Access Control settings. The Windows Control Panel displays a link. Click this link to display the page.

Figure 26: Change User Account Control settings in Windows Control Panel

The User Account Control Settings screen displays.

Figure 27: User Account Control Settings

b. Adjust this setting to the desired position for normal operations. Your setting may differ from the illustration shown above. The system prompts you to confirm this setting. Accept the changes.

c. Continue to License and Launch Ephesoft Transact 2019.2.

Service Pack Installation

After the release of Ephesoft Transact 2019.2, we discovered issues that impacted performance and reliability. Ephesoft has created a service pack to address these issues.

This service pack must be installed immediately after completing the Install Wizard.

Perform the following steps to install the service pack for Ephesoft Transact 2019.2:

  1. Stop the Ephesoft Transact server.
  2. Download and extract the Windows_Generic_Release-2019.2_ServicePack folder to a temporary location.
  3. Go to the extracted folder and run the .exe as an administrator. Wait for the .exe execution to complete.
  4. In case of an error, please check the .txt created in the same folder where the GenericHotFixServicePack.exe exists. After resolving the error, execute the .exe again and wait for it to complete.
  5. The following changes are required for any batch class that is configured for table extraction that leverages eText as part of the extraction.

a. Open the .rsp at [Ephesoft_home]\Sharedfolders\<Batch_class_id>\fixed-form-extraction\FPR.rsp

b. Navigate to </ImageSequence2Operator> ending xml tag.

c. Add <LayoutOperator Name=”LayoutOperator” FindTextBlocks=”true”/> entry after the tag found in step b.

d. If the issue is still observed on the Table Extraction screen, make sure the HOCR file generated previously in the [Ephesoft_Home] \SharedFolders\BC5\advanced-test-table\Invoice directory is deleted before setting up an extraction rule.

  1. Start the Ephesoft Transact server.

Note: These changes are to be applied on all servers (UI + Processing) in a cluster.

Note: If an Open File-security warning pop-up window displays while executing the batch after deployment, uncheck Always ask before opening this file checkbox and click Run and restart the Ephesoft Transact service. This pop-up window will not appear again. This behavior was observed only once during our testing and was not replicable again.

Web Scanner Service – Workstation Changes

  1. Stop the Ephesoft Transact Scanner Service. Stop the Ephesoft Transact Scanner Service on the Web Scanner workstations.
  2. Backup and delete the following jars inside the [Ephesoft_Scanner_Service_Home]\lib on the web scanner workstations.
    • WebScannerToolkit*.jar
    • WindowServiceIntegration*.jar
  1. Copy the following jars inside the extracted Hotfix\Scanner Service folder to [Ephesoft_Scanner_Service_Home]\lib
    • WebScannerToolkit_2019_2_ServicePack_15Oct2019.jar
    • WindowServiceIntegration_2019_2_ServicePack_15Oct2019.jar

Rollback Steps

To perform a rollback:

  1. Delete the Application and Dependencies\ImageMagick
  2. Copy the Application and Dependencies\ImageMagick folder from the backup (BackUP2019-2<timestamp>) to the installed folder.

License and Launch Ephesoft Transact 2019.2

Refer to Licensing Ephesoft Transact 2019.2 Depending on the version of Ephesoft Transact that you updated from, you may require a new license.

  1. Before starting your Ephesoft Transact service, review, verify, and implement customer configuration settings for your deployment.

a. Compare the post-upgrade properties files against the pre-upgrade properties files. You must implement your unique configuration settings into the post-upgrade properties files.

Note: Prior to installing the upgrade, the upgrade Install Wizard creates a backup folder to store the pre-upgrade configuration settings and components.

b. Use the Winmerge tool to compare and merge the pre-upgrade configurations into the post-upgrade configurations. Properties files settings or components that are unique to each deployment can include the following:

        • Computer names
        • Database paths
        • HTTPS settings, as applicable
        • ImageMagick settings, as applicable
        • JavaAppServer settings
        • Keystore location settings
        • Registry settings
        • Single Sign On (SSO) configurations
        • User connectivity settings for Active Directory, Apache Tomcat or LDAP

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

  1. Start the Ephesoft Transact service from the Windows Services interface. This initiates the post-upgrade process.

Note: You may choose to change the Startup Type option to Automatic so that Ephesoft Transact will start automatically whenever the server reboots in the future.

Figure 28: General tab for Ephesoft Transact Properties

Note: The first startup after the post-upgrade process performs updates to the database, batch classes and other Ephesoft Transact elements.

After starting the Ephesoft Transact service, you are ready to launch Ephesoft Transact. Follow the steps below:

  1. Open a web browser
  2. Enter the following Ephesoft Transact URL: http://<server_name>:8080/dcma/home.html

Note: Allow time for the background configuration processes to complete. The initial startup may require several minutes.

The Ephesoft Transact 2019.2 home page displays.

Figure 29: Ephesoft Transact Home Screen

  1. Select Administrator or Operator to log in.
  2. Enter the username and password.

Figure 30: Login Screen

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

Multi-Server Upgrade

This document provides instructions on how to upgrade whether in a single or multi-server environment. The steps for both environments are similar up to the section Define Log On Settings of this document where the Ephesoft Upgrade Installation screen is described.

If installing in a multi-server environment, it is important for users to follow the instructions outlined in Define Log On Settings.


This completes the upgrade process.



Was this article helpful to you? Yes No 1