No-media Deployment

Prerequisites

Important

Review the Limitations page before planning.

This section lists the requirements for the environment where EXEC is planned to be deployed. Mandatory and optional requirements are given in the corresponding sections below. 

Mandatory Environment Elements 

Redis Cache

EX Engage Connector supports Enterprise Redis version 6.x. Redis Cluster mode is not supported. Customers should plan to use 2 GB of Redis memory for contact centers with 1000 agents and a call rate of 5 CAPS.

Container Registry

EXEC components are provided as Docker containers. Customers should provide a container registry where EXEC Docker images can be hosted. Docker composer files of the EXEC components will be provisioned to pull Docker images from this registry.  

Virtual Machines for the EXEC Components

Four VMs have to be created to deploy EXEC components to have each VM to carry one component instance: 

• 1 VM for EX Engage Connector Config Sync (EXCS)
• 1 VM for EX Engage Connector Agent State Sync (EXAS)
• 2 VMs for 1 SIPS HA Pair for deploying EX Engage Connector Conversation Provider (EXCP)

VMs allocated for the EXEC components should be provisioned as follows: 

• 64-bit Linux OS with kernel version 4.18 or later
• Recommended resource allocation: 2 CPU Cores, 8 GB RAM, and at least 80 GB HDD
• Docker version 20 or later

The EXEC VM must sync the system time at least once every 24 hours as the communication between the EXEC services and Genesys Cloud are very time-sensitive.

All VMs running EX Engage Connector components should belong to the same local network segment and be interconnected so that all components can communicate over the network. EXEC components can use either FQDNs or IP addresses to establish communication with each other. The connectivity table lists both incoming and outgoing connections required by the EXEC components.  

Service	Direction	Protocol	Local Port	Remote Peer	Remote Peer Port	Purpose
EXCS	Outgoing	TCP/TLS	Any	Engage Config DB	5432 (default RDBMS listening port)	Read Engage configuration.
EXAS	Outgoing	TCP	Any	Engage Primary Stat Server	2060 ( default Primary Stat Server listening port)	Obtain real-time agent state data.
EXAS	Outgoing	TCP	Any	Engage Backup Stat Server	Backup Stat Server listening port (2060) default	Obtain real-time agent state data
EXCP	Outgoing	TCP	Any	Engage SIP Servers (multiple)	8000 (default SIP Server default listening port)	To fetch real-time Call, DN, and VQ details from SIP Server.
EXCP/EXAS	Outgoing	TCP	Any	EXCS	3640 (default)	Use EXCS REST API.
EXCS	Inbound	TCP	3640 (default)	EXCP/EXAS/Prometheus	Any	Use EXCS REST API and scrape metrics.
EXAS	Inbound	TCP	3630 (default)	Prometheus	Any	Scrape metrics.
EXCP	Inbound	TCP	3650 (default)	Prometheus	Any	Scrape metrics.
EXCS/EXAS/EXCP	Outgoing	TCP/TLS	Any	Redis	6379 (default)	Store config data to provide ID mapping services
EXCS/EXAS/EXCP	Outgoing	HTTPS	Any	Genesys Cloud	443	Call GC REST API.

Bootstrap Virtual Machine 

Bootstrap VM is required to execute EXEC deployment procedure by running a bootstrap Python script. Bootstrap VM specs include:

• Linux OS
• Docker version 20 or later
• Python 3.9+
• pip3 package manager 
• SSH connectivity to EXEC VMs

Genesys Cloud EX Organization 

The EX Organization should be created in Genesys Cloud to be used as a target for data injection by the EXEC components. 

An OAuth client with grant type Client Credentials created in the EX Org to connect to GC and the EX Integration role should be assigned to the OAuth client. This client's credentials will be used by the EXEC components to connect to Genesys Cloud.

Engage Environment

EX Engage Connector components operate with Genesys core services version 8.5+ on the back-end. Ensure the following Engage components (Config DB, Stat Server, and SIP Server) are deployed and running. Also, the EXEC components should be able to communicate with Config DB, Stat Server, and SIP Server.

Optional Environment Elements 

