Layer

Overview

The Layer object represents one of the core features of VoiceObjects. It allows the designer of an application to separate the application logic from the way the dialog is presented to the caller. Layers can influence aspects such as language, channel or persona, but they can also change the application behavior itself. For instance, a menu can have additional choices for gold customers depending on specific profile data available from a back-end system, or certain application features can be disabled outside normal business hours.

The Layer object is the place to specify a custom layer of an application. The Layer object definition always lists all states the corresponding layer can be in.

VoiceObjects also provides standard layers, the so-called system layers, which are language, channel, and input mode, plus the object-specific occurrence level. They are frequently required in applications and need not be implemented manually. They are present in many objects and can readily be used within the corresponding object editors. All other layers, which are rather application-specific such as persona, caller preferences, service level etc., are each defined within a single Layer object.

Infostore, the logging component of VoiceObjects Server, automatically keeps track of layer states for each call, if desired, to provide the data for reports on personalization in VoiceObjects Analyzer.

VoiceObjects distinguishes between manual layers and automatic layers.

Manual layers

Manual layers need to be switched manually during call time, typically activated by some command or choice made by the caller. The switch is performed by using the system function LAYER(layer, [state]) within an Expression object, which allows you to either retrieve the current state of a layer (leaving argument state empty), or to explicitly set it to a new state (providing argument state as the state to switch to).
Manual layers can only be in one state at a time. The most frequent example of a manual layer is Persona. The number of voices you want to have in your application corresponds to the number of states of this layer, one of which is declared as the default ( = initial) state. By using a Hyperlink object with a corresponding Expression object as its destination, the layer can be switched to a different state at call time, so that all subsequent prompts are spoken by the corresponding persona.

Automatic layers

Automatic layers change their states automatically, according to the status of the application during call time. Examples would be Caller Profile depending on back-end data, or TimeOfDay depending on the current time of day. Automatic layers, as opposed to manual layers, may have more than one active state. The state definition is typically done by analyzing the values of variables or expressions, which usually change during a dialog, e.g. due to back-end access or caller inputs.

For more information on the concept and use of layers, see Chapter 7 – How to Use Layers in the Design Guide.

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

The Layer object belongs to the object category Layers.

Dialog Flow Scenario

The following dialog flow example demonstrates how the caller can switch the persona using a hyperlink command. The Menu object holds two initial prompts that are associated with the manual layer Persona and corresponding states male and female. The layer is initially in state male, so this prompt is played first. After switching the layer to state female, the corresponding prompt is played. The selected prompt for playback is indicated by bold type:

Object – Caller		Dialog Flow
	male	[ male voice: ] *This is the main menu. Please make your choice: news, sports, or entertainment.*
	female	[ female voice: ] You are in the main menu. Please choose between news, sports, and entertainment.
Caller		Switch to female voice.
	male	[ male voice: ] This is the main menu. Please make your choice: news, sports, or entertainment.
	female	[ female voice: ] *You are in the main menu. Please choose between news, sports, and entertainment.*

The following example shows the effect of a layer TimeOfDay that affects the selection of a welcome prompt defined in an Output object. The layer has the four states morning, afternoon, evening, and night. Assume the caller calls in at 2pm. The correct prompt is played, indicated by bold type. The second Output object is not associated with a layer, so there is only one prompt defined. The final output in this example would thus be “Hello! Welcome to Prime Insurance.

Object – Caller		Dialog Flow
	morning	Good morning!
	afternoon	*Hello!*
	evening	Good evening!
	night	Hello!
		*Welcome to Prime Insurance*.

Object Definition

The Definition of the Layer object provides the following sections:

· State Indicator
To reference a Variable, Expression, Script, or another Layer object to compare values against (only for automatic layers).

· States
To list all available states for this layer.

· Default State
To define a default state.

· Formatting
To define formatting instructions for playback within an Output object.

· Options
To enable or disable the logging of layer states.

For information regarding the Properties section, refer to Properties in this Object Reference.

Manual and automatic layers differ in the way they are defined in the Layer editor:

Define manual layers

Manual layers are defined by specifying each individual state by means of their respective state ID and label, plus a default state. The obligatory default state is a full state definition on its own. Therefore it is not possible to list a state within the States section and at the same time define it in the Default State section, using the same state ID. The State Indicator is always left empty for manual layers.

Define automatic layers

Automatic layers can be defined in two different modes:

1. Provide a state indicator object and define the states by comparing the content of this object to some given values (static or dynamic). In this case, you do not define a condition declaration for any State definition within the States section.
Use this mode if the states all depend on the values of one specific object of your project, typically a Variable or Expression object.
In this mode, a layer state is active if the value of the state indicator object equals one of the comparison values provided for this state. Multiple states may be active at the same time.

2. Specify the states by explicit condition declarations for all State definitions within the States section. In this case, you must not define a state indicator object.
Use this mode if the states are rather unrelated to each other, and they all depend on distinct conditions.
In this mode, a layer state is active if its condition evaluates to true. Multiple states may be active at the same time.

