Overview

The Plug-In object enables the use of custom VoiceXML code. It can be used to access proprietary extensions available on a media platform (e.g. for call control or billing purposes), as well as to embed existing VoiceXML applications into the VoiceObjects environment.

The Plug-In object is only supported in the voice and video channel; it will be ignored in the text and Web channel.

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

The Plug-In object belongs to the object category Resources.

Dialog Flow Scenario

The dialog flow example shows the use of a Plug-In object for speaker verification in a banking application. This example assumes that the underlying media platform offers a custom tag to perform speaker verification.

Object – Caller	Dialog Flow
	To log into your account, please say the following identification phrase.
	Plug-In object containing custom tag that verifies the caller and provides the result back in a variable.
	Decide whether caller was successfully verified, and continue dialog accordingly.

Object Definition

The Definition of the Plug-In object provides the following sections:

·          VoiceXML Resource
To define the VoiceXML code either as embedded text or as a reference to an external file.

·          Parameter Set
To specify the set of parameters to be exchanged with the VoiceXML code.

·          Options
To specify processing options for the Plug-In object.

 

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

VoiceXML Resource

The VoiceXML Resource section defines the VoiceXML code to be executed within the Plug-In object. It can either be provided as an embedded definition typed into the Embedded Definition field (as shown in the example below), or via a reference to a file. In the latter case, an optional Resource Locator object and the name of the file need to be provided. The file may also be a server-side script that dynamically creates the VoiceXML code at call time.

i8    Note: If both an embedded definition and a file reference are given, the embedded definition takes precedence.

 

The VoiceXML resource can also be defined dynamically by using a Variable, Expression, Layer, or Script object.

There is an important difference between using an embedded and using an external definition of the VoiceXML resource. When using an embedded definition, VoiceObjects Server automatically creates wrapping VoiceXML code containing whatever navigation, event handling, and tuning is defined either locally within the Plug-In object or inherited from higher-level objects. Using embedded definitions, all elements are allowed that can be placed below the <vxml> element, especially <form> and <menu>.

When using an external definition, no wrapping VoiceXML is created. Instead, the external VoiceXML file is used exactly as it is provided. Any navigation, event handling, etc. needs to be manually coded within the VoiceXML code.

i8  Note: If you make use of namespaces inside embedded VoiceXML code, make sure to declare the namespace through the xmlns attribute, e.g. in the <form> element.

To return to the server from within the custom VoiceXML code, there are two options, one of which is only available when using an embedded definition:

1.        When using an embedded VoiceXML resource definition, the server automatically creates an additional <form> that provides a return statement. It can be accessed via the VoiceXML tag

       <goto next=”#ReturnToVO”/>

When using this return mechanism, all variables that were passed into the Plug-In object (see Parameter Set) are also automatically submitted back, and the corresponding objects are updated in the server.

2.        In both embedded and external definition, the return can be achieved by a custom <submit> tag within the VoiceXML code. This tag must be of the following form:

    <submit expr=”returnURL” namelist=”dialogID …”/>

where the namelist must contain at least the parameter dialogID which is used to identify the appropriate dialog session to be continued within the server. In addition, the namelist may contain whichever variables from the VoiceXML code are to be passed back into the server. Both returnURL and dialogID are passed into the VoiceXML code automatically, so they can be used without having to explicitly include them in the Parameter Set.

Even if you have an external file to be processed (either static VoiceXML or some CGI script), it is nevertheless recommended to use an embedded definition within the Plug-In object, as this gives you full control over the passing of parameters to the script and passing them back to the server. In most cases, it is appropriate to use a <submit> element and include dialogID and returnURL in the namelist attribute.

If the VoiceXML code fails for some reason (e.g. a syntax error) it depends entirely on the media platform whether this can be handled within VoiceObjects Server or not. When using an embedded VoiceXML resource definition, it is advisable to specify an event handling for the event type Error – Media Platform. This creates a handler for the VoiceXML event error within the VoiceXML wrapper that the server places around the custom code. Whether this handler is activated depends on the behavior of the respective media platform.

