Jump to: navigation, search

VXML Properties

This page provides details about the properties used to manage platform behavior: Note: Properties apply to their parent tag and all the descendants of the parent. A property at a lower level overrides a property at a higher level. If you already have GVP, note that the properties in defaults-ng.vxml will be (re)set as documented below only when a system is newly installed. If you simply upgrade from a previous release, the old values will be preserved. This means that any manual configuration of defaults-ng.vxml will be saved when you upgrade. It also means that when moving to newer versions in which GVP uses different default values, the defaults will not be reset unless you newly install (rather than upgrade).

Receive External Message

Property Description Default Value
com.genesyslab.

(GVP extension)

This property specifies whether an external message will be received asynchronously. The valid values are:
  • True--If the value equals true, external messages will be received asynchronously.
  • False--If the value equals false, external messages will be received synchronously.
 false
com.genesyslab.

(GVP extension)

This property specifies whether an external message will be queued or discarded. The valid values are:
  • True--If the value equals true, external messages will be queued. The external message is reflected to the application in the application.lastmessage$ variable (an ECMAScript object).
  • False--If the value equals false, external messages will not be delivered as a VoiceXML event (they will be discarded).

Note:If no external messages have been received, application.lastmessage$ is ECMAScript undefined. Only the last received message is available. To preserve a message for future reference during the lifetime of the application, copy the data to an application-scoped variable.

false

Speech Recognizer

Property Description Default Value
confidencelevel Specifies the speech recognition confidence level. Values range from 0.0 (minimum confidence) to 1.0 (maximum confidence). Recognition results are rejected (a nomatch event is thrown) if the confidence level of the results is below this threshold. 0.5
sensitivity Specifies the level of sensitivity to speech. Values range from 0.0 (least sensitive to noise) to 1.0 (highly sensitive to quiet input). 0.5
speedvsaccuracy A hint specifying the desired balance between speed versus accuracy when processing a given utterance. Values range from 0.0 (fastest recognition) to 1.0 (best accuracy).

Note: The Nuance MRCP engine uses the value of the speedvsaccuracy property to set its proprietary rec.Pruning parameter, using the following algorithm: If x is the speedvsaccuracy value, and x <= 0.5 then    rec.Pruning = (x * 400) + 600 else    rec.Pruning = (x * 800) + 400

0.5
completetimeout The length of silence required following user speech before the speech recognizer finalizes a result (either accepting it or throwing a nomatch event). The completetimeout is used when the speech is a complete match of an active grammar and no further words can be spoken. 1s
incompletetimeout The length of silence required following user speech before the speech recognizer finalizes a result (by either accepting it or throwing a nomatch event). In contrast to completetimeout, the incompletetimeout is used when the speech is an incomplete match to an active grammar, or when the speech is a match but it is possible to speak further. 1s
maxspeechtimeout The maximum duration of user speech. If this time elapses before the user stops speaking, the maxspeechtimeout event is thrown.   Note: Refer to your ASR engine documentation for support details. 60s
Maximum number of results returned by the recognizer. Also represents the maximum size of the application.lastresult$ array. 1

DTMF Recognizer

Property Description Default Value
interdigittimeout The timeout period allowed between each digit when recognizing DTMF input. 3s
termtimeout The terminating timeout to use when recognizing DTMF input. 0s
termchar The terminating DTMF character for DTMF input recognition. #
com.genesyslab.dtmf.offboard_recognition

(GVP extension)

This property makes it possible to use the DTMF Recognizer that comes with your ASR Engine instead of using the one provided by Genesys. The valid values are:
  • True--If the value equals true, offboard DTMF recognition is enabled for the call.
  • False--If the value equals false, offboard DTMF recognition is disabled for the call.

Notes:

  • If the value is invalid, an error.semantic will be thrown.
  • The recognizer will use the engine specified by the ASR engine property.
  • If you switch between external engines in mid call, any buffered digits will be lost.
Important
Changes to this setting after the first input in an application session will not have any effect.
 False

Prompt and Collect