• Monitoring Solution - EXEC component provides metrics that can be consumed by Prometheus to enable effective monitoring.
• Observability Solution - Prometheus-based observability solution (Grafana) to make monitoring and alerting friendly and efficient.
• Centralized Logging Solution - Log collection systems (Filebeat/ElasticSearch, Promtail/Grafana Loki, etc) to collect and index logs in a centralized place. 
• Container Monitoring Solution - third-party container monitoring tools (Portainer) to simplify management and monitoring of the EXEC containers 

Deployment Plan

1. Execute the procedure described in the Preparing Engage Configuration for the EX integration section.
2. Execute the procedure described in the Configuring OAuth Client in the GC Org section.
3. Execute the procedure described in the Configuring hybrid_integration transaction in CME section.
4. Download all EXEC components from Genesys FTP:
   • EXCS (excs-100.0.100.XX.tgz) - EXCS image
   • EXAS (exas-100.0.100.XX.tgz) - EXAS image
   • EXCP (excp-100.0.100.XX.tgz) - EXCP image
   • EXOP (exop-100.0.100.XX.tgz) - bootstrap package
5. Load EXEC images to the local container registry.
   1. Extract tarballs of the EXEC component image from the *.tgz archives.
   2. Deploy tarballs as images to the local container registry using docker import command.
   3. Save the paths to the images in the registry (for example myregistry.mycompany.com/exec) to use them later in the deployment process.
6. Execute the procedure described in the Installing EXEC Bootstrap Script section.
7. Execute the procedure described in the Configuring .env file section.
8. Execute the procedure described in the Deploying EXEC section.

Preparing Engage Configuration for the EX integration

1. Review Folder Filtering rules and how they are applied to the configuration objects of different types. Set the value of the EXCS environment variable, SYNC_CUSTOMER_FOLDER_NAME to the comma-separated list, which includes the names of all CME folders selected to be synchronized to GC.
2. Identify a routing domain to map to the EX Org
   • In this context Engage Routing Domain refers to a set of configuration objects, which create isolated or semi-isolated routing environment. Line of Business (LOB) can be an example of such environment. One LOB can be responsible for processing inbound calls landing on a set of toll free numbers of a contact center. In the Engage contact center such LOB would be configured with a set of dedicated resources: RP and VQ DNs, skills, agents, agent groups, and business attributes. Those are main configuration object, which define the routing domain of a selected LOB.
   • Usually, it is not possible to find a fully isolated LOB in the contact center. It is recommended to start with a small routing domain, observe mapping results for all three injected data types (configuration, agent states, and interactions), and then gradually increase the routing domain by adding more Engage configuration objects to it with the goal of injecting all Engage contact center configuration and activity into the EX Org.
   • Take current EXEC limitations into account while defining the routing domain. For example, consider selecting voice agents serving inbound calls because currently EXEC doesn't support digital interactions. Also, outbound campaign calls cannot be injected into the EX Org. So, if digital, blended, or voice outbound agents are selected their workload wouldn't be properly represented in the EX Org through the injected data, which may impact the quality of the WFM and Gamification services.
3. Skills:
   • Check that CME folders in the Skills unit selected to be synchronized to GC are added to the EXCS environment variable, SYNC_CUSTOMER_FOLDER_NAME.
4. Persons:
   • Check that CME folders in the Persons unit selected to be synchronized to GC are added to the EXCS environment variable, SYNC_CUSTOMER_FOLDER_NAME
5. Extension DNs
   1. Extension DNs are not mapped to the EX Org but EXCS reads the DNs of this type and stores them into Redis. Those DNs are used by the EXCP for the call event processing.
   2. All Extension DNs used to log in the Persons selected for the EX integration at the previous step should also become a part of the EX integration context.
   3. Review the EXCP Deployment Topologies section and select a SIP Server, which processes contact center voice calls and is panned to be used as a source for the interaction event injection to the EX Org, and identify a Switch this SIP Server uses.
   4. Check that CME folders in the DNs selected to be synchronized to GC are added to the EXCS environment variable, SYNC_CUSTOMER_FOLDER_NAME
