Configuring Tomcat deployments
To customize a Tomcat deployment, load an application.yaml file when you start the Connector.
Note: The download package includes sample YAML files that you can modify after extracting the WAR file. For example, modify \webapps\vxml-connector\WEB-INF\classes\application.yml
(do not move this file to a different location).
Some customization is required. Review this topic, decide what is needed, and then do the following:
- Prepare the configurations and store the yaml file in the Tomcat /lib/config/ folder.
- Restart Tomcat to automatically apply the configurations.
- To change the configuration at any time in the future, modify the yaml file and restart Tomcat.
Note: If you deploy multiple instances of Tomcat, you'll need an application.yaml for each.
Session configuration
VoiceXML Connector requires session management. By default the VXML browser stores all state information in the http session it establishes with VoiceXML Connector. Alternatively, you can deploy a Redis server to manage session information. Configure one of these:
Session storage | Description |
---|---|
HTTP |
Default. The http connection between the voice browser and the Connector stores session data. Good solution for most use cases, and especially useful for initial installation and proof of concept deployments. Requires additional configuration to run more than one instance of VoiceXML Connector. Note: There is no support for dynamic entities with http session management. If your Mix dialog uses dynamic wordsets you cannot use http. |
Redis | The Redis server stores all data related to individual sessions. Especially useful for scalable production environments with redundancy for failover scenarios. Requires Redis installation and configuration. See Redis configuration. |
Configuring multiple VoiceXML Connector instances
When you deploy multiple instances of VoiceXML Connector, each session must bind to a single Connector instance: once a session begins on a Connector instance, all subsequent communication for that session must also occur on that instance.
-
If using HTTP session management, deploy a load balance utility (such as Envoy) between the voice browser and the Connector instances, and configure the load balancer to manage “sticky” or persistent sessions. The disadvantage of this architecture is the lack of redundancy: there is no failover when a given Connector instance goes out of service.
-
If using Redis session management, the Redis server stores session data independently of the Connector instances. The voice browser communicates with any session on any instance of the Connector and the Redis server provides the relevant session data. This architecture enables scaling (more Connector instances) and redundancy (any Connector can handle any session).
Redis configuration
A single Redis server can store session data for multiple instances of VoiceXML Connector and Tomcat.
To set up Redis:
-
Deploy a Redis server.
-
Customize the Redis deployment by adding the following to your application-redis.yaml:
redisson:
config: classpath:redisson.yaml
spring:
profiles: redis
-
Configure the server in your redisson.yml (which must be available in the classpath). Define the Redis address (the default is localhost:6379. Optionally, define a Redis password (the default is NULL). For example:
# single redis server for testing
#
singleServerConfig:
address: "${REDIS_ADDRESS:-redis://localhost:6379}"
password: ${REDIS_PASSWORD:-null}
threads: 0
codec: !<com.nuance.coretech.session.redis.CustomJsonJacksonCodec> {}
- Enable the Redis profile. Append the following configuration to the tomcat-path
/bin/setenv
script.-Dspring.profiles.active=redis
-
Restart Tomcat whenever you change the configuration.
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. |
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). |
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.
Log file configuration
By default, all logs are written to the file system. After installation, you can write logs to the console by editing, configuring, and running this script:
Windows: $TOMCAT_PATH/bin/setenv.bat
Linux: $TOMCAT_PATH/bin/setenv.sh
VoiceXML Connector creates a new log every day, and saves previous logs with a filename that includes a date.
File | Description |
---|---|
vxml-connector |
The filename value you provide during installation. After installation, you can change the value with the LOGFILE_NAME parameter. If you install multiple instances of VoiceXML Connector, use a different filename for each instance (so you can distinguish which instances write which logs). For example, |
vxml-connector.log |
The currently active log file. If the file is too large, the Connector moves the content to temporary files named |
vxml-connector-yyyy-mm-dd.log |
Historical logs (concatenated logs from a previous day with an appended date). For example, |
Load balancing and failover
Nuance has no requirements for balancing loads or setting up redundancies to ensure service availability.
Considerations:
- For redundancy, deploy multiple instances of VoiceXML Connector on multiple application containers on the same or different hosts. Optionally, you can also deploy multiple instances of Tomcat.
- At runtime, send Start requests from your IVR application to a load balancer (such as Envoy), which distributes calls across the instances. If an instance of the VoiceXML Connector fails, the balancer automatically sends new Start requests to the next available instance.
- Optional. Send Start requests through a proxy server. This can have advantages for speed, bandwidth, centralized logging, and security.
- With http session management, the IVR application must handle any VoiceXML Connector instance failures that occur after the initial Start request. (The http session cannot be recovered.) For example, upon detecting an interruption the application could apologize to the customer and initiate a new Start request.
- Optional. You can also balance load across multiple instances of the Dialog service. You can set up a proxy server to balance loads on the server side, or specify all Dialog service addresses in the VoiceXML Connector configuration and balance loads with the client application.
service
|
Settings for the main service |
|
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.
-
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)
Jaeger configuration
The Jaeger container is enabled by default. To configure or disable, use the opentracing.jaeger parameter in your application.yml, which appears as follows:
opentracing:
spring:
web:
enabled: true
jaeger:
service-name: vxml-connector
enabled: true
log-spans: false
udpSender:
host: localhost
port: 6831
Configuration parameters
You can override defaults in your Tomcat configuration. To set these parameters, see Log file configuration.
Parameter | Description |
---|---|
LOG_TYPE | The logging output. Values: CONSOLE, FILE (default) |
LOGFILE_PATH |
Folder path for storing all logs. (Only used when LOG_TYPE = FILE.) Default: /var/VXML-CONNECTOR/logs/internal |
LOGFILE_NAME |
Name of the active log. (Only used when LOG_TYPE = FILE.) Default: vxml-connector |
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: |