List

Overview

The List object allows callers to navigate through a list of items and perform various actions on an individual item, e.g. reading, deleting, forwarding a message in an e-mail reader or selecting an item from a shopping list. The underlying data structure for the List object is represented by a Collection object and can either be a one-dimensional list (consisting of any number of rows) that only allows vertical navigation (using commands like next item, go back, repeat please etc.), or a two-dimensional table (consisting of any number of rows plus a predefined set of columns) that additionally provides horizontal navigation to jump to a column directly. In the latter case, the designer must explicitly specify which columns of the underlying table are to be read out to the caller. The designer can choose to present every column of the table, or only a subset thereof. It is also possible to present the data of more than one column together as one presentation unit. For this, the List object introduces the notion of column group to define the presentation units for each List item. A List item is equivalent to a row in the underlying collection. The List object presents its information item by item. This is also the case in the text and Web channel; the list data will not be displayed all at once.

The content of the list can either be defined statically at development time or retrieved dynamically during the dialog, e.g. from an external data source like a database system or a simple file. The List object also provides an optional selection cart (e.g. a virtual shopping cart in a shopping application) that stores selected items for later re-use.

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

The List object belongs to the object category Components.

Dialog Flow Scenario

The following dialog flow example shows how the caller navigates through a stock portfolio that offers quotes, news, and the number of shares the caller owns of each company in the list.

The table that serves as the content for the list looks as follows:

Grammar	Name	Quote_today	Quote_ yesterday	News	Portfolio
ibm	IBM	17.5	16.3	None.	56
apple, apple computers	Apple	23.8	21.4	Apple will release their new operating system tomorrow.	127
dell	Dell	56.1	58.0	Dell’s newly introduced laptop line is flying off the shelves.	83

Given this table, it is up to the designer to decide which columns to put into column groups. The dialog flow example below shows three column groups: The first one presents today’s and yesterday’s quotes together as one prompt; the next one reads out the news, whereas the last one presents the number of shares.

Object – Caller	Dialog Flow
	Here you can check quotes and news from companies of your stock portfolio. Please use the commands next, back, and repeat to navigate through the list. You can either simply listen to all information or say quotes, news, or shares* to jump to these items directly. You can also navigate to a particular company by saying its name. To exit the table say stop.*
	IBM. Their quote yesterday was 16.3, today it’s 17.5. (auto-advancing to next column group) <Earcon> News: None. (auto-advancing) <Earcon> You own 56 shares of IBM.
	(Does not say anything)
	(Auto-advancing to next row) Apple. Today’s quote is 23.8…
	(Barges in) News
	News: Apple will release their new operating system tomorrow. (auto-advancing) <Earcon> You hold 127 shares of Apple.
	Back
	(Moving to the previous row) IBM. Their quote yesterday was 16.3, today it’s 17.5. (auto-advancing) <Earcon> News: None. (auto-advancing) <Earcon> You own…
	(Barges in) Back
	(Trying to move to the previous row) This was the first entry in your list. You cannot go back here. IBM. Their quote…
	(Barges in) Dell
	Dell. The quote today is 56.1, yesterday’s close was 58. (auto-advancing) <Earcon> News: Dell’s newly introduced laptop line is flying off the shelves. (auto-advancing) <Earcon> You own 83 shares of Dell.
	Stop

Object Definition

The Definition of the List object provides the following sections:

· List Messages
To specify various kinds of optional messages related to the list as a whole.

· Navigation Grammar
To provide grammars for vertical and horizontal navigation through the list.

· Navigation Outputs
To define optional outputs to be presented after the caller has activated a navigation command; as well as presentation outputs for the commands, which are mandatory for the text and Web channel.

· Data Definition
To specify the content of the list and other information related to it.

· Content Formatting
To define sets of table columns to be played back as one presentation unit.

· Selection Commands
To specify the commands to be performed on a particular List item.

· Options
To provide processing options.

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

List Messages

The List messages section contains four subsections to specify the following optional messages through embedded Output objects.

· Welcome is presented as the caller enters the list.

· Begin of List is presented if the caller tries to navigate backward beyond the first item of the list.

· End of List is presented when the end of the list is reached, either through auto-advance or caller navigation.

· No Data is presented if the Collection object defining the list does not contain any data.

Instead of configuring these outputs as embedded definitions within the List object, existing Output objects can be referenced by over-linking the embedded definitions.

For further details, refer to the Output object.

Navigation Grammar

In the Navigation Grammar the possible input for vertical navigation among rows and horizontal navigation among column groups is specified. This covers the generic commands for relative navigation only, such as back, previous row, next item etc. Grammars for direct row access are defined within the data collection (see Data Definition), and grammars for direct column group access are defined in the Content Formatting section.

