Operations Documentation

Plum Voice Platform v. 2.6

© 2007 Plum Group, Inc. All rights reserved.
More on VoiceXML at Plumvoice.com

Introduction

The is the Operations Manual for the Plum Voice Platform. It includes all of the information needed to setup, maintain, and monitor the Plum Voice Platform and its users. This document is intended for both administrators and for developers, and is provided as documentation for the web interface. For information on creating VoiceXML applications please refer to the "Plum Voice Platform v. 2.5 -- VoiceXML 2.0 Tutorial" and the "Plum Voice Platform v. 2.5 -- Programmer's Reference Manual," provided with your Plum Voice Platform.

Outline
1.  First Time Configuration
1.1  Admin Password
1.2  Server ID
1.3  DNIS Settings
1.4  ASR and TTS configuration
2.  Administrative Procedures
2.1  Logging In and Out
2.2  Server Control
2.3  Call Event Logs
2.4  Session Logs
2.5  Error Logs
2.6  Applications
2.7  Users
2.8  Configuring Global Platform Attributes
2.9  Changing the Admin Password
3.  User Procedures
3.1  Setting a DNIS
3.2  Debug Logs
3.3  Scratch Pad Manager
3.4  Developer Tools
3.5  Changing the User Password
4.  Command-line Interface
4.1  Changing IP Address Settings
4.2  Changing Hostname
4.3  Changing Default Password
4.4  PlumVP Configuration Reset
4.5  Enable FTP Access
4.6  Set Date/Time
4.7  Shutdown the Server
4.8  Restart the Server
4.9  Logout

1. First Time Configuration

When you first use the PlumVP you will be prompted to do some initial configuration.  There is nothing in this setup that can not be changed at a later time.  Before the system is shipped to you, a small amount of preconfiguration has been done; that setup includes setting the boards to operate with the specified telephony settings with the purchased number of ports activated.

1.1 Admin Password

The admin password needs to be set in order to protect your system from unauthorized access to log files and for general system control. Plum recommends using a password with at least 8 characters consisting of both letters and numbers.

1.2 Server ID

If you have multiple Plum systems running on your network, each should be given an unique ID; this allows each box to share it's TTS and ASR engines.  Also if you are using your own reporting tools, having a unique ID allows reporting to combine and analyze logs from multiple systems. If you have only one Plum system running on your network, the default ID is fine.

1.3 DNIS Settings

Depending on your telephony configuration you may see a different interface.  For analog and loopstart channelized T1 (cT1) systems you will be given the option to configure the channel to DNIS (dialed number) mappings.

For E&M cT1 and ISDN based systems you will be given the option to provide a DNIS range(s).  To enter multiple DNIS block ranges, enter each range as XXXX-XXXX and place a comma between each range.

If you are unsure about this setting, leave the defaults; these values can be changed at a later time.

1.4 ASR and TTS Configuration

For configurations using a shared ASR and TTS setup, the IP address of the ASR or TTS engine you would like to connect to should be provided here. If you are unsure about this setting use the defaults provided.  Note: If multiple systems are sharing an ASR or TTS engine be sure to provide a unique server ID for each of those systems. See Section 1.2.


2. Administrative Procedure

2.1 Logging In and Out

Admin Account vs. User Accounts

The login screen is identical both for the admin and for users.  Once logged in the admin account has permission to control all facets of the system.  When users log in they are only permitted to view and manage the DNIS settings decided by the admin.

Logging In

In order to log in you must enter the username "admin" and the password you entered upon initial configuration of the system. If you have lost your password, please see the section about the command-line interface, Section 4.

Logging Out

Logging out of the PlumVP will force the user to go back to the login page.  In both the user and admin page the logout option is located at the bottom left of the navigation menu. Logins to the PlumVP are session based, so closing your browser will also log out any user.


2.2 Server Control


Checking Platform Status

