Plug-In demo "External Recording"

Introduction

This demo shows the usage of the plugin-object to call external code. It will store a recording in a place chosen in the application.
This is a purely academical example for the usage of the Plug-In object as VoiceObjects already contains a full featured Recording object in its object library - and this will give you a better handling within VoiceObjects compared to the example below.
Please read the online help of VoiceObjects for more information on the Plug-In and on the Recording object - both descriptions can be found in the Object Library.

The main concept is to have a Plug-In Object which only calls an external JSP - which then provides the VXML to the Media Platform for the recording. Another JSP will then store the recorded audio stream as WAV file to disk and pass control back to VoiceObjects.

The Plug-In Object

The Plug-In object needs the following:

• Embedded definition
  

  <form id="Plug-In">
  	<block>
  		<submit method="post" namelist="varfilePrefix exprfilePath dialogID returnURL"next="http://[IP]:[Port]/[Path]/Recording.jsp" />
  	</block>
  </form>
  

  
  To pass the control back to VoiceObjects the following two variables have been passed from within the Plug-in. The variables are available per default in the VXML of the Plug-In object. This means you won't need to pass them in the Parameter Set of the Plug-In.
  • dialogID - this variable is needed to re-enter the correct dialog session in VoiceObjects. See SaveAudio.jsp for the later usage.
  • returnURL - this variable contains the URL to the instance of VoiceObjects where the dialog is running on. See SaveAudio.jsp for the later usage.
• Parameter Set
  Here the following Parameters are needed - sorted by Alias. Please check alias names for exact spelling and uppercase / lowercase, otherwise the parameters can not be passed to the JSP from the Plug-In VXML-rendering of VoiceObjects.
  • disconnect
    A placeholder variable for returning data from a disconnect event. Usually VoiceObjects won't come into account again after a disconnect on either of the JSP-pages.
  • fileName
    The name of the recorded file will be in this variable.
  • filePath
    The path where the file should be stored. In case of a Windows file path with backslashes in it ("\") each backslash needs to be replaced by a plus ("+") sign. This will later be changed back (and the +-sign can be edited in SaveAudio.jsp).
    Please note that this path needs to be writable!
  • filePrefix
    Any prefix which the file should get. Otherwise the filename will be the DialogID.

The JSPs

Usually the JSPs Recording.jsp and SaveAudio.jsp only need to be unpacked from the attached zip file and placed on a web application server of your choice. No other changes should be needed.

In the example project you will see that I placed the files in the VoiceObjects Resources folder (Platform/Resources/). This setup will be OK for testing or demo purposes, but in a production environment it is recommended to deploy custom code to a seperate web application server.

Recording.jsp

This JSP will output the VXML for the recording. When the recording is done, the next page will be called. The parameters passed from the Plug-In to this page are re-routed to the next page - SaveAudio.jsp - without changing them. A new variable is added - the content of the recording is additionally passed to the next page.

SaveAudio.jsp

Here the audio file is saved to disk - and the control is passed back to VoiceObjects. To pass the control back, the dialogID and the returnURL have been passed from VoiceObjects through the Recording.jsp to this page. Now the URL to return to VoiceObjects is in the returnURL variable - and one of the parameters in the POST namelist is the dialogID. Only by providing the correct URL and the correct dialogID parameter in the URL VoiceObjects will be able to map the returned data to the correct ongoing session in VoiceObjects (and to take over control again).

The Project

A small test project is attached to show how the whole thing fits together. A project documentation will help you to re-build the project in case you are working with an older version of VoiceObjects. The following objects need to be adapted in the test project to the actual system the Plug-In example will run on:

1. The Plug-In object initiate Recording.jsp
   Here please change the XML to point to the Recording.jsp as described in The Plug-In Object.
2. The Resource Locator Recording Location
   1. Change the Variable Recording Path to the path where the files should be stored.
   2. Change the Variable Recording URL to the URL where the Audios can later be downloaded (for playback).

Downloads

1. Plug-In_Example.xml - the VoiceObjects 9 demo project
2. Plug-In_Example.zip - the JSPs SaveAudio.jsp and Recording.jsp
3. Plug-In_Example-Documentation.pdf - the VoiceObjects Project Documentation
4. Plug-In_Example.png - Screenshot of the Plug-In