You can define appropriate grammars for the following commands:

· Start (sltNavigation = start)
Navigates to the first column group of the first row in the list. If the caller already is at this position, this command has the same effect as Repeat.

· End (sltNavigation = end)
Navigates to the first column group of the last row in the list. If the caller already is at this position, this command has the same effect as Repeat.

· Previous (sltNavigation = previous)
Moves back one step in the navigation history. The navigation history keeps track of all column groups passed. If there is no previous step in the history, the caller will move up one row. In this case, the setting of the option Maintain column group during navigation (see Options) indicates if the first column group is then presented (if check box is clear), or the one the caller was in when activating this navigation command (if check box is selected). If the current row is the first one, the Begin of List message will be played (if defined).

· Next (sltNavigation = next)
Moves forward one step in the navigation history (as an undo to a Previous command). If there is no next step in the history, the caller will move to the next row. The setting of the option Maintain column group during navigation (see Options) indicates if the first column group is then presented (if check box is clear), or the one the caller was in when activating this navigation command (if check box is selected). If there is no next row, the End of List message will be played (if defined).

· First Column Group (sltNavigation = firstCG)
Navigates to the first column group of the current row. If the caller already is in the first group, this command has the same effect as Repeat.

· Last Column Group (sltNavigation = lastCG)
Navigates to the last column group of the current row. If the caller already is in the last group, this command has the same effect as Repeat.

· Next Column Group (sltNavigation = nextCG)
Navigates to the next column group of the current row. If the caller is in the last group, the application jumps to the first column group of the current row.

· Previous Column Group (sltNavigation = previousCG)
Navigates to the previous column group of the current row. If the caller is in the first group, the application jumps to the last column group of the current row.

· First Row (sltNavigation = firstRow)
Navigates to the first row of the list. If the caller already is in the first row, this command has the same effect as Repeat. The setting of the option Maintain column group during navigation (see Options) indicates if the first column group is presented (if check box is clear), or the one the caller was in when activating this navigation command (if check box is selected).

· Last Row (sltNavigation = lastRow)
Navigates to the last row of the list. If the caller already is in the last row, this command has the same effect as Repeat. The setting of the option Maintain column group during navigation (see Options) indicates if the first column group is presented (if check box is clear), or the one the caller was in when activating this navigation command (if check box is selected).

· Next Row (sltNavigation = nextRow)
Navigates to the next row of the list. If the caller is in the last row, the End of List message is played (if defined). The setting of the option Maintain column group during navigation (see Options) indicates if the first column group is presented (if check box is clear), or the one the caller was in when activating this navigation command (if check box is selected).

· Previous Row (sltNavigation = previousRow)
Navigates to the previous row of the list. If the caller is in the first row, the Begin of List message is played (if defined). The setting of the option Maintain column group during navigation (see Options) indicates if the first column group is presented (if check box is clear), or the one the caller was in when activating this navigation command (if check box is selected).

· Repeat (sltNavigation = repeat)
Plays the current column group again.

· Stop (sltNavigation = stop)
Exits the List object without assigning a value to the selection cart (see Data Definition for more details on the selection cart). Note that the selection cart is not reset, but instead retains whatever value it has when the caller exits the List object.

The navigation grammar needs to fill the slot sltNavigation with the exact values indicated above. Neither the name of the slot nor the values may be different (note, though, that it is possible to define a different slot name through a media platform driver if required). Not all commands need to be defined. It is the designer’s decision to offer all or a subset of the available commands to the caller.

An example grammar in TTG format for the voice and video channel might look as follows:

next (nextRow), previous (previousRow), back (previousRow), repeat, stop

This simple grammar defines commands for vertical navigation (next, and the synonyms previous and back) plus commands to repeat the current column group (repeat) and to exit the whole list (stop).

In the textual channels, the navigation grammar can only be defined using TTG. In the text channel, the grammar tokens will be displayed as the access keys for the navigation commands. An example grammar might look like this:

4 (previousRow), 6 (nextRow), 9 (stop)

This would assign the keys 4, 6, and 9 to the commands previous row, next row, and stop, respectively. How the commands are presented is defined in the Navigation Outputs section.

In the Web channel, grammars are conceptually not required, as they will not be offered to the caller as such. Instead, the presentation outputs of the commands will be displayed as clickable hyperlinks. Nevertheless, the navigation grammar requires naming the slot values of the commands that should be active in the list. Therefore, define the slot values and use the question mark “?” as a placeholder for the grammar tokens:

? (previousRow), ? (nextRow), ? (stop)

If you build an application for both the text and the Web channel, you can use the same grammar definition for both, by setting Channel to Text/Web.

@8 Tip: Offering all available commands can be more confusing to the caller than helpful, although it would certainly mean most flexibility for frequent callers. The commands previous and next, which operate on the navigation history, can get confusing when two-dimensional tables are used. The recommended commands to use are nextRow, previousRow, repeat, and stop, as these cover the most important navigation options necessary in both list and table navigation.

i8 Note: If there is standard navigation defined for the Module object that contains the List object, be aware that there might be overlaps in the active grammars while being in the list. Grammars defined in the List object have precedence over the standard navigation grammars. So, for example, when the same utterance can trigger the standard navigation command backward as well as the list command previous, the list command is processed. The behavior of the standard navigation commands backward, forward, skip, and repeat is slightly different from that of the list commands previous, next, and repeat. Backward is the same as previous, but, if on the first List item, backward jumps out of the List object, whereas previous plays the Begin of List prompt (if defined). Backward can also undo a selection command, whereas previous cannot. Forward is the same as next, but if the navigation history is empty, forward merely repeats the current List item, whereas next moves on to the next row. Forward also undoes a backward command, i.e. after undoing a selection command through backward, you can reprocess it via forward. Skip leaves the List object and proceeds with the next object in the dialog flow. Repeat has the same effect for both standard and list navigation.

8 Caution: Some media platforms running services in the voice or video channel do not support slot assignments in DTMF grammars. These platforms always return the DTMF keys pressed, but no semantic interpretation. If you use TTG for DTMF grammars, this will be handled by the server, i.e. in this case slot assignments will work as usual. If you use external, or inline but non-TTG grammars, you need to be aware of this restriction. See Appendix A – Media Platform Drivers in the Deployment Guide to find out how your media platform handles this.

Navigation Outputs

In the Navigation Outputs section, two kinds of outputs can be defined for all the navigation commands available (plus auto-advance).

· Activation
This output is presented after a navigation command has been activated by the caller or after the application moves on to the next row when using auto-advance. It is only supported in the voice and video channel, and will be ignored in the textual channels.

· Presentation
This output defines how the navigation command is to be presented to the caller. In the text and Web channel it is mandatory, as this output will be used to display the navigation command so that the caller can activate it. In the voice and video channel, the available commands are typically explained to the caller within the welcome message, so the presentation outputs are not required.

From the Navigation direction drop-down list at the top, select one of the available commands, and in the Activation Output or Presentation Output section define the desired output (see the Output object for more details). In addition, layers can be associated with individual navigation messages. This way, a navigation output can, for example, depend on the caller’s current position in the list and be disabled if desired.

Data Definition

The content of the List object is stored in a Collection object.

The Data collection field specifies the Collection object that holds the list data. The collection must consist of one or more rows, each holding one or more columns. The data columns can have arbitrary names. If direct access to rows is desired, add columns with the name attribute set to grammarVoice and/or grammarDTMF for each row. The content of these columns must be a comma-separated list of utterances that serve as the grammar to access this row. See below for an example.

i8 Note: Direct row access is only supported in the voice and video channel.

The Selection Cart field allows you to specify a Variable or Collection object, which serves as a place in which to accumulate one or more selections of List items during the processing of the list. It can be used to implement a virtual “shopping cart” that is filled by the caller during the dialog. If a Variable object is specified, then a comma-separated list of keys (as given in column name=”key” of the data collection) is generated for all selected items. If a collection is specified, then the entire current row is copied from the data collection into the selection cart collection. This new collection can later serve as the data collection for another List object that e.g. presents all items from the shopping cart, to allow the caller to review the items and optionally select or delete some. If the selection cart collection is not empty when entering the list and does not have the same column layout as the data collection, then the server responds with an Error - Internal when trying to copy the row into the selection cart collection.
The selection cart is optional, but if defined, the data collection needs to contain a column named key.

For the stock portfolio example, the data collection might look as follows:

<root>

<row>

</row>

<row>

<col name=”key”>apple </col>

<col name=”grammarVoice”>apple, apple computers</col>

<col name=”name”>Apple</col>

Apple will release their new operating system tomorrow.

</col>

</row>

<row>

Dell’s newly introduced laptop line is flying off the

shelves.

</col>

</row>

</root>

In the Row index field, link a Variable, Script, Expression, or Layer object. The row index serves two purposes:

· When first entering the List object, or when re-entering it after a selection command has been processed, the index indicates the row in which to start the presentation by setting it to the numerical index of the row (starting with 1). If it is empty or has a value that is outside the range of rows within the data collection, the first row is presented.

· If a Variable object is used as row index, it holds the index of the row currently being presented, for referencing purposes in selection command processing or in column group or navigation message formatting. Note that this does not work for Script, Expression, or Layer objects.

This field is optional, and if not given, the presentation of the list starts with the first row.

The Column group ID behaves quite similarly:

· It allows to start presenting a row at a specific column group, e.g. when first entering a row or after a selection command has been processed. Column groups are identified by their ID specified in the Content Formatting section.

· If a Variable object is used, it contains the ID of the column group currently being presented. Again, this does not work for Script, Expression, or Layer objects.

This field is also optional, and if not given, the presentation of each row starts with the first column group.

Content Formatting

The Content Formatting section defines any number of individual column groups, which form the logical entity that is presented to the caller and allows flexible formatting of the data to be read out. Note that column group is an abstract term; a column group does not necessarily need to be made up of actual columns from the data collection. It can consist of text (in all channels) or audio/video files (plus alternative text, in the voice and video channel only) defined in columns of the data collection, but also of existing objects that can be played back (such as Output, Audio, Video, Text, or Variable objects). When creating the List object, the designer needs to decide which columns from the data collection to present in what way. It is both possible to ignore certain columns of the collection, or to put the content of several columns into one prompt, i.e. form one column group out of several columns. In case of a simple one-dimensional list, exactly one column group needs to be defined. In case of a two-dimensional table (N x M), the number of column groups corresponds to the horizontal dimension N of the resulting List object, whereas M is the number of rows of the data collection.

In the voice and video channel, it is possible for the caller to just listen to the list, without interacting with it. If that is the case and the check box Enable auto-advance to the next column group is selected (see Options), each column group is presented one after the other, in the order they are defined in the Content Formatting section. When having reached the end of a row, the first column group of the following row is presented next. This way, the list is traversed column group by column group, row by row. If a grammar is specified for a column group (see below) the caller can directly jump to this column group by uttering the corresponding command.

For the voice and video channel, barge-in for the outputs played within a column group can be controlled individually for each column group.

i8 Note: When disabling barge-in on a column group, make sure the caller has sufficient time to make an input after the outputs for the column group have fully played, and before auto-advance to the next column group or row is activated.

i8 Note: In the text and Web channel, neither auto-advancing nor directly jumping to a column group is supported.

The Content Formatting section can hold any number of column group items each defining a column group.

In each column group item the following properties can be specified:

Property	Description
ID	Mandatory parameter to identify the column group. If a column group ID variable is defined in the Data Definition section, it is this ID that is stored in the variable to track the current horizontal position in the list during call time.
Layer	Layer definition for the column group. This layer is evaluated whenever the column group is entered, so that the presentation of the column group can be disabled or enabled dynamically during the session, e.g. after processing a selection command.
Channel	Channel setting for the column group. The column group is only presented when the channel is set to the currently active channel at call time, or if it is set to Default, in which case it is active in all channels.
Barge-in	Indicates whether barge-in is allowed within the column group or not. The default value Default specifies that the dialog context setting is applied. Barge-in only applies to the voice and video channel.
Skip column group on auto-advance	This check box only applies to the voice and video channel. If it is selected, the column group is not presented when auto-advancing through the row. If a grammar is specified for the column group, the caller can still access it by uttering the corresponding command (see next item).
Grammar	The grammar specifies the utterances the caller can make to jump to this column group. This grammar is optional. In the voice and video channel, if no grammar is defined, an automatic grammar is generated, based on the mandatory ID. The grammar does not need to fill any slots.
Presentation Output	An output to define how the column group is presented to the caller. This is primarily relevant in combination with the Grammar.
Columns	The list of columns forming the column group. Note that column is an abstract term and not necessarily associated with an actual column from the data collection. It is possible to combine content (text, audio, video) coming from the list with other data present in the dialog, like variable content or Output objects etc. See below for details on the Columns subsection.

Columns

The Columns subsection can hold one or more items, which together form the prompt for this column group.

As an example, a column group can consist of an Output object (Today’s quote is…), followed by content from the data collection (56.1). In this case, the Columns section would consist of two items.

The items of the Columns section are presented in the order they are defined.

As with other object items (e.g. Output items) you can also re-order whole Column Groups as well as items in the Columns section within the editor. Refer to Chapter 6 – Object Editors in the Desktop for Eclipse Guide or Desktop for Web Guide for information on how to re-order object items.

Each item contains the following fields:

Label
An optional label for this item.

Type
A drop-down list specifying the type of content for this item. It can be one of Audio, Video, Text, Object, and Object reference.

· Audio indicates an audio filename coming from the data collection. This type is only supported in the voice and video channel. The Column field specifies the column the filename is retrieved from, and the Object field lets you optionally link a Resource Locator object that is used to locate the audio resource (in case the column from the data collection does not already contain a path for the file).
The column can optionally hold alternative text that will be read out if the audio file cannot be played back. Alternative text is attached to the filename using the separator ";" (semi-colon). Any text coming after the first occurrence of ";" is taken as the alternative text (this includes other semi-colons), whereas any text coming before is taken as the filename. If the <col> starts with a semi-colon, i.e. no filename is given, the alternative text will be rendered into the VoiceXML document with no surrounding <audio> element. If no semi-colon is present, the content of the <col> element is taken as the filename.

Example:
<row>
...
<col name="news">ibmnews.wav;There are currently no news on IBM</col>
...
</row>

Given that no Resource Locator object is linked in the Object field, this will be rendered as
<audio src="ibmnews.wav">There are currently no news on IBM</audio>

· Video indicates a video filename coming from the data collection. This type is only supported in the video channel. The Column field specifies the column the filename is retrieved from, and the Object field lets you optionally link a Resource Locator object that is used to locate the video resource (in case the column from the data collection does not already contain a path for the file).
Note that the server will always include the current video type setting coming from the dialog context in the generated VoiceXML code.

· Text indicates textual data coming from the data collection. The Column field specifies the column the data is retrieved from, and the Object field lets you optionally link a Format object to be applied to the data. This way, data from the collection can flexibly be read out via TTS or TTA (prerecorded audio files) in the voice and video channel, or presented in a formatted way in the text and Web channel.

· Object indicates an object within the project, which is specified in the Object field. Note that in this case the column definition does not refer to a value from the data collection. Object is meant to allow objects like Output as part of a column group.
If the object referenced here has pre- or post-processing, this is ignored.

· Object reference indicates an object reference (via a reference ID) coming from the data collection. This allows you to process an object from the current project, driven by the data collection. The difference between Object and Object reference is that with Object, you link an existing object statically into the List object, whereas with Object reference, the object to be processed is dynamically defined based on the content of the data collection. The Column field specifies the column from which the object reference is retrieved, and the Object field lets you optionally specify a Format or Resource Locator object to be applied to the referenced object. If a Format object is used, it overrides any formatting that might be attached to the referenced object itself. Likewise, if a resource locator is given, it overrides any resource locator that might be attached to the object. Note that if no object with the given reference ID exists, the server responds with an Error - Internal. If an object with the given reference ID exists in your project but is not referenced anywhere in the dialog flow, add it to the Reference Library of the Module object to make sure it is loaded into the cache of the server on deployment.

Object
To link a Resource Locator object, in case the Type field is set to Audio or Video, and to link a Format object for Text or Object reference.
If Type is set to Object, link any object that can be played back (Output, Variable, Expression, Collection, Audio, Video, Text, Silence, and Script).

Column
A text field that contains the name of the data collection column providing the data for this element. If Type is set to Object, this field is ignored.

Selection Commands

The Selection Commands section defines any number of commands that can be performed on a List item. Examples are to select an entry from a list in a shopping application or to delete an e-mail from your inbox in an e-mail reader application.

In each Selection Command section the following properties can be specified:

Property	Description
Label	An optional label to identify the selection command.
Layer	A layer definition that is evaluated every time a new column group is entered during call time, so that selection commands can be enabled and disabled dynamically.
Action	This field is used to define special commands to add or remove items from the selection cart (if defined). If the selection command is not dealing with the selection cart, leave this setting at None. For a command that adds the current List item to the selection cart (if defined), set this field to Add item to selection cart. When the caller activates this command, the server adds the current item to the cart. You can optionally link any object in the Object field, e.g. an Output object presenting a message to confirm the selection. For a selection command that removes the current item from the selection cart (given it is already part of the cart), set this field to Remove item from selection cart. When the caller activates this command, the server removes the item that the caller is currently on from the selection cart. If the current item was not yet part of the selection cart, no action is performed and the current item is played again.
Exit list	If set to True, the list processing ends after the selection command has been processed and the dialog proceeds with the next object in the dialog flow. If set to False (the default), the List object proceeds with the next row.
Object	The object to be processed upon activation of the selection command. If the Action field (see above) is set to Add item to selection cart or Remove item from selection cart, this field can optionally be left empty.
Grammar	A grammar to define the input that activates this selection command. If no grammar is given, an automatic grammar is generated based on the label, or, if not given, the name of the object specified in the Object field (automatic grammars are only generated in the voice and video channel). If the latter is not defined, the server responds with an Error – Internal. No slots need to be filled by this grammar. For more information on how to define a grammar, refer to the Grammar object in this Object Reference.
Presentation Output	An output to define how the selection command is presented to the caller. In the text and Web channel it is mandatory, as this output will be used to display the selection command so that the caller can activate it. In the voice and video channel, the available commands are typically explained to the caller within the welcome message, so the presentation outputs are not required.

@8 Tip: It is possible to modify the row index and column group ID (see Data Definition) while processing a selection command (e.g. by using Expression objects), so that flexible navigation commands can be implemented.

Options

In the Options section, the editor offers several check boxes that mainly influence the list navigation behavior.

Enable auto-advance to the next row (selected by default)
This option only applies to the voice and video channel.
If selected, the first column group in the next row of the data collection is presented in the absence of any caller input at the end of the current row. When in the last row, the End of List message is played. The time to wait until the list advances to the next row can be specified by setting the Input - Speech timeout parameter in the Tuning definition of the List object.

Enable auto-advance to the next column group (selected by default)
This option only applies to the voice and video channel.
If selected, the list automatically advances to the next column group in the absence of any caller input while or after playing the current column group. The time to wait until the List object automatically advances to the next column group can be influenced by adding Silence objects to the output definition of the column group (see Content Formatting). When the check box Enable auto-advance to the next row is clear and the last column group of the current row is played, the presentation starts again from the first column group.

Maintain row during column group navigation (selected by default)
If selected and the caller activates a horizontal navigation command to switch column groups (nextCG or previousCG, when at least two column groups exist in the list definition) and passes a row border (i.e. first or last column group of a row), the presentation will stay in the current row. Example: If the caller activates nextCG while being in the last column group of a row, the first column group of the same row is being played next. Vice versa, activating previousCG on the first column group will jump to the last column group of the same row.
If this check box is clear, the List object always jumps to the next or previous row when passing row borders. Example: If the caller activates nextCG while being in the last column group of a row, the first column group of the next row is being played next. Vice versa, activating previousCG on the first column group will jump to the last column group of the previous row. This approach allows to offer the caller a navigation command that walks through a two-dimensional list from the "top left" (1, 1) to the "bottom right corner" (n, n).

Maintain column group during row navigation (clear by default)
If selected and the caller activates a vertical navigation command to switch rows (nextRow, previousRow, start etc.), the presentation of the target row starts at the current column group (the one the caller currently hears) instead of the first one. This allows selecting one particular item of interest for all rows, e.g. News in the stock portfolio example (see Dialog Flow Scenario), and navigating between these (staying in one column group of the List object). If this check box is clear, the List object always jumps back to the first column group when switching rows.
If there is only one column group defined in the List object, this option has no effect.

Enable auto-repeat for List (selected by default)
If selected, the List object automatically returns to the first List item when the last item has been presented and no caller input has occurred. Before doing so, the End of List output is presented (if defined).

Skip rows already in selection cart (clear by default)
This option allows the use of the selection cart as a negative list for the data collection. If selected and a selection cart is defined, rows that are already in the cart are ignored, i.e. not presented anymore. If all available rows in the data collection are also in the cart (making the two collections identical) the List object is left and the dialog flow proceeds with the next object.

Enable DTMF auto-numbering for rows (clear by default)
This option only applies to the voice and video channel.
If selected, rows can be accessed directly by entering the row index via DTMF (e.g. typing “3 “ to jump to the third row, or “1 4” to jump to the fourteenth row). This is only available when the option Enable direct row access is selected.

Enable direct row access (clear by default)
This option only applies to the voice and video channel.
It allows the caller to jump to a particular row directly by saying what is defined in the grammarVoice or grammarDTMF columns of the data collection (see Data Definition for an example of grammarVoice). If these grammars are not available, a DTMF grammar is automatically created based on the numerical row index, in case the check box Enable DTMF auto-numbering for rows is selected.

Increased Dialog Timeout specifies a timeout value that is applied for this object in case it is higher than the current dialog timeout in a session. If it is lower, the setting is ignored. It is mainly applicable in the text and Web channel, where the dialog timeout of a service should be set to a relatively low value, e.g. 40 seconds, to keep the number of concurrent sessions low, as they usually run into the server timeout due to technical reasons. Use this setting to increase the timeout temporarily for objects that are likely to require more time to respond to, e.g. when the caller has to type in an address.

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 List object is represented by the VoiceObjectsXML element <list>. It has thirteen attributes and fourteen groups of children.

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

The <list> element uses the embedded <contentFormatting>, <navigationMessages>, and <selectionCommands> elements.

List

Attributes

· autoAdvanceColumnGroup
Defines whether the list should automatically advance to the next column group in the current row if no caller input occurs. Either true or false. If not specified, defaults to true.

· autoAdvanceRow
Defines whether the list should automatically advance to the next row if no caller input occurs. Either true or false. If not specified, defaults to true.

· maintainColumnGroup
Defines whether to maintain the current column group when navigating between rows by explicit caller input. Either true or false. If not specified, defaults to false.

· maintainRow
Defines whether to maintain the current row when navigating between column groups by explicit caller input. Either true or false. If not specified, defaults to true.

· autoRepeat
Defines whether the list loops around from the last column group of the last row to the first column group of the first row. Either true or false. If not specified, defaults to true.

· excludeCart
Defines whether rows already in the selection cart should be excluded from presentation during auto-advance. Either true or false. If not specified, defaults to false.

· enableDirectRowAccess
Defines whether direct access to individual rows is possible. Either true or false. If not specified, defaults to false. If it is set to true, note that the data collection needs to contain a column grammarVoice or a column grammarDTMF (or both).

· dataCollection [required]
Reference to a Collection object containing the list data.

· rowIndex
Reference to a Variable object that is used to maintain the index for the currently active row within the List object. May also be provided via a reference to an Expression or Script object, in which case the current position is not written back.

· columnGroupID
Reference to a Variable object that is used to maintain the ID of the currently active column group within the current row. May also be provided via a reference to an Expression or Script object, in which case the current position is not written back.

· selectionCart
Reference to a Variable or Collection object used to maintain the cart.

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

· increasedDialogTimeout
Defines the increased dialog timeout in seconds. If not specified, the setting from the dialog context is applied at call time.

Children

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

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

· <output usage=”listWelcome”>
Defines the “list welcome” message.

· <output usage=”listBegin”>
Defines the “begin of list” message.

· <output usage=”listEnd”>
Defines the “end of list” message.

· <output usage=”listEmpty”>
Defines the “no data” message.

· <grammar usage=”navigation”> [required]
Defines the navigation grammar for the List object. Needs to fill a slot sltNavigation with the tokens start, firstCG, firstRow, end, lastCG,lastRow, previous, previousCG, previousRow, next, nextCG, nextRow, repeat, stop. (Note that it is possible to define a different slot name through a media platform driver if required).

· <contentFormatting> [required]
Defines how to present the list content via column groups.

· <navigationMessages>
Defines the set of navigation messages.

· <selectionCommands>
Defines the set of selection commands.

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

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

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

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

Example

      <text>Here is the list of our health care plans. You can
       browse through it by saying forward or backward. When you
       hear the plan you are interested in, say select. To return to
       the main menu, just say main menu.</text>

</outputItem>

<text>Here is a list of our health care plans.</text>

</outputItem>

</output>

<text>You are at the beginning of the list. You cannot go back
any farther.</text>

</outputItem>

</output>

</outputItem>

</output>

<text>We are not currently offering any health insurance
plans. </text>

</outputItem>

</output>

</grammarItem>

</grammar>

</columnGroup>

</contentFormatting>

<text>Moving on to the next plan.</text>

</outputItem>

</output>

</navigationMessage>

<text>Backing up to the previous plan.</text>

</outputItem>

</output>

</navigationMessage>

</navigationMessages>

</grammarItem>

</grammar>

<text>The monthly fee for this plan is only </text>

<argument><value>PlanPrice</value></argument>

</expression>

<text> dollars.</text>

</outputItem>

</output>

</selectionCommand>

</selectionCommands>

</list>

ContentFormatting

Children

· +<columnGroup>
Defines the list of individual column groups.

Example

</columnGroup>

</contentFormatting>

ColumnGroup

Attributes

· ID [required]
A text string providing an ID for the column group.

· layer
Defines the layer for the column group. 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 column group is valid. Can be default, voice, video, text, web, voiceVideo, or textWeb. If not specified, defaults to default.

· bargein
Defines the barge-in behavior of the column group. Can be true, false, or default. If not specified, defaults to default.

· skip
Defines whether this column group should be skipped in auto-advance. Either true or false. If not specified, defaults to false.

Children

· <grammar>
Defines the grammar for direct access to this column group.

· <output>
Defines the presentation output for this column group.

· +<column>
Defines the list of columns in this column group.