The first page the admin is sent to once logged in is the "Server Control" page.  From this page the admin can easily check the status of the PlumVP.  The possible status messages are "Running" or "Stopped."  The number of available channels on the system will be listed along with the number of currently active channels (channels in a call).  You can start the PlumVP by pressing the "Start PlumVP" control button.  The two means of shutting down the PlumVP are listed in the following two sections.

Graceful Platform Shutdown

The recommended means of shutting down the PlumVP is using the "Graceful Shutdown" button.  This will shut down the platform one channel at a time.  If a call is currently active on a given channel the system will wait for that session to complete, at which time the channel will be taken down.  When all channels on the system have been stopped the Status will be changed to "Stopped."

Immediate Platform Shutdown

The alternative to "Graceful Shutdown" is to press the "Immediate Shutdown" button.  This will force each channel to disconnect and will stop the server without any regard to current sessions.

2.3 Call Event Logs


Accessing Debug Logs

The debug logs are provided for administrators to help users experiencing problems with their VoiceXML scripts.  In order to view a debug log you must select the DNIS you want to debug; choose the "Last Call Completed" option, and the press "Open."

This will open a standard log window.  The top frame displays information about the last log: the DNIS, the starttime, the duration, and the last error that occurred. The "Save As..." button is provided as a convenience and does not work in all web browsers; if you are not using Internet Explorer you can simply right click on the bottom frame and select "Save Page As..." from the drop down menu. The bottom frame displays the actual contents of the log file, color coded to emphasize errors that have occurred.

Accessing Last Utterances

The last utterance logs are provided to complement the debug logs.  For each last call to a DNIS all of the audio used to determine responses to speech recognition are provided.  These audio files are the last utterances for the DNIS.  The format for the recordings is 8bit u-law encoded wav files.

Viewing Live Logging

The live logs are provided to improve the user/administrator understanding of the log files.  Using the live logs you can enter a currently active session to view the users' interaction and the execution of the system.  These log files contain the same data as the debug logs, except that they are streamed to the web browser in real time.  After a session is complete the live log will wait for the next session to begin on the provided DNIS.  For optimal performance a high speed broadband connection is recommended for remote systems; for local systems a LAN connection is preferred.

Checking Platform Call Status

The call status of the system is provided on the call logs page, and can be reloaded by hitting the refresh button.  However, clicking the "Popup Monitor" will display the same call information in a convenient pop-up window that refreshes every five seconds.  The pop-up monitor also provides a minimize feature where the taskbar text will indicate the current number of calls into the system that updates with the page, even if it is minimized.


2.4 Session Logs

The session logs interface allows the admin to view the session information in various ways.  From this interface a report can be created, raw logs over a range can be viewed, and daily session logs can be viewed or deleted.  Session logs contain general call information and include the data created by a Voice XML <log> tag.

Session Reports

The system has the ability to create reports based on the session logs.  The reporting tool allows the admin to pick a date/time range over which the report will be based.  The report will then be generated based on that range, and given a default detail interval of "Monthly" (this interval can be changed to regenerate a different report).  The values for total minutes are calculated by summing all of the seconds divided by 60 and then rounded to the nearest minute.  Note: Reports on systems with a high volume of calls can take several minutes to be generated.

Accessing Platform Session Logs

The raw session logs are available to the administrator in two ways.  The first is similar to the session reports: the admin can choose a date/time range for the output to be based on.  Clicking "View Session Log" will bring up a window containing the raw session log information.  As with the debug logs, clicking "Save As..." is browser dependent; if you are not using Internet Explorer, you can right click on the session log data and choose "Save Page As...."  The format for the log file differs depending on the line type.  There are four log line types: inbound, outbound, transfer, and local.  For the first three the format is as follows:

<line type> <ANI> <channel#> <CLF timestamp> <DNIS> <Session ID> <UNIX startime> <UNIX endtime> <call length>

2.5 Error Logs

The error logs interface allows the admin to view the accumulated error events.  From this interface raw logs over a range can be viewed and daily error logs can be viewed or deleted.  Error logs contain a copy of all error events logged in the call event log.


