Collection
Overview
The Collection object is a set of data values that can be accessed as cells or elements in a two-dimensional data structure, similar to a spreadsheet or a table in a relational database. It is typically used to store the result of a database query or the access result of any other back-end system (e.g. a Web site or a legacy system). The status and the data values of a Collection object are managed within the dialog context of each call. The content of a Collection object is often dynamically populated at call time via a Connector object, which handles the connectivity and communication to any third-party back-end system. It is also used in the List object as the container for the data to be read out.
The content of a Collection object itself is represented through a generic XML data structure using the elements <root>, <row> and <col> and has the following structure:
|
<root> |
Generic XML Data Structure
The example above describes a single data cell with the column name “quote” and the assigned value “13.7”.
· <root> – The <root> element is the wrapping XML element for the entire Collection object structure. Only one <root> element is allowed.
· <row> – The <row> element forms a block of an arbitrary number of columns represented by the <col> element. The order of rows is relevant to the data structure and will always be processed top down, with the numbering starting at 1. The only valid parent element of <row> is <root>.
· <col> – The element <col> provides the attribute name which identifies a column uniquely within a row. Multiple columns of the same name are not allowed. When having multiple rows, the same set of column names should be used in each row to form a homogeneous two-dimensional data structure as presented below with the sample spreadsheet. The only valid parent element of <col> is <row>.
The following sample spreadsheet containing two columns A and B and two rows 1 and 2 is outlined below in the corresponding XML data structure of the Collection object:
Sample Spreadsheet
|
<root> |
XML Data of the Spreadsheet
i8 Note: There are several functions available that allow reading out or manipulating values from a collection. They are categorized as collection functions in the Expression object. In addition, the XPath function can be utilized to analyze collection values.
The Object Definition below covers the configuration of the Collection object with VoiceObjects Desktop. For information on how to define this object type using VoiceObjectsXML, refer to the VoiceObjectsXML Definition paragraph.
The Collection object belongs to the object category Logic.
Dialog Flow Scenario
The dialog flow scenario demonstrates a List object that plays the content of a Collection object to the caller as part of a Traffic Info service.
|
Object |
Dialog Flow |
|
|
|
|
[ This is the list of current traffic reports.] |
|
|
<Traffic message 1> |
|
|
<Traffic message 2> |
||
|
… |
||
|
… |
||
|
<Traffic message N> |
||
|
|
[ End of the available traffic messages..] |
|
Object Definition
The Definition of the Collection object provides the following sections:
· Declaration
To specify the initial value and reference ID.
· Formatting
To define formatting instructions for playback within an Output object.
For further details regarding the Properties section refer to Properties in this Object Reference.
Declaration
Within the Declaration section an optional initial value for the Collection object can be defined. For a new Collection object, a sample initial value is provided as shown below.
The sample value can be modified as desired, or removed altogether if an empty initial value (<root> </root> or <root/>) is desired.
The initial value can also be set dynamically at call time by referencing a Variable, Expression, Script, Layer, or another Collection object.
You can use the system functions INIT() and REFRESH() to initialize a collection to the initial value again at a later point in the dialog. REFRESH() re-evaluates the initial value in the current dialog context, whereas INIT() resets the collection to the value it got when it was first initialized. For static initial values, both functions have the same effect.
i8 Note: Make sure that the Collection object itself is not part of its own initial value definition (e.g. by being part of the parameter set passed to a Script object that computes the initial value), as this will lead to infinite loops.
The Reference ID field can be used to identify and reference a Collection object outside of the VoiceObjects framework, e.g. when using the Collection object in conjunction with a Connector or a VoiceXML Plug-In. In these cases, the automatically generated reference ID should be replaced by a more readable name.
Note that the reference ID may not contain blanks or other special characters except hyphens and underscores. It is not case-sensitive and limited to 40 characters in length. No two objects within one project may have the same reference ID.
Formatting
The Formatting section defines how the content of the Collection 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 Collection object, or can be linked to an autonomous Format object. Formatting is applied individually to all entries in the collection, which are read out row-by-row and column-by-column within a row.
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.
VoiceObjectsXML Definition
The Collection object is represented by the VoiceObjectsXML element <collection>. It has one attribute and two children.
In addition, the element has the standard attributes described in the XDK Guide.
8 Caution: The name attribute is required for Collection objects.
The attribute referenceID can be used to identify and reference a Collection object outside of the VoiceObjects Server framework. For details refer to Declaration above.
The <collection> element uses the embedded <value> element.
Collection
Attributes
· initial
Reference to a Collection, Expression, Script, or Variable object defining the initial value of the collection.
For details on the initial value also refer to Declaration above.
Children
· <value>
Optionally defines the constant initial value of the Collection object. It would typically be wrapped in CDATA.
· <format>
Defines the output formatting for the Collection object
Example
<collection name=”Health care plans” initial=”#Build collection”/>
<collection name=”alphabet”>
<value>
<![CDATA[
<root>
<row>
<col name=”a”> alpha </col>
<col name=”b”> beta </col>
</row>
<row>
<col name=”a”> aleph </col>
<col name=”b”> beth </col>
</row>
</root>
]]>
</value>
</collection>
Value
Children
· CDATA
Embedded code for a Plug-In or Script object, or embedded value for a Variable object, Collection object, or argument.
Example
<value> 42 </value>
Working with Collections
Collections are extremely useful when dealing with structured data derived e.g. from a database or other backend system. A variety of operations and expression functions are available to efficiently work with them. More details on these functions can be found in the Expression object entry.
Set and extract values
Individual cell values within a collection can be set and retrieved using the assignment (:=) and the INDEX functions, respectively.
Access to individual cells is facilitated by the INDEX function using row index and column name.
Cells can be assigned simple values such as the content of a variable or a constant by providing the row index and column name as well as the value to be set:
Alternatively, a cell can be assigned the content of a different cell (from the same or a different collection) by again providing the row index and column name of the cell to be set as well as the collection, row index, and column name from which to retrieve the value:
An entire collection can be emptied using the CLEAR function.
Find values
Collections often contain lists of certain entries, e.g. recent transactions on a bank account. In such cases it is desirable to be able to find a specific entry in this list based on a given piece of information, e.g. the recipient of a money transfer. Two functions are available for this purpose.
FINDCELL retrieves the value of a specific column given the value in some other column of the same row. It is similar to the SQL statement
select field where key=value
FINDROW retrieves the index of an entire row given the value in a column of that row. It is similar to the SQL statement
select * where key=value
Manipulate rows and columns
Sometimes it is desirable to manipulate entire rows or columns within a collection in a single operation. Multiple functions are available for this purpose.
ADDROW and ADDCOLUMN add an entire new row or column to an existing collection. Reversely, DELETEROW and DELETECOLUMN delete an entire row or column from a collection. Finally, REPLACEROW and REPLACECOLUMN replace an existing row or column by an alternate one.
Rows within a collection can be sorted by the values within any of its columns by using the SORTROWS function.
The number of columns and rows in a collection can be retrieved using the COLUMNS and ROWS function, respectively.
The list of column names occurring in a collection is available using the COLUMNNAMES function.
Advanced collection operations
Collections of specific formats (i.e. using specific column names) are also used to provide certain advanced functionalities.
The VALUESUBSTITUTION function facilitates the mapping of certain internal values to multi-lingual external representations. As an example, transaction types represented by internal codes can be mapped to e.g. English, French, and German terms that callers can understand.
The APPLYCONFIGURATION function enables the bulk assignment of values to other Variable, Collection, and Layer objects e.g. to set a caller-specific application configuration. Further details can be found in Application Defaults in Chapter 4 – Service Deployment in the Deployment Guide.
Usage Examples
Collection objects can be used e.g. to store
· Caller profiles
· Top Ten lists of songs
· Shopping carts
· Lists of transactions on a bank account
Object Interoperability
The following table contains all object types that can reference a Collection object:
|
Icon |
Object Name |
Use Case Example |
|
|
A List object uses Collection objects for both the list data and the selection cart, if defined. |
|
|
|
A Collection object can be used within Expression objects in a variety of expression functions. |
|
|
|
A Collection object can be passed as parameters to a Connector object. The Connector object will have access to the collection content as an XML string in the format described in the documentation above. |
|
|
|
A Collection object can be used as the return value in a Database object. |
|
|
|
A Collection object can be passed as parameters to a Script object. The Script object will have access to the collection content as an XML string in the format described in the documentation above. |
|
|
|
A Collection object can be passed as parameters to a Plug-In object. The Plug-In object will have access to the Collection content as an XML string in the format described in the documentation above. |
|
|
|
A Collection object can be linked within the parameter set of any OSDM object. |
|
|
Any object that has a Precondition |
A Collection object can be used as a Precondition.
|
|
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 Collection object should be as short as possible and at the same time precise enough that other users will know immediately what the Collection object is all about. The description of a Collection object should provide additional information about the structure and form of the content (e.g. number, text, date, time or a Boolean values), the expected or valid value domain and finally something about the initialized value (if available).
The table below is listing various examples as a general guideline:
|
Name |
Description |
|
|
List of valid destination airport names stored in the column Airport (e.g. London Heathrow). |
|
|
Customer list with two columns containing a 14 digits customer ID and the according name (first and last name). |
|
|
Actual list of traffic news provided in text form for a particular highway. |
|
|
Email inbox with 6 columns: Sender (Txt), Subject (Txt), Body (Txt), Date (MM/DD/YYYY), Importance (high/low), Attachment (Int). |
|
|
Top down sorted list of the top ten ring tones as complete audio URLs. |