i8    Note: If your code contains an input state definition, e.g. through a <menu> or <field> element, you need to set the Contains input state option, otherwise the correct processing in terms of standard navigation, Infostore logging and utterance recording cannot be guaranteed. See Options for more details.

Parameter Set

The Parameter Set section defines an optional list of parameters to enable the exchange of processing information with the VoiceXML code.

 

Each Parameter section provides the following properties:

Property	Description
Parameter	Specifies the value of the parameter. Possible parameter types are Variable, Collection, Expression, Layer, Resource Locator or Script objects, and constants. When using a Resource Locator object as a parameter, its URL definition is passed to the script. The field can be left empty to denote an empty value.
Alias	Optionally specifies the name under which the parameter is accessible within the VoiceXML code. If left empty, the reference ID of the object defined in the Parameter field will be used as the name. This means in particular that for constant values an alias needs to be defined (as they do not have a reference ID). Constant parameters without a defined alias are ignored.

 

Note that neither the entries in the Alias fields nor the reference IDs which you pass into the plug-in may contain special characters such as hyphens.

For parameters passed to the custom VoiceXML code, the prefix var is attached to the reference ID (or alias, if defined) of all Variable objects and constants, the prefix lay is attached to the reference ID (or alias, if defined) of all Layer objects, and the prefix expr is attached to the reference ID (or alias, if defined) of all Collection, Expression, Script, and Resource Locator objects. When accessing the variables within the VoiceXML code or passing them back in a manual <submit> as described above, the names must be provided using these same prefixes. Note that only variables, collections, and layers can reasonably be passed back to the server.

Any number of parameters can be exchanged with the VoiceXML code.

 

Options

The Options section of the Plug-In object specifies four processing options.

 

The check box Contains input state tells the server if the VoiceXML code also defines an input state, e.g. contains a <menu>, <field> or <record> element. This instructs the server to consider the plug-in for standard navigation. If the check box is clear, the plug-in is skipped when navigating over it using commands like go back or forward. If it is selected, the server stops at the plug-in and executes it as a full-fledged dialog step.
In addition, this property controls whether the plug-in will occur as an input state in the Infostore table VOLDDSSEQ. If it is selected, the plug-in will be logged as an input state, otherwise it will not. If you use the ReturnToVO form to go back to the server (see the section on VoiceXMLResource above) the transition type (DS_TR_TYPE) for the plug-in will be Recognition by default. If you want to avoid this, you cannot use the ReturnToVO form but instead need to submit manually to the server, optionally calling the count script with the desired event name that will control the transition type to be logged.

Standby timeout indicates how long the VoiceObjects dialog session is kept alive while the call is being handled by the plug-in code. If the call stays in the plug-in for longer than the standby timeout, a return to the VoiceObjects dialog session is not possible.
When using a Variable, Expression, Script, or Layer object to define the standby timeout at call time, or when typing in a custom value instead of selecting one of the values from the drop-down list, the value needs to be a positive number and will be applied as seconds, e.g. for a custom timeout of 5.5 minutes, type in 330. The default setting is Default, indicating that the standby timeout setting is controlled by the service. For more information see Chapter 2 – Configuring Servers and Services in the Deployment Guide. Alternatively, a standby timeout can be selected from the drop-down list or it can be provided via a Variable, Expression, Script, or Layer object.

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.

i8  Note: Utterance recording will be turned off if the check box Contains input state is not selected, even if the Record utterances option is true at call time. This is due to the fact that if the plug-in code does not contain an input state, no recording can be made.

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.

i8  Note: The server can only store recordings of utterances made within code segments rendered by the server, e.g. inherited No Match handlers or hyperlinks. If you want to record utterances within your own VoiceXML, see Plug-in object in Chapter 6 – Recording of Utterances in the Deployment Guide for a description of the code you need to use.

VoiceObjectsXML Definition

The Plug-In object is represented by the VoiceObjectsXML element <plugin>. It has seven attributes and eight groups of children.

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

