TeleFlowRelay Media Authorization and Content Creation
From TeleFlow
Contents |
Media System
The Media Management system is used to manage the creation of content via TeleFlow applications. Files are created in the following directory by TeleFlow applications. TeleFlow can receive the name of the file to record thought the MediaFileCreateNew XML command, along with others.
- Relative www (../)
- $incPath
- Client media (CLIENT_MEDIA_AREA)
- define("CLIENT_MEDIA_AREA", "cr_client_media");
- Client folder
- $uploadroot.'/client_'.zeroFill($mClient_id,5); //.'/recordings';
- Date folder
- yyyy-mm-dd
Processing and Command files
- xml_media_publish.php - Create and eventually mark recordings as ready for processing. This information is provided by XML request so that both web and TeleFlow applications can interact with the media environment
- cr_media_file_transfer.php - Scans client databases, and checks the application subscription for MEDIA_XFER, and processes and transfers the recordings appropriately.
- mediaWorkUnit.php - Defines the names of the recordings, along with how interim files are named
Creating a New Recording
When a local TeleFlow needs to create a new recording, it contacts a local copy of xml_media_publish to know how to create the file
- TeleFlow: Ask for File Name (MediaFileCreateNew) via XML Request to (cr_transfer_system/xml_media_publish.php)
Optionally:
- TeleFlow: Provides the file name (MediaFileCreateFileName) via XML Request to (cr_transfer_system/xml_media_publish.php)
- xml_media_publish.php: Runs MediaFileCreateNew or MediaFileCreateFileName which inserts a new entry into the media_file table, returns mediafile_pk
- TeleFlow: Records the file name sent or requested, and remembers the mediafile_pk
- TeleFlow: Once recording is completed, MediaFileComplete via XML Request with pk and details goes to (cr_transfer_system/xml_media_publish.php)
Optionally:
- TeleFlow: Once recording is canceled, MediaFileCancel via XML Request with pk goes to (cr_transfer_system/xml_media_publish.php)
Once the recording is completed, it is stored in the CLIENT_MEDIA_AREA (define constant) using the client_xxxxx and date for the path. This is where the file resides until cr_media_transfer.php processes the recording. (See Media Transfer)
Media Transfer
Note: This program runs in a loop, and will transfer files to other servers or locations by watching the media_files table for new files created by TeleFlow XML calls (see TeleFlow Voice Application)
- cr_media_transfer: Cycles each client checking to see if there is new work to do. This happens occasionally and throughout the day
- cr_media_transfer: Will convert files to other formats, and then transfer by various means including FTP, FTPS and HTTP Post
HTTP Post Publish
- cr_media_transfer: When this method is used, MediaFileReceive
Media File Creation Example
The following steps will create a media recording or file with the following codes being applied as the file is recorded and eventually processed by the media system.
- CREATED - A file name is requested using MediaFileCreateNew
- NEW - The file is recorded successfully, completed and ready for processing by using MediaFileComplete
- ABANDONED - The user abandoned the file, so it is dropped by using MediaFileAbandon
- SAVED - Processed by another application elsewhere, the recipient decided to save the recording
- DELETED - Processed by another application elsewhere, the recipient decided to delete the recording
The following documentation provides an overview of the file creation environment by TwitYax (an open source application for use TeleFlowRelay). The steps can apply to any application from voice messages to dictation to call recordings, and are created with the following steps:
Authorize a Caller / User
In this case, the TwitYax application will request via XML a file name to record once authorization is completed to ensure a user has the right to record a Yax. All recordings performed by TeleFlow is considered content creation, and is handled by the media management system command using:
Authorization is checked by evaluating the telephone number of the current caller / user. It is assumed that caller id will be used in conjunction with a password to quickly determine if a caller is authorized to use the system.
<REQUEST action="Authorize" client_id="2" app_type_name="TWITYAX" caller_id="6045554457" caller_pass="123456"></REQUEST>
A success result will be:
<RESPONSE action="Authorize"><SUCCESS action="Authorize" user_id="39" result="0">User is Authorized</SUCCESS></RESPONSE>
A fail result will be:
<RESPONSE action="Authorize"><FAILURE action="Authorize" result="3" callerID="6049284457" callerPassword="12334567">Invalid Password</FAILURE></RESPONSE>
Response codes for failures are:
- -1: Couldn't connect to the database. "Database Error"
- 2: Database indicates that user has not confirmed their account. "Account has not yet been activated"
- 1: User does not exist. "Username could not be found"
- All others: General error. "Invalid Password"
TeleFlow Requests a File Name
Once authorized, the next step is to request a file name to record. The following command takes care of creating all folders (date name included for ease of management), and file names which include information within the file name itself. Include the user_id if you would like to assign the user as the owner of the recording.
<REQUEST action="MediaFileCreateNew" client_id="2" user_id="39" app_type_name="TWITYAX" media_file_type="RECORDING" ivr_port="12" called_number="6046396391" calling_number="6046170310"></REQUEST>
- Note: ivr_computer_name="KORE" can be added, however, TeleFlowRelay will select the computer name on which it runs if this parameter is not included. Generally, you should let TeleFlowRelay read and store computer name unless you expect the file to occur on a different system due to specific programming.
The response is:
<RESPONSE action="MediaFileCreateNew"><SUCCESS action="MediaFileCreateNew" result="SUCCESS" type="DB" media_file_id="20" media_file_fullpath="c:\TeleFlowRelay\cr_client_media\client_00002\2009-08-18\TWITYAX_2_RECORDING_20090818193810_012_6046396391_6046170310.wav" media_file_name="TWITYAX_2_RECORDING_20090818193810_012_6046396391_6046170310.wav">Creating TWITYAX_2_RECORDING_20090818193810_012_6046396391_6046170310.wav</SUCCESS></RESPONSE>
A second method of creating a file is if the TeleFlow application creates the file name, and passes it through to the media processor. This is provided using:
- action=MediaFileCreateFileName
with a file parameter
- media_file_name
The media_file_name must be a full path of the recording, and will be referenced using media_file_id, which is returned.
Complete or Abandon a Recording
The media_file_fullpath result is recorded to by the TeleFlow Application. The media_file_id is also remembered so that the file status can be updated once the recording is completed. The XML request to complete the recording is:
<REQUEST action="MediaFileComplete" client_id="2" media_file_id="20"></REQUEST>
The response is:
<RESPONSE action="MediaFileComplete"><SUCCESS action="MediaFileComplete" duration="190" result="SUCCESS" type="DB" media_file_id="20">Updating 20 to SAVED</SUCCESS></RESPONSE>
The duration, UTC times were set, and the client_application_subscription table was updated to show MEDIA_XFER as set for processing. Refer to cr_file_media_transfer for the steps that are carried out when MEDIA_XFER is set for a client.
Should the recording not be required, or was abandoned by the caller / user, then the file should be marked as abandoned with the following command.
<REQUEST action="MediaFileAbandon" client_id="2" media_file_id="20"></REQUEST>
The response is:
<RESPONSE action="MediaFileAbandon"><SUCCESS action="MediaFileAbandon" duration="0" result="SUCCESS" type="DB" media_file_id="20">Updating 20 to ABANDONED</SUCCESS></RESPONSE>
This process will also destroy the recording if the file was created before the caller / user chose to abandon it.
