1. Home
  2. Transact
  3. Install and Upgrade
  4. Transact 2022.1.00
  5. Windows Upgrade Guide 2022.1.00

Windows Upgrade Guide 2022.1.00


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

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

Important: Steps unique to a multi-server upgrade are identified where applicable in this document.

Upgrade Overview

Known Issue: When upgrading Transact from version 2020.1.05 to version 2022.1.00, there is a known issue in which Transact will not run successfully if the AI Table Rule Builder is installed. As a workaround, you will need to re-install the AI Table Rule Builder after completing the upgrade.

The process of upgrading to Ephesoft Transact 2022.1.00 follows this general sequence of tasks. Before proceeding, review the 2022.1.00 Release Notes.

Installation Task General Scope of Activity
Prerequisites Prepare for 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 Install Wizard.
Obtain and Launch the Install Wizard Package Launch the 2022.1.00 Install Wizard with the Windows Command Prompt. Complete all settings and dialogs as prompted.
License and Launch Ephesoft Transact 2022.1.00 Perform these steps to complete the upgrade for Ephesoft Transact 2022.1.00.


Perform these steps for a successful software upgrade and startup:

  1. Determine if you need to perform a single-server or multi-server upgrade with approximately 10GB of disk space available for the upgrade.

Important: Steps unique to a multi-server environment upgrade are identified where applicable throughout this document. Follow the instructions and adjust as necessary if upgrading on a multi-server environment.

  1. Verify that the existing installation of Ephesoft Transact is supported for direct upgrade to Ephesoft Transact 2022.1.00.
    • If the system is currently running Ephesoft Transact version 2020.1.x, your system is supported for a direct upgrade to Ephesoft Transact 2022.1.00.
      • If the system is currently running Ephesoft Transact 2020.1 and you are using the Cloud HyperExtender plugin, you will need to install the 2020.1.01 service pack before you can upgrade to 2022.1.00.
    • 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 2022.1.00.

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

  1. Refer to Platform Configurations and Third-Party Integrations and verify that Ephesoft Transact 2022.1.00 is supported on your operating system.

User Instructions

Prepare the Server for Upgrade

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

  1. Stop Ephesoft Transact, whether running as an application or service:
    a. To stop Ephesoft Transact when running as an application, close the Java Console in which Ephesoft Transact is running (as shown in the screenshot below) with CTRL + C.

Figure 1. Ephesoft Transact Command Prompt

b. Open the Windows Task Manager and click End Task to terminate the following processes, if they were not terminated:

    • soffice.exe
    • soffice.bin

c. 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 2. Sample Illustration of the Windows Services Utility

d. If the EphesoftTransact service is running, right-click EphesoftTransact, and click Stop. The service stops.

e. 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 enough 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 10GB of space for the installation.
  3. Log onto the Windows system and set the User Access Control (UAC) to Never notify.

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

a. 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 3. Change User Account Control settings in Windows Control Panel

The User Account Control Settings screen displays.

Figure 4. User Account Control Settings

b. 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 4. The system prompts the user to confirm this setting.

c. Accept the changes.

  1. If you previously installed Ephesoft Transact using a Windows service account and you want to use that same account after the upgrade, ensure you know 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 download and launch the Ephesoft Transact Install Wizard:

  1. Refer to the Downloads page for information on how to obtain the Ephesoft Transact installer.
  2. Download the Ephesoft Transact 2022.1.00 Install Wizard as instructed by Ephesoft. This is a zipped file with the following filename:
  3. 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 9. 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 10. Installer Package Contents

  1. If you are logged in as the Administrator, right-click Ephesoft_2022.1.00 and click Install. Otherwise, open the Windows Command Prompt as an Administrator. Navigate to the directory where you extracted the installer zip file, then execute the msiexec.exe /i Ephesoft_2022.1.00.msi command to download the Windows installer package.
  1. After you launch the Windows installer package, the Ephesoft Transact 2022.1.00 Setup screen appears. The Next button will be disabled while the installer determines if there is enough disk space to install the software.

Figure 11. The Ephesoft Transact 2020.1 Setup screen when computing space requirements
Note: As a reminder, you will need approximately 10GB of disk space for the upgrade. If you need to make space available for the upgrade, remove any files and apps that you no longer need.

  1. The Ephesoft Transact 2022.1.00 Setup screen will refresh and the Next button will be enabled. Click Next.