The raw error logs are available to the administrator in two ways. First, the admin can choose a date/time range for the output to be based on.  Clicking "View Aggregate Error Log" will bring up a window containing the raw error log information.  As with the debug logs, clicking "Save As..." is browser dependent; if you are not using Internet Explorer, you can right click on the session log data and choose "Save Page As...."  The format for the log file differs depending on the line type.

The error log format is as follows:
error <ANI> <channel#> <CLF timestamp> <DNIS> <Session ID> Error message

2.6 Applications

The PlumVP can run multiple applications at once. The way it does this is by assigning each DNIS on the system with an application to run.  There are two kinds of applications: URLs and user Scratch Pads.  The owner of a DNIS is allowed to set the application of that DNIS.

2.6.1 Adding a DNIS - URL

It is recommended that all development of applications be done from a user account; the application development interface is designed to support many users.  However, for production applications, where a URL - DNIS mapping is likely to remain static the admin should add a mapping from the admin interface.  This can be done using the form at the bottom of the "Applications" page.  An admin taking ownership of a new DNIS-URL takes ownership of it upon adding it, and no other users will be allowed access to the logs, or to modify that application

Editing a DNIS - URL

The admin user has permissions to view and edit all DNIS mappings on the system.  However, there are certain restrictions placed on how a DNIS can be edited.  An admin selecting the edit option for an application is only allowed to reassign that DNIS to a URL, and is not allowed to change who that DNIS is owned by.

Clearing a DNIS

A quick way to remove a user's permission from a DNIS and to clear the DNIS - URL mapping is to click the "C" link for that application.  Clearing the DNIS removes all permissions to access that DNIS for a user, and clears it from the list of claimed DNISes.  At this point the admin can add a new DNIS - URL, providing a new mapping for that DNIS.  Unassigned DNISes, when called, will play a message indicating that the number is not in service generated by the PlumVP.

2.7 Users

On the PlumVP the term "Users" is synonymous with "Developers."  Each user of the system can be assigned one or more DNISes; when this DNIS is assigned to a given user, that user is given permissions to view all debug logs, as well as the right to modify the DNIS - URL mapping.

Adding a User Account

The first step in adding a user account is to provide a username and password.  After choosing the username and entering the password twice, simply click the "Add" button.  As soon as the user account has been created, the user can log in to the PlumVP. However, the user will not be able to test any applications until a DNIS is assigned. After pressing the "Add" button the system is placed in a edit user mode.  For managing DNIS associations,

Editing a User Account

Editing a user account consists of two different settings: the user password, and the user DNIS permissions.  To change the user password, simply enter the new password twice and press the "Commit" button.

Managing DNIS Associations

Managing the DNIS associations of multiple users can be a difficult process.  In order to make this easier for the admin, Plum provides the option to choose from a predefined list of DNIS ranges and values.  For initial user setup at least one DNIS should be assigned to each user.  Assigning a DNIS is performed by first choosing a DNIS from the DNIS column, and then pressing the "Add" button.  

To reassign a DNIS, select the user you want to own the DNIS, then click the "Show all" checkbox.  This will change the DNIS drop down menu to include already assigned DNISes.  Select the DNIS you want to reassign and click "Add."  If that DNIS is already assigned, a warning will be displayed indicating that the system will override the previous settings; click "OK."

To remove a DNIS from a user click the "E" link in the Edit Column in the User Summary table.  When the user's information appears there will be a list of assigned DNISes; simply press the "Delete" button to remove the DNIS permission for the user.

Note: Changes to DNIS permissions take effect immediately and do not require pressing the "Commit" button.  Similarly, the "Cancel" button does not affect already assigned DNISes.  

Deleting a User Account

To delete a user account, find the user you wish to delete from the "User Summary" table, and click the "D" link in the Delete column.  A warning will appear that you are deleting a user and that it will free all associated DNISes and scratchpads; click OK.

2.8 Configuring Global Platform Attributes

