Migration Procedure

Migration Procedure (3.9.4 to 3.15.0)

The following section describes the migration procedure from HC 3.9.4 to HC 3.15.0.

Turn down HC 3.9.4 completely using the down command for docker-compose, destroying existing containers.
Stop NGINX service and disable auto-restart for it using
Stop & Disable NGINX Service

BASH
```
# Stop the service
systemctl stop nginx.service

# Disable auto-restart of NGINX service upon host reboot
systemctl disable nginx.service
```
In HC 3.15.0, NGINX is part of the HC Docker containers group and does not need installation.
Upgrade the reporting database using the following procedure:

The following scripts will throw errors if the HC reporting database does not adhere to SQL naming rules. If your HC database does not adhere to the naming rules, please rename it according to the rules before moving forward with this guide.
1. Take a backup of the reporting database.
2. Make sure that no instance of reporting connector is running. These scripts set database mode to the single-user to avoid data inconsistencies. After the script execution is done, the database mode is set back to multi-user for normal operations.
3. It is recommended to execute these scripts using SQL CMD because it ensures only one connection is made to the database for query execution. However, SSMS can be used to execute these scripts but sometimes it can lead to an issue when a database remains stuck in the single-user mode after a script is executed. If you face this issue, execute this script to set the database to multi-user mode. After the database is set to multi-user mode, execute the script again which originally caused this issue.
4. Move forward with the following steps only after taking a backup of the reporting database. Execute these scripts exactly in the same order as described below.
5. Download & edit the upgrade-from-3.9.4.sql script. Set your database name in line # 2 of this script and execute it. If using SSMS, also select the HC 3.9.4 database from the Available Databases dropdown menu (Windows OS shortcut: Ctrl + U).
6. Download & edit the upgrade-from-3.10.2-to-3.11.sql script. Set your database name in line # 2 of this script and execute it. If using SSMS, also select the HC 3.9.4 database from the Available Databases dropdown menu (Windows OS shortcut: Ctrl + U).
7. Download and execute the update-from-3.11-to-3.12.1.sql script. Select HC 3.9.4 database before execution of the script in SSMS or SQL CMD.
8. Download & execute the upgrade-from-3.12.1-to-3.13.0.sql script. This script does not set the database to the single-user mode so it is recommended to execute it via SSMS. Select to HC 3.9.4 database from the Available Databases dropdown menu in SSMS before proceeding. This script does not expect the database name. If you want to execute it via SQL CMD, select HC 3.9.4 database first before proceeding.
9. Download & edit the upgrade-from-3.13.x-to-3.14.0.sql script. Set your HC FQDN in line # 4 in the script and execute using SSMS or SQL CMD. Select HC 3.9.4 database first before execution of the script in SSMS or SQL CMD.
10. Download and execute the remove-uq-botname.sql script. Select HC 3.9.4 database first before execution of the script in SSMS or SQL CMD.
11. The reporting database migration is complete. For the updated schema of this database, refer to the Hybrid Chat Reporting Database Schema. For updated reports, refer to the Reports.
Deploy HC 3.15.0 in a different directory using the Docker-based deployment guide. Use the same reporting database server and name that was being used with HC 3.9.4 when prompted by the install script.
Stop HC 3.15.0 after deployment using the efutils utility. This utility is available from any location in the host OS after HC 3.15.0 deployment. Turn down HC 3.15.0 using
Turn Down HC 3.15.0

BASH
```
# try efutils help to get familiar with efutils e.g.
# efutils help
# the following command is used to turn the HC 3.15.0 down
efutils all down
```
Take backup of 3.9.4 MongoDB. MySQL backup for HC 3.9.4 is not compatible with HC 3.15.0 so you will have to re-sync UMM with Finesse and create Business Calendars.

Migrate the environment variables using the following procedure:

Take a backup of the HC 3.15.0 environment variables

Take Backup of HC 3.15.0 Env Variables

BASH

mv <hc-3.15.0-install-dir>/docker/environment-variables <hc-3.15.0-install-dir>/docker/environment-variables.backup

Create an environment variables directory for updated environment variable files in HC 3.15.0 installation
Make directory for environment variables

BASH
```
mkdir -p <hc-3.15.0-install-dir>/docker/environment-variables
```

The following script will merge the HC 3.9.4 and HC 3.15.0 environment variables in the following way:

It will read environment variable files one by one from HC 3.9.4 deployment.
Will add these environment variables in a new file with the same name in <hc-3.15.0-install-dir>/docker/environment-variables directory.
Will add newly added environment variables from HC 3.15.0 environment variables backup directory and add them in the file created in step ii.

It yields a new file that contains environment variables from HC 3.9.4 with their values and added environment variables with the default values from HC 3.15.0 release
The usage details are added below

Merge Environment Variables

BASH