6. Queues:
   1. EXCS can convert four types of the Engage DNs into the ACD queues in GC EX Org: ACD Queue, Routing Queue, Virtual Queue (VQ), and Routing Point (RP). However, the only supported call distribution model from a queue to an agent is the one where call lands on RP DN, then it is placed on a VQ DN for an agent selection, and then is distributed to a selected agent. From this perspective it is recommended to map Engage queue DNs of only two types to the EX Org:
      1. RP: select all RP DNs, which belong to a routing domain being mapped
      2. VQ: select only routing VQ DNs, which are used by the URS for target selection, do not map reporting VQ DNs
   2. Select a SIP Server, which processes contact center voice calls and is panned to be used as a source for the interaction event injection to the EX Org, and identify a Switch this SIP Server uses.
   3. Check that CME folders in the DNs configuration unit under the selected switch selected to be synchronized to GC are added to the EXCS environment variable, SYNC_CUSTOMER_FOLDER_NAME
   4. Review the EXCP Deployment Topologies section and select a SIP Server, which processes contact center voice calls and is panned to be used as a source for the interaction event injection to the EX Org, and identify a Switch this SIP Server uses.
   5. Check that CME folders in the DNs configuration unit under the selected switch that has RP and VQ DNs selected to be synchronized to GC are added to the EXCS environment variable, SYNC_CUSTOMER_FOLDER_NAME
7. Agent Groups
   • Select a folder at the Agent Group configuration unit to be synced to the GC.
   • Identify agent groups (AG) and virtual agent groups (VAG) used for routing or reporting by the Persons selected to be mapped to the EX Org.
   • Link selected AGs and VAGs to their corresponding queue DNs by applying the following configuration to the properties of these groups:
     • Annex / hybrid / WFM_queue_number = <ROUTING_VQ_DN_NAME>
8. Supervisors
   • Engage Supervisors should be marked as shown below to get a Supervisor role assigned in the EX Org:
     • Person has 'Is Agent' checked
     • Person has Annex/htcc/roles list containing a 'Supervisor' as one of its elements
   • If customers use WWE/GWS, then their supervisors should already be configured like this. In other cases this configuration should be added.
9. Review all objects of all types under CME folders selected to be synchronized to GC for the case-sensitivity conflicts. Refer to the Case-Sensitivity of Object Names section. Resolve those conflicts if found.

Configuring OAuth Client in the GC Org

EXCS requires an OAuth client with grant type Client Credentials created in the EX-Org to connect to GC. Create a new OAuth client and assign the EX Integration role to the OAuth client. Refer to Create an OAuth client for more information.

Configuring hybrid_integration transaction in CME

EX Org parameters required for the hybrid_integration transaction configuration

The following configuration parameters should be fetched from EX Org to provision the hybrid_integration transaction in the Engage CME. Configuration Alias is used to refer to the value of the EX Org parameter.

Configuration Alias	EX Org Parameter Path	Parameter Description
CFG_ALIAS_EX_ORG_SHORT_NAME	Organization Setting / Organization Details / Short Name	Short name of the EX Org
CFG_ALIAS_EX_ORG_ID	Organization Setting / Organization Details / Advanced / Organization ID	EX Org Organization ID
CFG_ALIAS_EX_ORG_OAUTH_CLIENT_ID	Integrations / OAuth / <OAUTH_CLIENT_NAME> / Client Details / Client ID	OAuth client ID
CFG_ALIAS_EX_ORG_OAUTH_CLIENT_SECRET	Integrations / OAuth / <OAUTH_CLIENT_NAME> / Client Details / Client Secret	OAuth client secret

Transaction Object

Transaction object hybrid_integration contains EXEC configuration. It should be configured as:

• Path to the transaction object:
  • for the single-tenant Engage deployment the transaction object should be created in the Transactions configuration unit in the Resources structure
  • for the multi-tenant Engage deployment there must be a separate transaction object under each of the tenant. Each transaction should point at a dedicated EX Org. EX Orgs cannot be shared by multiple Engage tenants.
• Name: hybrid_integration
• Type: List

Transaction Annex Folders

Folder	Parameter Name	Value	Description
general	organization_sname	CFG_ALIAS_EX_ORG_SHORT_NAME	Short name of the EX Org.
	organization_id	CFG_ALIAS_EX_ORG_ID	EX Org Organization ID.
	base_service_url		Base service URL used for framing the REST API calls to the EX Org.
	base_auth_url		Base auth URL used for logging into the EX Org.
	region	GENESYS_CLOUD_REGION_URL	Service URL for the particular region.
