EngageCX Upgrade Guide

Overview

Each business organization is unique, and so are the databases, storage and other infrastructure systems that interact with your EngageCX Platform, therefore there is no upgrade solution to fit all enterprises. This guide will get you through all the required tasks recommended for upgrading the EngageCX Platform.

The intended audience of this guide consists of System Engineers, System Architects or Technical Decision Makers.

Why Upgrade?

There are a lot of advantages you must benefit from an upgrade. You must consider upgrading your EngageCX Platform to help address your customer’s demands and also, seek to achieve:

New Features: A large range of new features are developed by our Development Team with every release. For more information, access the Release Notes section, which outlines all the new features and improvements for each release;
Bug Fixes: Upgrading to the latest version helps you gain time by avoiding troubleshooting on existing issues, already solved by our team;
Performance Improvements: As with every release, we have always continued to improve the performance and reliability of core components;
Technical Support Access: We provide support for EngageCX solutions released within two years of the current Generally Available (GA) release. If your production system is not within two years of the current GA release, additional charges may apply.

Planning the Upgrade

For a successful Production Upgrade of the EngageCX Platform, it is a good practice to design an upgrade strategy in advance. This section brings to the fore some essential keys to ensure your production upgrade will run smoothly.

Upgrade Path

Before taking the first step in the upgrade process, check your current version of the EngageCX software and establish the version you want to upgrade it to. In this document, we've put together step by step instructions for upgrading from an older software version, released within two years of the current GA release, to the latest EngageCX release (i.e. Nido), as well as particular points for each individual upgrade case.

Upgrading to the Nido release will bring you a complete overhaul of the user interface that streamlines users’ interactions and reduces the learning curve. To see a list with all the new features, please access the Release Notes section from our documentation guide.

Upgrade Time

Before running the upgrade, it is always a good idea to ensure there is no activity on the system, to preserve the system integrity. To do this, you can check that:

No user is performing any operation or generating documents. One way to do this is to stop the IIS Websites;
There are no active jobs. One way to do this is to stop the EngageCX Services from Windows Services;
No operation is performed on the EngageCX Database. The installer process may alter the database to accommodate for new features and enhancements.

Upgrade Requirements

When upgrading the EngageCX Platform, it must be necessary to ensure the software and hardware requirements for the EngageCX Platform installation. For more details, please read the Pre-Installation Checklist document.

Testing the Upgrade

For a more successful and reliable upgrade, it might be a good idea to set up a staging environment and test the EngageCX Platform upgrade, by considering all your company particularities that might affect the process.

If you encounter any issue while testing the upgrade, please do not hesitate to contact our EngageCX Technical Support team.

When the upgrade is complete within the staging environment, take a few moments to write down any notes, questions or comments that come up during the testing, as they will be helpful in the production upgrade.

Migration Examples

This section describes some examples of a general upgrade process and certain particularities that differentiate one version from another. The steps in this section are for guidance only, as the step processes might change based on your organization’s profile.

11.5 (Mantine) to 12.0 (Nido)

This section provides step by step instruction for upgrading an EngageCX Platform version 11.5 (i.e. Mantine) to the latest available release version, EngageCX Platform 12.0 (i.e. Nido).

Step 1 - Review the Upgrade Plan and Software - Hardware Requirements

Before you start the upgrade, make sure you have created an upgrade plan and you have reviewed all the software and hardware requirements for upgrading the server to the latest version. To learn more, please access the Planning the Upgrade section of this guide.

Step 2 - Uninstall Licenses

After you upgrade the EngageCX Platform to the latest version (Nido), the old licenses will no longer be available.

Note

Upgrading to the Nido version of the solution requires new product keys. To upgrade your current licenses, please contact your Customer Executive or call the Sales Team at 866-259-1158 to find out more information.

To proceed with the upgrade, make sure to uninstall the older licenses from your machine.