Property Description Default Value
inputmodes Determines which input methods to use. Value is a space separated list of input methods:
  • dtmf--allows DTMF sequences as input
  • voice--allows voice as input
 dtmf voice
timeout Once the prompt has finished playing, the length of time to wait, if no speech or dtmf input occurs, before throwing a noinput event. 10s
universals Specifies universal command grammars to activate.  Value is a space-separated list of all or fewer of the following command grammars:
  • cancel--If this grammar is activated, and the caller says "cancel" (or equivalent phrase configured for another language), the cancel event is thrown.
  • exit--If this grammar is activated, and the caller says "exit" (or equivalent phrase configured for another language), the exit event is thrown.
  • help--If this grammar is activated, and the caller says "help" (or equivalent phrase configured for another language), the help event is thrown.

A setting of none disables universal commands.  A setting of all can be used as a short form for activating all 3 command grammars.

none
com.genesyslab.asrengine

(GVP extension)

Specifies the name of the ASR (Automatic Speech Recognition) engine to use. For details about available names, consult with your platform administrator.

Note: If this property is not specified, the per call configuration value specified in the vxmli.asr.defaultengine property (see the Genesys Voice Platform 8.1 Configuration Options Reference) will be used. The default is empty string (""). Note: It is valid to specify a particular engine only if that engine is installed for the platform running the application. Otherwise, an error.asr.unknownengine event will be thrown. Note: The configured name for SpeechWorks OSR must be speechworks, otherwise a recognition error will occur.

platform-specific
com.genesyslab.ttsengine

(GVP extension)

Specifies the name of the TTS (Text-to-Speech) engine to use (that is, the voice). For details about available names, consult with your platform administrator.

Note: If this property is not specified, the per call configuration value specified in the vxmli.asr.defaultengine property  (see the Genesys Voice Platform 8.1 Configuration Options Reference) will be used. Note: It is valid to specify a particular engine only if that engine is installed for the platform running the application. Otherwise, an error.tts.unknownengine event will be thrown.

platform-specific
com.genesyslab.endbeep

(GVP extension)

Specifies whether a beep should be played at the end of prompts in fields, when bargein is disabled. When bargein is enabled, this attribute has no effect (there is never a beep). Platform owners can access the audio file (endofprompt.vox) in the configured audio path. false
com.genesyslab.utterancedest

(GVP extension)

Specifies the path of the directory to use for saved utterance audio files. The value will be resolved to the configured audio path. This property can be used with the recordutterance property. Note: If you specify the utterancedest and enable the savetmpfiles property, the utterance will only be saved under the utterancedest path. It will not also be saved with the other tmp files. files are written to the tmp directory (may or may not be saved, depending on whether the savetmpfiles property is enabled)
recordutterance

(VoiceXML 2.1 feature)

This property tells the platform to enable recording while simultaneously gathering input from the user. Set to true to enable user utterance to be recorded. Set to false otherwise. Upon completion of user input, the recording shadow variable will be set.   Note: The <vxml> version attribute must be specified as 2.1 (or higher) to use this property. Note: If the recordutterance property has been specified in a VoiceXML 2.0 page, it will behave as if it is a VoiceXML 2.1 page. false
recordutterancetype

(VoiceXML 2.1 feature)

This property specifies the audio format to use for recording utterances. Only used with the recordutterance property. GVP currently supports the following types:
  • audio/basic--Raw (headerless) 8kHz 8-bit mono mu-law [PCM] single channel. (G.711)
  • audio/x-alaw-basic--Raw (headerless) 8kHz 8-bit mono A-law [PCM] single channel. (G.711)
  • audio/x-wav--WAV (RIFF header) 8kHz 8-bit mono mu-law [PCM] single channel.
  • audio/x-wav--WAV (RIFF header) 8kHz 8-bit mono A-law [PCM] single channel.
 audio/basic
com.genesyslab.asr.get_swi_literaltimings

(GVP extension)

Set to true to allow the special OSR variable, SWI_literalTimings, to be accessed through the application.lastresult$ variable. Requires com.genesyslab.fieldobject to be set to true.  Available with SpeechWorks ASR only. false
com.genesyslab.tts.<Your vendor specific name>