Example

</columnGroup>

Column

Attributes

· label
A text string providing a name for the column.

· type [required]
Defines the type of this column. One of object, text, audio, video, reference (see type description above).

· property
Defines a reference to an object. The legal object types vary depending on the selected type.
If attribute type has the value object, the object itself can also be defined as a child.

· columnName
Specifies the column name in the data collection from which to retrieve data. The interpretation of this data depends on the selected type.

Children

· <expression> or
<script> or
<variable> or
<collection> or
<output> or
<layer>or
<silence>or
<audio>or
<text>or
<video>
Defines an object to be played. Only valid if attribute type has the value object.

Example

<text>Now moving on to the next entry.</text>

</outputItem>

</output>

</column>

NavigationMessages

Children

· *<navigationMessage>
Defines the list of navigation messages; at most one for each navigation direction.

Example

<text>Now moving on to the next entry.</text>

</outputItem>

</output>

</navigationMessage>

</navigationMessages>

NavigationMessage

Attributes

· direction [required]
Specifies the navigation direction to which this navigation message applies. Possible values are previous, previousRow, previousCG, next, nextRow, nextCG, repeat, start, firstRow, firstCG, end, lastRow, lastCG, stop, autoAdvance.

· layer
Defines the layer for the selection command. 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”.

Children

· <output usage=”activation”>
Defines the output that is played when the navigation direction is activated.

· <output usage=”presentation”>
Defines the presentation for this navigation direction.

Example

<text>Now moving on to the next entry.</text>

</outputItem>

</output>

</navigationMessage>

SelectionCommands

Children

· *<selectionCommand>
Defines the list of selection commands corresponding to the commands that can be performed on list cells.

Example

<text>The item has been added to your shopping cart.<text>

</outputItem>

</output>

</selectionCommand>

</selectionCommands>

SelectionCommand

Attributes

· label
A text string providing a name for the selection command.

· exit
Either true or false. Indicates whether the processing of the List object is terminated after processing the selection command. If not specified, defaults to false.

· action
Indicates whether the selection cart should be modified. Legal values are none, add, remove. For add, the key for the current list row is added to the cart variable or collection before processing the selection command. For remove, the key for the current list row is removed from the cart variable or collection before processing the selection command. For none, nothing is done with the selection cart.
If not specified, defaults to none.

Children

· <grammar> [required]
Defines the activation grammar for the selection command.

· <output usage=”presentation”>
Defines the presentation for the selection command.

· One of the following:
<module>, <input>, <output>, <sequence>, <menu>, <confirmation>, <list>, <osdm>, <plugin>, <connector>, <script>, <log>, <if>, <case>, <goto>, <loop>, <expression>, <recording>, <transfer>, <pause>, <exit>
Defines the object to be processed when the selection command is activated.

Example

<text>The item has been added to your shopping cart.<text>

</outputItem>

</output>

</selectionCommand>

Usage Examples

Usage examples for the List object are:

· Presenting a list of items fitting a certain description (e.g. top ten tracks, books by a certain author, etc.) with the option to place one or more items in a shopping cart.

· Presenting a stock portfolio with quotes, news, etc. with the option to perform actions (buy, sell, etc.) on the stock.

· Presenting the weather forecast for a city for the next several days, browsable by days.

· Presenting traffic information for a list of major highways.

· Presenting sports score tables.

· Implementing an e-mail reader that allows reading an e-mail, forward it, reply to it, delete it, etc.

Object Interoperability

The following table contains all object types that can reference a List object:

Icon	Object Name	Use Case Example
	Module	A List object can be used within the embedded sequence of a Module object.
	Sequence	Most commonly, a List object is used within a Sequence object in a dialog flow.
	Menu	A List object can be used as the destination object within a Menu item.
	Confirmation	A List object can be used as the destination object within a Correction item inside a Confirmation object.
	If	A List object can be within either the THEN item or the ELSE item of an If object.
	Case	A List object can be used in any WHEN item of a Case object.
	Loop	A List object can be used within the embedded sequence of a Loop object.
	Goto	A List object can be referenced via a Goto object.
	Hyperlink	A List object can be the destination of a Hyperlink 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 List object should describe which list of data is presented. The short description should contain a brief explanation of the caller’s options. The table below lists three examples:

Name	Description
Top Ten Tracks	Plays the current list of top ten tracks. Caller can add tracks to a shopping cart.
Stock Portfolio	Presents the caller’s stock portfolio with today’s and yesterday’s quotes, the number of shares owned, and news about the company.
Weather Forecast	Presents the weather forecast for the next three days, browsable by day.