In the Sysadmin Portal > Licensing tile, select, by turn, each license ID you need to uninstall and click the Uninstall ( ) button.

Screenshot

Click Ok in the Release Product Key dialog and copy the generated string from the box.
Access your EngageCX Account and go to the Product Keys tab. From the product key list, select the ID of the license you intend to uninstall.

Screenshot

Select the Uninstall button and paste the copied string in the Uninstallation key box.
Click Uninstall to finish the process, You will get a notification message informing that the license ID has been successfully uninstalled.

Step 3 - Back Up

It is highly recommended to back up your data before a software upgrade. The EngageCX assets for which it is recommended to create backups are configuration files, database(s) and storage.

The main configuration file and component’s configuration files are located at: <%Application_Data%>\EngageCX\ EOS4.config. In a full EngageCX instance, you will be able to find 4 configuration files:
- EOS4.config: the main config file of the EngageCX Platform;
- PublisherSvc.config: the config file of the Publisher Engine component;
- BISvc.config: the config file of the Analytics Engine component;
- DASSvc.config: the config file of the Data Engine component.

Screenshot

The web config files are located by default, at C:\Program Files\EngageCX\Engage 2019 (64 bit)\Websites. You will see three Web.config files associated with the three IIS Websites.

Screenshot

Then backup your EngageCX Storage and EngageCX Database. The Lillipup version provides three ways you can use to back your database and storage, described below. Make sure the user you are using has permissions to access your data.

Using the Sysadmin Website

Sign in to the Sysadmin website, access the Domain tile and click on the Backup Details button;
In the Backup page, select the Backup Now button and wait until the backup is created.

Screenshot

Using the Command Line

Another way to back up your storage and database is to use the Backup Tool. The default location of the tool is \Windows Service\EOS Utility\EOSBackup\Tools.EOSBackup.exe.
To back up your data, open a command line as an administrator and run the command below:

Tools.EOSBackup.exe -backup2 -u sysadmin -p sysadminpassword -backupDescription "some description"

Screenshot

The default location for the backup files is C:\ProgramData\EngageCX\BackupFolder. For distributed installation, you will need to create a shared network folder so that the database server can access and write in the file.
To run the backup using the shared folder, please use the -backUpFolder parameter, as follows:

Tools.EOSBackup.exe -backup2 -u sysadmin -p sysadminpassword -backupDescription -backUpFolder networkFolderPath

Manual Backup

If using a manual backup, you will have to back up the Storage Folder and EngageCX Database. For the storage folder, please create a zip archive.
It is a good practice to store database backup and storage backup at the same location.

Step 4 - Stop the EngageCX services and websites

Stop the EngageCX Websites and the EngageCX Services to ensure there is no running process. The EngageCX Websites can be stopped from IIS Manager. The default names of the three websites are: ADMINEOS4, EOS4 and PORTALEOS4.

Screenshot

The EngageCX Services can be stopped from Windows Task Manager. Sometimes the service does not stop. In that case, you need to disable the service and then force it to stop by killing the process with Task Manager.

Screenshot

Step 5 - Uninstall the old EngageCX version

Access the server that contains the old EngageCX Platform version (in our case, 11.5 Mantine) and uninstall the software. For more details regarding this, please access the Uninstallation Procedure section of the Installation Guide.

Step 6 - Install the new EngageCX version

Download the executable on the server where you want to install the new EngageCX Platform version (in our case, 12.0 Nido). Double-click on the setup and follow the on-screen instructions to complete the installation. For more information, please read Installation Guide. Ensure that the user with whom you are logged in has permission to install new tools.

Make sure to point out to the correct configuration file. If the new EngageCX software version is installed on another server than the old one, to use the same configurations, you will need to paste the EOS4.config backup copy to the EngageCX Application Data location before running the setup.

Step 7 - Re-configure Bindings

Once the installation is complete, reconfigure the bindings for the IIS Websites. The services will automatically start once the product installation is finished.