(GVP extension)

Users will be able to define TTS vendor-specific global properties in the Entry block. The exact set of property names is not known to Composer and therefore no validations will be performed on the names. The general format of these properties will follow this pattern: com.genesyslab.tts.<property_name>  
com.genesyslab.asr.<Your vendor specific name>

(GVP extension)

When using GVP's MRCP direct integration with an ASR engine, the VoiceXML application can use this property format to specify arbitrary vendor-specific parameters to be sent to the ASR engine.

In the property name, <Your vendor specific name> is replaced with the actual vendor-specific parameter name; and the value of the property must be a valid value for that vendor-specific parameter. For example, to set Nuance's rec.GrammarWeight parameter to 10: <property name="com.genesyslab.asr.rec.GrammarWeight" value="10"/> Notes:

  • Vendor parameter names and values could be case-sensitive. Refer to the vendor documentation to ensure you are using valid names and values.
  • You can only set a vendor parameter using <property> if the parameter can be set by the ASR engine at runtime. Refer to the vendor documentation to confirm which parameters are runtime-settable.
  • Once a vendor parameter is set using <property>, the setting will stay in effect for the remainder of the call, unless it is set again later in the VoiceXML application.
 parameter-specific
swiep_*/swirec_*

(GVP extension)

Many of OSR's swiep_*/swirec_* configuration parameters can also be set as VoiceXML properties.

To find out whether a particular parameter can be set as a property, look it up in the OSR Reference Manual. If the line under the parameter name includes "API" (and if the description mentions SWIepSetParameter() or SWIrecRecognizerSetParameter()), then it can be set as a property. Some of the parameters that are commonly used are:

  • swirec_suppress_event_logging
  • swirec_suppress_waveform_logging
  • swirec_audio_environment (OSR 2.0+ only)
  • swirec_backward_compatible_confidence_scores (OSR 2.0+ only)

See the OSR Reference Manual for details about the values/usage for each parameter. These properties are specific to Nuance OSR, and are only supported in GVP's MRCP native integration with OSR.  (They are not supported in GVP's MRCP direct integration with OSR, using SWMS.)

parameter-specific
com.genesyslab.logtoasr

  (GVP extension)

If set to true, this will enable GVP to log data directly to the ASR engine's log. Note: If this property is true, then the <log> tag's level attribute is ignored. true

Prompt and Collect--Barge-in

GVP supports Recognition Based Barge-in.

Property Description Default Value
bargein Controls whether user input can be collected before prompts have finished playing:
  • true--Any user input can barge in during prompts.
  • false--No user input can barge in during prompts.
 true
bargeinype Specifies the bargein type:
  • speech--Any user utterance can barge in the prompt.
  • hotword (equivalent to recognition)--Only user input that matches a grammar can barge in on the prompt.

Note: Not all bargeintypes are supported with all ASR engines.

speech

MARK Tag

Composer and GVP support the use of the MARK tag from the VXML Specs to detect whether or not a barge-in was detected. The Mark tag in VXML is used to set the place in a sequence of prompts and can be used to detect the barge-in position during the playback of prompts.

As described in the GVP 8.1 Legacy Genesys VoiceXML 2.1 Reference Manual, the variable application.lastresult$ is a read-only session variable that holds information about the last recognition to occur within this application. Additionally, application.lastresult$[i] provides the ability to use an array of tags when using N-best recognition.

Prompt and Collect--Wakeup Word Spotting Recognition Mode

In GVP's MRCP native integration with Nuance OSR, OSR's "magic word" feature is exposed through the following properties.

Property Description Default Value
com.genesyslab.wakeupword

(GVP extension)

Specifies whether Wakeup Word Spotting should be used for input in fields, menus, and initials.  If set to true, recognition is only performed if input length is between a minimum and maximum length, and (only with Nuance OSR 2.0+) if input matches a grammar. false
com.genesyslab.wakeupwordminimum

(GVP extension)

If com.genesyslab.wakeupword is set to true, this specifies the minimum length that input must be in order for recognition to be performed.  
com.genesyslab.wakeupwordmaximum

(GVP extension)

