Hyperlink

Overview

The Hyperlink object allows callers to branch out to a given dialog component at any point in time through predefined commands, which activate the link. In addition, it also provides the capability for integrated confirmation in order to prevent the unwanted activation of a hyperlink, e.g. due to misrecognition.
Conceptually, a hyperlink in voice or video applications can be compared to a hyperlink on a Web page. The Hyperlink object is supported in all four channels.

The Object Definition below covers the configuration of the Hyperlink object with VoiceObjects Desktop. For information on how to define this object type using VoiceObjectsXML, refer to the VoiceObjectsXML Definition paragraph.

The Hyperlink object belongs to the object category Actions.

Dialog Flow Scenario

The following dialog flow example presents the use of a Hyperlink object within the Voice Shopping portal. It branches out to the Entertainment portal and is activated by the caller through a particular command.

Object – Caller	Dialog Flow
	Hello and welcome to the Voice Shopping portal.
	Switch to the Entertainment portal.
	Hello and welcome to the Entertainment portal. Say games to go to the game section, jokes to hear some funny jokes or music to go to the jukebox.

Object Definition

The Definition of the Hyperlink object provides the following sections:

· Destination
To provide the behavior upon activation of the hyperlink and specify how to proceed with the call after the link has been processed.

· Activation Grammar
To define the grammar for the input that activates the Hyperlink object.

· Presentation Output
To define an output that presents this hyperlink to the caller. This output is mandatory in the text and Web channel and optional in the voice and video channel.

· Confirmation Request
To optionally request a confirmation from the caller before activating the Hyperlink object.

· Confirmation Grammar
To define the grammars for denying or confirming the activation of the Hyperlink object.

· Message
To define optional outputs for the following cases:

· Activation: to present an output before the hyperlink destination object is processed.

· Deactivation: to present an output if the caller explicitly denies processing of the hyperlink destination object.

· Return: to present an output before returning to the dialog flow after the hyperlink destination object has been processed.

· Options
To define various processing options.

For information regarding additional object configuration refer to Pre-/Postprocessing, Event Handling, Navigation, Tuning, and Properties in this Object Reference.

Objects defined within preprocessing are processed immediately after activation of the hyperlink by the caller, i.e. prior to anything defined in the Hyperlink object itself. The postprocessing is done after the entire Hyperlink object has been processed, i.e. right before continuing with the original dialog flow (independent of the setting of Continuation within the Destination section).

i8 Note: Configurations made in the Event Handling, Navigation and Tuning sections are only interpreted if you make use of the confirmation functionality of the Hyperlink object. When simply specifying the Destination and Activation Grammar, event handling, navigation and tuning will be ignored. So, in particular, a confidence level for a specific hyperlink command cannot be defined by setting the corresponding tuning parameter in the Tuning section. Use the Weight field in the Activation Grammar section to increase or decrease the prominence of a specific Hyperlink object in the voice or video channel.

i8 Note: The embedded version of the Hyperlink object – as it occurs within the Custom Navigation definition of the objects Module, Input, Menu, Confirmation, List, Plug-In, and Hyperlink itself – is structurally simpler and only contains an equivalent of the Destination section and the Activation Grammar section.

Destination

The Destination section defines the destination of the hyperlink. There are two different modes of using a Hyperlink object. One is to process a specific object whenever the Hyperlink object is activated. The other is to activate a specific event, which can then initiate other processing.

Select Process object (the default) in the Mode field, to process a specific object when the hyperlink is activated; then specify the object to be processed by linking it in the Object field.

Select Activate event in the Mode field to activate an event instead; in that case, pick an event from the Event field or type in a custom event name. When typing in a custom event, you can make use of the "dot" notation ("myevents.event1") to work with a hierarchy of events.
When rendering the current dialog step, the server will start looking for a corresponding event handler, first in the current object, then in parent Module objects. If a handler with the same name, or, in case the event uses the "dot" notation, a more generic handler is found, it will be rendered into the VoiceXML document. If no matching handler can be found, though, a default handler gets rendered that simply logs the activation of the event to Infostore and a corresponding log message is written to the processing log files. The effect of this "silent" handler is that the caller utterance is simply ignored. If you do not want the server to render this default handler, use the <suppressedDefaultHandlers> element in the MPDrivers.xml file to list names of events that default handlers should not be rendered for.