The Server Config page allows the admin to adjust various platform specific settings. All of the settings in this section require the PlumVP to be restarted for the changes to take effect.  Many of these settings are from the initial setup phase.

Server ID

If you have multiple Plum systems running on your network, each should be given an unique ID; this allows each box to share its TTS and ASR engines.  Also, if you are using your own reporting tools, having a unique ID allows reporting to include logs from multiple systems.

DNIS Settings

Depending on your telephony configuration you may see a variety of interfaces, depending on your telephony configuration.  For analog and loopstart channelized T1 (cT1) systems you will be given the option to configure the channel to DNIS (dialed number) mappings.

For E&M cT1 and ISDN based systems you will be given the option to provide a DNIS range(s).  To enter multiple DNIS block ranges, enter each range as XXXX-XXXX and place a comma between each range.

ASR and TTS Configuration

For configurations using a shared ASR and TTS setup, the IP address of the ASR or TTS engine you would like to connect to should be provided here.  Note: If multiple systems are sharing an ASR or TTS engine be sure to provide a unique server ID for each of those systems.

Bargein and Silence Threshold

One of the features of the PlumVP is that it is possible to customize the bargein (speech) and silence (end of speech) threshold settings to best suit your environment.  The settings are useful if there is considerable line noise, or if the general volume of the line is too low.  The best way to decide what settings are right for your environment is to create a simple speech recognition program, and then use the system's built-in utterance logging to listen to how the system is terminating the recognition.

Number of Rings

On analog systems the number of rings before the system picks up the phone is configureable.  There are two recommended settings for this. In the case of systems that want to collect ANI (caller id) the number of rings should be set to 2.  For all other systems the number of rings should be set to 0; on an analog system this means that the system will pick up in the middle of the first ring.

2.8.6 Caching Engine Settings

There are three options when choosing a caching engine: aggressive caching, no caching, or external proxy.  The Plum aggressive caching engine is a standard HTTP compliant caching engine; however, developers tend to be confused by its default settings.  If the PlumVP fetches a static file, that file will not be refetched until it is considered stale. Changing the file on the web server does not make this stale; it is a value stored by the caching engine.  This behavior can be changed through the use of caching parameters when fetching a file within a VoiceXML page.  Some developers may find that while initially developing their applications, having no caching is useful.  However, when that application goes into production caching should be enabled for performance reasons.

2.8.7 Default Message

When calls come in to a DNIS for which there is no application set, the platform can play one of two messages. The platform can either inform the caller "This number is not in service" or it can process a VoiceXML script that tests all of the major subsystems of the platform.

2.9 Changing the Admin Password

Changing the admin password is as simple as entering the new password twice and clicking "Apply".  The system will save the new password, and for all future logins that password should be used.


3. User Procedures

3.1 Setting a DNIS



To configure a DNIS select the DNIS from the drop down menu, and press Edit.  This will open the "Set Application" window.



To set the DNIS to a URL, select the URL radio button and then enter the remote URL in the text area next to it.  From this interface there is also the option to open that URL in a new window, or to validate the URL.  Once the URL has been entered, press "Commit." This will store the DNIS  - URL mapping and close the window.

To set the DNIS to a Scratch Pad, select the Scractch Pad radio button and then select the scratch pad you wish to use.  From this interface you can edit the scratch pad you have selected or validate it.  Once the scratch pad has been selected, press "Commit." This will store the DNIS - Scratch Pad mapping and close the window.

3.2 Debug Logs

All logs for the user are available on the "Application Setup" page.  Clicking the log type link corresponding the the DNIS you wish to debug will open that log.

3.2.1 Last Logs

In order to view a debug log you must select the DNIS you want to debug, choose the "Last Call Completed" option, and then press "Open."

This will open a standard log window.  The top frame displays information about the last log, including DNIS, starttime, duration, and last error that occurred. The bottom frame displays the actual contents of the log file, color coded to emphasize errors that have occurred. Note: The "Save As..." button is provided as a convenience and does not work in all web browsers; if you are not using Internet Explorer you can simply right click on the bottom frame and select "Save Page As..." from the drop down menu.