Step 8 - Install the new product keys

Sign in to the Sysadmin Website and select the Licensing tile to proceed with the product keys installation. To learn more about licensing in Nido, please access this link.

Access the Licensing tile from the Sysadmin Portal.
Enable the toggle button and provide your EngageCX credentials to connect to your EngageCX Account.
Select +Add Product Key to install the licenses you need.

Screenshot

Choose the product keys that you need from the available keys associated to your EngageCX Account and click Install license.
Once the license is displayed in the Product Keys, the product key has been installed successfully and it enables your access in Enterprise Portal.

Step 9 - Check the Upgrade

Lastly, we recommend performing a smoke test on your side after the upgrade completes to ensure that everything works as expected. For example, please check your environment documents and run some sample communications tests in order to identify if there is anything missing. If you encounter any issues, you can always contact us at engagecxsupport@mhcautomation.com.

11.0 (Lillipup) to 12.0 (Nido)

This section provides step by step instruction for upgrading an EngageCX Platform version 11.0 (i.e. Lillipup) to the latest available release version, EngageCX Platform 12.0 (i.e. Nido).

Step 1 - Review the Upgrade Plan and Software - Hardware Requirements

Step 2 - Uninstall Licenses

After you upgrade the EngageCX Platform to the latest version (Nido), the old licenses will no longer be available.

The first step to upgrading to the new keys is to contact our Operations Team to upgrade your licenses. Then, uninstall the keys using the License Administrator tool available on the Windows Start menu. In License Administrator, select, by turn, each license name you need to uninstall and click the Uninstall button. Next, follow the on-screen instructions to complete the process.

Screenshot

Step 3 - Back Up

It is highly recommended to back up your data before a software upgrade.

The main configuration file and component configuration files are located at: <%Application_Data%>\EngageCX\ EOS4.config. In a full EngageCX instance, you will be able to find 4 configuration files:
- EOS4.config: the main config file of the EngageCX Platform;
- PublisherSvc.config: the config file of the Publisher Engine component;
- BISvc.config: the config file of the Analytics Engine component;
- DASSvc.config: the config file of the Data Engine component.

Screenshot

The web config files are located by default, at C:\Program Files\EngageCX\Engage 2018 (64 bit)\Websites. You will see three Web.config files associated with the three IIS Websites.

Screenshot

Then backup your EngageCX Storage and EngageCX Database. The Lillipup version provides three ways you can use to back your database and storage, described below. Make sure the user you are using has permission to access your data.

Using the Sysadmin Website

Sign in to the Sysadmin website, access the Domain tile and click on the Configure Backup button.
In the Configure Backup dialog, set up your Backup, then select the Run Backup Now button and wait until the backup is created.

Screenshot

Using the Command Line

Another way to back up your storage and database is to use the Backup Tool. The default location of the tool is \Windows Service\EOS Utility\EOSBackup\Tools.EOSBackup.exe.
To back up your data, open a command line as an administrator and run the command below:

Tools.EOSBackup.exe -backup2 -u sysadmin -p sysadminpassword -backupDescription "some description"

The default location for the backup files is C:\ProgramData\EngageCX\BackupFolder. For distributed installation, you will need to create a shared network folder so that the database server can access and write in the file.
To run the backup using the shared folder, please use the -backUpFolder parameter, as follows:

Tools.EOSBackup.exe -backup2 -u sysadmin -p sysadminpassword -backupDescription -backUpFolder networkFolderPath

Manual Backup

If using a manual backup, you will have to back up the Storage Folder and EngageCX Database. For the storage folder, please create a zip archive.
It is a good practice to store database backup and storage backup at the same location.

Step 4 - Uninstall the old EngageCX version

Access the server that contains the old EngageCX Platform version (in our case, 11.0 Lillipup) and uninstall the software. For more details regarding this, please access the Uninstallation Procedure section of the Installation Guide.