i8 Note: If Mode is set to Process object and no destination object is defined, or Mode is set to Activate event but no event is defined, then the hyperlink is ignored altogether and processing continues normally. A corresponding warning message in the processing log files will point to this.

The event Caller - Help is particularly useful in many applications, since it allows designers to activate help (as defined in event handling) using custom grammars. Note that the help event should always be activated by explicitly defining a hyperlink with a custom grammar, in order to have control over the utterances that activate the help event. You can make use of a “universal” grammar for this event, though, by setting the tuning parameter Input – Universal Commands to help (which is the default value for this parameter). In this case, the media platform provides a generic grammar for this command (usually containing utterances like help or I need help). For more information on setting this tuning parameter, refer to Tuning in this Object Reference.

The Continuation drop-down list indicates how to proceed with the dialog flow after the hyperlink has been processed. This setting only applies if the mode is set to Process object. If the mode is set to Activate event, the corresponding event handler will govern how the dialog proceeds.
The Continuation drop-down list has three options:

· Return (default)
The original object in which the hyperlink was activated is processed again (increasing the object occurrence counter), and the prompt defined in this object is replayed. This gives the caller some orientation when coming back from the hyperlink subdialog.
This option is commonly used when callers interrupt the dialog for additional information or instructions before proceeding.

· Proceed
The object in which the hyperlink has been activated is skipped when returning from the hyperlink subdialog, and the application proceeds with the next object in the original dialog flow. If no subsequent object is defined, the call terminates.
If you want to define a command that simply skips the current object, use an Output object as destination. You can then either define a prompt like Okay, I’m skipping this question, or not define any prompt in the Output object. In the latter case the dialog proceeds silently with the next object in the dialog flow.

· Do not return
The application does not return to the object in which the hyperlink has been activated. This option is typically used e.g. when defining a hyperlink that jumps back to a main menu from anywhere in an application. Note that if the destination defined does not explicitly specify the dialog flow any further (e.g. when using an Output object as the destination), the dialog terminates with this option.

i8 Note: When reprocessing the object in which the hyperlink has been activated, i.e. Continuation is set to Return, the occurrence level of this object is incremented. Be aware that this affects the selection of the prompt to play, as defined in the Initial section of the object where the hyperlink was activated.

The Channel field allows you to activate the hyperlink only for a specific channel. If you want the hyperlink to be active in all channels, leave it at Default.

The Finish Tasks field defines whether currently active business tasks are to be finished or not when the hyperlink 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. Note that this will only happen when the hyperlink is really processed, i.e. it will particularly not happen if a confirmed hyperlink is denied by the caller. In case one or more tasks get finished, then they will automatically be marked with status Caller Abort, which means they will be logged as incomplete to Infostore.

i8 Note: This setting is only applicable if Mode is set to Process object. If Mode is set to Activate event, Finish Tasks has no effect.

Activation Grammar

The Activation Grammar specifies the input a caller can give to activate the Hyperlink object. This grammar does not need to fill any slots. The grammar is mandatory in all channels. If not defined, or all Grammar items are ruled out at call time due to layer conditions, the hyperlink will not be active.

In the text channel, the grammar needs to be defined using the TTG format. The activation grammar will be shown as the access key of the option the USSD browser will generate for this hyperlink. See Chapter 10 – How to Support Multiple Phone Channels in the Design Guide for examples of how the display of a text application could look like. Therefore, define some digit as the grammar for this hyperlink, e.g. 0 (zero). If you do not want to define the access key, but instead want to rely on auto-numbering on the USSD browser side, use question mark “?” as a placeholder in the grammar definition.
In the Web channel, the grammar will not be processed at all, only the presentation output will be used to display the hyperlink. Nevertheless, a grammar definition is mandatory in all channels. So either re-use the text channel grammar definition in case your application should support both channels, or use question mark “?” as a placeholder definition in case you only define a Web grammar.