config_sync	client_id	CFG_ALIAS_EX_ORG_OAUTH_CLIENT_ID	OAuth client ID.
	client_secret	CFG_ALIAS_EX_ORG_OAUTH_CLIENT_SECRET	OAuth client secret.
	skill_level_max_value	ENGAGE_MAX_SKILL_LEVEL	Maximum skill level value set for Engage agents to match the skill proficiency in Genesys Cloud. See ACD Skills for more information.
	skill_level_min_value	ENGAGE_MIN_SKILL_LEVEL	Minimum skill level value set for Engage agents to match the skill proficiency in Genesys Cloud. See ACD Skills for more information.
agent_state_sync	client_id	CFG_ALIAS_EX_ORG_OAUTH_CLIENT_ID	OAuth client ID.
	client_secret	CFG_ALIAS_EX_ORG_OAUTH_CLIENT_SECRET	OAuth client secret.
conversation_provider	client_id	CFG_ALIAS_EX_ORG_OAUTH_CLIENT_ID	OAuth client ID.
	client_secret	CFG_ALIAS_EX_ORG_OAUTH_CLIENT_SECRET	OAuth client secret.
	sta_default_programid	<DEFAULT_STA_PROGRAM_ID>	Program UUID for topic detection
	sta_default_language	<DEFAULT_STA_LANGUAGE>	ISO 639-1 two letter language code + '-' + ISO 3166-1 alpha-2 two letter country code string. Default language to use for transcription
	password	CFG_ALIAS_EX_ORG_OAUTH_CLIENT_SECRET	OAuth client secret.

Create a genesys user on Virtual Machines

It is mandatory to create 'genesys' user on all the Virtual Machines including Bootstrap Virtual Machine. This step ensures seamless, password-free deployment of EXEC components onto their corresponding Virtual Machines.

Installing EXEC Bootstrap Script

Important

You should always deploy EX Engage Connector using the bootstrap script.

Perform the following items before deploying EX Engage Connector:

1. Move EXOP bootstrap package downloaded from the FTP (for example exop-100.0.100.XX.tgz) to the Bootstrap VM and place it under /usr/home/genesys/exec.
2. Go to the installation directory where the bootstrap script is copied and extract the package in the same folder.
3. Under the installation directory, verify if the following files are available:
   • .env
   • bootstrap.py
   • Docker Compose files for EXCS, EXCP, and EXAS
   • alerts.yml
   • prometheus.yml
4. Make sure the file is executable: chmod +x bootstrap.py
5. Run ./bootstrap.py --help and verify if the following screen is displayed:

Welcome to EXEC deployment bootstrap script. Following actions are supported
 
init                                      - Initialize EXEC environment
start                                     - Start EXEC services
stop                                      - Stop EXEC services
restart                                   - Restart EXEC services
update                                    - upgrade/downgrade EXEC services
rollback                                  - rollback EXEC service

Configuring .env file

The .env file contains the description of the EXEC Docker environment. Configure all mandatory parameters to describe the environment where EXEC components are planned to be deployed. Bootstrap script converts data from this file into the Docker compose yml configuration files.

You can specify parameters for the deployment by overriding the default values in the .env file. See the Parameters table for a full list of overridable values.

Common Parameters

Parameter Name	Description
EXEC_DOCKER_REPOSITORY *	Jfrog Artifactory Edge repository for pulling EXEC images.
EXEC_INFRA_DOCKER_REPOSITORY	Docker repo for Redis, grafana, and Prometheus containers, if empty - docker hub will be used.
EXEC_HOST_LOGS_VOLUME_PATH *	Host path which is mounted inside the container to store logs.
EXEC_ORG_ID *	EX Org ID is taken from the following path in the GC UI Admin view: Organization Settings / Organization Details / Advanced / Organization ID
EXEC_TENANT_ID *	Unique ID to identify the Engage tenant. DBID of the Tenant configuration object in the Engage Configuration DB can be used.
EXEC_REDIS_HOST *	IP Address of the Redis proxy in case of enterprise Redis and IP Address of Redis server in case of Lab environment
EXEC_REDIS_PORT *	Port of Redis server
EXEC_REDIS_SECURE	If the Redis server is password protected via the requirepass option.
EXEC_REDIS_PASSWORD	Do not configure the password in the .env file, provide it as input when you run the bootstrap script
A * indicates mandatory fields.

