The VoiceGenie platform provides configurable levels of information gathering and reporting to support. This information is stored on the platform, and can optionally be migrated to other platforms for review, depending upon the installation requirements. Typically the information is pre-processed, and written to an off-platform database.
For example, the VoiceGenie developer node uses MySQL to write call log and trace information to the Developer Workshop site. The logging and tracing functionality can take advantage of any database platform providing a JDBC-compliant client information (including Oracle, MySQL, Sybase, and others). You can browse real call log and trace information by visiting the VoiceGenie Developer Workshop, and signing up for an account. When you tie your application to a VoiceGenie extension, you can browse your call log information. Do not forget to add the <property> tags discussed below.
The simplest way to find out what is happening with your VoiceXML application is to add the following information to your VoiceXML page:
<meta name="MAINTAINER" content="yourname@yourserver.com"/><property name="com.voicegenie.maintainer.sendwhen" value="always"/>
If the MAINTAINER meta tag is defined at least once in your application, it will be used. If it is defined more than once, the value used will be the first once processed by the Interpreter. The content for the MAINTAINER meta tag should be the email address that you want the information sent to.
Note: On Windows installations, the Interpreter needs to be configured to use a local or remote SMTP server, in order to be able to send maintainer emails. This is done through the "email.smtpAddr" parameter in the Configuration. The SMTP server needs to be configured to allow relaying of messages for the Interpreter machine.
The email contains the following information:
Logs generated from the <log> tag with destination maintainer
Warnings and Errors generated by the Interpreter
Thrown events with a base of error. This feature is be controlled by the configuration value specified by vxmli.maintainer.log_message.on_error, which defaults to true.
Metrics
Voice XML Pages
When the VoiceXML session ends, either implicitly or because of an <exit>, the property com.voicegenie.maintainer.sendwhen is examined as follows:
always - Indicates that the Maintainer Email should be sent regardless of its contents
never - Indicates that the Maintainer Email should 'not' be sent
on_message - Indicates the Maintainer Email should be sent if at least one <log> message has been added to the maintainer message lists
Note: At most one email is sent per session. An email will only be sent if a maintainer email address has been specified at some point in the application.
The session ID will be logged in maintainer email to identify the session that generated the log information.
The email.fromaddr parameter in the VoiceXML Interpreter configuration specifies who the maintainer email is coming from (see the VG Media Platform System Reference Guide for more details on this parameter).
The Interpreter offers the Save Temp Files feature to aid developers and support individuals. Using this feature, the Interpeter can save various information to disk for later use. This information can be such things as prompts and VoiceXML pages. There are three properties used to control the behaviour of this feature.
This property specifies what types of files are saved. The value is interpreted as a string with a list of words. The words may be: all, none, prompts, inputs, pages, recordings. When a list of keywords is specified, the superset of all the keywords are saved. Each of these keywords are described below:
|
keyword |
Content Saved |
|
none |
Nothing |
|
all |
The same as specifying "prompts inputs pages recordings". |
|
prompts |
The prompt queue, the fetched prompts, and the HTTP request/response used to generate the prompts. Note that the prompt queue may have been built across a sequence of pages, but only the <property> in effect when the prompt queue is flushed is used. Also note that some prompts may not be saved (ie. rtsp:// or prompts played by a 3rd party media server). |
|
inputs |
The recognition/transfer/record/object request, the content of the inline/generated grammars and the fetched DTMF grammars (together with the HTTP request/response to fetch the grammars), the recognition/transfer/record/object result are saved in the temporary directory. |
|
pages |
The VoiceXML pages, external JS scripts and external <data> fetches, together with the HTTP request/response headers. |
|
recordings |
The recording from the <record> tag. |
Note: In particular, this means if someone specifies <property name= "com.voicegenie.savetmpfiles" value="none inputs"/> it is equivalent to specifying <property name= "com.voicegenie.savetmpfiles" value="inputs"/>.
This property can take on one of two values: "immediate" or "delayed". The default value for this property is "immediate". This property only takes effect when com.voicegenie.savetmpfiles is enabled. If set to "immediate" the files are written to disk immediately. If set to "delayed" the files are stored in memory. Note that the disposition of these files is determined at session end, by the value property com.voicegenie.onexit.keeptmpfiles or the keeptmpfiles attribute of <exit> if specified.
This property specifies whether or not keep temp files around after the VoiceXML session has ended. This property will only have meaning if at least one temp files has been saved. If this value is false, all temp files on the disk will be erased, and any files in memory will be discarded. If this value is true, all temp files on disk will be kept, and files in memory will be flushed to disk.
In this example, the application root page has savetmpfiles enabled, and they?re not enabled at the leaf pages. All types of temp files are saved for the session, immediately written to disk (default behaviour), and they?re not erased at the end of the session.
root.vxml
<vxml version="2.1" xmlns="...">
<property name="com.voicegenie.savetmpfiles" value="all"/>
...
</vxml>
In this example, page1.vxml would not be saved to disk (because savetmpfiles is set to none), while page2.vxml would be saved to disk (because the document-scope property is set to "pages").
page1.vxml
<vxml version= "2.1" xmlns="...">
<property name= "com.voicegenie.savetmpfiles" value="none"/>
<form id="a">
<block>
<goto next="page2.vxml"/>
</block>
</form>
</vxml>
page2.vxml
<vxml version= "2.1" xmlns="..."> <property name= "com.voicegenie.savetmpfiles" value="pages"/> ... </vxml>
In this example, page1.vxml is saved to disk (because the document-scope property is set to "all"), while page2.vxml would also be saved to disk (because the savetmpfile property is set to "all" in the <goto> element?s scope).
page1.vxml
<vxml version= "2.1" xmlns="...">
<property name= "com.voicegenie.savetmpfiles" value="all"/>
<form id="a"> <block> <goto next="page2.vxml"/> </block> </form> </vxml>
page2.vxml
<vxml version= "2.1" xmlns="..."> <property name= "com.voicegenie.savetmpfiles" value="none"/> ... </vxml>
In this example, when the application enters the field f1 on page2.vxml, it will not perform any savetmpfiles for the input or the prompts. The reason is that when it enters the <field>, the property in that scope has been set to "none". Note that when we queue welcome.wav, the property is set to savetmpfiles, but since we would take the property at queue flush time the Interpreter will not save the prompts.
page1.vxml
<vxml version= "2.1" xmlns="..."> <property name= "com.voicegenie.savetmpfiles" value="all"/> <form id="a"> <block> <prompt> <audio src="welcome.wav"/> </prompt> <goto next="page2.vxml"/> </block> </form> </vxml>
page2.vxml
<vxml version= "2.1" xmlns="..."> <property name= "com.voicegenie.savetmpfiles" value="all"/> <form id="a">
<field name="f1" type="boolean"> <property name= "com.voicegenie.savetmpfiles" value="none"/> <prompt> <audio src="please_say_your_name.wav"/> </prompt> </field> </form> </vxml>
In this example, when the application enters the field f1 on page2.vxml, it perform savetmpfiles for the prompts, but not the input parameters. The reason is that when it enters the <field>, the savetmpfiles property in that scope has been set to "prompts".
page1.vxml
<vxml version= "2.1" xmlns="..."> <property name="com.voicegenie.savetmpfiles" value="all"/> <form id="a"> <block> <prompt> <audio src="welcome.wav"/> </prompt> <goto next="page2.vxml"/> </block> </form> </vxml>
page2.vxml
<vxml version= "2.1" xmlns="..."> <property name= "com.voicegenie.savetmpfiles" value="input"/> <form> <field name="f1" type="boolean"> <property name= "com.voicegenie.savetmpfiles" value="prompts"/> <prompt> <audio src="please_say_your_name.wav"/> </prompt> </field> </form> </vxml>
In this example, both page1.vxml and page2.vxml would be saved as a tmpfile. When page1.vxml was saved, it was saved to memory without writing this to disk. When page2.vxml was saved it is written to disk. When the application exits, because neither the property com.voicegenie.onexit.keeptmpfiles nor the keeptmpfiles attribute is set, it takes on the default value of true and page1.vxml is written to disk at that time.
page1.vxml
<vxml version= "2.1" xmlns="..."> <property name= "com.voicegenie.savetmpfiles" value="pages"/> <property name="com.voicegenie.savetmpfilesmode" value="delayed" /> <form id="a"> <block> <goto next="page2.vxml"/> </block> </form> </vxml>
page2.vxml
<vxml version= "2.1" xmlns="..."> <property name= "com.voicegenie.savetmpfiles" value="pages"/> <property name="com.voicegenie.savetmpfilesmode" value="delayed" /> <form id="a"> <block> <goto next="page2.vxml"/> </block> </form> </vxml>
In this example, both page1.vxml and page2.vxml would be saved as a tmpfile. When page1.vxml was saved, it was saved to memory without writing this to disk. When page2.vxml was saved it is written to disk. When the application exits, because the keeptmpfiles attribute of <exit> is set to false, page1.vxml is not written to disk, and page2.vxml is erased from disk.
page1.vxml
<vxml version= "2.1" xmlns="...">
<property name= "com.voicegenie.savetmpfiles" value="pages"/>
<property name="com.voicegenie.savetmpfilesmode" value="delayed" /> <form id="a"> <block> <goto next="page2.vxml"/> </block> </form> </vxml>
page2.vxml
<vxml version= "2.1" xmlns="..." xmlns:vg="...">
<property name= "com.voicegenie.savetmpfiles" value="pages"/>
<property name="com.voicegenie.savetmpfilesmode" value="immediate"/>
<form id="a">
<block>
Application exited successfully. Goodbye.
<exit vg:keeptmpfiles="false"/>
</block>
</form>
</vxml>
The platform can log substantial information about your VoiceXML page. The information you can gather is shown in the table below. The level of page tracing can be controlled using the property tag:
<property name="com.voicegenie.metricslevel" value="0"/>
|
The previous sections explain how to select different levels of automated logging - either to have platform-generated debugging information emailed to the maintainer, or to have platform-generated call tracing details written to the metrics file.
However, it is often necessary to define additional log content. For example:
The <log> element allows additional debugging messages to be generated by the application, according to the developer's definitions. For example:
<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<form>
<var name="test1" expr="1"/>
<block>
<log>The value of test1 is <value expr="test1"/>.</log>
</block>
</form>
</vxml>
When the application is executed, the application generates the content for each <log>, and writes the contents to the metrics file, as well to the page that is sent as an email (if applicable).
For details on the full usage, see the Log reference in the VoiceXML 2.0 documentation.
So where do you go from here? Well, the Developer Workshop has lots of information regarding how to build VoiceXML applications. It's important to remember that designing good speech applications is tricky. The Developer Workshop will point out some of the common pitfalls in building speech applications and present some examples on using the tags.