################################################################################
# Usage Guide:                                                                 #
# 1. Copy this script and either edit it using any text editor or create       #
#    an sh file & paste the script in it                                       #
# 2. Edit the value of hc_3_9_4_baseDir variable in this script, enter         #
#    absolute path to HC 3.9.4 deployment directory, do not put a forward      #
#    slash at the end of this value.                                           #
# 3. Edit the value of hc_3_15_0_baseDir variable in this script, enter        #
#    absolute path to HC 3.15.0 deployment directory, do not put a forward     #
#    slash at the end of this value.                                           #
# 4. Copy this script, paste in your shell and execute. If you have created an #
#    sh file in step # 1, execute that file.                                   #
################################################################################

hc_3_9_4_baseDir="/root/chat-solution"
hc_3_15_0_baseDir="/var/lib/expertflow"

################################################################################
# The following script makes an assumption that backup of HC 3.15.0 env vars.  #
# is located at <hc3.15.0-base-dir>/docker/environment-variables.backup, if    #
# this is not the case with your deployment, update the following path in this #
# script:                                                                      #
# $hc_3_15_0_baseDir/docker/environment-variables.backup/$filename             #
################################################################################

for file in $hc_3_9_4_baseDir/docker/environment-variables/*; do
        [ -e "$file" ] || continue
        filename=${file##*/}
        echo "Merging $filename"
        awk -F= '!a[$1]++' $hc_3_9_4_baseDir/docker/environment-variables/$filename $hc_3_15_0_baseDir/docker/environment-variables.backup/$filename > $hc_3_15_0_baseDir/docker/environment-variables/$filename
done

The script above merges files but cannot assure environment variables sequence/order in a file. It can lead to leaving some comments in environment variable files out of sequence. So it is recommended to refer to the documentation of environment variable files in <hc-3.15.0-install-dir>/docker/environment-variables.backup directory to review environment variables comments/explanation. The recommended way is to refer to Environment Configurations for env variables details.

The following table contains environment variables that are needed to be updated manually after executing the merge script. If an env variable value is already the same as the updated value, leave it be.

	Component	Env Variables File	Env Variable	Status	Recommendation	Previous Value	Updated Value	Description