For further details on grammar definition refer to the Grammar object in this Object Reference.

Presentation Output

The presentation output is used to present the hyperlink to the caller. In the voice and video channel, a hyperlink is fully defined with the destination and the activation grammar. Using the presentation output is optional here. You can either tell the caller about the presence of the hyperlink inside some general introduction prompt at the beginning of the dialog (e.g. in the main menu), or you use the hyperlink’s presentation output to do this. A typical output could be “To go back to the main menu at any point, say main menu”. It is recommended to set the occurrence level of this output to Only once, so that this prompt is only played once per call. Otherwise it will be played after the main prompt of each object in which the hyperlink is active.

In the text and Web channel, the presentation output is required, as it is used to display the hyperlink on the mobile device, so that the caller can activate it. A typical output for a main menu hyperlink could be “Main Menu”. This would be displayed on the mobile device as an option. In the text channel, the option would be associated with the access key coming from the activation grammar. The occurrence level setting should be left at Always, so that a generic hyperlink is really displayed in all input states where it is active. If the presentation output is missing, the caller cannot activate the hyperlink.

The hyperlinks are displayed at the end of each page in the text and Web channel, and played at the end of the main prompt of an object in the voice and video channel. If more than one hyperlink is active, the order in which they are presented depends on some server-internal order. If you want to define yourself in which order the hyperlinks are presented, use the Label field of the presentation output as a criterion for sorting. Of all hyperlinks active in an input state, the server applies alphanumerical sorting on the labels of all hyperlinks. As an example, define “01” as the presentation output label of one hyperlink, and “02” as that of another one. Finally, the server will present the “01” hyperlink first, then the “02” one.
Use this mechanism also in standard navigation commands, to define the order between custom and standard navigation.

For further details on output definitions refer to the Output object in this Object Reference.

Confirmation Request

The Confirmation Request is used in conjunction with the confirmation grammar to request an explicit confirmation from the caller before activating the Hyperlink object. This is useful for hyperlinks the activation of which would be annoying in case of misrecognition by the media platform in voice or video applications, e.g. a “goodbye” hyperlink that would end the call.

Using the confirmation functionality is optional. If not needed, leave the Confirmation Request and Confirmation Grammar empty. In the Message section, you can still define the Activation and Return outputs, though.

For more information on the Initial and Event Reprompt sections refer to the Input object in this Object Reference.

In addition to the confirmation request, a Confirm and Deny output can be defined. These are optional outputs in case of the voice and video channel; they could contain prompts that tell the caller what to say or press to confirm or deny the activation of the hyperlink, respectively. In the text and Web channel, these outputs are mandatory. Use them to define the output that should be displayed for the options to confirm and deny the hyperlink.

Confirmation Grammar

The Confirmation Grammar defines two separate grammars that indicate the input the caller can make to confirm processing of the Hyperlink object (in the Confirm section) or deny processing of the Hyperlink object (in the Deny section). Neither of these two grammars needs to fill any slots.

In the text channel, the confirmation grammar is used to define the access keys for the confirm and deny options the USSD browser will generate. In the Web channel, the grammar is conceptually not required. But since the grammar is mandatory, you can use the question mark “?” placeholder as the grammar, or use the definition of the text channel.

For further details on grammar definition refer to the Grammar object in this Object Reference.

Message

The Message section defines optional output for various purposes:

Activation defines an optional output that is presented after the caller has explicitly confirmed the hyperlink, if applicable, and before the hyperlink destination object is processed.

Deactivation defines an optional output that is presented if the caller explicitly denies processing of the hyperlink destination object. Note that the deactivation output can only be played if both a confirmation output and a confirmation grammar are defined.

