ShoreTel Voice Forms IVR Application User Guide - Amazon Simple ...

ADMINISTRATION & USAGE GUIDE

SHORETEL VOICE FORMS IVR APPLICATION ShoreTel Professional Services

Introduction This application provides an Interactive Voice Response (IVR) system to interface with callers who wish to place orders and have those orders recorded and the recordings submitted to a ShoreTel voice mail box. The system is driven by an XML configuration file which defines the settings for the system as well as for each script. A script or form is associated with a given extension (a ShoreTel Route Point) and inbound calls to the extension are handled by the script after the call is answered. Scripts typically play some form of greeting and then consecutively prompt for various data items and record each response into a single wave file. When the user hangs up or the script completes or the user is given a menu of options, the voice mail message containing the wave file is created and posted to a voice mail box associated with the script. If a menu is provided it can include options to start another order, transfer the caller to an operator (also associated with the script) or transfer to an extension. New in version 3.1.0 we now support a separator prompt setting which causes a pre-recorded wave file to be appended after each recorded segment. This helps to make it clear where each response lies.

ShoreTel Voice Forms IVR Application

Page 1 of 12

6/28/2012

Contents Introduction ......................................................................................................................... 1 Contents .............................................................................................................................. 2 Requirements ...................................................................................................................... 2 Licensing ............................................................................................................................. 2 Installation........................................................................................................................... 2 Configuration ...................................................................................................................... 4 Creating the Route Point ..................................................................................................... 8 Creating Wave Files for Scripts .......................................................................................... 9 Logging ............................................................................................................................. 11

Requirements   

This server must be installed on a ShoreTel Headquarters of Application (DVS) Server. This server requires the .NET 2.0 runtime to be installed on the server. If it is not, the setup program will detect this and the user will be directed to the Microsoft web site to download and install the runtime. This application is a licensed application. This means that in order to run correctly the corresponding ShoreTel Professional Services licensing server must be installed on the customer’s ShoreTel Headquarters server and an application specific license must be configured.

Licensing Before installing this application you should first install the required license. This could be a trial license or it could be a permanent license. If a trial license is used this will allow full usage for up to 45 days at which point a permanent license must be installed for this application to continue to function. If there is a problem with this application’s license after the service has started then the application will log the issue to its log file as well as adding an event to the Windows Event log. The customer will have up to three days to resolve the issue. If the issue is not rectified in this time period then the server will stop routing calls and all calls will be sent to the script’s error extension.

Installation To install the application you'll want to unzip the STVMForms.zip file. This contains a setup program and associated MSI install file. After unzipping the files to a folder, run the STVMFormsSetup.exe from the folder. If the .NET 2.0 runtime needs to be installed then you will be directed to the Microsoft web site to download it. Once it is installed the setup should start to run and this screen should be displayed:

ShoreTel Voice Forms

IVR Application Page 2 of 12

6/28/2012

Click Next at each screen to install the application and when complete, click Close. The service should be installed and configured to run automatically every time the server is restarted. It should also be automatically running although as initially configured, it won't actually do anything until some additional configuration is made and the service restarted. You can verify that the service is installed as well as stop, start or restart and change its startup mode by running the Windows Services application and looking for the "ShoreTel Professional Services VM Forms Server" service:

ShoreTel Voice Forms

IVR Application Page 3 of 12

6/28/2012

While the server comes with a preconfigured XML file based on the customer specifications along with prerecorded wave files, it is still necessary to edit the XML file to set the route point, voice mail and operator extensions associated with each of the scripts. While a script will still be processed, until the values are set, it will not be functional.

Configuration All of the configuration for the server is via modifying an XML file and then restarting the server's service. The XML file is located in the application's install directory. Assuming you accepted the default install location, this file will be located at: C:\Program Files\ShoreTel\ShoreTel Voice Mail Forms Server\STVMForm.xml To view the file, double click it to show it in Internet Explorer. To edit it, you can use any XML or text editor. This shows the file open in Internet Explorer:

The XML consists of two main node types:

ShoreTel Voice Forms

IVR Application Page 4 of 12

6/28/2012



STVMForm This is the root node for the settings. The service level settings are set via attributes of this node. The following are the attributes used by this node:  RecordTimeout (Default if not set is 30 seconds) This is the maximum time, in seconds, that a record segment will be allowed. If the user does not press the pound key (#) within this time then the recording to that point is saved and the caller is transferred to the scripts operator extension.  MenuTimeout (Default if not set is 5 seconds) This is the maximum time, in seconds, that a menu will wait for user input. If no input is received in that time, the menu will repeat and wait again. If there is still no response after the third repetition then the call will be transferred to the script's configured operator extension.  LogLevel (Default if not set is 1) This sets the level of logging. Level 0 is no logging. Level 1 logs startup, shutdown, settings and any errors in the settings and/or with the execution of scripts. Level 2 logs level 1 as well as logging each call processed. Level 3 logs level 2 as well as low level events. Generally level 1 or 2 would be appropriate.  STLogLevel (Default if not set is 0) This sets the level of logging for the internal ShoreTel COM object which provides the interface to the telephony events. This ranges from 0 (no logging) to 3 (full logging.) In general, this would only be enabled if requested by ShoreTel Professional Services in the event of a problem.  STLogWave (Default if not set is false) This enables low level logging of the wave file related events and requests. For wave logging to be enabled the STLogLevel must be set to 3 along with this setting set to “true” or “True”. The default is no wave logging. In general, this would only be enabled if requested by ShoreTel Professional Services in the event of a problem.



Script Contained in the STVMForm node are zero or more script nodes. The script nodes contain three types of sub nodes, Play, Record and Menu. A script has several settings set via attributes of the script node. These are the valid attributes which can be used:  Name This is the name of the script. This will show up in the logging related to the script.  RoutePoint This is the extension of the ShoreTel route point device which triggers this script. Each script is started by a call offering at the route point. The server answers the call and starts the execution of the script. See the section below on creating the route point in ShoreTel's Director.

ShoreTel Voice Forms

IVR Application Page 5 of 12

6/28/2012









MailBox This is the extension of the ShoreTel Voice Mail box where recordings made of callers into this script should be deposited. Scripts send their recorded file to this mailbox when the caller hangs up, when the script executes a menu and in the case of any errors. Operator This is the extension of the ShoreTel extension which should receive calls when the user requests it via the Menu Operator node type (see below.) Note that this can be pretty much any ShoreTel extension type including the auto attendant, a workgroup, another script route point and so on. Error This is the extension of the ShoreTel extension which should receive calls when the user fails to respond to menu timeouts or fails to terminate a given recording before the record timeout expires. In addition, if the system encounters any failure with the call then it will try to transfer the call to this extension. SeparatorPrompt This is the name of a prompt file to be automatically appended after each recorded segment. If not included or if set to an empty string then no separator prompt is appended. The data is assumed to be the name of the file without any path or .wav suffix.

The sub nodes of the script node define the features and flow of the actual script which is executed for a caller. The nodes are executed from top to bottom or until the caller hangs up. These are the four valid node types:  Play This plays a single file from the server's wave directory. See the section below on creating wave files. You can execute several Play commands in sequence in order to form text from wave "pieces". Play has one required attribute:  File This is set to the name of the file without any path or .wav suffix.  Record This records and appends to a single wave file associated with the scripts. It does so until the user presses the pound key, the record time out is exceeded or the caller hangs up. If the record timeout is exceeded, the caller is transferred to the operator. Record has one optional attribute:  File This is set to the name of a file to play as a prompt before starting the record. Usually this prompt (or a previous play if this attribute is not used) should tell the caller to press the # key when they are done speaking.  Menu This provides a menu with choices to the caller. Menu nodes contain four types of menu item sub nodes (see below), Restart, Operator, Transfer and Label. The Menu node has one optional attribute:

ShoreTel Voice Forms

IVR Application Page 6 of 12

6/28/2012





File This is set to the name of a file to play as a prompt before the menu waits for user input. Usually this prompt (or a previous play if this attribute is not used) would tell the users what their choices are. Label This is used in conjunction with the Menu item Goto node (see below.) The Label node marks a location in the script which can be branched to from a menu. The Label node has one required attribute:  Name This is set to the name of the label and should match the Label attribute of the Goto menu item node's Name attribute.

The sub nodes of the menu node define the menu choices. The order of the choices is not important. Typically you would only use at most one Restart and one Operator node type. However, you may well want to use multiple transfer nodes and you might want to use several Goto nodes to branch up farther higher in a script. In fact, through configuring a script with Plays and a menu with a number of transfer options it is easy to build a simple call routing script. All of the choice nodes have a required attribute, Key which indicates which telephone key this choice is intended to handle. This must be set to one of the values "0" through "9", "*" or "#".  Restart This menu choice causes the script to restart from the beginning if its Key attribute is selected by the caller. A new recording (if the script uses record) will be created. Restart has one required attribute:  Key This is the digit ("0" through "9", "*" or "#") that triggers this menu choice.  Operator This menu choice causes the caller to be transferred to the script's operator extension. If for any reason we fail to transfer the call to the operator extension we have no choice except to disconnect the call. Operator has one required attribute:  Key This is the digit ("0" through "9", "*" or "#") that triggers this menu choice.  Transfer This menu choice transfers the caller to a number provided as an attribute to this node. If for any reason we fail to transfer the call to the extension then we instead try to transfer the call to the script's operator extension. Transfer has two required attributes:  Key This is the digit ("0" through "9", "*" or "#") that triggers this menu choice.  Number This is the number to transfer the caller to if they select this menu choice. This can be either an internal ShoreTel extension or it could be an external number. If you use an external number make sure that it contains the trunk

ShoreTel Voice Forms

IVR Application Page 7 of 12

6/28/2012



access code and any required prefix digits. Also ensure that the route point used by the script is in a user group allowed to make external calls. Goto This menu choice causes the script to branch up to a script Label node with a Name attribute which matches the Goto node's Label attribute. Note that unlike Restart, Goto does NOT start a new recording. Any Record nodes will continue to use the current recording file. Goto has two required attributes:  Key This is the digit ("0" through "9", "*" or "#") that triggers this menu choice.  Label This is the name of the script node Label we are branching to. It will match Name attribute of a script node Label.

Creating the Route Point Each Script node is tried to a single route point via the RoutePoint attribute. To create the route point you would run ShoreTel's Director and select the Call Control... | Route Points menu and then click "Add New" to create a new route point. You will want to set the Route Point Server to the server where this application is being installed. You will want to set the call stack to the maximum trunks or callers who will simultaneously call into the route point. If you plan to have menus which allow external transfers then you'll need to make sure the route point is in a user group with sufficient privileges. You may also want to set the call forwarding on no answer as a fail safe in case the server has a problem and stops responding to calls.

ShoreTel Voice Forms

IVR Application Page 8 of 12

6/28/2012

Creating Wave Files for Scripts The service comes preconfigured with a number of scripts and the wave files needed to support those scripts. In general, most of the wave files are reused for most of the scripts with only a few parts recorded for a specific script. The wave files are in ShoreTel voice mail wave file format. This shows the wave properties of a recording:

ShoreTel Voice Forms

IVR Application Page 9 of 12

6/28/2012

There are various tools which allow recording of wave files. You should start by recording a single replacement file for the existing scripts and make sure that the format matches and that the server can play it along with existing files. Once you've confirmed that then you can easily record the various prompts you need and modify your configuration XML file to use these new prompts. Note that you will want to fully test all scripts to ensure that all files play. If you mistype the name of a file you recorded in the XML configuration then the caller will be transferred to the operator when the problem is encountered at run time. You can examine the log while testing to see what file caused the problem. All of the wave files are stored in the Wave folder stored in the server's install directory. Assuming the server was installed in the default location this would be: C:\Program Files\ShoreTel\ShoreTel Voice Mail Forms Server\Wave This shows the directory with some of the files:

ShoreTel Voice Forms

IVR Application Page 10 of 12

6/28/2012

Logging The system supports a log file. This is useful for checking that the XML settings file was correctly processed and for resolving errors in the XML or wave files or possibly other problems. The log file is written to the server's install directory. Assuming the server was installed to the default location, this would be: C:\Program Files\ShoreTel\ShoreTel Voice Mail Forms Server\STVMForm.log The file is a simple text file which can be opened in most editors including Notepad. The level of logging is determined by the LogLevel attribute of the root STVMForm node. Level 0 is no logging. Level 1 logs startup, shutdown, settings and any errors in the settings and/or with the execution of scripts. Level 2 logs level 1 as well as logging each call processed. Level 3 logs level 2 as well as low level events. At the default level of logging (1) it will display startup, shutdown, settings and any errors. This should allow diagnosing and fixing configuration issues. This shows a sample of the logging: 1/21/2008 - 1:32:08 PM: ---------------------------------1/21/2008 - 1:32:08 PM: Log file opened 1/21/2008 - 1:32:08 PM: Voice Mail Path Set to C:\Shoreline Data\Vms\Message\ 1/21/2008 - 1:32:08 PM: Cfg Exe Path Set to C:\Program Files\Shoreline Communications\ShoreWare Server\cfg 1/21/2008 - 1:32:08 PM: ---------- SETTINGS ----------

ShoreTel Voice Forms

IVR Application Page 11 of 12

6/28/2012

1/21/2008 - 1:32:08 PM: XMLFile=C:\Program Files\ShoreTel\ShoreTel Voice Mail Forms Server\STVMForm.xml 1/21/2008 - 1:32:08 PM: STVMForm LogLevel=3, STLogLevel=3, RecordTimeout=30, MenuTimeout=5 1/21/2008 - 1:32:08 PM: 1/21/2008 - 1:32:08 PM: IMRefillNO: RoutePoint=170, MailBox=212, Operator=100, Error=110 1/21/2008 - 1:32:08 PM: Play File=GreetingSSMCPrefix 1/21/2008 - 1:32:08 PM: Play File=IMRefillNOPhoneNumber 1/21/2008 - 1:32:08 PM: Play File=GreetingSSMCSuffix 1/21/2008 - 1:32:08 PM: Play File=PromptBegin 1/21/2008 - 1:32:08 PM: Record File=PromptFirstLastName 1/21/2008 - 1:32:08 PM: Record File=PromptDateOfBirth 1/21/2008 - 1:32:08 PM: Record File=PromptDoctorName 1/21/2008 - 1:32:08 PM: Record File=PromptPharmacy 1/21/2008 - 1:32:08 PM: Record File=PromptPhoneNumber 1/21/2008 - 1:32:08 PM: >>Append 1/21/2008 - 1:32:08 PM: Record File=PromptMedicationName 1/21/2008 - 1:32:08 PM: Record File=PromptMedicationStrength 1/21/2008 - 1:32:08 PM: Menu File=MenuDefault 1/21/2008 - 1:32:08 PM: 0: Operator 1/21/2008 - 1:32:08 PM: 1: Goto Append 1/21/2008 - 1:32:08 PM: 2: Restart 1/21/2008 - 1:32:08 PM: 1/21/2008 - 1:32:08 PM: IMRefillKN: RoutePoint=171, MailBox=212, Operator=100, Error=110 1/21/2008 - 1:32:08 PM: Play File=GreetingSSMCPrefix 1/21/2008 - 1:32:08 PM: Play File=IMRefillKNPhoneNumber 1/21/2008 - 1:32:08 PM: Play File=GreetingSSMCSuffix

and so on...

ShoreTel Voice Forms

IVR Application Page 12 of 12

6/28/2012