In both modes of automatic layers, the Default State section defines a state that is active if none of the other states are active. For automatic layers, the definition of a default state is optional.

8 Caution: Mixing both modes for automatic layers, e.g. defining a state indicator object and also specifying condition declarations for some states is not possible and will lead to an internal error on VoiceObjects Server at call time.

State Indicator

The State Indicator only needs to be defined for automatic layers. If you make use of a state indicator (see Define automatic layers for a description of the two different modes of automatic layers), link a Variable, Expression, Script, or some other Layer object as a state indicator object. The content of this object is compared to the indicator values specified in the States and Default State sections. If the content is identical to one of the values defined as indicator values, then this state is an active state of the layer. If none of the states defined in the States section is active, the default state (if defined) is the only active state of this layer.

States

The States section lists all states the layer can be in, except for the default state, which is an additional state and defined in the Default State section.

In each State the following properties can be specified:

Property	Description
State ID	Mandatory parameter that identifies a state within a layer. It must be unique across the project, i.e. there cannot be two states – independent of the Layer object – with the same state ID in your project. State IDs must not contain blanks or other special characters except hyphens or underscores.
Label	Used for display purposes of layer states outside the Layer editor. In all editors that allow you to associate layer conditions, the label is shown instead of the state ID. If you do not specify a label, the state ID is copied into this field when saving the Layer object. The label must be unique across the project, i.e. there cannot be two states – independent of the Layer object – with the same label in your project. Labels must not contain the characters ‘=’ or ‘!=’ to prevent confusion in layer state conditions.
Description	Text area that allows you to provide a description of this state within the layer, for documentation purposes (optional).
Indicator Value	When defining an automatic layer via a state indicator (first mode, as described in Define automatic layers), use this field to define a value or a comma-separated list of values to compare the content of the state indicator object to. If the content of this object is equal to one of the indicator values, then this state is an active state of the layer. You can also link a Variable, Expression, Collection, Script, or Layer object to dynamically define the indicator values at call time.
Condition Declaration	When defining an automatic layer using condition declarations (second mode, as described in Define automatic layers), use this section to specify the condition that must be met for the corresponding state to be active. Either define an embedded condition by selecting an appropriate operator from the function drop-down list and specifying the required arguments, or link a Variable, Expression, Collection, Script, or Layer object that returns a Boolean value. For more information on the use of functions, see the Expression object in this Object Reference.

Manual layers are defined by specifying a state ID, a label, and optionally a description. Automatic layers additionally require indicator values or a condition declaration, depending on the mode used (see Define automatic layers).

i8 Note: Be careful when setting the labels and state IDs of layer states. Avoid swapping or renaming layer states once a Layer object has been created, as this might lead to problems in the object structure when saving the object.

Default State

The Default State definition can be interpreted in two different ways, depending on the type of layer:

· For manual layers, the default state is the initial state the layer is in when the dialog starts. The state is defined the same way as in the States section, by providing a state ID, a label and optionally a description.

· For automatic layers, the default state is the active state in case that all other states defined in the States section are not active, i.e. no other state condition evaluates to true in the corresponding dialog step at call time. Because of this, there is no need to specify any conditions in the default state. The default state for an automatic layer is therefore defined the same way as for manual layers, by providing a state ID, a label and optionally a description.

i8 Note: The default state is a separate state definition. It is not possible to define a state in the States section and then repeat this state in the Default State section, since each state ID must be unique across all layers within a project.

Formatting

The Formatting section defines how the active state of a Layer object is presented to the caller when it is used within an Output object.

Two different categories of formatting types are offered, which are only relevant for the voice and video channel:

· Text-To-Audio (TTA)
The object content is played back to the caller through the concatenation of prerecorded audio files.

· Text-To-Speech (TTS)
The object content is played back to the caller through text-to-speech synthesis provided by the media platform.

The formatting instructions can be defined as an embedded definition as part of the Layer object, or can be linked to an autonomous Format object.

To define formatting types for the text and Web channel, use the Formatting bus as described in Appendix B – How to Use the Formatting Bus in the Administration Guide.

For further details on formatting capabilities refer to the Format object in this Object Reference.

Options

The Options section specifies if logging of layer states to Infostore is enabled or disabled.

If the option Enable Layer State logging is selected, Infostore will log the state the layer was in when the call was finished. More precisely, it is the state the layer was set to the last time it was used in a call. This means, e.g., evaluated as a precondition or changed through the LAYER function. Automatic layers can be in more than one state, in which case a set of states will be stored.

General information about Layer objects, such as names, layer states, creation and modification timestamps etc., is additionally logged to Infostore with every redeploy or restore of an application. Thus, if you make bigger changes to a Layer object such as deleting states, its information will simply be updated so that old Infostore data might not be usable anymore. In that case, consider creating a new Layer object instead of modifying an existing one.

See Chapter 3 – The Physical Data Model in the Infostore Guide for detailed information on the table structure, and Chapter 3 – Report Library in the Analyzer Guide for information on available reports on Layer State logging.

Usage Examples