The <plugin> element uses the embedded <value> and <parameterSet> elements.

Plug-In

Attributes

·          location
Defines the location from where the VoiceXML file is to be retrieved. Must be a reference to a Resource Locator object.

·          file
The file name of the VoiceXML file. Can be a constant name, or a reference to an Expression, Script, or Variable object.

·          embeddedRef
Defines the plug-in code through a reference to an Expression, Script, or Variable object.

·          standbyTimeout
Defines the standby timeout for the plug-in. Either default or a numerical value that is interpreted as seconds. If not specified, defaults to default.
May be static text or a reference to an Expression, Script, or Variable object.

·          inputState
Indicates whether the code that is processed within the plug-in contains an input state that should be considered during standard navigation. Legal values are true or false. If not specified, defaults to false.

·          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.

 

Children

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

·          <sequence usage=”preprocessing”>
Defines the preprocessing sequence for the Plug-In object.

·          <value>
Optional embedded constant definition of the plug-in code.

·          <parameterSet>
Defines the parameter set for the Plug-In object.

·          <eventHandling>
Defines the event handling for the Plug-In object.

·          <customNavigation>
Defines the custom navigation settings for the Plug-In object.

·          <tuning>
Defines the tuning settings for the Plug-In object.

·          <sequence usage=”postprocessing”>
Defines the postprocessing sequence for the Plug-In object.

 

Example

<plugin location=”#Plugin locator” file=”playAd.vxml”>

  <parameterSet>

    <item alias=”useAudio” object=”#Audio enabled”/>

    <item alias=”audioPath” object=”#Audio locator”/>

  </parameterSet>

</plugin>

Value

Children

·          CDATA
Embedded code for the Plug-In object.

 

Example

<value>

  <![CDATA[

    <form>

      <block>

        <prompt>Hello world!</prompt>

      </block>

    </form>

  ]]>

</value>

ParameterSet

Children

·          +<item>
Defines the list of entries in the parameter set. The use of the alias attribute is optional when the object attribute is used, and required when the value attribute is used.

 

Example

<parameterSet>

  <item alias=”customer” object=”#Customer number”/>

  <item alias=”locale” value=”de-DE”/>

</parameterSet>

Item

Attributes

·          object
Defines a reference to an object. If this attribute is defined, the value attribute must not be defined.

·          value
Defines a constant value. If this attribute is defined, the object attribute must not be defined.

·          alias
Defines the parameter alias by which the parameter can be accessed within the VoiceXML code.

 

Example

<item alias=”premium” object=”#Annual premium”/>

 

<item alias=”locale” value=”en-US”/>

Object Interoperability

The following table contains all object types that can reference a Plug-In object:

Icon	Object Name	Use Case Example
	Module	A Plug-In object can be used within the embedded sequence of a Module object.
	Sequence	Most commonly, a Plug-In object is used within a Sequence object in a dialog flow.
	Menu	A Plug-In object can be used as the destination object within a Menu item.
	Confirmation	A Plug-In object can be used as the destination object within a correction item inside a Confirmation object.
	If	A Plug-In object can be used within either the THEN or the ELSE item of an If object.
	Case	A Plug-In object can be used in any WHEN item of a Case object.
	Loop	A Plug-In object can be used within the embedded sequence of a Loop object.
	Goto	A Plug-In object can be referenced via a Goto object.
	Hyperlink	A Plug-In object can be the destination of a Hyperlink object.
	Exit	A Plug-In object can be the destination of an Exit 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 Plug-In object should indicate which task it performs. The short description should contain a brief explanation of what is done within the plug-in, and which data is exchanged with it. The table below lists three examples:

Name	Description
Verify caller	Uses an <object> tag to authenticate the caller using speaker verification.
Invoke legacy application	Invoke the VoiceXML-based legacy application. After it is finished, the service continues.
Extended agent transfer	Transfer the call to an agent, simultaneously dropping all information gathered so far into the Call Center information system for agent pop-up.