Figure 12. The Ephesoft Transact 2020.1 Setup Screen when the installer determines there is enough disk space to install the software.

  1. The End-User License Agreement displays.

Figure 13. End-User License Agreement

  1. Read the end-user license agreement to be aware of any changes, select the check box to accept the terms, and click Next to continue. perform update checks, and create a backup of the existing Transact installation in the [Ephesoft_Directory]\Back-up-full[current_Transact_version] folder.

Note: When upgrading and launching the installer for the first time, Windows may report the installer as Not Responding on the End User License Agreement screen. Do not cancel or kill the installation, the installer is making a backup of the existing Transact environment in the [Ephesoft_Directory]\Back-up-full[current_Transact_version] folder and performing upgrade checks. This process may take some time to complete and installation will resume once complete.

The Ephesoft Prerequisites Check displays.

Figure 15. 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 16. .NET Framework 4.5.2 Installation

The following factors enable or disable the Next button:

  • The Next button is enabled if the .NET Framework 4.5.2 is installed on the system.
  • The Next button is disabled if the .NET Framework 4.5.2 is not installed on the system. A Download button will display. Follow these steps:
    a. Click Download and go to the appropriate link.
    b. Download and install the .NET 4.5.2 Framework.
  • Once you have completed the installation of .NET 4.5.2 Framework, continue to step 12.
  1. Click Next. The Install Wizard performs a check of Microsoft® Visual C++ Redistributables.

Figure 17. Ephesoft Prerequisites Installation

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. Continue to Define Service Credentials.

Define Service Credentials

If you are running the Ephesoft Transact Server as a Windows service, the Install Wizard prompts you to choose which service account to use. It is recommended to use the same Windows account that was used to install your previous version of Ephesoft Transact. Ensure to choose the account that complies with your organization’s security policy.

  • In most cases, users select Local System Account.
  • To use another existing account, select This Account.

Figure 18. Service Credentials and Account Selection

Note: Use this option with a Windows service account that has access to the SharedFolders folder, whether locally or remote. Ephesoft recommends configuring SharedFolders on a network location for future growth and scalability. To proceed, enter the username and password for an account that has full access permissions to the network SharedFolders path.

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

Figure 19. Ephesoft Upgrade Installation Dialog for Database Changes

  1. The following steps vary depending on a single or multi-server upgrade.
  • Check the Apply database changes check box if you are upgrading a single-server environment, or if you are upgrading the first server in a multi-server environment.
  • Do not check the Apply database changes checkbox if you have already upgraded the first server in your multi-server installation and are now upgrading a subsequent server.
  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 20. 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 21. Database Backup Screen

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

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

Figure 22. 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.

Note: This message displays if an issue occurred upon executing the database patch:

Figure 23. Provide SA Password

Refer to Upgrade on Windows halts at DB Credentials required for DB patch to resolve the issue.

  • If you don’t receive any warnings, the installer is ready to perform the upgrade. Click Next to continue the upgrade.

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 24. Ready to Install Screen

A Status bar displays the installation’s progress.

Figure 25. Status Bar of the Install Wizard Progress

Note: This may take some time.

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

Figure 26. 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 upgrade is complete.

Figure 27. Ephesoft Transact 2020.1 Setup is Complete Screen

  1. Select Restart my computer.

Important: A restart is required for Ephesoft Transact to function properly.

  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 28. Change User Account Control settings in Windows Control Panel

The User Account Control Settings screen displays.

Figure 29. 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.

This completes your upgrade. Continue to License and Launch Ephesoft Transact..

License and Launch Ephesoft Transact 2022.1.00

  1. To complete the upgrade, refer to Licensing Requirements.
  • You will need an additional license if you want to purchase the ID Extraction feature. To purchase the ID Extraction Plugin, please contact your Sales Representative and ask for “Quickscreen”.

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: Prior to installing the upgrade, the upgrade Install Wizard creates a backup folder to store the pre-upgrade configuration settings and components.

  • Use the Winmerge tool to compare and merge the pre-upgrade configurations into the post-upgrade configurations. Original configuration files are backed up on the same server. You can navigate to the Ephesoft Install Directory and find the backup folder of your previously installed version of Ephesoft Transact to get access to your old configuration files and settings. 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 30. 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 2022.1.00 home page displays.

Figure 31. Ephesoft Transact Home Screen

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

Figure 32. Login Screen


This completes the upgrade process.

Was this article helpful to you? Yes No