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:

  1. Prepare the configurations and store the yaml file in the Tomcat /lib/config/ folder.
  2. Restart Tomcat to automatically apply the configurations.
  3. 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:

  1. Deploy a Redis server.

  2. Customize the Redis deployment by adding the following to your application-redis.yaml:

    redisson:
       config: classpath:redisson.yaml
    spring:
       profiles: redis
  3. 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> {}
  4. Enable the Redis profile. Append the following configuration to the tomcat-path/bin/setenv script.
    -Dspring.profiles.active=redis
  5. 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.

  • This example shows a single address. It could be a proxy server (that resolves to multiple Dialog service instances) or an individual Dialog service: 

    grpc.client.dlgaas.address: 
           - dns:///dlg.api.nuance.com:443
  • This example shows multiple addresses. These could be proxy servers or individual Dialog service instances:

    -	address:
           - dns:///dlg.api.nuance.com:443
           - dns:///dlg2.api.nuance.com:444
           - dns:///dlg3.api.nuance.com:445

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:

  grps:

    client:

              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:

  1. Set mix.proxy.proxyEnabled to true.

  2. Set mix.proxy.host and mix.proxy.port to relevant values.

  3. For the proxy credentials, set proxy-user and  proxy-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.

application.audio_base_url

Base URL for recorded audio files. The default is a dummy value that must be replaced.

Example: `http://promptserver:8080`

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: `http://grammarserver:8080`

application.backend_base_url

Base URL for middleware calls executed from VXML connector. The default is a dummy value that must be replaced..

Example: `http://backendserver:8080`

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: 

  • NVP (default). Use this value for Nuance Voice Platform or any other compliant platform.

  • Genesys. Use any version supported by Speech Suite.
  • Cisco. Use any version supported by Speech Suite.

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-1, vxml-connector-2, and so on.)

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-1.log, vxml-connector-yyyy-mm-dd-2.log, and so on.

vxml-connector-yyyy-mm-dd.log

Historical logs (concatenated logs from a previous day with an appended date).

For example, vxml-connector-2021-01-21.log.

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

service:

  isHeadless:true

  type:ClusterIP

vxml_connector:

  port:8080

  nodePort:30100

  name:vxmlconnector

metrics:

  name:metrics

  path:/actuator/prometheus

metrics_envoy:

  name:envoy-admin

  path:/stats/prometheus

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
  • custom metrics
    • Counter
      • redis.query
      • client.backend
      • speechSuiteException (shows alerts generated by Speech Suite)

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: false

docType.docString

The doctype string to be added the the VoiceXML page.

Default: <!DOCTYPE vxml PUBLIC "-//Nuance/DTD VoiceXML 2.0//EN" "http://voicexml.nuance.com/dtd/nuancevoicexml-2-0.dtd">

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.

  • This example shows a single address. It could be a proxy server (that resolves to multiple Dialog service instances) or an individual Dialog service: 

    grpc.client.dlgaas.address: 
           - dns:///dlg.api.nuance.com:443
  • This example shows multiple addresses. These could be proxy servers or individual Dialog service instances:

    -	address:
           - dns:///dlg.api.nuance.com:443
           - dns:///dlg2.api.nuance.com:444
           - dns:///dlg3.api.nuance.com:445

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.

  • The default is 0 (no cookie used).

  • To expire the cookie with the session, use any negative value.

  • When the value is non-zero, the system automatically creates and shares cookies to manage continuity among VoiceXML Connector sessions.

grpc.client.dlgaas.sessionCookieSecure

Accept the NuanceSessionId cookie through HTTPS only. The default is true.

This property is ignored when sessionCookieMaxAge is 0.

tts.promptConcatenationEnabled

Specifies whether concatenates messages between nodes.

Default is true. Change to false to not concatenate.

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 10000ms (10 seconds).

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: voice, dtmf, voice dtmf (default)

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: open, encrypt, suppress (default)

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: open, encrypt, suppress (default)

vxml.security.callerInputLevel.swirec_mute_wcr

Replaces confidential data in whole-call recordings with silence. Relevant for caller input data only. Values:  1 (mute, the default), 0 (unmute)

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:  1 (mute, the default), 0 (unmute)