Upgrading to a new version of the EPIC client

Updated April 17, 2023 17:16

Don Clark

The EPIC (Export Plus Import Controller) data synchronization utility is a command-line tool that allows you to automatically synchronize user data with xMatters. This article explains how to upgrade from a previous version of the EPIC client to the latest version.

Checking your current version

If you are not certain what version of the EPIC client you are currently using, navigate to your EPIC client installation folder and open the <EPIC>/log/epic.log file. The first line indicates the version number of your EPIC client; for example:

... INFO - E.P.I.C. Control Client 5.5.### r##### ...

System requirements

Before installing the latest version, review the following system requirements to ensure that you will be able to use the EPIC client with your deployment.

Proxy server support

EPIC synchronizations can be run through a proxy server; while other configurations are possible, the following deployments have been successfully implemented either in the test lab or in production environments:

Apache 2.2.3
Blue Coat 5
NTLM

Java

As part of the end-of-life for TLS v1.0 support, Java 7 is no longer supported. You must have Java 8 installed and included on your system path to run the EPIC client.

If your current EPIC client version is prior to 5.5.77, upgrading to Java 8 will cause your EPIC synchronizations to stop working. It is recommended that you stop any running EPIC process and pause any scheduled jobs that may cause EPIC processes to start, upgrade to Java 8, and then upgrade your EPIC client.

If you want your EPIC synchronizations continue working while you are upgrading, the following steps are recommended (though you will still need to pause any scheduled jobs while upgrading your EPIC client):

Upgrade your EPIC client to version 5.5.77.
Upgrade your environment to Java 8.
Upgrade your EPIC client to the latest version.

You can download and install Java from http://www.oracle.com.

Environment variables

The location of the Java Development Kit (JDK) or Java Runtime Environment (JRE) must be defined by the JAVA_HOME system variable or included directly on the system PATH.

Other tools

Other utilities (such as Pentaho ETL) may have their own Java requirements. Before running these tools on the same system as the EPIC client, verify that they are compatible with Java 8.

System memory

The EPIC client validates data in-memory before it begins the data synchronization process. The amount of memory required to perform this validation depends on the amount of data that is being synchronized to xMatters. The EPIC client requires four megabytes of memory to validate one megabyte of uncompressed data. (This ratio is approximate and depends on the properties of the uncompressed data.)

To calculate the amount of memory that EPIC requires, multiply the size of the uncompressed (unzipped) data by four. To do this for ZipSync mode, unzip the ZipSync input file, calculate the total size of the CSV files, and multiply this value by four. For example, if your ZipSync input file is 6.6 Megabytes, and the combined size of the unzipped CSV files is 78.5 megabytes, the EPIC client requires approximately 314 megabytes of RAM.

The EPIC client sets the Java Virtual Machine (JVM) to use a maximum of 800 Megabytes of memory. If this limit is exceeded, or if your system runs out of memory, the EPIC client fails and your data is not synchronized to xMatters. If required, you can increase the amount of memory that is available to the JVM. To do this, edit the epic file (Mac/Linux) or epic.bat file (Windows) and modify the value of DEFAULT_JVM_OPTS. For more information about configuring JVM memory usage, refer to your Java documentation.

Upgrade the EPIC client

Because the xMatters EPIC Client does not include an installer, patching an existing EPIC Client installation requires only that you extract the latest version of the EPIC Client archive over your existing deployment.

It is strongly recommended that you complete these steps on a non-production or staging environment before attempting to upgraded your production deployment.

Step One: Backup your existing EPIC client

Before you begin, create a backup copy of your existing EPIC client installation directory in a safe location.

This ensures that you will have a working EPIC Client to fall back on if you encounter complications while configuring the new version.

You may also want to create backups of any scripts you use to launch the EPIC synchronization process.

Step Two: Prepare for extraction

Ensure that there are no EPIC processes currently running, and that there are no scheduled jobs that might start an EPIC process while you are applying the upgrade.

Step Three: Install the new version

Download the latest version of the EPIC client (epic-client-5.5.<version>.zip).
Extract the EPIC client archive to a new location on your local machine.
Copy config/transport.properties from your previous installation into the same location in the new installation structure.
Copy any other customized configuration files or backups from the old installation folder into the matching location in the new installation.
Update any starting scripts to use the path to the new installation directory.

Step Four: Test your installation

To test your upgrade, run any script or scheduled job that will start the EPIC synchronization process. You can then check the version in the <EPIC>/log/epic.log file; it should resemble the following:

2016-11-03 16:18:28,214 20327 [main] com.xmatters.epic.client.Main INFO - E.P.I.C. Control Client 5.5.124 r10436

Once you have confirmed that the EPIC client is working properly, you can re-enable any scheduled jobs.