Planning

Important

Review the Limitations page before planning.

Prerequisites

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

EXEC supports Enterprise Redis version 6.x. Redis Cluster mode is not supported. 

Container Registry

EXEC components are provided in a form of Docker containers. Customers should provide a container registry where EXEC docker containers can be hosted. Docker composer files of the EXEC components will be provisioned to pull docker containers 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 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: 4 CPU Cores, 8 GB RAM, and at least 20 GB HDD
• Docker version 20 or later

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	RDBMS listening port 5432(default)	Read Engage configuration
EXAS	Outgoing	TCP	Any	Engage Primary Stat Server	Primary Stat Server listening port (2060) default	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)	SIP Server default listening port (8000) default	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, 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	TCP/TLS	Any (opened by local log agent e.g. filebeat)	Logging Solution	9200 (default)	Upload JSON logs to the logging solution (e.g., ElasticSearch)
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 hybrid_integration in CME section.
3. Download all EXEC components from Genesys FTP
   • The following packages should be downloaded from Genesys FTP:
     1. EXCS (excs-100.0.100.XX.tgz) - EXCS container
     2. EXAS (exas-100.0.100.XX.tgz) - EXAS container
     3. EXCP (excp-100.0.100.XX.tgz) - EXCP container
     4. EXOP (exop-100.0.100.XX.tgz) - bootstrap package
4. Deploy EXEC containers to the local container registry
   1. Extract tarballs of the EXEC component containers from the *.tgz archives
   2. Deploy tarballs as containers to the local container registry using 'docker import' command
   3. Save the paths to the containers in the registry (e.g. myregistry.mycompabny.com/exec) to use them later in the deployment process
5. Execute the procedure described in the Installing EXEC Bootstrap Script section.
6. Execute the procedure described in the Configuring .env file section.
7. Execute the procedure described in the Deploying EXEC section.

Deployment Procedures

Preparing Engage Configuration for the EX integration

Procedure to select a subset of the Engage Configuration Objects to be mapped to GC

This procedure selects Engage configuration objects, which should be mapped to the EX Org. No information about the EX Org is required to execute this step. It's recommended to complete it before running EXCS for the first time. Otherwise, EXCS would map all eligible configuration objects to the EX Org, which may temporarily impact solution performance by mapping large volume of data and incur some unexpected GC charges.

1. Review Folder Filtering rules and the rules of selecting individual configuration objects above.
2. Select a folder name to be used for the Engage configuration object selection. Name EX_EVOLUTION is used in this section as an example.
3. Skills:
   • Create a folder EX_EVOLUTION at the root level of the Skills configuration unit and move the Skills to be mapped there
4. Persons:
   • Create a folder EX_EVOLUTION at the root level of the Persons configuration unit and move the Skills to be mapped there
5. Queues:
   • 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.
   • Create a folder EX_EVOLUTION at the root level of the DNs configuration unit under the selected Switch and move the queue DNs to be mapped to the EX Org into this folder. The following DN types should be considered:
     1. ACD Queue
     2. Routing Queue
     3. Virtual Queue - select only routing VQs used by the URS for target selection, do not map reporting VQs
     4. Routing Point
6. Agent Groups
   • 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>
7. 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.
8. Review all objects of all types moved to the EX_EVOLUTION folders for the case-sensitivity conflicts. Resolve those conflicts if found.

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
general	organization_id	CFG_ALIAS_EX_ORG_ID	EX Org Organization ID
general	base_service_url	<GENESYS_CLOUD_API_URL>	Base service URL used for the REST API calls to the EX Org
config_sync	client_id	CFG_ALIAS_EX_ORG_OAUTH_CLIENT_ID	OAuth client ID
config_sync	client_secret	CFG_ALIAS_EX_ORG_OAUTH_CLIENT_SECRET	OAuth client secret
agent_state_sync	client_id	CFG_ALIAS_EX_ORG_OAUTH_CLIENT_ID	OAuth client ID
agent_state_sync	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
conversation_provider	client_secret	CFG_ALIAS_EX_ORG_OAUTH_CLIENT_SECRET	OAuth client secret