
		IVR Developer Sample: Room Reservation


Overview
--------

This tutorial shows how to create a simple but non-trivial IVR application using Voicent IVR Studio. It is recommended that readers first finish the basic IVR Studio Tutorial. The sample IVR application is a room reservation system that people can call in to make or cancel a room reservation. The usage of the system is described below:

* To reserve a room, a user enters the room number and the meeting time. If the time slot is available, the room is reserved for this caller; otherwise the desired room and time are saved, indicating the caller is interested in the time slot. Once a room is reserved, a confirmation email will be sent automatically.

* To cancel an existing reservation, the system will prompt the user with existing reservations and ask the user to press a key to cancel or check the next one. If cancel is selected, the system remove the reservation from the system.

* If the room later becomes available due to cancellation, the system will check if there is any user maybe interested in the newly available time slot. If it does find one, the system automatically calls the user, indicating that the room is available for the specified time slot.

This application will utilize a database to keep room and user information. It is assumed that readers are familiar with relational databases, such as MySQL.


Database
--------

This sample makes heavy use of a database, which we assume you are familiar with already. To learn more, please take a look at MySQL database and its admin tools like phpMyAdmin. You can also setup a local test environment on your computer by downloading and installing a pre-packaged installer like XAMPP, which is usually much easier to setup. Once XAMPP is installed type 'localhost' into the address bar of a browser to enter the XAMPP setup. Enter your language and then click on security to set your SQL and Apache passwords. Once XAMPP is installed and running, pgpMyAdmin can be opened by typing "localhost/phpmyadmin" into a web browser address bar.

The phpMyAdmin window will open. Select the Databases tab. If the Databases tab does not appear click the home button on the left.

Create a new Database called room_reservation. The default 'Collation' will be OK for the character set.
 
After creating the new database select it in the left pane.

In this sample, we use the following three database tables: user_profile, room_profile, and room_schedule. The SQL scripts shown here are for MySQL database. Make sure the Click the SQL tab to open the input window.

* USER PROFILE TABLE

The table: user_profile is used to store user information, such as phone number and email address. Copy or type the following code into the SQL text window and select Run to create the following three tables:

CREATE TABLE IF NOT EXISTS user_profile (
    user_id int(11) NOT NULL AUTO_INCREMENT,
    phone_number varchar(32) NOT NULL,
    email_addr varchar(64) NOT NULL,
    PRIMARY KEY (user_id)
);

* ROOM PROFILE TABLE

The table: room_profile is used to store room information, such as room number and room size.

CREATE TABLE IF NOT EXISTS room_profile (
    room_id smallint(6) NOT NULL,
    room_size smallint(6) NOT NULL,
    PRIMARY KEY (room_id)
);

* ROOM SCHEDULE TABLE

The table: room_schedule is used to store room reservation information, such as meeting room and time

CREATE TABLE IF NOT EXISTS room_schedule (
    room_id smallint(6) NOT NULL,
    user_id int(11) NOT NULL,
    reserve_status enum('reserved','waiting') NOT NULL,
    start_time datetime NOT NULL,
    end_time datetime NOT NULL
);

* INSERT SOME DATA

Once the tables are created, you can populate it with some initial data. Run the following SQL statement and make sure to replace the user_profile data with your own information.

INSERT INTO room_profile (room_id, room_size) VALUES

(200, 10),
(300, 20);

INSERT INTO user_profile (user_id, phone_number, email_addr) VALUES
(100, '14080001111', 'you@yourcompany.com'),
(101, '16501112222', 'me@mycompany.com');


JDBC Driver
-----------

In order to access the database, a JDBC driver is needed. For mysql database, the mysql-connector.jar is included in the package.


Build.bat
---------

A simple batch file for compiling the java program is included. You may need to change the installation path to your JDK installation.




Steps to Create the IVR App
---------------------------

* room_reservation_step1.ivr:

Create a simple main menu and utilize a database action to check the caller ID. This app require callers to be pre-registered with database with their phone number. The app authenticate the caller by its caller ID. With db action, you can do SQL statement directly. In this action of the 'welcome' element:

SELECT * FROM user_profile WHERE phone_number = '${__VG__CALLER_ID_NUMBER__}'

where ${__VG__CALLER_ID_NUMBER__} is the system variable for call ID.


* room_reservation_step2.ivr:

Extension step1 to collect user input for rooom selection etc. In the DoReserve element, a java action is used to do more complicated database access. The java program is listed in RoomReservation.java. 

Write the Java program as usual. The only requirement is that the return type of the java program should be java.util.Properties
if there are multiple name value pairs need to be returned. The name value pairs can be then accessed from your IVR application in IVR Studio. Simply use the dot notion to access the value, such as: 'doReserve.status', where 'doReserve' is the name for the java action, and 'status' is one of the name value pairs returned.

To invoke a particular method of the class, simply specify it in the java action.

You must also specify the arguments for the method. The argument must be specified with the actual java class name, such as java.lang.String, and the value.


* room_reservation_step3.ivr:

This step adds an email confirmation to the IVR app. The email is sent using the email action. As usual, you can use variables in your email content:

Room Reserved: ${theRoom}
Date: ${theDate}
Time: ${theTime}

Make sure to specify the email server info.


* room_reservation_step4.ivr:

This step adds TotalReservation sub tree in the IVR app. Based on the java program returns, the IVR app loops through the room reserved, asking caller to keep or cancel.

In the Notify element, an HTTP action is used to post an HTTP request, which is like submit a form to a web server. In this sample, the request is submitted to Voicent gateway, which contains a web server.

The HTTP post url is: localhost:8155/ocall/callreqHandler.jsp

which is the address to send an outbound call from the gateway, using the simple call interface.


* room_reservation.ivr

The last step adds call handling for unauthorized caller. It simple transfer the call to help desk or collect voicemail.



Summary
-------

This sample contains most frequently used IVR Studio built-in actions.