The following two examples demonstrate how to build the manual layer Persona and the automatic layer TimeOfDay, as introduced in the Dialog Flow Scenario. All necessary definitions in the Layer editor are described, followed by the steps required to use the layers within other objects.

Manual layer Persona

This layer represents two personas of your application, male and female.

1. Create a new Layer object.

2. Enter Persona as the name of the Layer object.

3. In the States section, define the first State by entering male both as the state ID and as the label.

4. Define the second layer state as the default state by entering female as state ID and label in the Default State section.

5. Save this Layer object.

You can use this Layer object to provide different prompts, e.g. different prerecorded audio files, in your application corresponding to the selected persona. There are basically two ways to do this, as described in Chapter 7 – How to Use Layers in the Design Guide. Either use the Layer object inside a Resource Locator object to dynamically change the path to the audio files during call time, or explicitly associate the layer with different Output items within an Output object. For the layer Persona, the first approach is more adequate, since different personas typically only result in different prompts to be played while the dialog structure stays the same. See Resource Locator in this Object Reference for a description of how to embed a Layer object into the definition of a Resource Locator object.

Automatic Layer TimeOfDay

This layer represents different times of day, with states morning, afternoon, evening, and night. It is implemented in the first mode (see Define automatic layers), using a state indicator object. In addition to the Layer object itself, an Expression object is necessary to retrieve the current time.

1. Create a new Layer object.

2. Enter TimeOfDay as the name of the Layer object.

3. In the State Indicator section, insert a new Expression object into the Object field.

4. Enter CurrentHours as the name of the Expression object.

5. From the Function drop-down list, select NOW.

6. Enter HH as first argument to always retrieve the current time as full hours (0-23).

7. Save and close this Expression object to link it to the State Indicator section of the Layer object.

8. In the States section, define the first State by entering morning both as the state ID and the label. Enter 8, 9, 10, 11 as the indicator values for this layer state. Enter From 8am to 11:59am as the description of this state.

9. Define a second State by entering afternoon as state ID and label. Enter 12, 13, 14, 15, 16, 17 as the indicator values for this layer state. Enter From noon to 5:59pm as the description of this state.

10. Define a third State by entering evening as state ID and label. Enter 18, 19, 20, 21 as the indicator values for this layer state. Enter From 6pm to 9:59pm as the description of this state.

11. Define a fourth layer state as the default state by entering night as state ID and label in the Default state section. Enter From 10pm to 7:59am as the description of this layer state.

12. Save this Layer object.

This Layer object is typically used to play a time-dependent greeting at the beginning of a dialog. The following screenshot taken from an Output object definition shows how to use different layer conditions of the TimeOfDay layer to distinguish between several Output items.

VoiceObjectsXML Definition

The Layer object is represented by the VoiceObjectsXML element <layer>. It has four attributes and two groups of children.

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

The <layer> element uses the embedded <layerState> and <defaultLayerState> elements.

Layer

Attributes

The standard attribute name is required for Layer objects.

· stateIndicator
Defines the layer state comparison value. Must be a reference to an Expression, Script, or Variable object.

· layerStateLogging
Defines if Layer State logging is to be enabled or not. Set it to true (the default) to enable it, and to false otherwise.

Children

· +<layerState>
Defines the set of states for the Layer object.

· <defaultLayerState>
Defines the (optional) default state for the Layer object.

· <format>
Defines the output formatting for the layer return value.

Example

</layer>

</layer>

LayerState

Attributes

· stateID [required]
Defines the ID of the layer state. Must be unique across all Layer objects.
State IDs must not contain blanks or special characters other than underscore.

· label
A text string providing a name for the layer state. If not specified, the state ID is used as label.

· shortDescription
A text string providing a description for the layer state.

· values
Defines either a comma-separated list of constant values, or a reference to an Expression, Script, or Variable object. Either this attribute is defined, or the child described below is defined, but not both.

Children

· <expression> or
<variable> or
<collection> or
<script>
Defines an embedded object as condition for the layer state.

Example

</expression>

</layerState>

DefaultLayerState

Attributes

· stateID [required]
Defines the ID of the default layer state. Must be unique across all Layer objects. State IDs must not contain blanks or special characters other than underscore.

· label
A text string providing a name for the default layer state. If not specified, the state ID is used as label.

· shortDescription
A text string providing a description for the default layer state.

Example

Object Interoperability

Layer objects can be referenced in all objects that provide layers and/or have a precondition setting. They can also be used within an Output, Log or Database object to play back their state to the caller or log it to a database or file. Furthermore, layer conditions can appear as arguments in Expression objects, as well as values in OSDM objects.

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 description of a Layer object should mention the type of the layer (manual or automatic) and also list all possible states of this layer. In case of automatic layers, describe the conditions that need to be met for the individual states.

The table below shows three examples:

Name	Description
Persona	Manual layer that covers all personas available in the application. Possible states are robert, marc, lisa, and susan.
TimeOfDay	Automatic layer that covers four times of the day: morning (from 7am to 11am), day (from 12pm to 5pm), evening (from 6pm to 10pm), and night (all other hours).
Customer Status	Manual layer that represents the status of the caller. Possible states are standard, premium, or gold.