Step 5 - Install the new EngageCX version

Download the executable on the server where you want to install the new EngageCX Platform version (in our case, 12.0 Nido). Double-click on the setup and follow the on-screen instructions to complete the installation. For more information, please read the Installation Guide. Ensure that the user you are logged in has permission to install new tools.

Make sure to point out the correct configuration file. If the new EngageCX software version is installed on another server than the old one, to use the same configurations, you will need to paste the EOS4.config backup copy to the EngageCX Application Data location before running the setup.

Step 6 - Re-configure Bindings

Once the installation is complete, reconfigure the bindings for the IIS Websites. The services will automatically start once the product installation is finished.

Step 7 - Install the new product keys

Sign in to the Sysadmin Website and select the Licensing tile to proceed with the product keys installation. To learn more about licensing in Nido, please access this link.

Access the Licensing tile from the Sysadmin Portal.
Enable the toggle button and provide your EngageCX credentials to connect to your EngageCX Account.
Select +Add Product Key to install the licenses you need.

Screenshot

Choose the product keys that you need from the available keys associated to your EngageCX Account and click Install license.
Once the license is displayed in the Product Keys, the product key has been installed successfully and it enables your access in Enterprise Portal.

Step 8 - Check the Upgrade

10.5 (Klink) to 12.0 (Nido)

This section provides step by step instruction for upgrading an EngageCX Platform version 10.5 (i.e. Klink) to the latest available release version, EngageCX Platform 12.0 (i.e. Nido).

Step 1 - Review the Upgrade Plan and Software - Hardware Requirements

Step 2 - Uninstall Licenses

After you upgrade the EngageCX Platform to the latest version (Nido), the old licenses will no longer be available.

The first step to upgrading to the new keys is to contact our Operations Team to upgrade your licenses. Then, uninstall the keys using the License Administrator tool available on the Windows Start menu. In License Administrator, select, by turn, each license name you need to uninstall and click the Uninstall button. Next, follow the on-screen instructions to complete the process.

Screenshot

Step 3 - Back Up

It is highly recommended to back up your data before a software upgrade.

The main configuration file and component configuration files are located at: <%Application_Data%>\EngageCX\ EOS4.config. In a full EngageCX instance, you will be able to find 4 configuration files:
- EOS4.config: the main config file of the EngageCX Platform;
- PublisherSvc.config: the config file of the Publisher Engine component;
- BISvc.config: the config file of the Analytics Engine component;
- DASSvc.config: the config file of the Data Engine component.

Screenshot

The web config files are located by default, at C:\Program Files\EngageCX\Engage 2018 (64 bit)\Websites. You will see three Web.config files associated with the three IIS Websites.

Screenshot

Then backup your EngageCX Storage and EngageCX Database. The Klink version provides three ways you can use to back your database and storage, described below. Make sure the user you are using has permission to access your data:

Using the Command Line

Another way to back up your storage and database is to use the Backup Tool. The default location of the tool is \Windows Service\EOS Utility\EOSBackup\Tools.EOSBackup.exe.
To back up your data, open a command line as an administrator and run the command below:

Tools.EOSBackup.exe -backup2 -u sysadmin -p sysadminpassword -backupDescription "some description"

The default location for the backup files is C:\ProgramData\EngageCX\BackupFolder. For distributed installation, you will need to create a shared network folder so that the database server can access and write in the file.
To run the backup using the shared folder, please use the -backUpFolder parameter, as follows:

Tools.EOSBackup.exe -backup2 -u sysadmin -p sysadminpassword -backupDescription -backUpFolder networkFolderPath

Manual Backup

If using a manual backup, you will have to back up the Storage Folder and EngageCX Database. For the storage folder, please create a zip archive.
It is a good practice to store the database backup and storage backup at the same location.

Step 4 - Uninstall the old version