If com.genesyslab.wakeupword is set to true, this specifies the maximum length that input may be in order for recognition to be performed.  

Prompt and Collect--Magic Word / Selective Barge-in Recognition Modes

With Nuance SWMS 3.1.4+, OSR's "magic word" and "selective barge-in" features are exposed through the following properties. GVP does not have default values for the following properties. If the application specifies them, GVP passes the specified values through to SWMS. Otherwise, GVP does not pass anything to SWMS - in which case, SWMS would use its own default settings (see the SWMS documentation for these details).

Property Description Default Value
com.genesyslab.ASR.Recognition-Mode

(GVP extension)

Set to hotword to enable the OSR selective barge-in or magic word recognition mode:
  • Selective Barge-in--Only user input that matches a grammar can barge in on the prompt.  (This mode is enabled if com.genesyslab.ASR.Hotword-Max-Duration is set to 0.) 
  • Magic Word--Only user input that matches a grammar, and whose duration is between a minimum and maximum length, can barge in on the prompt.  (The minimum and maximum utterance lengths are specified by com.genesyslab.asr.Hotword-Min-Duration and com.genesyslab.asr.Hotword-Max-Duration.)

For example: <property name="com.genesyslab.asr.Recognition-Mode" value=""hotword""/> Note: After setting this property, the specified mode will remain in effect for all subsequent recognitions (even if the property is not set in subsequent input fields), unless a new mode is explicitly set. So, to switch back to normal recognition mode after using one of the above hotword modes, the application must explicitly set this property back to normal (and not set any of the three related properties listed below).  For example: <property name="com.genesyslab.asr.Recognition-Mode" value=""normal""/> (Available with Nuance SWMS 3.1.4+ only.)

 
com.genesyslab.asr.Hotword-Min-Duration

(GVP extension)

If com.genesyslab.asr.Recognition-Mode is set to hotword, this specifies the minimum length (in ms) that input must be in order for recognition to be performed.  For example:

<property name="com.genesyslab.asr.Hotword-Min-Duration" value=""50""/> If com.genesyslab.asr.Hotword-Max-Duration is set to 0, this property will be ignored.

 
com.genesyslab.asr.Hotword-Max-Duration

(GVP extension)

If com.genesyslab.asr.Recognition-Mode is set to hotword, this specifies the maximum length (in ms) that input may be in order for recognition to be performed.  For example:

<property name="com.genesyslab.asr.Hotword-Max-Duration" value=""2000""/> If this property is set to 0, the OSR selective barge-in mode will be enabled (for example, no minimum and maximum duration constraints are used, so com.genesyslab.asr.Hotword-Min-Duration will be ignored).  Otherwise, the OSR magic word mode will be enabled (for example, the minimum and maximum duration constraints specified by com.genesyslab.asr.Hotword-Min-Duration and com.genesyslab.asr.Hotword-Max-Duration will be used).  

 
com.genesyslab.asr.Hotword-Confidence-Threshold

(GVP extension)

If com.genesyslab.asr.Recognition-Mode is set to hotword, this specifies the speech recognition confidence level that should be used. Values range from 0 (minimum confidence) to 1000 (maximum confidence). Recognition results are rejected (a nomatch event is thrown) if the confidence level of the results is below this threshold.

For this property to take effect, you must also set the standard confidencelevel property to an equivalent decimal percentage. For example: <property name="com.genesyslab.asr.Hotword-Confidence-Threshold" value=""100""/> <property name="confidencelevel" value="0.1"/>

 

Fetching

Property Description Default Value
audiofetchhint Defines when audio files can be fetched:
  • prefetch--audio file may be downloaded when the page is loaded
  • safe--only load the audio file when needed

Currently, all audio is fetched when needed.

prefetch
audiomaxage Defines maximum acceptable age, in seconds, of cached audio resources. undefined
audiomaxstale Defines maximum staleness, in seconds, of expired cached audio resources. undefined
datafetchhint Defines when XML data files can be fetched:
  • safe--only load the XML data file when needed

Currently, all data files are fetched when needed.

