Event Handling
Overview
Event handling specifies how to proceed within a dialog in the case of any exceptions. In the voice and video channel in particular, various kinds of exceptions may occur during a dialog. Standard events are, for example, No Input - the caller does not respond to a question from the application – or No Match – the utterance cannot be matched to the active grammars. The VoiceObjects platform distinguishes between server-internal and media platform-related events. Server-internal events may occur in all channels, whereas media platform-related events are specific for the voice and video channel. This means that handlers for all platform-related event types will be ignored in the text and Web channel. See Server-Internal vs. Platform Events for more information on this.
Event Levels
Typically, an application will need event handling for the standard events No Match and No Input. For each dialog step, every event can occur never, once, or several times in a row, depending on the caller’s behavior. The Voice User Interface designer needs to define how to react to these events, taking the occurrence level of an event into account. For example, the designer may choose to play the prompt “Excuse me?” for No Match, level 1 (meaning the first occurrence of this event at the current dialog step), and then listen to the caller again. For No Match, level 2, a prompt “I still didn’t understand you” could be played, followed by a context-sensitive message that repeats what the caller can say at that point in the dialog. For the No Input event, similar strategies could be used. If both events occur three or four times in a row at one dialog step, the designer may decide to have the application perform a transfer to a call center agent. Note that the occurrence level of an event is reset when the caller has successfully responded to a question, i.e. when the input state has been exited and the dialog proceeds.
The following dialog flow scenario shows how a voice application might deal with consecutive No Input and No Match events occurring in an input state that asks for the caller’s age:
|
Object - Caller |
Dialog Flow |
|
|
How old are you? |
|
|
[ does not respond within 4 seconds ] |
|
|
[ No Input 1: ] Please tell me your age |
|
|
I... err... my age is twenty. |
|
|
[ No Match 1: ] Excuse me? |
|
|
[ does not respond within 4 seconds ] |
|
|
[ No Input 2: ] Sorry, I still did not hear you. Please say your age, for example ‘twenty-five’, or enter it on your keypad. |
|
|
[ DTMF: ] 2 0 |
|
|
Thank you. |
For detailed information on how to build a sophisticated event handling mechanism including the reprompting functionality, see Chapter 8 – Advanced Event Handling in the Design Guide.
For further information on event handling strategies with respect to aspects of Voice User Interface design also refer to Event Handling Strategies in Appendix A - Voice User Interface Design in the Design Guide.
Inheritance
Event handling can be specified on different levels of your application. Module objects are used to specify global event handling whereas the object-specific events may be set locally on the subordinate objects themselves.
Event handling is inherited starting from the first processed Module object, down through any other Module objects used within the dialog flow, to the current object. If different event handling items are defined for the same event type and occurrence level, the lowest one (i.e. the closest when moving up from the current object) within the dialog flow will be processed.
Inheritance can be disabled in the Options section of the Event Handling definition. When switched off, no event handling items are inherited into the current object but only locally defined ones (if any) are used.
Event Handling Definition
The definition of event handling described in this paragraph refers to VoiceObjects Desktop. For information on how to define event handling using VoiceObjectsXML refer to the VoiceObjectsXML Definition paragraph.
Event Handling can be defined in the Event Handling section of the respective object editors as for instance the Module editor (entered by clicking it in the Outline in Desktop for Eclipse; represented by a tab in Desktop for Web).
In the Event Handling section you can specify the following parameters for each event handling item:
Label
In the Label field, you may optionally enter a label to identify a specific event handling item more easily within a list.
Event type
In the Event type field, select one of the following event types:
|
Event |
Description |
|
ASR – Invalid Answer Limit |
Counts all No Input and No Match events within a single input state and is activated if the caller reaches the defined limit of invalid answers. E.g. if an ASR – Invalid Answer Limit event with occurrence 3 is defined, it will be activated if the caller causes a total of three No Input or No Match events in any combination. Note that if multiple ASR – Invalid Answer Limit events with different occurrence levels are active, only the one with the lowest occurrence is used. |
|
ASR – Max Processing Time |
The caller exceeded the maximum recording or transfer time. Can only be used in Recording and Transfer objects. |
|
ASR – Max Speech Duration |
The caller exceeded the maximum speech time. Can be used in all input state dialog objects except Recording (see Max Processing Time). |
|
ASR – No Input |
The caller did not respond to a request for input within the timeout interval. |
|
ASR – No Input/Match |
A No Input or a No Match event occurred. Using the combined handler has the same effect as defining individual No Input and No Match handlers with the same settings. |
|
ASR – No Match |
The caller said or entered something, but it did not match any of the currently active input grammars. |
|
ASR – No Match (DTMF) |
The caller used DTMF for his last input and typed in DTMF keys that did not match any of the active grammars. |
|
ASR – No Match (Voice) |
The caller used speech for his last input and said something that did not match any of the active grammars. |
|
Caller – Cancel |
The caller said the universal command Cancel, or a hyperlink triggered the cancel event. |
|
Caller – Exit |
The caller said the universal command Exit, or a hyperlink triggered the exit event. |
|
Caller – Exit/Cancel |
The caller said the universal commands Exit or Cancel, or a hyperlink triggered the exit or cancel event. |
|
Caller – Help |
The caller said the universal command Help, or a hyperlink triggered the help event. |
|
Disconnect |
A Disconnect Hangup or Disconnect Transfer event occurred. i8 Note: The Disconnect event should not be used to trigger clean-up tasks at the end of a dialog session. This should be done using dialog end processing as described in the Module object. |
|
Disconnect – Hangup |
The caller hung up. Typically, an Exit object is used in this event to send custom markup code to the media platform. |
|
Disconnect – Transfer |
The caller ended the dialog via a blind transfer. Typically, an Exit object is used in this event to send custom markup code to the media platform. |
|
Error – Connector |
An error occurred during the processing of a Connector or Database object. |
|
Error – Internal |
An internal error occurred within VoiceObjects Server. This includes errors during the processing of Expression objects (e.g. a division by zero), Script objects (e.g. invalid JavaScript code), or other internal issues. If no specific event handling has been defined for Error Connector (or Error Script), a connector or database (or script) problem will also activate this error type. |
|
Error – Media Platform |
An error occurred on the media platform. This error may be an installation or configuration issue on the media platform, missing or invalid resource files like grammars, or other invalid code encountered during processing (e.g. from a Plug-In object). |
|
Error – Script |
An error occurred during the processing of a Script object. |
|
OSDM – Max Invalid Answers |
The caller reached the maximum number of allowed invalid answers in an OSDM object. |
|
OSDM – Max No To Confirms |
The caller reached the maximum number of confirmation rejections in an OSDM object. |
|
OSDM – Max Repeats |
The caller reached the maximum number of allowed repetitions in an OSDM object. |
|
OSDM – Max Turns |
The caller reached the maximum number of allowed turns in an OSDM object. |
There is a difference between events that are activated by the media platform and those that are activated by the server. See Server-Internal vs. Platform Events below for a description of this difference.
For more information on the use of input mode specific No Match handlers, ASR – No Match (Voice) and ASR – No Match (DTMF), see Chapter 8 – Advanced Event Handling in the Design Guide.
You may also handle custom events not listed above. This can be useful to handle more specific (error) events that the media platform might activate; note that the predefined event type Error – Internal handles all subtypes of error events.
To do this, you can either type a custom event name into the Event type field, or you can define the event type dynamically by referencing a Variable, Expression, Layer, or Script object. The content of the respective object needs to be the fully qualified name of the event, e.g. “error.custom.noresource”. For a full list of error events supported in VoiceXML, see the VoiceXML specification at http://www.w3.org/TR/voicexml20/#dml5.2.6.
Object
In the Object field, select the object to be processed in the case of the specified event. Only Output, Goto, or Exit objects can be selected here. Other objects need to be accessed via a Goto object.
Occurrence
In the Occurrence field, select the occurrence level. The occurrence level specifies how many times an event must have occurred within the same input state before the specified event handling item is processed.
Example: Specify two No Input events, one with Occurrence >=1 and the other with Occurrence >=3. The first two times a No Input event occurs, the first event handling item will be processed. Starting with the third time and thereafter the second event handling item is used.
Layer
In the Layer field a custom layer can be defined using a Variable, Expression, Script, Layer, or Collection object to dynamically enable or disable the event handling item.
Continuation
In the Continuation field you can define what happens after the event handling item has been processed:
· Return – Return to the dialog flow expecting input from the caller again. Note, that the prompt is not replayed if an Output object is linked into the Object field. If you want the prompt to be replayed, link a Goto object instead, and select the Return check box in the definition of this Goto object.
· Reprompt – Return to the dialog flow and play the appropriate reprompting output before expecting another input. For further details on reprompting, refer to Chapter 8 – Advanced Event Handling in the Design Guide.
· Proceed – Proceed with the next object in the dialog flow. The current object is skipped.
8 Caution: Reprompt does not work together with Goto or Exit objects. When you link a Goto or Exit object in the Object field and select Reprompt in the Continuation field, then the Goto or Exit object is not processed. When using Goto or Exit objects, you can only select Return or Proceed.
Channel
In the Channel field, you can set a specific channel or a combination of channels in which the event handling item is to be active. Leave it at Default if you want the event handling item to be active in all channels.
Finish Tasks
Defines whether currently active business tasks are to be finished or not when the event handling item is processed. It can be set to None (the default), which means that no task will be finished, Active, which means that only the currently active task will be finished, or All, which means that all tasks, active or inactive, will be finished. In case one or more tasks get finished, they will automatically be logged as incomplete to Infostore, with a status that depends on the event type. The following table lists each possible state with its corresponding event type. The values in parentheses denote the value that is internally used, e.g. in VoiceObjectsXML or as return values of the TASKSTATUS function.
|
Status |
Set on event types |
|
Backend error |
Error – Connector |
|
Business logic |
None |
|
Caller abort |
Caller – Exit Caller – Cancel Caller – Help All custom event handlers |
|
Recognition failure |
ASR – Invalid Answer Limit ASR – Max Processing Time ASR – Max Speech Duration ASR – No Input ASR – No Match ASR – No Match (Voice) ASR – No Match (DTMF) |
|
Task restart |
None |
|
Session termination |
Disconnect Disconnect – Hangup Disconnect – Transfer |
|
Technical error |
Error – Internal Error – Media Platform Error – Script |
i8 Note: Finish Tasks is only applicable if a Goto or Exit object is used in the event handling item. In case of an Output object, the Finish Tasks setting has no effect.
Filtering
In the case of an event handler of type Error – Connector, select Error Code from the Filtering drop-down list if you want to define a handler for specific error codes only. For generic handlers of type Error – Connector leave the Filtering drop-down list at None. See the Connector object for more information on how to return error codes to the application.
Values
The codes that activate the handler are listed in the Values field. Enter either a single numerical code or a comma-separated list of codes. By doing this, the corresponding handler is activated only if the error code returned from the connector is in this list of values. If you set Filtering to Error Code but leave the Values field empty, the handler is activated for “all other error codes” (except zero). In this case, the server first checks the event handling items with non-empty values lists to deal with the more specific handlers, and then goes over to the ones with an empty list.
The option Send notification on event types “Error – Connector” or “Error – Internal” allows you to send a notification for event handlers of type Error – Connector and Error – Internal. If the check box is selected and the handler is activated at call time, the server sends a notification with the ID 1.3.6.1.4.1.24140.1.2.5.8.1 and the message Error Internal or Error Connector, respectively, depending on the event type defined.
For details on notifications, refer to Chapter 8 – Notifications in the Deployment Guide.
VoiceObjectsXML Definition
Event handling is defined using the <eventHandling> element.
It has one attribute inheritance, which indicates whether event handling from parent objects should be used (true, the default) or not (false).
In addition, the <eventHandling> element contains one or more <eventHandlingItem> elements.
The <eventHandlingItem> element has the following attributes:
· label
A text string providing a name for the event handling item.
· layer
Defines the layer for the event handling item. Can either be a reference to a Collection, Expression, Script, or Variable object; or a layer state reference of the form “Layer=State” or “Layer!=State” where “State” is the label of a state for the layer “Layer”.
· channel
Defines the channel(s) for which this event handling item is valid. Can be default, voice, video, text, web, voiceVideo, or textWeb. If not specified, defaults to default.
· eventType [required]
Defines the event type to be handled by this event handling item. One of invalidAnswerLimit, noInput, noMatch, noMatchVoice, noMatchDTMF, noInputNoMatch, maxInvalidAnswers, maxNoToConfirms, maxRepeats, maxSpeechDuration, maxTurns, help, exit, cancel, exitCancel, errorMediaPlatform, errorInternal, errorConnector, errorScript, disconnect, disconnectHangup, disconnectTransfer. In addition, custom event types may be used.
Alternatively, a reference to an Expression, Script, or Variable object can be provided.
|
Event |
Description |
|
cancel |
The caller said the universal command Cancel. |
|
cancelExit |
The caller said the universal commands Exit or Cancel. |
|
disconnect |
A Disconnect Hangup or Disconnect Transfer event occurred. |
|
disconnectHangup |
The caller hung up. Typically, an Exit object is used in this event to send custom markup code to the media platform. |
|
disconnectTransfer |
The caller ended the dialog via a blind transfer. Typically, an Exit object is used in this event to send custom markup code to the media platform. |
|
errorConnector |
An error occurred during the processing of a Connector or Database object. |
|
errorInternal |
An internal error occurred within VoiceObjects Server. This includes errors during the processing of Expression objects (e.g. a division by zero), Script objects (e.g. invalid JavaScript code), or other internal issues. If no specific event handling has been defined for Error Connector (or Error Script), a connector or database (or script) problem will also activate this error type. |
|
errorScript |
An error occurred during the processing of a Script object. |
|
errorMediaPlatform |
An error occurred on the media platform. This error may be an installation or configuration issue on the media platform, missing or invalid resource files like grammars, or other invalid code encountered during processing (e.g. from a Plug-In object). |
|
exit |
The caller said the universal command Exit. |
|
help |
The caller said the universal command Help. |
|
invalidAnswerLimit |
Counts all No Input and No Match events within a single input state and is activated if the caller reaches the defined limit of invalid answers. E.g. if an ASR – Invalid Answer Limit event with occurrence 3 is defined, it will be activated if the caller causes a total of three No Input or No Match events in any combination. Note that if multiple ASR – Invalid Answer Limit events with different occurrence levels are active, only the one with the lowest occurrence is used. |
|
maxNoToConfirms |
The user has reached the maximum number of “no” answers to a confirmation request. |
|
maxRepeats |
The user has reached the maximum number of repetitions of the same input state. |
|
maxSpeechDuration |
The caller has exceeded the maximum speech time. |
|
maxTurns |
The user has reached the maximum number of total turns. |
|
noInput |
The caller has not responded to a request for input within the timeout interval. |
|
noInputNoMatch |
A No Input or a No Match event occurred. Using the combined handler has the same effect as defining individual No Input and No Match handlers with the same settings. |
|
noMatch |
The caller said or entered something, but it did not match any of the currently active input grammars. |
|
noMatchDTMF |
The caller used DTMF for his last input and typed in DTMF keys that did not match any of the active grammars. |
|
noMatchVoice |
The caller used speech for his last input and said something that did not match any of the active grammars. |
· occurrence [required]
Defines the occurrence level to be handled by this event handling item. Must be an integer between 1 and 10.
· continuation
Defines the continuation mode. Legal values are return, reprompt, proceed. If not specified, defaults to return.
· errorCodeFilter
Defines whether this event handler should use error code filtering. Only relevant for event types errorConnector and errorScript. Either true or false. If not specified, defaults to false.
· errorCodeList
Comma-separated list of error codes for which this event handler applies. Only relevant for event types errorConnector and errorScript, and if errorCodeFilter is true. The list of error codes can be defined statically, or via a reference to a Variable, Expression, or Script.
· sendNotification
Indicates whether to send a notification when this event handler is activated. Only relevant for event types errorConnector, errorScript, and errorInternal. Either true or false. If not specified, defaults to false.
· finishTasks
Defines whether business tasks are to be finished or not. One of none, active, all. If not specified, defaults to none.
As children, the <eventHandlingItem> element uses <output>, <goto>, or <exit>.
Server-Internal vs. Platform Events
The Event type defined for an event handling item covers events that are activated by the media platform, and events that can only be activated internally by VoiceObjects Server. The latter are Error – Internal, Error – Connector and Error – Script. They are activated if a general error occurs while processing a dialog object (Error – Internal), a Java, CGI or Web Service connector (Error – Connector), or script code (Error – Script). All four channels support these event types.
All remaining types are platform-initiated events and only supported in the voice and video channel. They will be ignored in the text and Web channel. They are activated in voice or video applications if something "irregular" happens during the interaction between media platform and caller (e.g. ASR - No Match or Disconnect – Hangup).
The event handlers that handle the platform events are always rendered into the VoiceXML code, so that the media platform knows how to deal with this kind of events. This includes the handler for Error – Media Platform. The internal events, on the other hand, are handled completely within the server, i.e. while the server is preparing the next dialog step and before sending out a VoiceXML document to the platform. All internal events have the restriction that their occurrence level setting is ignored; the server will simply take the handler that is defined first in the "closest" corresponding object (e.g. Connector, Script, or Module), i.e. taking the inheritance hierarchy into account.
ACTIVATEEVENT function
The Expression function ACTIVATEEVENT allows activating custom events by using an Expression object at some point in the dialog flow. The event handlers for these events are also processed internally, even if the event name is that of a platform event (like noMatch). The reason for this is that the Expression object is never rendered as a single dialog step (even though the event handlers for these events are rendered in the voice and video channel into the VoiceXML documents of dialog steps that inherit the handlers).
If you want to activate a handler for a platform event using the ACTIVATEEVENT function, use one of the following values:
noInput, noMatch, noMatchVoice, noMatchDTMF, noInputNoMatch, help, maxInvalidAnswers, maxNoToConfirms, maxProcessingTime, maxRepeats, maxSpeechDuration, maxTurns, exit, cancel, exitCancel, errorMediaPlatform, errorInternal, errorConnector, errorScript, disconnect, disconnectHangup, disconnectTransfer
As the events activated with this function are processed internally, the handlers will be supported in all four channels.
The processing of this function works as follows:
When an event is activated through this function, the server checks whether a corresponding handler is found at the current point in the event handling inheritance structure. If that is the case, the target object is processed. Note that the continuation modes Reprompt and Return are treated as Proceed, since the event is never triggered in the immediate scope of an input state object, but in an Expression object instead. Therefore, processing continues with the next object in the flow after the Expression object, once the target object has been finished (given that the second argument of ACTIVATEEVENT, "return", is set to true). If there is a handler and it does not have a target object, but only a continuation mode (like Proceed, or Reprompt), ACTIVATEEVENT is ignored and processing continues with the next object (again only if "return" = true).
Note also that the occurrence level of the handlers for this event will be ignored as well.
When the event name uses the dot notation (e.g. myevent.flavour1.subflavour2), the search for corresponding handlers will include more general handlers. The server starts by looking at the most local module scope and tries to find a handler that exactly matches the event name. If none can be found, it stays in the current level and starts cutting qualifiers off the event name from the right and continues searching. For the above example this means that the server first looks for a myevent.flavour1.subflavour2 handler, then for myevent.flavour1, then for myevent. If none can be found, the server climbs up one step in the module hierarchy and repeats the search.
i8 Note: As a result, a more generic handler at a level closer to the current object will have precedence over an exact handler that's further up in the hierarchy.
If no suitable handler can be found, an Error – Internal event is activated and an ERROR message is written to the log files.