Upgrade to Ephesoft Transact 2019.2 – Single-server – Microsoft® Windows

Introduction

Revision 2 — August 14, 2019

Document Overview

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

  • Environment — Single-server
  • Operating System — Windows®

Note: Ephesoft Transact releases prior to Ephesoft Transact 4.1.0.0 are not supported for direct upgrade to Ephesoft Transact 2019.2.

Ephesoft Transact 2019.2 supports the following Windows versions for fresh installation, silent installation, or upgrade:

  • Windows 10
  • Windows Server 2012
  • Windows Server 2012 R2
  • Windows Server 2016

Upgrade Overview

Upgrading to Ephesoft Transact 2019.2 follows this general sequence of tasks.

Installation Task General Scope of Activity
1. Complete the Prerequisite Checks Prepare for upgrade by gathering the required resources and confirming that Ephesoft Transact 2019.2 supports the target environment.
2. Prepare the Server for Upgrade Perform these steps to prepare the server for the upgrade Install Wizard.
3. Launch the Install Wizard Launch and use the Windows Command Prompt to start the upgrade Install Wizard.
4. Complete the Install Wizard Complete all settings, dialogs, and instructions.

1. Complete the Prerequisites Checks

Perform these steps to prepare for all conditions required for successful software upgrade and startup:

1. Supported Ephesoft Transact version — 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 4.1.1.0–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 4.1.1.0, you must first upgrade to version 4.1.1.0 before upgrading to Ephesoft Transact 2019.2.

Warning: If you must perform an intermediate upgrade before upgrading to Ephesoft Transact 2019.2,
then you must start the Ephesoft Transact 4.1.1.0 service at least once after upgrading to version 4.1.1.0.
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, this will break the upgrade process.

2. Operating System — Verify that Ephesoft Transact 2019.2 is supported for the operating system and hardware environment. Refer to the following resources for additional information:

Ephesoft Transact 2019.2 — Platform Configuration and Third-Party Integrations

3. Database — Verify the database type and database version of your existing database. Using the document cited immediately above, confirm that your database version is supported.

Important: If you are upgrading to Ephesoft Transact 2019.2 with an existing MariaDB or MySQL database, please refer to the following document before proceeding any further with this upgrade.

Install and Migrate MariaDB or MySQL for Windows

4. Backup — Ensure that you have backed up the existing deployment of Ephesoft Transact before running the upgrade Install Wizard. Refer to the following articles for additional information:

2. Prepare for 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 for the system.
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.

Important: This is a temporary setting, and in a later step of this document, you will re-enable the Ephesoft Transact service after the upgrade is complete.

2. Close any Open Files — Close all open files inside the existing Ephesoft installation directory.

3. Disk Space — 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.

4. Backup — If you have not already done so, back up your Ephesoft installation area and all Ephesoft Transact databases. Refer to the following document for more information:

How to Perform Routine Ephesoft Transact Backups

5. User Access Control — 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
    • In many cases, the initial settings may be on higher levels of security (toward the Always notify side of the scale). Adjust this setting to the bottom-most position (Never notify), as shown in figure 3.
    • The system prompts the user to confirm this setting. Accept the changes.

6. IPv6 — Disable or verify that the IPv6 network protocol is disabled on this server. This control is available in the Windows network settings.

a. Browse to 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 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. Scroll to the Internet Protocol Version 6 (TCP/IPv6) setting, and ensure that it is disabled (i.e., ensure that the check box is clear).

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.

7. Windows Service Account User — Either create a Windows Service Account user on the Windows system or confirm the username and password for an existing Windows Service Account user to be used with Ephesoft Transact.

8. Continue to the next procedure.

3. Launch the Upgrade Install Wizard

After verifying that all prerequisite conditions are met, complete these steps to upgrade to Ephesoft Transact 2019.2:

1. 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

The xxx is an Ephesoft build number that may be subject to change.

2. Extract the zip file to a temporary location.

The following figure illustrates the contents of the extracted installer package:

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-10.png
Figure 8: Installer Package Contents

3. Open a Windows Command Prompt as Administrator, navigate to the directory where you extracted the installer zip file, then execute the following command:

msiexec.exe /i Ephesoft_2019.2.msi

Note that this command assumes that you are in the same folder as the Ephesoft Transact installer setup file.

The following screen may be displayed.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-15.png
Figure 9: Security Warning

4. Click Run to continue launching the Ephesoft Install Wizard.

5. Continue to the next procedure.

4. Complete the Upgrade Install Wizard

The Install Wizard Welcome screen appears:

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-16.png
Figure 10: Install Wizard Welcome screen

1. Click Next. The End-User License Agreement displays.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-17.png
Figure 11: End-User License Agreement

2. Read the terms of the license agreement, check the check box to accept the terms, and click Next to continue.

The Install Wizard may take several minutes to perform these prerequisite checks. If your Transact environment previously used an instance of MariaDB that was installed inside the Ephesoft Transact installation area, the following popup dialog appears:

Figure 12: Bundled MariaDB Installation Not Supported

3. 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.

If you have not yet 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

Warning: 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 upgrade Install Wizard displays the Ephesoft Prerequisites Check.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-18.png
Figure 13: Ephesoft Prerequisites Check Screen

Ephesoft Transact performs this check and displays a warning if there is a possible issue. If a warning appears, click Details for more information.

4. Click Next when the prerequisites check is acceptable for this installation.

.NET Framework 4.5.2 Installation

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

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-19.png
Figure 14: .NET Framework 4.5.2 Installation Screen

Be aware of the following factors that 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. Be aware of and follow these tasks:
      • Click Download to navigate to the appropriate web link.
      • Download and install the .NET 4.5.2 Framework.
      • Once you have completed installation of .NET 4.5.2 Framework, return to this step in the Install Wizard.

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

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-20.png
Figure 15: Ephesoft Prerequisites Installation Screen

Note: The upgrade Install Wizard may display a temporary message at the bottom:

Transact prerequisites are being installed in the background.

Important: Allow time for the background configuration processes to complete.

6. Wait for the Setup Successful message and click Close.

Define Logon Settings

7. Click Next when prerequisites are verified. The upgrade Install Wizard prompts you for account selection and log on credentials.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-21.png
Figure 16: Ephesoft Transact Log On Credentials and Account Selection

In most cases, users select Local System Account.

To use another existing account, select This Account, and be aware of the following information:

    • Use this option with a service account that has access to the SharedFolders component located on another network server.
    • Enter the username and password for a local Windows Server Account that already exists for this function.
    • To use this option, the account must already exist before using this account in the Install Wizard.

8. Click Next to complete these settings.

The next dialog prompts you to review database changes.

9. Enable or disable the Apply database changes setting according to your requirements.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-22.png
Figure 17: Ephesoft Upgrade Installation Dialog for Database Changes

For a single-server Ephesoft Transact environment, this checkbox must be enabled before clicking the Next button.

The upgrade Install Wizard checks if you have enough disk space to continue the upgrade. If your server does not have enough free space, the following message may appear:

Figure 18: Disk Space Warning

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

The Database Backup screen appears.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-23.png
Figure 19: Database Backup Screen

10. Indicate whether you have backed up the database and click Next.

A message similar to the following screen appears if there are Ephesoft Transact files or folders that are in use or if the Install Wizard does not have administrative privileges.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-24.png
Figure 20: 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 again.

If you receive no warnings, the installer is ready to perform the upgrade.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-26.png
Figure 21: Ready to Install Dialog

11. Click Install and the Install Wizard performs the upgrade.

Once the upgrade Install Wizard has completed the installation, Post-Installation Instructions displays.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-27.png
Figure 22: Post-Installation Instructions and License Information

Read these instructions carefully to be aware of license-related tasks that must take place after the installation. Refer to the following document for additional information about licensing:

Licensing Ephesoft Transact 2019.2

12. After reading the license requirements in the above screen, click Next. The following screen appears to confirm that the installation is complete.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-28.png
Figure 23: Ephesoft Transact 2019.2 Setup is Complete

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

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

13. Click Finish to complete this step of the upgrade.

14. When the upgrade Install Wizard 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 upgrade.

    • 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 24: Change User Account Control settings in Windows Control Panel

The User Account Control Settings screen displays.

Figure 25: User Account Control Settings

 

    • 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.

15. If you need a new license file, install the license file after rebooting your server and before starting the Ephesoft Transact upgrade for the first time. Refer to the following document for additional information about licensing:

Licensing Ephesoft Transact 2019.2

16. Review, verify and implement custom configuration settings for your deployment before starting the Ephesoft Transact upgrade for the first time.

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. Alternatively, the pre-upgrade configurations are also available from the backup you performed in Step 4 of the section titled 1. Complete the Prerequisites Checks.

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

c. Complete these post-upgrade configurations before starting the Ephesoft Transact upgrade for the first time. Refer to the following article for additional information:

Folders where Customer-specific Data is Stored

17. 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.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-29.png
Figure 26: General Tab for Ephesoft Transact Properties

Note: Allow time for the background configuration processes to complete.
The first startup after the post-upgrade process performs updates to the
database, batch classes and other Ephesoft Transact elements.

Once the post-upgrade tasks are complete, the application is available.

18. Open a browser and enter the Ephesoft Transact URL. For example:

<server_name>:8080/dcma/home.html

The Ephesoft Transact 2019.2 home page appears.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-30.png
Figure 27: Ephesoft Transact Home Screen

 

19. Select Administrator or Operator to log in.

20. Enter the Username and Password.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-31.png
Figure 28: Login Screen

Conclusion

Upon successful completion of this document, you have upgraded to, licensed and launched Ephesoft Transact 2019.2 on a Windows server.

For additional information about using Ephesoft Transact, refer to: