Configuring Helm deployments
The helm chart bootstraps VoiceXML Connector on a Kubernetes cluster using the Helm package manager, and deploys two services. Each service has one pod instance:
- vxmlconnector-envoy: the default deployment includes an Envoy service for balancing load across instances of the VoiceXML Connector. The Envoy instances distribute the load evenly and avoid the blocking of upstream pods. Load balancing is optional. You can disable Envoy.
- vxmlconnector
Some customization is required. Define parameters in an application.yaml file, and apply the configuration (with the -f argument) when starting the Connector.
Redis session configuration
Required. Configure Redis to manage the session state. The Redis server stores all data related to individual sessions.
VoiceXML Connector supports Redis cluster and sentinel configurations in addition to the default standalone configuration.
Best practices:
- Recommended. Deploy Redis before deploying VoiceXML Connector. Deploy both in the same namespace. Do not use the default namespace.
- Required. Configure the
redis_config_name
andredis_secret_name
parameters in the Helm charts. - Required. A secret named vxmlconnector-redis must exist. Replace this example with your own secret:
apiVersion: v1
kind: Secret
type: Opaque
metadata:
name: vxmlconnector-redis
data:
redis-password: U09NRV9IQVNIRURfVkFMVUVfSEVSRQ==
- Required. A configMap named vxmlconnector-redis-configuration must exist. Change the default endpoint as needed. The ConfigMap name must NOT match the Redis release name. Otherwise, the file gets overwritten when the images share the same namespace. Example configMap:
apiVersion: v1
kind: ConfigMap
metadata:
name: vxmlconnector-redis-configuration
data:
redis_endpoint: redis://vxmlconnector-master:6379
redis_host: vxmlconnector-master
redis_port: "6379"
redis_ssl: "false"
-
Optional. The Redis configuration supports sentinel and cluster configurations. To enable cluster mode use these override values:
redis:
enabled: true
mode: cluster
address: redis://dns-name-of-one-cluster-node:6379
# other settings as needed
To enable sentinel mode use these override values:
redis:
enabled: true
mode: sentinel
address: redis://dns-name-of-one-sentinel-node:6379
masterName: the-configured-sentinel-master-name
# other settings as needed
- Optional. If using neural TTS, use Configuring Helm deployments to allow playing final TTS requests to the customer after the dialog model completes.
- The configuration is organized into a multi-threaded connection pool. See the redis.pool parameters below.
Troubleshooting: If VoiceXML Connector reports a redis response timeout error, set redis.pool.keep_alive to true.
General troubleshooting: if you detect any problem with the Redis server, a first course of action is to decrease the value of sessionTimeoutin the application's start request.
Dialog service configuration
Required. Configure the Dialog service in the VoiceXML Connector deployment.
Parameter |
Description |
---|---|
grpc.client.dlgaas.address |
Location of one or more Dialog services or proxy servers. When there is more than one address, VoiceXML Connector automatically balances sessions in round-robin style.
Allowed address formats: static:///<ip>:<port> dns:///<hostname>:<port> |
grpc.client.dlgaas.negotionType | Values: TLS or PLAINTEXT |
grpc.client.dlgaas.customHeaders |
Optional. Enables addition of any HTTP headers that might be needed by the Dialog service. The value is a comma-separated list of key:value pairs enclosed in {braces}. For example, the headers could indicate whether incoming calls are part of a staging or production system: customHeaders: {x-temp-app-id: Staging} customHeaders: {x-temp-app-id: Production} |
grpc.client.dlgaas.enableClientRequestId |
Optional. For the NVP browser only, ensures that VoiceXML Connector and the Dialog service use the same ID in their log files. Default:
dlgaas: enableClientRequestId: false |
Recommended. Deploy the CCSS component and a URN configuration for the artifact server with the Dialog service. At runtime, your IVR application sends dialogModelRef in the start request to VoiceXML Connector (see Start request). The value is the name or location (a URN or URL) of the web server where Mix artifacts are deployed. Nuance recommends using URNs because they isolate applications from the physical topography of your network.
To access the Dialog service via a proxy:
-
Set
mix.proxy.proxyEnabled
to true. -
Set
mix.proxy.host
andmix.proxy.port
to relevant values. -
For the proxy credentials, set
proxy-user
andproxy-password
.For Tomcat deployments, set the properties in the application.yaml file.
For Helm deployments, create a secret named
vxmlconnector-proxy
, and set the properties. Replace this example with your own secret:```yaml
apiVersion: v1
kind: Secret
type: Opaque
metadata:
name: vxmlconnector-proxy
data:
proxy-user: dXNlcg==
proxy-password: cGFzc3dvcmQ=
```
Authentication configuration
Required. If your Mix dialog model enables authentication (required when using the neural TTS solution), you must configure authentication in the VoiceXML Connector deployment. Otherwise, disable authentication:
Parameter | Description |
---|---|
mix.authEnabled
|
Enables authentication in the Connector. Set in the deployment configuration (Helm or Tomcat). NOTE: You must disable if not using authentication. |
mix.Auth
|
URL for OAuth authentication. Set in the deployment configuration (Helm or Tomcat). |
mix.ClientId
|
The Mix client ID. Can be overwritten in your IVR application's Start request. Define the value in the Mix dashboard when implementing the dialog. |
mix.Secret
|
The Mix client secret. Can be overwritten in your IVR application's Start request. Define the value in the Mix dashboard when implementing the dialog. |
If you are self-hosting the Dialog service, you probably do not require authentication because your clients and servers belong to the same Kubernetes cluster.
Optional. You can tune the performance of a cache where VoiceXML Connector stores authentication tokens.
Parameters | Description (all timers are in seconds) |
---|---|
timerTaskDelay
|
Delays start of the tuning jobs. Use this to reduce load during system initialization. For example, 60 (1 minute). |
clearTokenTaskInterval
|
How often to remove unused tokens. For example, 300 (5 minutes). |
refreshTokenTaskInterval
|
How often to refresh tokens. For example, 120 (2 minutes). |
refreshTokenBufferTime
|
Determines which tokens to refresh. It refreshes tokens whose remaining life expires sooner than this property value. For example, 180 (3 minutes). |
idleTimeToClearTokenCache
|
Determines which tokens to remove. It removes unused tokens when their client applications are idle longer than this property value. For example, 900 (15 minutes). |
Microsoft Neural TTS configuration
On your behalf, Nuance sets these parameters in hosted environments when applications use the neural TTS solution.
Parameter | Description |
---|---|
tts.neuralTtsEnabled: false
|
Specifies whether Neural TTS is enabled or disabled. |
tts.neuralTtsUrl
|
Specifies the URL of the middleware service for the neural text-to-speech solution. (See Nuance-hosted deployment.) Example: ' Best practices:
|
tts.promptConcatenationEnabled
|
Specifies whether VXML Connector concatenates messages when Neural TTS has multiple messages between nodes. When set to the default |
Troubleshooting:
-
Nuance configures a URL connection between VoiceXML Connector and NTM. Without this configuration, any attempt to use neural TTS fails with an exception, and the dialog teminates.
-
Once the URL configuration is created, VoiceXML Connector reports any NTM or neural TTS errors to your application, and uses Vocalizer as a fallback TTS engine if neural TTS is unavailable.
IVR platform configuration
These parameters relate to components of the IVR platform.
Most VoiceXML Connector deployments store documents such (as audio files for the text-to-speech engine, and grammars for the recognizer) on an application server. To configure access, define the base URL locations. VoiceXML Connector adds the URL prefix to filepaths provided in the Mix dialog model.
Parameter | Description |
---|---|
adjustConfidenceOne
|
Converts confidence scores of 1 to 0.01. This is not a conversation of ranges. It is an explicit change of the value "1" to "0.01" to address an edge-case scenario. Enable this parameter if you detect a problem where the IVR platform returns a confidence score of 1 to your VoiceXML application when the actual Dragon Voice recognition result is very low confidence. For example, this problem might occur on Cisco-based IVR platforms. |
|
Base URL for recorded audio files. The default is a dummy value that must be replaced. Example: ` |
application:
dtmfAvayaEnabled: false
|
Required for the Avaya IVR platform to ensure correct DTMF syntax. Otherwise, must be false. |
application.grammar_base_url
|
Base URL for grxml grammar files. The default is a dummy value that must be replaced. Example: ` |
application.backend_base_url
|
Base URL for middleware calls executed from VXML connector. The default is a dummy value that must be replaced.. Example: ` |
docType.docString
|
Specifies a vxml DOCTYPE definition, which is required by some voice browsers. By default, docString is disabled and has a sample value that works with Nuance Platform Add-on. docType: Enabled: false docString: <!DOCTYPE vxml PUBLIC "-//Nuance/DTD VoiceXML 2.0//EN" "http://voicexml.nuance.com/dtd/nuancevoicexml-2-0.dtd"> When you enable docType, you must provide a docString value. |
voicebrowser.type
|
Specifies your deployed browser. (When you change this property, VoiceXML Connector might change the default value of other properties for optimal performance.) Values:
|
Optional. Speech Suite has features to prevent confidential data from appearing in logs and other locations. Set these features via the vxml:securityLevelProperties properties. See the Speech Suite documentation for details.
Java performance configuration
Optional. Modify Java performance default settings.
VoiceXML Connector instances are tested to handle 127 requests per second concurrently with default settings and a resource limit of 4 CPU and 4 GB storage. The service uses standard OpenJDK 11 settings for heap usage by default. You can override the values by modifying the java_options
setting. For example:
java_options: -XX:MaxRAMPercentage=50 -XX:G1ReservePercent=20 -XX:ConcGCThreads=2
Monitoring, alerts, and metrics
Recommended. Use an EFK stack to collect, store, and display diagnostic log messages. Configure the stack to collect from stdout and stderr.
VoiceXML Connector provides metrics endpoints for the service and the Envoy front end. Configure the endpoints in the Helm chart under service.metrics and service.metrics_envoy.
-
Use Prometheus to monitor system runtime performance, detect fatal alarms, and collect push metrics.
-
Use Grafana to collect and analyze metrics. To acquire metrics, you must configure the system.
-
Use Jaegar for detailed tracing and troubleshooting.
To disable the ServiceMonitor, set servicemonitor.enabled
to false. Disabling is not recommended unless you have an alternative for monitoring the deployed pods.
vxmlconnector
To acquire metrics in Prometheus format, use this endpoint:
port name | port | path |
---|---|---|
metrics | 8080 | /vxml-connector/actuator/prometheus |
The exported labels can change in future releases: This is not a complete list:
- default spring gRPC metrics (for details see spring boot starter)
- Counter
- grpc.client.requests.sent
- grpc.server.responses.received
- grpc.client.requests.received
- grpc.server.responses.sent
- Timer
- grpc.client.processing.duration
- grpc.server.processing.duration
- Counter
- custom metrics
- Counter
- redis.query
- client.backend
speechSuiteException (shows alerts generated by Speech Suite)
- Counter
When Prometheus reports "unavailable", check the diagnostic logs for possible issues.
vxmlconnector-envoy
To acquire metrics in Prometheus format, use this endpoint:
port name | port | path |
---|---|---|
envoy-admin | 8080 | /vxml-connector/stats/prometheus |
The metrics exported are:
- default envoy metrics
- envoy.server.initialization.time.ms
- envoy.cluster.external.upstream.rq.time
- envoy.cluster.upstream.cx.length_ms
- envoy.cluster.upstream.rq.time
- envoy.http.downstream.cx.length.ms
- envoy.http.downstream.rq.time
- envoy.listener.downstream_cx_length_ms
- (many more)
OTEL Collector configuration
The OpenTelemetry Collector is disabled by default. To use it:
- Enable the OTEL Collector. Example:
otelCollector:
enabled: true
endpoint: http://localhost:4317/v1/traces - Required. A configMap named services-otlp must exist. The helm chart has a preconfigured configMap: you must add the Otel Collector configuration:
apiVersion: v1
kind: ConfigMap
metadata:
name: services-otlp
labels:
app: opentelemetry
data:
otel-collector-config: |
OTEL COLLECTOR CONFIGURATION - see manual for opentelemetry
Configuration parameters
You can customize the deployment configuration with an application.yaml added to your Helm configuration.
Additional parameters
Property | Description |
---|---|
application.dlm_weight
|
Default weight of the Domain language model (DLM) when the value is not set in the Dialog service. Default: 0.5 |
application.sessionTimeout
|
Maximum session idle time (seconds) for the Dialog service. Applies to Redis sessions/profile only; does not affect HTTP sessions. Can be overridden at session start, see Start request. Default: 900 (15 minutes) |
mix.authEnabled
|
Authentication for the mix application. The default is true . |
mix.auth
|
Mix Auth server URL. The default is https://auth.crt.nuance.com/oauth2/token . |
docType.enabled
|
Adds the doctype string to the start of the VoiceXML page delivered to Speech Suite. Default: |
docType.docString
|
The doctype string to be added the the VoiceXML page. Default: |
grpc.client.GLOBAL.negotiationType
|
Negotiation type for the gRPC client. The default is PLAINTEXT . |
grpc.client.dlgaas.address
|
Location of one or more Dialog services or proxy servers. When there is more than one address, VoiceXML Connector automatically balances sessions in round-robin style.
Allowed address formats: static:///<ip>:<port> dns:///<hostname>:<port> |
grpc.client.dlgaas.enableRetry
|
Enable retries on the communication channel with DLGaaS. Allowing retries allows the channel to resolve interruptions without sending exceptions to the VoiceXML Connector and your client application. Defaut: true. |
grpc.client.dlgaas.idleTimeout
|
Set the duration of idle time before entering idle mode on the communications channel. The purpose of idle mode is to minimize unneeded resources by shutting down all connections on the channel. Channels begin in idle mode, they become active upon receipt of the first runtime procedure call, and they re-enter idle mode if the idleTimeout timer expires. Default: 1 minute. |
grpc.client.dlgaas.enableKeepAlive
|
Keep alive the communication channel with DLGaaS. The default is true . |
grpc.client.dlgaas.keepAliveWithoutCalls
|
Keep alive the communication channel even if there are no calls. The default is true . |
grpc.client.dlgaas.keepAliveTimeout
|
Timeout for the DLGaaS keepAlive. The default is 20 . |
grpc.client.dlgaas.negotiationType
|
Negotiation type for the gRPC communication with DLGaaS. The default is TLS . |
grpc.client.dlgaas.sessionCookieMaxAge
|
Seconds until the NuanceSessionId cookie expires.
|
grpc.client.dlgaas.sessionCookieSecure
|
Accept the NuanceSessionId cookie through HTTPS only. The default is This property is ignored when sessionCookieMaxAge is |
tts.promptConcatenationEnabled
|
Specifies whether VXML Connector concatenates messages between nodes. Default is |
vxml.defaultVxmlProperties.confidencelevel
|
Speech recognition confidence. Level from 0 (min) to 1 (max). The default is 0 . |
vxml.defaultVxmlProperties.sensitivity
|
Sensitivity of speech. Level from 0.0 (least) to 1.0 (high). The default is 0.5 . |
vxml.defaultVxmlProperties.speedvsaccuracy
|
Desired balance of recognition latency versus accuracy. Values from 0.0 (fastest) to 1.0 . The default is 0.5 . |
vxml.defaultVxmlProperties.completetimeout
|
Duration of silence to define end-of-speech when the already-collected speech is a complete match of the grammars and no further words can be spoken. Default is 0s . |
vxml.defaultVxmlProperties.incompletetimeout
|
Duration of silence to define end-of-speech when the already-collected speech is a partial match of the grammars and it is possible to speak further. Default is 500ms . |
vxml.defaultVxmlProperties.maxspeechtimeout
|
Maximum duration of user speech. If expired, the maxspeechtimeout event is thrown. Default is 2000ms . |
vxml.defaultVxmlProperties.interdigittimeout
|
Time allowed between each DTMF digit. Default is 5000ms . |
vxml.defaultVxmlProperties.termtimeout
|
Time allowed for DTMF input. Default is 0s . |
vxml.defaultVxmlProperties.termchar
|
Terminating DTMF character for DTMF input. Default is # (the hash or pound symbol). |
vxml.defaultVxmlProperties.bargein
|
Enables user input to interrupt while prompts are playing. Default is true . |
vxml.defaultVxmlProperties.bargeintype
|
Bargein with any speech or a hotword. Values: speech (default), hotword |
vxml.defaultVxmlProperties.timeout
|
Time to wait for user input after prompt finishes. If expired, the noinput event is thrown. Default is 7000ms . |
vxml.defaultVxmlProperties.audiofetchhint
|
When to fetch audio files. Values: prefetch (when page loaded, default). safe (only when needed) |
vxml.defaultVxmlProperties.audiomaxage
|
Maximum age of cached audio resources. Default is 86400 . |
vxml.defaultVxmlProperties.audiomaxstale
|
Maximum staleness of expired cached audio resources. Default is 0 . |
vxml.defaultVxmlProperties.documentfetchhint
|
When to fetch the next document. Values: prefetch (default), safe |
vxml.defaultVxmlProperties.documentmaxage
|
Maximum age of cached documents. |
vxml.defaultVxmlProperties.documentmaxstale
|
Maximum staleness of expired cached documents. Default is 0 . |
vxml.defaultVxmlProperties.grammarfetchhint
|
When to fetch grammar files. Values: prefetch , safe |
vxml.defaultVxmlProperties.grammarmaxage
|
Maximum acceptable age of cached grammar resources. |
vxml.defaultVxmlProperties.grammarmaxstale
|
Maximum staleness of expired cached grammar resources. |
vxml.defaultVxmlProperties.objectfetchhint
|
When to fetch objects. Values: prefetch (default), safe |
vxml.defaultVxmlProperties.objectmaxage
|
Maximum acceptable age of cached object resources. Default is 86400 . |
vxml.defaultVxmlProperties.objectmaxstale
|
Maximum staleness of expired cached object resources. Default is 0 . |
vxml.defaultVxmlProperties.scriptfetchhint
|
When to fetch scripts. Values: prefetch (default), safe |
vxml.defaultVxmlProperties.scriptmaxage
|
Maximum acceptable age of cached script resources. Default is 86400 . |
vxml.defaultVxmlProperties.scriptmaxstale
|
Maximum staleness of expired cached script resources. Default is 0 . |
vxml.defaultVxmlProperties.fetchaudiodelay
|
Time to wait at the start of a fetch delay before playing fetchaudio. Default is 2000ms . |
vxml.defaultVxmlProperties.fetchaudiominimum
|
Minimum time to play fetchaudio, once started, even if the fetch result arrives in the meantime. Default is 0ms . |
vxml.defaultVxmlProperties.fetchtimeout
|
Timeout for fetches. Default is Alternatively, a different timer is used for server-side data fetching: when a data access node in the dialog executes a latency prompt. In this case, the timeout is the sum of backendConnectionSettings fetchtimeout and backendConnectionSettings connectTimeout in the data access node plus an internal timer of 1000ms (1 second) . |
vxml.defaultVxmlProperties.inputmodes
|
Input mode. Values: Troubleshooting DTMF: If you encounter "DTMF grammar syntax error," your platform is probably configured to recognize DTMF instead of deferring to Nuance Speech Suite. To resolve, change the platform configuration. |
vxml.defaultVxmlProperties.maxnbest
|
Max nbest. Default is 3. |
vxml.security.callerInputLevel.swirec_secure_context
|
Protects confidential data. Applies to caller input only. Values: |
xml.security.applicationLevel.switts_secure_context
|
Protects confidential data in logs of text-to-speech conversions. Relevant for application data in the Speech Suite TTS service. Values: |
vxml.security.callerInputLevel.swirec_mute_wcr |
Replaces confidential data in whole-call recordings with silence. Relevant for caller input data only. Values: |
xml.security.applicationLevel.switts_mute_wcr
|
Replaces confidential data in whole-call recordings with silence. Relevant for application data in the Speech Suite TTS service. Values: |