// ---------------------------------------------------------------
//
// -----------------------------------------------------
//	copyright 2000 by voxeo corporation. (see LGPL.txt)
// -----------------------------------------------------
//
//	v1.0 Coded in CallXml, HTML, and Cold Fusion
//	v1.0 Coded by Dev Bradley
//
// ---------------------------------------------------------------
//
//	Call Center (cc) is an application that allows incoming calls 
//	to transfer to the first available telephone number in a group.
//	Each called number is assigned to a transfer group.
//	Destination telephone numbers are added to each group and can be
//	ordered to allow them to be connected in sequence if desired.
//	Each location in the Group gets called until one gets answered, 
//	and if the call is answered, the caller is connected to it.
//	If there is no answer at that location, the next location is called.
//	After all locations in a Group have been called with no answers, 
//	the caller is informed and the call is disconnected.
//
//	There are 2 tables in a database which are used first to assign
//	an incoming call to a group, and second, to get all phone numbers
//	which are in that group.
//
//	This application uses ColdFusion to access a back end SQL database and
//	to dynamically generate HTML and CallXML.
//
// -------------------------------------------------------------------
//
//			Server Requirements
//
//	To properly run this application, the server it is installed on 
//  	must be visible from the internet. ColdFusion Server 4.5 must be
//	installed and fully functional on the server. Modifications to the
//	application can be done with any text editor, however, application
//	development is simplified by using ColdFusion Studio 4.5 from allaire.
//	Instructions on installing and configuring ColdFusion products can be
//	obtained from allaire at http://www.allaire.com/developer/index.cfm
//
// -------------------------------------------------------------------
//
//			Quick Start Instructions Overview
//
//	1. Unzip the CallCenter.zip package
//	2. Connect the database file as an ODBC data source
//	3. Point a community.voxeo.com phone number to the voice application
//	4. Modify the database to create a group of destination phones
//	5. Call the community.voxeo.com phone number to test the transfers.
//
//
//			Quick Start Instructions Details
//
//	1. Unzip the CallCenter.zip package
//
//		a. Create a folder (or directory) on your server which will hold
//			the CallCenter application files.
//
//		b. Copy the CallCenter.zip file into the folder.
//
//		c. Unzip the contents if the CallCenter.zip file into the folder.
//
//		d. Confirm the contents of the folder from the file list below.
//
//
//	2. Connect the database file as an ODBC data source
//
//		a. Use a web browser and start the ColdFusion Administrator with
//			http://(Server Name)/Cfide/Administrator/index.htm
//
//		b. Enter the ODBC password on the form and press the Password button.
//
//		c. Under "data sources" on the left, press the "ODBC" link.
//
//		d. If "CallCenter" is in the "Data Source Name" list,
//			Stop, it is already connected.
//
//		e. Otherwise, press the "Add..." button under "ODBC Driver"
//
//		f. Fill in the "Create ODBC Data Source" form.
//
//			Data Source Name = CallCenter
//
//			Database File - Press the "Browse Server.." button to find
//				the CallCenter.mdb file.
//
//			Leave everything else in the form as it is when it comes up.
//
//		g. Press the "Create" button to create the data source.
//
//		h. "CallCenter" should now appear in the "Data Source Name" list.
//
//		i. Press the "Verify" link on the right side of the "CallCenter" line.
//
//		j. The connection to the data source should verify successfully.
//
//
//	3. Point a community.voxeo.com phone number to the voice application
//
//		a. Point your browser to the voxeo community page:
//			http://community.voxeo.com/
//
//		b. Click on the "account login" button
//
//		c. Create an account if you do not already have one by
//			pressing the "you can get one here" link.
//
//		d. If you have an account, press the "log in here" link.
//
//		e. After log in, you should be on the "account administration" page.
//
//		f. Press the "phone number administration and url mapping" link.
//
//		g. Fill in the url mapping form:
//
//			select a city: - pick one close to where you are
//
//			select number type* - Leave it on the "CallXML" default
//
//			url: - point to the cc_c_Answer.xml file
//
//		h. Press the "Add Mapping" button
//
//		i. A new number should appear with the URL
//
//		j. Test the URL link by pressing it.
//
//		k. You should see a XML file that starts with the following 3 lines:
//
//	<?xml version="1.0" encoding="UTF-8" ?> 
//	<!--  ================================================================   --> 
//	<!--      copyright 2000 by voxeo corporation. (see LGPL.txt)            --> 
//
//
//	4. Modify the database to create a group of destination phones
//
//		a. Point your browser to the cc_d_admin.htm file.
//
//			A page should appear with 6 panels, 3 across and 2 down.
//
//			The example data in the database tables can be examined by
//			pressing the arrow buttons in the top panel of each column.
//
//			Single arrows advance the selection by a single item. 
//			Double arrows go to the end (or beginning) of the list.
//
//			The left side panels are for mapping incoming phone numbers 
//			to groups. A Called phone number is 10 digits starting with
//			the area code. Groups can have any name you choose.
//
//			The center panels are for selecting a group which limits the
//			display of the right side panels.
//
//			The right side panels are for mapping a selected group to a
//			list of destination phone numbers. The order field is used
//			to control the sequencing of the phone numbers. The phone
//			numbers are 11 digits, starting with a "1" plus the area code.
//
//			The order in which the phone numbers appear in the group, is
//			the order that is used to try to connect the caller.
//
//		b. Press the "Add" button in the top left hand panel.
//
//		c. Fill in the "Called Edit Record" form.
//
//			CalledID: - This is the 10 digit phone number assigned 
//				from the community page (step 3.j) above.
//
//			Group: - Enter a group name such as "test"
//
//		d. Press the "OK" button and view the new entry in the list.
//
//
//
//	5. Call the community.voxeo.com phone number to test the transfers.
//
//
//
//
//
// -------------------------------------------------------------------
//
//	The entire suite contains 24 files and 1 sub directory with 8 audio files:
//
// -------------------------------------------------------------------
//
//			Database
//
//	CallCenter.mdb			a sample database in MSAccess
//
// -------------------------------------------------------------------
//
//			CallXML Voice Application
//
//		To start the voice application, point a phone number to cc_c_Answer.xml
//
//	cc_c_Answer.xml			CallXML application starting document
//		Answers the call and starts (goto) cc_cr_Hold.cfm
//
//
//			CallXML Routines:
//
//	cc_cr_Hold.cfm			CallXML routine to wait for a phone to answer
//		Starts (run) cc_cr_CallGroup.cfm and plays hold music
//
//	cc_cr_CallGroup.cfm		CallXML routine to call each phone in a group
//		Calls a phone and, if no answer, restarts (run) itself
//
//
//			CallXML Modules:
//
//	cc_cm_PlayMessage.cfm		CallXML message module
//		Plays .wav file or a text message
//
// -------------------------------------------------------------------
//
//			Display Application For Database Administration
//
//		To start the Display Application, point a browser to cc_d_admin.htm
//
//	cc_d_admin.htm			Display application starting page
//		Redirects browser to cc_ds_View.cfm
//
//
//			Display Screens (Each contains up to 6 panels):
//
//	cc_ds_View.cfm				View and browse all records
//	cc_ds_EditCalled.cfm		Allows editing of a Called record
//	cc_ds_EditTransfer.cfm		Allows editing of a Transfer record
//	cc_ds_DBModified.cfm		Pass through when the database is modified
//		This pass through is needed to allow the database updates to complete 
//		before the next database "SELECT" in the cc_ds_View.cfm screen.
//
//
//			Display Screen Modules (Creates a uniform look to all screens):
//
//	cc_dm_Bottom.cfm		Display module to finish an HTML page
//	cc_dm_Title.cfm			Display module to start an HTML page
//
//
//			Display Panels (Components to a screen):
//
//	cc_dp_Called_RecordView.cfm	To view and select a Called record
//	cc_dp_Called_TableView.cfm	To view all Called records
//	cc_dp_CalledRecordEdit.cfm	To edit a called record 
//		(Edit panel is activated with "Edit" and "Add" buttons)
//
//	cc_dp_Group_RecordView.cfm	To view and select a Group
//	cc_dp_Group_TableView.cfm	To view all Groups
//
//	cc_dp_Transfer_RecordView.cfm	To view and select a Transfer record
//	cc_dp_Transfer_TableView.cfm	To view all Transfer records in a Group
//	cc_dp_Transfer_RecordEdit.cfm	To edit a Transfer record
//		(Edit panel is activated with "Edit" and "Add" buttons)
//
//
//			Display Form Action Routines (Used when a button is pressed):
//
//	cc_da_Called_RecordAction.cfm	Action routines for Called Panels
//	cc_da_Group_RecordAction.cfm	Action routines for Group Panels
//	cc_da_Transfer_RecordAction.cfm	Action routines for Transfer Panels
//
// -------------------------------------------------------------------
//
//
//	cc_Voice	Folder holding all audio files
//
//		All audio files are PCM format, 8-bit, mono, unsigned.
//
//
//	Audio File Name		Module Usage	Text
//	---------------		------------	----
//	cc_Greeting.wav		cc_c_Answer.xml	Thank you for calling the call center.
//
//	cc_Hold.wav		cc_cr_Hold.cfm	Please hold while we connect you to an agent.
//	cc_NoAgents.wav		cc_cr_Hold.cfm	No agents are currently available to service your call.
//	cc_HangUp.wav		cc_cr_Hold.cfm	Please hang up and try your call again later.
//	cc_Group.wav		cc_cr_Hold.cfm	Call Center Transfer Group is... #FoundSkill#.
//	cc_Connecting.wav	cc_cr_Hold.cfm	Your call is connecting to an agent, now.
//
//	cc_NewCaller.wav	cc_cr_CallGroup.cfm	Please hold for a new caller.
//
//
// -------------------------------------------------------------------
// 
// The database is an ODBC resource named CallCenter
// and contains two tables "CalledGroups" and "GroupTransfers" described below.
//
//	CalledGroups - This table contains all incoming called numbers with group assignment
//
//		CalledID - Primary key - Called telephone number (DNIS)
//		callType - Always set to "P" (not currently used)
//		group - Group name
//
//	GroupTransfers - This table contains a transfer numbers in each group
//
//		ID - primary key - internal unique sequential number
//		group - Group name
//		order - Used to force a specific sequencing of the transfer numbers
//		callMaxTime - Number of seconds to allow the phone to ring
//		phone - Telephone number to transfer to, format: 14085551234
//
// -------------------------------------------------------------------
//
//		Voice Application call flow:
//
//	cc_c_Answer.xml
//
//		Greet Caller
//		Goto cc_cr_Hold.cfm
//
//	cc_cr_Hold.cfm
//
//		Start playing hold music (maximum of 3 times)
//		Set Group based on a Select to CalledGroups with Session.CalledID
//		Set order to ""
//		Run cc_cr_CallGroup.cfm
//
//		On Answer, conference to other session
//
//		Any other, play message and disconnect
//
//	cc_cr_CallGroup.cfm
//
//		select phone, order, callMaxTime 
//		from GroupTransfers 
//		where group = #Group# 
//		and order >= than #order#
//		and phone > #phone#
//
//		Call phone
//
//		On Answer, raise "answer" to cc_cr_Hold.cfm session
//
//		Any other, Run cc_cr_CallGroup.cfm - recursive through Group
//
// -------------------------------------------------------------------