1	Agent Gadget	agent-gadget-variables.env	SERVER_URL	UPDATE	RECOMMENDED	https://hc-fqdn	https://hc-fqdn/chat	Supervisor dashboard for queue statistics reload time
2	Customer Channel Manager	ccm-variables.env	PUBLISHER_ENABLE	UPDATE	RECOMMENDED	true	false	This is only needed when CCM is integrated with CIM. Need to set it to false in this case.
3	Customer Channel Manager	ccm-variables.env	CONSUMER_ENABLE	UPDATE	RECOMMENDED	false	true	Set to true when CCM is integrated with HC
4	Customer Channel Manager	ccm-variables.env	AMQ_PRIMARY	UPDATE	RECOMMENDED	activemq:61617	activemq:61617?verifyHostName=false	CCM will not be able to connect to ActiveMQ in the 3.15.0 release if hostname verification is not enabled
5	Customer Channel Manager	ccm-variables.env	AMQ_SECONDARY	UPDATE	RECOMMENDED	activemq:61617	activemq:61617?verifyHostName=false	CCM will not be able to connect to ActiveMQ in 3.150 release if hostname verification is not enabled
6	Chat Server	chat-variables.env	AMQ_HOST	REMOVE	OPTIONAL	activemq		This environment variable is deprecated. You may remove it from the Chat Server environment variables file. You should remove it from the file to avoid operational issues.
7	Chat Server	chat-variables.env	LOG_LEVEL	UPDATE	RECOMMENDED	debug	info	It is recommended to set the Chat Server log level to info for better performance.
8	Communication Server	comm-server-variables.env	ACTIVEMQ	REMOVE	OPTIONAL	activemq:61617		This environment variable is deprecated. You may remove it from the Communication Server environment variables file. You should remove it from the file to avoid operational issues.
9	Communication Server	comm-server-variables.env	GRC_CONSUMER_PRIORITY	REMOVE	OPTIONAL	127		This environment variable is renamed to AMQ_CONSUMER_PRIORITY which is already added to the file after script execution. You should remove it from the file to avoid operational issues.
10	Communication Server	comm-server-variables.env	AGENT_LOGS_FILE_SIZE	UPDATE	RECOMMENDED	100	10MB	Set size for individual agent log files
11	Communication Server	comm-server-variables.env	UMM	REMOVE	OPTIONAL	http://umm:8080		This environment variable is renamed to UMM_PATH which is already added to the file after the script execution. You should remove it from the file to avoid operational issues.
12	Communication Server	comm-server-variables.env	KEYSTORE_PATH	UPDATE	RECOMMENDED	/src/app/client.ks	/src/app/ssl/client.ks	Comm Server Keystore path for AMQ, it will not work without updating this.
13	Communication Server	comm-server-variables.env	TRUSTSTORE_PATH	UPDATE	RECOMMENDED	/src/app/client.ts	/src/app/ssl/client.ts	Comm Server truststore path for AMQ, it will not work without updating this.
14	Communication Server	comm-server-variables.env	JKS_KEYSTORE_PATH	UPDATE	RECOMMENDED	/src/app/keystore.jks	/src/app/ssl/keystore.jks	Comm Server Keystore path which is used to host Comm Server APIs via SSL. Comm Server will not work without updating this.
15	Reporting Connector	cs-reporting-connector-variables.env	AMQ_HOST	REMOVE	OPTIONAL	activemq		This environment variable is deprecated. You may remove it from Reporting Connector environment variables file. You should remove it from the file to avoid operational issues.
16	Customer Gadget	customer-gadget-variables.env	PHONE_PREFIX	REMOVE	OPTIONAL			This environment variable is deprecated in 3.15.0 release. You may remove it from the Customer Gadget env variables file
17	Database Connector	database-connector-variables.env	DBURL	REMOVE	OPTIONAL	mongo		This is deprecated in this release. You should remove it to avoid operational issues
18	Database Connector	database-connector-variables.env	DBUSER	REMOVE	OPTIONAL			This is deprecated in this release. You should remove it to avoid operational issues
19	Database Connector	database-connector-variables.env	DBPWD	REMOVE	OPTIONAL			This is deprecated in this release. You should remove it to avoid operational issues
20	Database Connector	database-connector-variables.env	AMQ_HOST	REMOVE	OPTIONAL	activemq		This is deprecated in this release. You should remove it to avoid operational issues
21	Database Connector	database-connector-variables.env	AMQ_PORT	REMOVE	OPTIONAL	61615		This is deprecated in this release. You should remove it to avoid operational issues
22	Database Connector	database-connector-variables.env	AMQ_API_URL	REMOVE	OPTIONAL	https://activemq:8162		This is deprecated in this release. You should remove it to avoid operational issues
23	Database Connector	database-connector-variables.env	STOMP_TLS_ENABLED	REMOVE	OPTIONAL	true		This is deprecated in this release. You should remove it to avoid operational issues
24	Database Connector	database-connector-variables.env	AMQ_RETRIES	REMOVE	OPTIONAL	500000		This is deprecated in this release. You should remove it to avoid operational issues
25	Database Connector	database-connector-variables.env	AMQ_DELAY	REMOVE	OPTIONAL	1000		This is deprecated in this release. You should remove it to avoid operational issues
26	EABC	eabc-variables.env	DB_URL	REMOVE	OPTIONAL	jdbc:mysql://mysql:3306/eabc		This is deprecated in this release. You should remove it to avoid operational issues
27	EABC	eabc-variables.env	DB_DRIVER	REMOVE	OPTIONAL	com.mysql.jdbc.Driver		This is deprecated in this release. You should remove it to avoid operational issues
28	EABC	eabc-variables.env	DB_DIALECT	REMOVE	OPTIONAL	org.hibernate.dialect.MySQL5InnoDBDialect		This is deprecated in this release. You should remove it to avoid operational issues
29	EABC	eabc-variables.env	DB_USER	REMOVE	OPTIONAL			This is deprecated in this release. You should remove it to avoid operational issues
30	EABC	eabc-variables.env	DB_PASS	REMOVE	OPTIONAL			This is deprecated in this release. You should remove it to avoid operational issues
31	UMM	umm-variables.env	LD_LIBRARY_PATH	REMOVE	RECOMMENDED	/opt/apache-tomcat-8.5.41/bin		UMM will not work if this variable is not removed
32	MRE	mre-variables.env	KEYSTORE_PATH	UPDATE	RECOMMENDED	/src/app/client.ks	/src/app/ssl/client.ks	MRE Keystore path for AMQ, it will not work without updating this.
33	MRE	mre-variables.env	TRUSTSTORE_PATH	UPDATE	RECOMMENDED	/src/app/client.ts	/src/app/ssl/client.ts	MRE truststore path for AMQ, it will not work without updating this.
34	MRE	mre-variables.env	JKS_KEYSTORE_PATH	UPDATE	RECOMMENDED	/src/app/keystore.jks	/src/app/ssl/keystore.jks	MRE Keystore path which is used to host Comm Server APIs via SSL. Comm Server will not work without updating this.

Migrate key stores and trust stores if you have added custom client certificates in your HC deployment

CODE

# take backup of current certificates
mv <hc-3.15.0-install-dir>/docker/certificates <hc-3.15.0-install-dir>/docker/certificates.backup

# copy certificates from HC 3.9.4 deployment
cp -r <hc-3.9.4-install-dir>/docker/certificates <hc-3.15.0-install-dir>/docker/certificates

Migrate your HC public certificate by replacing the localhost.crt and localhost.key files in <hc-3.15.0-install-dir>/docker/nginx/certs
Deploy the updated web-init-widget from the 3.15.0 tag. Update config.json file accordingly.
Restore MongoDB backup.
Start HC 3.15.0.
Login to UMM and sync contact center agents/create standalone agents.
If Communication Server stays in an unhealthy state after the upgrade, execute the following:
1. Stop Comm Server using efutils
2. Execute the following script to clear real-time events for Agents
  CODE
```
docker exec -it expertflow_mongo_1 mongo
use chatsolution
db.agents.deleteMany({});
exit
```
3. Start Comm Server again
MRE queues in HC 3.9.4 are not compatible with HC 3.15.0, so execute the following steps:
1. Delete queues from MRE UI
2. Recreate queues in MRE UI
3. Restart MRE