safe
datamaxage Defines maximum acceptable age, in seconds, of cached XML resources. undefined
datamaxstale Defines maximum staleness, in seconds, of expired cached XML resources. undefined
documentfetchhint Defines when next document can be fetched:
  • safe--only load the next document when needed

Currently, all documents are fetched when needed.

safe
documentmaxage Defines maximum acceptable age, in seconds, of cached documents. undefined
documentmaxstale Defines maximum staleness, in seconds, of expired cached documents. undefined
grammarfetchhint Defines when grammar files can be fetched:
  • prefetch--grammar file may be downloaded when the page is loaded
  • safe--only load the grammar file when needed

Currently, all grammars are fetched when needed.

prefetch
grammarmaxage Defines maximum acceptable age, in seconds, of cached grammar resources.

SpeechWorks OSR 1.x does not support this.

undefined
grammarmaxstale Defines maximum staleness, in seconds, of expired cached grammar resources.

SpeechWorks OSR 1.x does not support this.

undefined
objectfetchhint Defines when objects can be fetched:
  • prefetch--object may be downloaded when the page is loaded
  • safe--only load the object when needed
 prefetch
objectmaxage Defines maximum acceptable age, in seconds, of cached object resources. undefined
objectmaxstale Defines maximum staleness, in seconds, of expired cached object resources. undefined
scriptfetchhint Defines when scripts can be fetched:
  • prefetch--script may be downloaded when the page is loaded
  • safe--only load the script when needed

Currently, all scripts are fetched when needed.

prefetch
scriptmaxage Defines maximum acceptable age, in seconds, of cached script resources. undefined
scriptmaxstale Defines maximum staleness, in seconds, of expired cached script resources. undefined
fetchaudio The URI of audio to play while waiting for documents to be fetched. builtin:background_audio.wav
fetchaudiodelay The length of time to wait at the start of a fetch delay before playing fetchaudio. 1s
fetchaudiominimum The minimum length of time to play fetchaudio, once started, even if the fetch result arrives in the meantime. 0s
fetchtimeout Timeout for fetches.  This is not supported when using Nuance(MRCP). An error.badfetch is thrown when a fetch duration exceeds fetchtimeout. 30s

Audio Control

The Audio Control Feature is an extension to VoiceXML. Note: Audio control functions are only applied to the currently playing prompt, and not across the queued prompt list. Note: These properties may not work properly for TTS. <tbody></tbody>

Property Description Default Value
com.genesyslab.noaudiocontrol

(GVP extension)

If this property is set (to any value), the com.genesyslab.audiocontrol property is disabled. undefined
com.genesyslab.audiocontrol

(GVP extension)

(Only used if com.genesyslab.noaudiocontrol is undefined.) Set to true to enable Audio Control during playing of audio. Set to false to disable the feature. true
com.genesyslab.audio.skipduration

(GVP extension)

Sets the duration of audio to be skipped when using the skipahead/skipback features. Note: Time units (s or ms) must be provided. 6000ms
com.genesyslab.audio.skipahead

(GVP extension)

Sets the DTMF button for skipping ahead in the audio file/TTS. The duration skipped depends on the value of the com.genesyslab.audio.skipduration property. If set to "-" or undefined, this feature is disabled. undefined
com.genesyslab.audio.skipback

(GVP extension)

Sets the DTMF button for rewinding the audio file/TTS. The duration rewound depends on the value of the com.genesyslab.audio.skipduration property. If set to - or undefined, this feature is disabled. undefined
com.genesyslab.audio.louder

(GVP extension)

Sets the DTMF button for turning volume up. If set to - or undefined, this feature is disabled. This is not supported with VoIP. undefined
com.genesyslab.audio.softer

(GVP extension)

Sets the DTMF button for turning volume down. If set to - or undefined, this feature is disabled. This is not supported with VoIP. undefined
com.genesyslab.audio.pause

(GVP extension)

Sets the DTMF button for pausing playback temporarily, until the pause button is pressed a second time. If set to- or undefined, this feature is disabled. undefined
com.genesyslab.audio.stop

(GVP extension)