EXCS Parameters

Parameter Name	Description
EXCS_VM_HOST *	IP Address of VM machine where CS will be deployed
EXCS_PORT *	Config Sync Service port
EXCS_TAG *	Config Sync Service Image Version
EXCS_CONFIG_DB_HOST *	IP Address of Config Database.
EXCS_CONFIG_DB_PORT *	Port Number of Config Database
EXCS_CONFIG_DB_USER *	Config Database Username
EXCS_CONFIG_DB_SSL*	Config Database SSL connectivity
EXCS_CONFIG_DB_PASSWORD *	Do not configure the password in the .env file, provide it as input when you run the bootstrap script
EXCS_CONFIG_DB_NAME *	Config Database name
EXCS_CONFIG_DB_TYPE *	Config Database Type. Supported Values are postgresql, oracle, or mssql. Default value is postgresql.
EXCS_SYNC_CUSTOMER_OBJECTS_ONLY	When set to true, EXCS only synchronizes objects under customer folder hierarchy to Genesys Cloud. If this environment variable is set to true, then environment variable SYNC_CUSTOMER_OBJECTS_ONLY must contain a comma-separated list of folders to be synchronized to the GC. See Folder Filtering section for more information. Default is false, i.e. all objects of the supported types are synchronized. Values: true/false (default)
EXCS_SYNC_CUSTOMER_FOLDER_NAME	When SYNC_CUSTOMER_OBJECTS_ONLY is set to "true", , set this EXCS environment variable to a comma-separated list of the CME folder names. EXCS searches those folders in four configuration units, Persons, Skills, DNs, and Agent Groups, and syncs configuration objects found in those folders to GC. If a listed folder has subfolders, then all subfolders are synchronized to the GC too.
EXCS_LOG_PATH	File system path for logs. If not provided, logs will be directed to stdout.
EXCS_LOG_FILENAME *	File name for logs. If LOG_FILENAME is specified, this environment variable further describes the file name. Example: 'excs-<TENANT_ID>.%Y%m%d_%H%M%S_%L.log'
EXCS_LOG_LEVEL	Defines the EXCS log level. Values: trace, debug, info, warn, error, fatal
EXCS_GC_QUEUE_NAME_SUFFIX *	Set it to -Engage-external. This suffix is needed to distinguish Queue objects synced from Engage environment.
A * indicates mandatory fields.

EXAS Parameters

Parameter Name	Description
EXAS_HOST *	IP Address of VM machine where AS will be deployed
EXAS_PORT *	Agent Sync Service port
EXAS_TAG *	Agent Sync Service Image Version.
EXAS_STAT_SERVER_PRIMARY_HOST *	Primary Stat Server's host IP/FQDN
EXAS_STAT_SERVER_PRIMARY_PORT *	Primary Stat Server's port number.
EXAS_STAT_SERVER_BACKUP_HOST *	Backup Stat Server's host IP/FQDN
EXAS_STAT_SERVER_BACKUP_PORT *	Backup Stat Server's port number.
EXAS_LOG_PATH	File system path for logs. If not provided, logs will be directed to stdout
EXAS_LOG_FILENAME *	File name for logs. If LOG_FILENAME is specified, this environment variable further describes the file name. Example: 'exas-<TENANT_ID>.%Y%m%d_%H%M%S_%L.log'
EXAS_LOG_LEVEL	Defines the EXAS log level. Values: trace, debug, info, warn, error, fatal
A * indicates mandatory fields.

EXCP Parameters