Access the server that contains the old EngageCX Platform version (in our case, 10.5 Klink) and uninstall the software. For more details regarding this, please access the Uninstallation Procedure section of the Installation Guide.

Step 5 - Install the new version

Download the executable on the server where you want to install the new EngageCX Platform version (in our case, 12.0 Nido). Double-click on the setup and follow the on-screen instructions to complete the installation. For more information, please read the Installation Guide. Ensure that the user you are logged in has permission to install new tools.

Step 6 - Re-configure Bindings

Once the installation is complete, reconfigure bindings for the IIS Websites. The services will automatically start once the product installation is finished.

Step 7 - Install the new product keys

Sign in to the Sysadmin Website and select the Licensing tile to proceed with the product keys installation. To learn more about licensing in Nido, please access this link.

Access the Licensing tile from the Sysadmin Portal.
Enable the toggle button and provide your EngageCX credentials to connect to your EngageCX Account.
Select +Add Product Key to install the licenses you need.

Screenshot

Choose the product keys that you need from the available keys associated to your EngageCX Account and click Install license.
Once the license is displayed in the Product Keys, the product key has been installed successfully and it enables your access in Enterprise Portal.

Step 8 - Check the Upgrade

EngageCX Platform in High Availability

This section provides information on how to proceed with the upgrade if your EngageCX Platform is deployed in a High Availability (HA) mode.

Upgrading in HA mode requires you to upgrade each of the EngageCX instance, separately. Below you can view an example of upgrading EngageCX Software deployed in a two-instance HA mode. The diagram below illustrates a HA setup with two full EngageCX instances.

Screenshot

Steps:

Start by planning the upgrade time and review the software and hardware requirements.
Create backup copies for the EngageCX database and file storage.
Upgrade the EngageCX Software on the EngageCXServer1 node. Use the steps described above, based on your EngageCX version.
Repeat the steps on the EngageCXServer2 node.
Re-configure bindings for IIS Websites. The services will automatically start once the product installation is finished.
Verify the upgrade and configure additional settings.

Post-Upgrade Configurations

Backup Manifest File

When upgrading from an older version than 11.0, it may be necessary to manually create a backup file so the EngageCX Platform can see the backup files. This section provides the steps required to create a backup file.

Note

The backup file is required only if you want to restore your files using the Sysadmin Website or the Backup Tool. It is not necessary for manual restore.

Go to your database and storage backup files location. (For example,C:\ProgramData\EOS4Backup).
Create a new Text Document file.
Open the file to a Text Editor and add the following statements:

<?xml version="1.0"?>
<backup xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.ecrion.com/eos4.0">
  <name>{BackUp Manifest Name}</name>
  <start-time-utc>2018-09-14T13:54:39.8019449Z</start-time-utc>
  <description>{Backup Process Name}</description>
  <sql>
    <file>{SQL Backup Name}.bak</file>
  </sql>
  <storage>
    <file>{Storage Backup Name}.zip</file>
  </storage>
</backup>

Save the file. The name of the file should be similar with “backup {BackUp Manifest Name}.manifest”.
Go to the Sysadmin Website and notice that the backup is now visible.

Restore Database and Storage

If you encounter issues during the upgrade process, you can restore your old database and storage to the new version of EngageCX Platform.

In Nido, there are three ways to restore your data:

Using the System Administrator Interface;
Using the Command Line;
Performing a Manual Restore.

To learn more about restoring in Nido, please access the Restore section from the Sysadmin Guide.

Before Restoring

Please find below some notes to be considered, before performing a restore procedure.

There are certain precautions that should be taken when restoring the EngageCX assets. We highly recommend contacting EngageCX Technical Support to discuss the best options to meet your company needs;
If you backed up your database manually, it is NOT recommended to restore your database automatically, as the software will use another database. In this scenario, it is indicated to re-run the setup again and specify the database you want to migrate, then perform an automatic restore;
For restore using the System Administrator interface or Command Line, you will need to add the backup manifest file to the location of the backup files. Go to the Backup File section for more information.