Sets the DTMF button for stopping all queued audio playback. If set to - or undefined, this feature is disabled. undefined
com.genesyslab.audio.next

(GVP extension)

Sets the DTMF button for interrupting the current audio playback, and starting the next audio playback in the queue. If set to - or undefined, this feature is disabled. undefined
com.genesyslab.audio.faster

(GVP extension)

Sets the DTMF button for increasing the rate of audio playback. If set to - or undefined, this feature is disabled.

This is not supported with VoIP.

undefined
com.genesyslab.audio.slower

(GVP extension)

Sets the DTMF button for decreasing the rate of audio playback. If set to - or undefined, this feature is disabled.

This is not supported with VoIP.

undefined

Miscellaneous

Property Description Default Value
com.genesyslab.loglevel

(GVP extension)

The loglevel limits execution of <log> tags to the ones whose level attribute have a value up to (including) the loglevel value. 1
com.genesyslab.private This property enables data masking. This means that private data like credit card numbers, social insurance numbers, and so on are converted to asterisks (for example, 123 would be converted to ***). The valid values are:
  • True--If com.genesyslab. equals true, data masking is enabled. The data that is masked includes: - asr_trace (result) - dtmf (digit) - input_end (phrase) - prompt _play (all) - subdialog_start (param_value and URL query string) - eval_cond - eval_expr (expression and value) - eval_var (expression and value) - submit (namelist and URL query string) - link (URL query string) - parse_error (URL query string) - wf_arrived (URL query string) - wf_lookup (URL query string) - event_handler_enter (URL query string) - filling (value) - filled_enter (namelist)
  • False--If com.genesyslab. equals false, data masking is not enabled.

Note: The default value is false. Note: This attribute is overridden by the gvp:private attribute (in the <block>, <field>, <transfer>, <record>, <subdialog>, and <initial> tags).

 

Platform

The following properties are specific to GVP.  The first three are useful for debugging purposes.

Property Description Default Value
com.genesyslab.maintainer.sendwhen This property indicates if the maintainer email message should be sent. Valid values are: always, never, on_message. on_message
com.genesyslab.savetmpfiles The value is interpreted as a string with a list of words.  The words may be: all, none, prompts, inputs, pages, recordings.  When a list of keywords is specified, the superset of all the keywords are saved.  In particular, this means if someone specifies <property name= "com.genesyslab.savetmpfiles"  value="none inputs" /> it is equivalent to specifying <property name= "com.genesyslab.savetmpfiles"  value="inputs"/>.    none
com.genesyslab.savetmpfilesmode This property two valid values:immediate or delayed. This property only takes effect when com.genesyslab.savetmpfiles is enabled. If set to immediate the files are written to disk immediately. If set to delayed the files are stored in memory. immediate
com.genesyslab.onexit.keeptmpfiles This property specifies whether or not keep temp files around after the VoiceXML session has ended. This property will only have meaning if at least one temp files has been saved. If this value is false, all temp files on the disk will be erased, and any files in memory will be discarded. If this value is true, all temp files on disk will be kept, and files in memory will be flushed to disk. true
com.genesyslab.maxrecordtime Defines the default (also the upper limit) for the maxtime attribute of the <record> tag. 10 minutes

Order of Precedence

To find the property value that will take effect at a particular point in an application, the current form item is checked first (to see if the property is defined there), and enclosing scopes are checked as necessary. Here is the full order of precedence for properties:

  1. First, look for a property in the current form item (for example, in <field>, <record>, <transfer>, and so on.). If found, use its value.
  2. If not found, check the current form (for example, lookdirectly under <form> or <menu>). If the property is found, use its value.
  3. If not found, check the current document (for example, look directly under <vxml>). If the property is found, use its value.
  4. If not found, check the current document's application root document (if specified by <vxml application="..."> in the current document).  If the property is found, use its value.
  5. Finally, if not found in any of the above, use the setting from the interpreter context for the current call, which includes the settings in the defaults file (for example, defaults.vxml) and hard-coded default values that are used if no value is configured anywhere else.
This page was last edited on February 2, 2021, at 07:47.
Comments or questions about this documentation? Contact us for support!