Configuration Guide - Cisco Connector

Overview

The Cisco Connector is a Spring Boot service that listens to Cisco JTAPI events, correlates call legs with Cisco CC database records, and forwards conversation activity to the EF CX Platform. For more details please refer to the overview of Cisco-Connector.

Prerequisites

Ensure the CUCM_APPLICATION_USER configured via environment variables is assigned the controlled device for which the Cisco connector will listen to live JTAPI events.
Ensure a Cisco-type channel is configured in CX with the same service identifier as the conversation in Cisco. Otherwise, the conversation will not be synced in CX.

Limitations / Issues:

Stale Call Legs Accumulating in the Processing Queue

When a call happens, multiple call legs are created. Each leg is enriched with data fetched from the Cisco database (CCE/CCX) before being forwarded to the CX platform. However, Cisco does not always have a record for every leg particularly the first/primary leg at the time the batch processor runs. When this happens, the batch job skips the call and logs a warning, but the legs remain in the queue with sync_with_cx = false. Since the query that fetches unsynced legs has no age filter, these legs are picked up again in every subsequent batch run indefinitely, causing the warning logs to pile up and the queue to grow without bound.

Fix: Configurable Expiry for Unresolved Call Legs

A configurable expiry threshold (CALL_LEG_EXPIRY_MINUTES, default 30) was introduced. During each batch run, if no Cisco record is found for a call's first leg and that leg's created_at timestamp is older than the threshold, all legs belonging to that call are marked as abandoned (sync_with_cisco = true, sync_with_cx = true) and persisted removing them from all future batches. An ERROR log is emitted in this case. Legs that are still within the expiry window continue to be retried as before, with a WARN log.

Before deploying, ensure the following are available:

A running PostgreSQL instance accessible by the service (Vault Managed)
- Postgres is installed while deploying CX.
A running Cisco CUCM instance with a configured application user
A running Cisco CC database (CCX)
A running EF CX Solution
A running Keycloak instance

Step 1: Edit the Deployment file

vi helm-values/cx-ciscoConnector-custom-values.yaml

Step 2: Configure Environment Variables as Required

The service is configured entirely through environment variables. The table below describes each variable.

Postgres - Local Database of Cisco Connector

Cisco Connector uses the CX managed postgres instance.

Variable	Description	Default Value
`DB_URL`	Full JDBC URL (overrides host/port/name if set)	`jdbc:postgresql://ef-postgresql.ef-external.svc:5432/cisco_connector?sslmode=verify-ca&sslrootcert=/postgresql/ca.crt`
`POSTGRES_ROLE_PATH`	The role set while configuring vault managed access of postgres.	`database/creds/postgres-cisco-connector-role`
`DB_USER`	Database username	`sa`
`DB_PASSWORD`	Database password	`yourpassword`

Cisco CUCM

Variable	Description	Example
`CUCM_APPLICATION_USER_NAME`	CUCM application user username - The user that has the access of the controlled device for which the application will listen the live JTAPI events.	`appuser`
`CUCM_APPLICATION_USER_PASSWORD`	CUCM application user password	`yourpassword`
`CUCM_IP`	IP address of the CUCM instance	`192.168.1.212`

Cisco CC Database

Variable	Description	Example
`CC_TYPE`	Contact Center type: `CCE` or `CCX`	`CCX`
`CC_ENGINE`	JDBC engine for CC database	`informix-sqli`
`CC_IP`	CC database host	`192.168.1.96`
`CC_PORT`	CC database port	`1504`
`CC_DATABASE`	CC database name	`db_cra`
`CC_SERVER`	CC server name	`uccx15_uccx`
`CC_USERNAME`	CC database username	`uccxhruser`
`CC_PASSWORD`	CC database password	`yourpassword`

Correlation

Variable	Description	Default
`CORRELATION_BATCH_SIZE`	Number of records processed per batch	`1000`
`CORRELATION_BATCH_INTERVAL_MS`	Interval between correlation runs (ms)	`30000`

Cisco Connector Specific

Variable	Description	Default
`CALL_LEG_EXPIRY_MINUTES`	Configurable Expiry for Unresolved Call Legs, explained above in the limitation section.	`30`

EF CX Platform

Variable	Description	Example
`EFCX_FQDN`	Base URL of the EF CX Platform	`https://your-cx-domain.com`
`CALL_BACK_URL`	Callback URL sent with conversation events	`https://your-cx-domain.com/callback`
`CONVERSATION_BATCH_SIZE`	Number of call legs processed per batch	`50`
`CONVERSATION_BATCH_INTERVAL_MS`	Interval between conversation sync runs (ms)	`40000`
`OB_SERVICE_IDENTIFIER`	Service identifier used for outbound calls	`8899`
`ROUTING_ENGINE_URL`	URL of the routing engine	`https://your-cx-domain.com/routing-engine`
`TENANT_ID`	The tenant ID	`expertflow`
`TRIGGER_SURVEY`	The flag that controls whether a survey is triggered after syncing the conversation in CX.	`true`

Phone Number Normalization

These variables control how outbound customer phone numbers are converted from local format to international format before being sent to WhatsApp or SMPP connectors. Normalization ensures that local numbers are converted to international format for connectors that only accept international format (e.g., WhatsApp connector requires international format).

Variable	Description	Example
`CUSTOMER_COUNTRY_CODE`	Country code to prepend (leave empty to disable normalization)	`92` (Pakistan), `44` (UK), `1` (US)
`CUSTOMER_LOCAL_PREFIX`	Local trunk prefix to strip before prepending country code (leave empty if the country has no trunk prefix)	`0` (Pakistan, UK), `` (US)

How normalization works:

`CUSTOMER_COUNTRY_CODE`	`CUSTOMER_LOCAL_PREFIX`	Input	Output
`92`	`0`	`03001234567`	`923001234567`
`44`	`0`	`07911123456`	`447911123456`
`1`	(empty)	`2125551234`	`12125551234`
(empty)	(any)	`03001234567`	`03001234567` (no change)

Numbers already in international format (e.g., 923001234567 or +923001234567) are detected and passed through unchanged to prevent double-prefixing.

Keycloak

Variable	Description	Example
`KEYCLOAK_REALM_NAME`	Keycloak realm name	`expertflow`
`KEYCLOAK_CLIENT_ID`	Keycloak client ID	`cim`
`KEYCLOAK_CLIENT_SECRET`	Keycloak client secret	`your-secret`
`KEYCLOAK_AGENT_ROLE_NAME`	Agent role name in Keycloak	`agent`
`KEYCLOAK_AGENT_ROLE_ID`	Agent role ID in Keycloak	`a0cedb21-bc4f-4f4d-955f-45f8d54747b2`
`KEYCLOAK_USERNAME`	Keycloak admin username	`admin`
`KEYCLOAK_PASSWORD`	Keycloak admin password	`admin`

Step 3: Verify the Deployment

Check that the pod is running:

kubectl get pods -n expertflow | grep cisco-connector

Check the logs to confirm successful startup and JTAPI connection:

kubectl logs -n expertflow -f cisco-connector --tail=100

On successful startup you should see log lines indicating:

Spring Boot application started
JTAPI provider connected to CUCM
Conversation job scheduled

Step 4: Verify Phone Number Normalization (Optional)

If CUSTOMER_COUNTRY_CODE is configured, the logs will confirm normalization is active when the calls are processed:

Normalized phone number from 03001234567 to 923001234567

If the number is already in international format:

923001234567 is already in normalized form

To disable normalization, leave CUSTOMER_COUNTRY_CODE unset or set it to an empty string:

- name: CUSTOMER_COUNTRY_CODE
  value: ""