Logs Migration

Starting with the EngageCX Platform 11.0, released on February 01, 2018, log files are stored in the EngageCX Database. If you are upgrading from an older version before 11.0 (e.g. 10.5 Klink, 10.0 Inkay, 9.1 Gallade, etc.) to 12.0 (Nido), then you can use once the tool from below to migrate the old logs.

The Logs Migration tool can be found in:
\Windows Service\EOS Utility\Logs Migration\Tools.LogsMigration.exe.

The usage is as follows:

Tools.LogMigration.exe
    -ALL    <!-- will migrate all EngageCX logs - {analytics|audit|billing|customers|discussions|execution|jobs|notifications|schedulers|triggers} -->
    -ANALYTICS  <!-- will migrate only analytics logs -->
    -AUDIT  <!-- will migrate only analytics logs -->
    -CUSTOMERS  <!-- will migrate only customers logs -->
    -DISCUSSIONS    <!-- will migrate only discussions logs -->
    -EXECUTION  <!-- will migrate only executions logs -->
    -JOBS   <!-- will migrate only executions logs -->
    -NOTIFICATIONS  <!-- will migrate only notifications logs -->
    -SCHEDULERS <!-- will migrate only schedulers logs -->
    -TRIGGERS   <!-- will migrate only triggers logs -->

For example: To migrate all EngageCX logs, the syntax should be as follows:

Tools.LogsMigration.exe -ALL

You can also specify multiple parameters (exception: the -ALL parameter) in a single request:

Tools.LogsMigration.exe -ANALYTICS -JOBS -EXECUTION

The Log Migration tool needs to be run on the server where the log service is installed.

The Log Migration tool needs to be used just once, and only when you want to migrate from a version older than 11.0 - Lillipup to the latest version (e.g.: 11.5 - Mantine, 12.0 – Nido, etc.). If you want to upgrade the EngageCX Platform 11.5 Mantine to a newer version, for example 12.0 - Nido, you will NOT need to use the log migration tool.

Upgrading IIS Bindings for Website Remote Access

If you want to access one of the EngageCX Platform Websites remotely, you will need to follow these steps for each EngageCX Website.

Open IIS Manager.
From the Connections Tree View, navigate to the EngageCX Website exhibiting the issue.
On the right-side pane, select Bindings.
Edit the existing binding, and change localhost to * (to accept all connections) or specify an IP Address.
Click OK to save the changes.

Note

If you do this, the website will be accessible from the intranet if the firewall allows it. Make sure that this is the intended functionality and that website access (especially for System Administration) is properly secured before making the change.

Services and Data Verification

After you upgrade the EngageCX Platform, it may be necessary to check and perform some tests on your domain to ensure everything is working as expected. Below we list some recommendations to follow:

Check that the EngageCX Services are up and running. One way to do this is to access the System Status page from the Sysadmin Website;
Inspect EngageCX Storage, by scrolling down the System Status page of the Sysadmin Website;
Make sure that the EngageCX functionalities are working as expected and get acquainted with the new features. A best practice is to create a test environment, install the Project Samples and run communications.

Upgrade Retrospective Completion

Lastly, review and note what went well and what (if anything) did not. Identify and document the bad points and how to prevent it in the future.

You might want to consider updating the Disaster Recovery plan with the new specifications highlighted during the upgrade.

Do not forget to forward to end-users that the process is done and highlight the major changes found in the new version (e.g. let them know about the release notes).

Getting Help

As the success of your business relies on your customers, EngageCX helps you increase your client’s engagement by offering a solid foundation for creating and delivering successful communication between them. This document provides a good start for understanding how EngageCX should be upgraded from previous versions to the latest release. If you want to discuss the best deployment or upgrade options around your company's individual needs, please contact our EngageCX Professional Services Team today. We'd love to hear from you!