3.2.2 Live Logs

The live logs are provided to improve the user's understanding of the log files.  Using the live logs you can enter a currently active session to view the users' interaction and the execution of the system.  These log files contain the same data as the debug logs, except that they are streamed to the web browser in real time.  After a session is complete the live log will wait for the next session to begin on the provided DNIS.  For optimal performance a high speed broadband connection is recommended for remote systems; for local systems a LAN connection is preferred.

3.2.3 Last Utterances

The last utterance logs are provided to complement the debug logs.  For each last call to a DNIS all of the audio used to determine responses to speech recognition are provided.  These audio files are the last utterances for the DNIS.  The format for the recordings is 8bit u-law encoded wav files.


3.3 Scratch Pad Manager


3.3.1 Creating a New Scratch Pad

To create a new scratch pad select the new option from the drop down menu and click "Edit"; this will open up the scratch pad editor interface.



Once the scratch pad has been given a label, you can save at any time.  After you have saved the scratch pad it will be available in the scratch pad manager.

3.3.2 Editing a Scratch Pad

The scratch pad manager can also be used to edit a preexisting scratchpad.  Select the scratch pad you wish to edit from the drop down menu and the click "Edit"; this will open the scratch pad editor.  The interface is the same as creating a new scratch pad, only the label has been locked and cannot be edited.

3.3.3 Deleting a Scratch Pad

To delete a scratch pad, locate it in the list of scratch pads at the bottom of the scratch pad manager screen, and press the delete button next to it.  This will display a confirmation to delete.  A javascript warning will appear to confirm the deletion of the scratch pad.  The warning will also indicate if that scratch pad has been assigned to any DNISes.

3.4 Developer Tools

The Developer Tools are provided to make developing applications easier; they include remote URL and scratch pad validators, as well as useful links to developer resources.

3.5 Changing the User Password

Changing the user password is as simple as entering the new password twice and clicking "Apply."  The system will save the new password, and for all future logins that password should be used.



4. Command-Line Interface
The command line interface for the PlumVP is a low level box access for the administrator.  From this interface the system admin can change the IP address of the box, change the login password, reset all of the PlumVP configuration, shut down the computer, or restart the computer.  These options are not appropriate for the web interface and have been made available here.


4.1 Changing IP Address Settings

The first step in changing IP address settings is to reenter the password for the user account.  Next will be prompts for the new IP address, netmask, nameserver IP address, and gateway IP address.  When updating these settings remotely be extremely cautious; an incorrect setting can mean a trip to the datacenter.

4.2 Changing Hostname

Changing the hostname will update the platform's official hostname and update the static hosts file. The changes will be reflected immediately at the login prompt. However, restarting the server is recommended.

4.3 Changing Default Password

Changing the default password is as simple as entering the old password and then reentering the new password twice.  This will change the password for all future logins.

4.4 PlumVP Configuration Reset

The option to "Completely reset the Plum Voice Platform platform configuration" should be used with extreme caution. Selecting this will remove all configuration of the system -- this includes all users, all DNIS - URL mappings, and all user scratchpads. This option should only be used if the system needs to be completely reset to the state in which it was shipped (and in some cases prior to it being configured by Plum).

4.5 Enable FTP Access

This option will enable or disable FTP access for the "plum" account. Any files deposited in the directory will be accessible through the platform's web server at the URI: "/~plum/filename".

4.6 Set Date/Time

This option will set the date and time for the server and update the hardware clock as well.

4.7 Shutdown the Server

This option will shut down the server; it should rarely be needed.  Note: This option should be used with caution, since a server with no power will not be accessible remotely.

4.8 Restart the Server

This option will restart the server; it should rarely be needed.

4.9 Logout

This option logs you out of the command line interface.




For more information about Plum VoiceXML products and services, contact us:
web: www.plumgroup.com
e-mail: sales@plumgroup.com
phone: 800-995-PLUM