Return defines an optional output that is presented after the hyperlink destination object has been processed and before processing returns to the normal dialog flow. Note that the return output is only played if Return or Proceed is selected in the Continuation field in the Destination section. The return output can also be used if the Hyperlink object is not a confirmed one, i.e. without having the confirmation request and grammar defined.

For further details on output definitions refer to the Output object in this Object Reference.

Options

The Options section of the Hyperlink object specifies five processing options.

For hyperlinks that have a confirmation request defined, Enable auto-advance on No Input enables auto-advance in case the caller does not respond to the confirmation request. If the check box is selected, a No Input event is interpreted either as an implicit (“silent”) confirmation or denial, depending on the setting of Auto-advance direction (see below). By default, the check box is clear. This option is only supported in the voice and video channel.

Enable auto-advance on No Match enables auto-advance in case the caller says something that does not match the confirm or deny grammars. If the respective check box is selected, a No Match event is interpreted either as an implicit confirmation or denial, depending on the setting of Auto-advance direction (see below). By default, the check box is clear. This option is only supported in the voice and video channel.

Auto-advance direction defines whether or not to process the hyperlink destination object if one of the auto-advance options is activated:
Destination (the default) indicates that in cases of auto-advance, the destination object is processed.
Origin indicates that in cases of auto-advance, the destination object is not processed, and the dialog returns to the dialog flow, reprocessing the current object (regardless of which option is selected in the Continuation field in the Destination section).

Record utterances specifies whether utterances made in this object are to be recorded (True) or not (False), given that utterance recording is switched on for this session. Always indicates that utterances in this object are always recorded when utterance recording is enabled on the service, regardless of statistical filtering. By default the value is Default, indicating that the current value of the corresponding dialog context setting RECORDUTTERANCES is used.

Recording scope defines the scope in which recordings will be made. If set to Recognition, only those utterances will be recorded that were successfully recognized (including the activation of hyperlinks). If set to No Match, only those utterances will be recorded that triggered a No Match event. If set to All, any recording will be stored. If set to Default, the current value of the corresponding dialog context setting RECORDINGSCOPE is used. By default the value is Default.

Due to the nature of recordings, the feature of recording utterances is only available in the voice and video channel. For more information on this refer to Chapter 6 – Recording of Utterances in the Deployment Guide.

VoiceObjectsXML Definition

The Hyperlink object is represented by the VoiceObjectsXML element <hyperlink>. It has twelve attributes and seventeen groups of children.

In addition, the element has the standard attributes described in the XDK Guide.

Note that the label, layer and channel attributes may only be used when the hyperlink is embedded in <customNavigation>, while the children required for confirmation as well as the attributes recordUtterances and recordingScope may only be used if the hyperlink is defined as an autonomous object.

Hyperlink

Attributes

· mode
Defines whether to process an object or to activate an event. Legal values are object and event. If not specified, defaults to object.

· object
Defines the object to be processed if the hyperlink is activated.

· event
Defines the event to be activated if the hyperlink is triggered. Can be any internal VoiceXML event (like help, cancel, noMatch etc.), or an arbitrary custom event name.

· continuation
Defines the continuation mode. Legal values are return, noReturn, proceed. If not specified, defaults to return.

· label
A text string providing a name for the hyperlink.
This attribute must only be used if the hyperlink is directly embedded inside <customNavigation>.

· layer
Defines the layer for the hyperlink. 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”.
This attribute must only be used if the hyperlink is directly embedded inside <customNavigation>.

· channel
Defines the channel(s) for which this hyperlink is valid. Can be default, voice, video, text, web, voiceVideo, or textWeb. If not specified, defaults to default.
This attribute must only be used if the hyperlink is directly embedded inside <customNavigation>.

· autoAdvanceNoInput
Defines whether the dialog should automatically advance in case of a No Input event. Either true or false. If not specified, defaults to false.
This attribute must only be used if the hyperlink is autonomous.