Parameter Name	Description
EXCP_1_VM_HOST_PAIR *	VM Host IPAddress list where Conversation Provider service will be running
EXCP_1_PORT *	Conversation Provider Service port
EXCP_1_TAG *	Conversation Provider Container version
EXCP_1_VOICE_SERVER_VQ *	A list of SIP Server host:port for receiving Virtual Queue Events. EXCP should connect to the default port. Format: primary1:port/backup1:port
EXCP_1_VOICE_SERVER_AGENT *	A list of SIP Server host:port for receiving Extension DN Events . EXCP should connect to the default port. Format: primary1:port/backup1:port
EXCP_1_VOICE_SERVER_CALL *	A list of SIP Server host:port for receiving Call Monitoring Events. EXCP should connect to the default port. Format: primary1:port/backup1:port
EXCP_1_LOG_PATH	File system path for logs. If not provided, logs will be directed to stdout
EXCP_1_LOG_FILE_NAME *	File name for logs. If EXCP_1_LOG_FILE_NAME is specified, this environment variable further describes the file name. Example: 'excp-.%Y%m%d_%H%M%S_%L_${TENANT_ID}_${HOSTNAME}.log'
EXCP_1_LOG_LEVEL	Defines the EXCP log level. Values: trace, debug, info, warn, error, fatal
A * indicates mandatory fields.

Deploying EX Engage Connector

To set up the EX Engage Connector services, run the init command: ./bootstrap.py --action init.

The init script performs the following actions:

1. Prompt for following passwords:
   • DB password - The password for the Config database.
   • Redis password - The password for the Redis server (if the redis-secure parameter is set to true).
   • Config Server password - The password for the Config Server.
2. Create a /tmp/.env file containing the provisioning information along with password information.
3. Extract the VM address for each service and copy the docker-compose file of the respective service to their respective VMs.
4. Copy the /tmp/.env file to the list of VMs on which the connector services need to be installed and delete the /tmp/.env file.

The docker-compose files and .env files are stored under the exec directory in the home path of the Genesys user.

Run EXEC Services for First Time

Once the EXEC service environment is initialized, the EXEC services should be started in the following order:

1. Start the EXCS Service by running ./bootstrap.py --action start --service excs.
2. Check the health of EXCS Service and once it shows as healthy then it signifies that EXCS service is running fine.

   curl -v http://<EXCS_VMHOST_IPADDRESS>:3640/health
   200 OK with dependency status

3. Wait for all the Engage Objects to be synced to the GC side. Initial sync-up of contact centers with 1000 agents will be around 30 - 40 minutes.
4. To check if all the Engage Objects are synced to GC successfully, run the status command to see if the initialization status is "success".

   curl http://<EXCS_VMHOST_IPADDRESS>:3640/status
    {"status":{"code":0,"message":"Latest database updates for orgId:6662cb10-0d4d-4710-b979-db69011e66fd have been successfully processed on 2023-07-11T10:23:08.062Z","corrId":"bd4c0e9a-ba02-491c-93e5-6fd1e3a7e51e"},"data":{"syncStatus":{"timeStamp":"2023-07-11T10:23:08.062Z","status":"Success"},"updateStatus":{"timeStamp":"2023-07-11T10:23:08.062Z","status":"Success","previousHWM":0,"latestHWM":567,"processedHWM":567,"operation":"Initialization"}}}

5. Start the EXAS Service by running ./bootstrap.py --action start --service exas.
6. Check the health of EXAS Service; once it shows as healthy, it signifies that EXAS service is running fine.

   curl -v http://<EXAS_VMHOST_IPADDRESS>:3630/health
   200 OK with dependency status

7. Start the EXCP Service by running ./bootstrap.py --action start --service excp --pair 1.
8. Check the health of EXCP Service; once it shows as healthy, it signifies that EXCP is running fine.

   curl -v http://<EXCP_VMHOST_IPADDRESS>:3650/health
   200 OK with dependency status

Starting EXEC Services

The EXEC services can be started/stopped/restarted using the below commands:

• ./bootstrap.py --action start - starts all the EXEC services in their respective VMs configured.
• ./bootstrap.py --action start --service=exas - starts the EXAS service in its respective VM
• ./bootstrap.py --action start --service=excp --pair 1 - starts the EXCP service in both the VMs belonging to excp pair 1
• ./bootstrap.py --action start --service=excp --pair 1 --host 1 - starts the EXCP service in the VM host 1 belonging to excp pair 1

Stopping or Restarting EXEC Services

All services or a specific service or a specific instance of a service can be stopped using the ./bootstrap.py --action stop command. The ./bootstrap.py --action restart command can be used to restart all services or a specific service or a specific instance of a service.