· autoAdvanceNoMatch
Defines whether the dialog should automatically advance in case of a No Match event. Either true or false. If not specified, defaults to false.
This attribute must only be used if the hyperlink is autonomous.

· autoAdvanceDirection
Defines the direction of an auto advance. Can be either destination or origin. If not specified, defaults to destination.
This attribute must only be used if the hyperlink is autonomous.

· recordUtterances
Defines whether to use utterance recording. One of true, false, always, default. If not specified, defaults to default.

· recordingScope
Defines the scope for utterance recording. One of all, noMatch, recognition, default. If not specified, defaults to default.

· finishTasks
Defines whether business tasks are to be finished or not. One of none, active, all. If not specified, defaults to none.

Children

· <expression usage=”precondition”> or
<variable usage=”precondition”> or
<collection usage=”precondition”> or
<script usage=”precondition”>
Defines the precondition for the Hyperlink object.

· <sequence usage=”preprocessing”>
Defines the preprocessing sequence for the Hyperlink object.

· <grammar usage=”activation”>
Defines the activation grammar for the Hyperlink object.

· <output usage=”confirmation” type=”initial”>
Defines the “initial” section of the confirmation message.

· <output usage=”confirmation” type=”reprompt”>
Defines the “event reprompt” section of the confirmation message.

· <output usage=”presentation”>
Defines the presentation for the Hyperlink object.

· <grammar usage=”confirm”>
Defines the grammar used to confirm the processing of the Hyperlink object.

· <grammar usage=”deny”>
Defines the grammar used to deny the processing of the Hyperlink object.

· <output usage=”activation”>
Defines the activation message.

· <output usage=”deactivation”>
Defines the deactivation message.

· <output usage=”return”>
Defines the return message.

· <output usage=”confirmPresentation”>
Defines the confirm presentation.

· <output usage=”denyPresentation”>
Defines the deny presentation.

· <eventHandling>
Defines the event handling for the Hyperlink object.

· <customNavigation>
Defines the custom navigation settings for the Hyperlink object.

· <tuning>
Defines the tuning settings for the Hyperlink object.

· <sequence usage=”postprocessing”>
Defines the postprocessing sequence for the Hyperlink object.

Example

</grammarItem>

</grammar>

</hyperlink>

</grammarItem>

</grammar>

</hyperlink>

<grammarDefinition mode="voice">hang up, goodbye
</grammarDefinition>

</grammarItem>

</grammar>

</outputItem>

</output>

</grammarItem>

</grammar>

</grammarItem>

</grammar>

<text>OK, we will continue.</text>

</outputItem>

</output>

</hyperlink>

Object Interoperability

The following table contains all object types that can reference a Hyperlink object. In general, Hyperlink objects can be used in all objects that offer navigation.

Icon	Object Name	Use Case Example
	Module	Most commonly, a Hyperlink object is referenced in the Navigation definition of a Module object.
	Input	A Hyperlink object can be referenced in the Navigation definition of an Input object.
	Menu	A Hyperlink object can be referenced in the Navigation definition of a Menu object.
	Confirmation	A Hyperlink object can be referenced in the Navigation definition of a Confirmation object.
	List	A Hyperlink object can be referenced in the Navigation definition of a List object.

Object Naming Conventions

In order to leverage the capabilities of the integrated documentation of VoiceObjects it is important to provide intuitive and self-explanatory object names and descriptions.

The name of a Hyperlink object should indicate the target of the hyperlink. The short description should also provide an indication which utterances activate the hyperlink, and whether the hyperlink will return to the current position in the dialog or not. The table below lists three examples:

Name	Description
Main Menu	Jumps back to the main menu. Activated only by the command main menu. Does not return.
Switch to female Persona	Switches the active Persona to the female one. Activated by a variety of commands such as female Persona, switch to female speaker, etc. Returns to current position after switching and replays prompt.
Pause application	Enters the Pause object. Activated by utterances such as short break or pause application. Returns to current position when caller continues and replays prompt.