Download This File                   Download All Documents                        Go to Home Page

Chapter 11

User Programmable Functions

User Programmable Functions make it possible to do predictive dialing (Telemarketing), test traffic generation (Blasting) and user programmed IVR's with OmniBox. 

Predictive Dialing and Blasting are outbound functions that will be executed by the OmniBlaster which is triggered from the a specially featured OmniMonitor (see below) by selecting (marking) channels and then hitting Start Blast.  

User programmed IVR's are triggered by an inbound call into a Domain with  a Function  that matches a user programmed state machine ID (which must be always greater than 100). You may also add special features to standard IVR functions by inserting "HOOKS" to user programs in their state machines. 

User Programming

State Machines

The programming style for users will be that of State Machines. State machine programming involves two main concepts, states and events. OmniBox state machine system will have 20 events and as many states as needed for the user application.. The 20 events are the 12 normal dtmf digits (0123456789#*),  four typical happenings in the telephony world DTMF_Count, Timeout, Invalid and Hang-up, a Repeat_Limit event that happens when the Invalid plus the Timeout event count reached 3 and finally four Pseudo Events  that are used to return results of commands, register comparisons and user decisions. 

In a nutshell, the Flow of a user program will be controlled by records in the sysStMachine table. This table will have one record per state and 22 fields, 2 indexes StMachID and StateID and one for each of the 20 events. When the program is in a certain state and then an event happens, the value of the corresponding field points to the next state. When ever there's a state transition, a user defined sequence of commands, to do prompting, digits getting, recording, dialing, etc., is going to be executed. The sequence of commands for each state will be stored in the Sequences table

OmniBox have standard IVR funcions described in Chapter 4. For efficiency, all switching ones and the basic silent call blasting are totally hard-coded, but PIN verification, test service and call making IVR's read their state machines from the sysStMachine in the database, though their command sequences remain hard-coded. 

WARNING: Records for state machine with ID's 0, 1 and 2 correspond to OmniBox standard functions, THESE RECORDS MUST NEVER BE ERASED!

The tables sysStMachine and Sequences contain all the records for all state machines, so they must indexed in a StMachID field. Below is an example of a state machine for a user program to make a call through a calling card service. These can't be the only records in the tables, but we are showing only the ones that belong to the example. There are inbound applications and outbound ones, this one is outbound. In outbound application the calls must be generated, we will refer to the call generator as the OmniBlaster and it will be discussed in more detail further in this chapter. The OmniBlaster will setup a call in a selected channels and when it connects or fails, the state machine will be called with an event that depends on the attempt result in the following manner:

Events thrown according to Call Analysis

BUSY                                                        PsEv3

NO_ANSWER:                                         PsEv2

NO_DIALTONE
NO_RINGBACK:                                    Timeout

HUNG_UP_WHILE_RINGING:
HUNG_UP_BEFORE_RINGBACK:
TRUNCATED:
DEST_CALL_DROP                                Hung_up

FAX_DETECTED:                                    PsEv4

HARDWARE ANSWER SUPERVISION:
VOICE_DETECTED                                PsEv1

RECORDING_DETECTED:                    DTMF_Count

MAKE_CALL_ERROR:
MAKE_CALL_EXCEPTION:
CALL_ANALYSIS_ERROR                   Invalid

In outbound state machines, transition to the State 0 executes no sequence of commands, the first record only defines which is going to the next state depending on the result of the call attempt. According to the values of the fields for StMachID = 110 and State 0, the state machine will do a transition to state 1 if voice or recording is detected, but will or to state 3 if the call fails for any reason or if a FAX. A transition to a state greater than the maximum state ID defined will terminate the state machine. In an outbound call, the OmniBlaster takes care of dropping the call.  Not all the events are possible in every state, in state 0, for instance, events from 0 to star will not happen, thus the value of their fields is totally irrelevant. Cells with irrelevant values will have a gray background..

If a call connects for voice or recording detection, then the transition goes to state 1 and so, the first 3 commands in the above table will be executed. The order in which a sequence will be executed, will be that of the field Step in ascending order. In this example, the sequence starts with command 1 with a parameter of 2000 that pauses the execution for 2000 ms, next a string of digits ending with '#' is dialed, this is the PIN for the calling card service. Now command 104 is invoked, this is "Analyze sound", it will listen to the channel and will throw an event according to the table "Call Analysis" above. If voice or recording, this is, if PsEv1 or DTMF_count, the system will to a transition to state 2, if Timeout or Invalid, meaning silence or some error, then go to state 1 or repeat analysis. In case of any other result, transit to state 3, since it is higher than the last defined, it means terminate.

The event Repeat_Limit is thrown on the count to three of invalids plus timeouts. For example, the default timeout is 6 seconds, if you get silence on the first analysis, a Timeout event is thrown and the system repeats the Analysis command, but if you get silence on your third analysis, then a Repeat_Limit event is thrown and there's a transition to state 3, which as you already know, in this case means to terminate.

If the analysis renders VOICE, the PsEv1 is thrown and there will be a transition to state 2 which triggers a four step sequence. The voice detected was the prompt for the number to be dialed, so the first step is command 103 that dials the phone number. Next step is command 3, that changes timeout to 15 seconds, the third, command 105,  will record the sound of whatever happens in that line for the next 15 seconds into the file "Rectest.wav" and the fourth will terminate the state machine.

Some final comments: 

• In state 1, events 0 to DTMF_Count are impossible, 0 to Star you already know why but you may wonder about DTMF_Count which means recording detection. Command 104 (See command description below) without a parameter won't activate the PAMD feature (Positive Answering Machine Detection), if the feature is not activated a recording will be returned as voice detection. 
• In state 2, the only four possible events that can happen will depend on how the recording ends, PSEv1 if there was silence for more than 5 seconds, PsEv2 if ended by a digit, PsEv3 if timeout or Hung_up (if called party actually answers and hangs up)  I this program whatever event is thrown, the command 0 of step 50 will terminate. If you don't include this last command, any of the events will produce a transition to state 3, which terminates anyway.
• Recording can be an alternate way to the analog line for monitoring a link for voice quality or CO messages, for more detail you may read the description to Command 105.

Registers and Digit Entry 

Every command will be identified by its number, the one that goes in the CmdID field of the Sequence table and some require or accept a parameter, that goes into the Parm field.. The OmniBox state machine system supports 10 registers. These may store partial results and for some complex commands, serve as a way to do variable number of parameters. A parameter showing a number (0 to 9)  inside brackets will be interpreted as the contents of that register, for example [2] will be interpreted as the content of register 2.

Besides the numbered registers, there are 3 named registers: [ANI], [DNIS] and {ENTRY]. For an inbound application [ANI] and [DNIS] will contain the the ANI and DNIS received with the call setup, while for an outbound application would be those sent in the outbound generated call. 

The [ENTRY] register stores the digits entered by the user. When a sequence ends with "no event" or event -1, the state machine goes into a "wait for an event" state, if a key is entered the corresponding event from 0 to Star will be thrown and the digit stored at the end of the [ENTRY] string register, if there's a hang-up during the wait, then it will be the Hung_up event. If for a particular state not all the keys are valid, the corresponding field of the invalid keys in the sysStMachine table may be set to -1 (or any negative number), if any of these invalid keys are hit, the Invalid event will be thrown and the "invalid" prompt played. If nothing happens, then it will be the a "Hurry up" prompt and a Timeout event (if a key is hit during the said prompt, instead of the Timeout, the one corresponding to the digit keyed will be thrown) . If it is a third Timeout or Invalid that happens, the Repeat_Limit will be thrown instead. When the application requires the entry of a fixed number of digits, there is a command 114 that sets this maximum count, if the digit entered hits the count limit, then the DTMF_Count event is thrown instead of the usual 0 to Star. 

All the Registers are initialized to empty when the state machine is started, except [9] that inherits the value left by the last state machine in that channel. This is useful, for example, to count the calls blasted into a channel, redial last number, etc.

The Command Set

Numbering

The command numbering is organized as follows:

• Flow Control                 -1 to 9

• Call Control                   10 to 99

• Sound IO                    100 to 199

• Account issues             200 to 299

• Register operations       300 to 399

• High level commands >1000   

Commands and Events

Some commands in the set can throw events, no other command in that state will be executed after an event has been thrown. Commands 4, 13, 104, 113, 309 and all the high level commands (>999) always throw events. All commands that take parameters throw the Invalid event if they don't validate also, the commands that take time to execute, like those that play back prompts or tones, record etc. will throw a Hung_up if the line gets disconnected while executing. Some commands like (PLAY TONE) or ((PROMPT) can set events without throwing them, meaning commands can continue to be executed in that state. If a sequence concludes without any events being set, the system goes into waiting for one, a key, a hang-up or ... a Timeout, but if an event has been set, it will transit, without waiting, to the state specified in the sysStMachine table.

Parameters

Though there's only one parameter field in the Sequences table, some commands take more than one parameter. In these cases, parameters will go in that same field separated by semicolons. A parameter can be a numerical or string value, depending on what a command expects. Don't use double or simple quotes around string parameters unless they are a valid part of them. A number between brackets will be interpreted as the content of a register, of course, it must be 0-9 only. You may expressed the contents of the named registers by entering [ANI], [DNIS] or [ENTRY] in the parameter field.

Flow Control

CmdID -1 <no parm>            (NOP)

CmdID 0 <no parm>             (END)

CmdID 1  <number of ms>   (SILENCE)

CmdID 2  <no parm>            (STOP BLAST)

CmdID 3  <Timeout ms>      (SET T-OUT)

CmdID 4  <Event Number>  (THROW EVT)

CmdID 5  <no parm>            (STANDBY)

CmdID 6  <1/0>                     (STOP PROMPT)

CmdID 7  <1/0>                     (T-OUT_IS_VALID)

Call Control

CmdID 10 <no parm>  (WINK/ACCEPT)  if R4 wink, if CCS then send the ACCEPT msg
CmdID 11 <no parm>  (ANSWER CALL)
CmdID 12  <cause>     (DROP CALL)
CmdID 13  <PhNum; St Mach ID>  (MAKE A CALL) -if no parm then DNIS will be dialed 
CmdID 14  <no parm> (LOG PARTIAL)
CmdID 15  <no parm> (LOG CALL)l
CmdID 16  <no parm> (PSEUDO HANG-UP)
CmdID 17  <no parm> (PSEUDO CALL WAIT)
CmdID 18  <no parm> (PSEUDO SEIZURE)
CmdID 19  <no parm> (HANG-UP ASSOC) Hang up associated channel
CmdID 20  <no parm> (GET DNIS-ANI)
CmdID 21  <no parm> (FREE ASSOC CH)

Sound IO

CmdID 100 < Tone ID>                                  (PLAY TONE)  Play a tone or cadence
CmdID 101 < Prompt ID or Prompt Path>     (PROMPT) 
CmdID 102: <integer>                                    (PROMPT INT) Prompts an integer number
CmdID 103  <Dial String>                              (DIAL) - Digit String of digits
CmdID 104  < PAMD choice>                        (ANALYZE) Analyze the sound on the line - 
CmdID 105  < Path to file>                              (RECORD)
CmdID 106  <Language Offset>                    (SET LANG)
CmdID 108  <1/0>                                           (DIGIT TYPE)   0 DTMF, 1 MF
CmdID 109   <no parm>                                  (FLUSH)
CmdID 110    <1/0>                                          (IGNORE KEY) Don't break the Prompts with users dtmf
CmdID 111    <1/0>                                          (KEEP DIGIT)  What to do with the digit that breaks the prompt
CmdID 112    <no parm>                                  (CLEAR ENTRY) Clears [ENTRY] without flushing the buffer
CmdID 113    < ToneID>                                  (WAIT TONE) Waits for the specified tone 
CmdID 114    < max digit count>                      (SET MAX DIGITS) Set max digits - 

Account Issues

CmdID 200  <charge>            (CHARGE ACCOUNT) - (if 0 charge the call sell value)
CmdID 201  <no parm>          (CLEAR LAST DIALED)
CmdID 202      <1/0>               (SET LOGIN STS)  0 for Not Logged in and 1 for logged in
CmdID 203  <RoutingSet>     (OVRD ROUTING SET)

CmdID 204  <Reg #,Field>     (ACC_FIELD_TO_REG)
CmdID 205  <Account>           (CHANGE_ACCOUNT) Sets a different account
CmdID 206  <Client Type>     (OVRD_CLIENT_TYPE)

CmdID 207  <NewValue;Field> (OVRD_ACC_FIELD)

CmdID 208  <Field;Reg #>     (CALL_INFO_TO_REG) Call information to specified register

Registers Commands

CmdID 300 <Obj1; Obj2>                             (COPY) Obj can be a value or any register Copy Obj1 to Obj2
CmdID 301 <Obj1; Obj2>                             (SWAP) Swap Obj1<-> Obj2, where Obj can be a value or any register
CmdID 302  <SQL Statement; RegNum>    (LOAD REG) if RegNum = 3, fields from SQL Stnt will be read and load starting with 3
CmdID 304  <SQL Statementc; RegNum > (ACTION QUERY)   RegNum is the First Parameter
CmdID 305  <MsgFrmStr; RegNum>          (SEND TO MON)  RegNum is first parm
CmdID 306  <Reg; Obj>                               (INCR)  Increment Register with Obj
CmdID 307  <Reg; Obj>                               (CONC)  Concatenate Obj to Register
CmdID 308  <Reg; Obj>                               (DECR)  Decrement Register in Obj
CmdID 309 <Obj1; Obj2>                             (COMP) Compare Obj1 with Obj2 if  =, PsEv1, if <, PsEv 2, if >, PsEv3, else evINVALID
CmdID 310 <RegNum>                                (ChNum) Load channel number into registry

High level commands

CmdID 1000  <Login Mask;

                        LoginStMachID;

                        MakeACallStMachID> (LD_PROCEDURE) Starts a long distance procedure (Login and Make a call)
CmdID 1020 <St Mach ID> (RUN ST MACH) 

The OmniBlaster

The OmniBlaster is controlled by the t[Ch] and T[Ch] OmniMonitor action commands and the tec_BurstDetails table (in case you wonder, the blasts were called bursts in early traffic generators). To use the OmniBlaster you will need a special OmniMonitor. It features two new Stop/Start blaster buttons. It works as follows: you mark outbound (or two way) channels you need to generate calls into, you hit the Start button and a t action command will be sent to the OmniBox for each marked channel. Marked inbound channels will be ignored. The Stop button will do the same with the T commands and will stop the blast in all marked channels.

When a channel is triggered by a t command a thread is spun to do the "Blasting", this meaning that calls will be generated until a T command is received or if a (STOP BLAST) command (CmdID 2) is executed. Before every call, the tec_BurstDetail table is queried for a match of ChNum = BurstDetail_ID or just a match to its modulus to 100. In plain English, say we are triggering a blast on channel 502, if there's no record with BurtsDetail_ID equal to 502, one with just a 2 will do. Still in other words, a record with a BurtsDetail_ID between 1 -24 for a T1 or 1-31 for an E1, will work as kind of a wild card for any span. For Example, channel 501, will use the wild card record with BurtsDetail_ID = 1 but channel 801 would use its "own" record with BurtsDetail_ID = 801.

The number in PhoneNumber will be the one dialed, since this table is read before every call of the blast, it can be changed on the fly.  This feature is used by the PredictiveDialer, state machine 300, to call a different number every time.

The last sequence of this state machine300,  invokes the tm_SetNextPhNum stored procedure that looks up the next uncalled number in the tm_PhoneList table and replaces the old one in tec_BurstDetails. The procedure includes the status change from 0 (not served) to 1,2,3 or 4 according to the result of the call. Status values can be:1 for call answered, message recorded; 2 for Call failed; 3 for voice mail left and  4 for call answered but caller hung up with no message 

The last record has an empty dial string, this go terminating the blasts when the list is exhausted..

The x (or X) inside a dialing string means extension,  OmniBlaster can dial extensions  For instance, consider record 11 in the tec_BurstDetail table above. It will dial "9547351005", when the call is answered it will listen to the prompt for 2 seconds (the comma after the 'x'), then it will dial the extension, waiting for 10 seconds (the 5 commas) to make sure the analysis starts after the extension starts to ring (this skips messages and music), then it will wait for a voice or recording to execute either the life person prompt or the voice mail one.

The StMachID specifies which state machine to execute, if you need a blasts of silent calls, only to test for connections, you may use the value -1. 

The first sysStMachine  record for a user state machine, usually the one for state 0, won't execute a sequence, its only roll is to the select the right real first state depending on the call analysis result.

Events thrown according to Call Analysis

BUSY                                                        PsEv3

NO_ANSWER:                                         PsEv2

NO_DIALTONE
NO_RINGBACK:                                    Timeout

HUNG_UP_WHILE_RINGING:
HUNG_UP_BEFORE_RINGBACK:
TRUNCATED:
DEST_CALL_DROP                                Hung_up

FAX_DETECTED:                                    PsEv4

HARDWARE ANSWER SUPERVISION:
VOICE_DETECTED                                PsEv1

RECORDING_DETECTED:                    DTMF_Count

MAKE_CALL_ERROR:
MAKE_CALL_EXCEPTION:
CALL_ANALYSIS_ERROR                   Invalid

The ANI field does not require a lot of explaining, is just the ANI that will be sent in case the protocol supports ANI.

HOOKS 

A HOOK is where you "hang" a user procedure to execute within a standard one. HOOKs are set in the sysStMachine table, you can tell a HOOK when you see a state greater than the greatest State number in the state machine, normally over 99. When OmniBox finds a state number higher than the highest state within the records of a standard state machine, it interprets it as a HOOK, meaning that there is a User State Machine ID to execute. There are a couple of exceptions to the above rules, in Standard State Machine 1,  states 16 and 103 are valid for internal code reasons so, these numbers shouldn't be used as HOOK ID's. Also the HOOK concept can not be used for nesting user programmed state machines, a state ID greater than the last state will simply terminate a user programmed one. 

The following HOOK will offer the caller higher rated routing options after a call attempt failure. Below is the record corresponding to state 7 of the standard state machine 1. In this state the prompt "Your call failed, you may dial again now". has been played and PsEv1 is thrown. The next should be 14, that will do all the resource releasing, but there's where you inter the HOOK. 

Here is the same record but with State Machine 150 HOOKed into PsEv1. Set PsEv2 to the former state to allow continuation, in other words, PsEv1 will start the HOOK and the HOOK must be programmed to finish throwing event PsEv2. 

Before entering the State 0 of the hooked machine, the buffer is flushed and the Keep Digit Flag is set, in this example, only one event is possible, namely the PsEv1 inherited from the parent State Machine and it will always transit to State 1 playing the routing prompt while waits for a digit. If the caller breaks the prompt with a key other than 1, transition goes to state 4.that ends the state machine throwing event PsEv2 that will continue the parent state machine. If the prompt finishes, PsEv1 will be set causing an immediate transit to state 2 where a prompt consisting in a beep and a silence will be played. If being in state 2 the caller hits a key other than 1 or timeouts, there will be a transition to state 4 to continue with the parent, if a one is hit while in state 1 or 2, then the routing set and the client type will be changed before continuation. If a hang-up is detected in any state, the hooked state machine will terminate throwing a Hung_up event, this will terminate the parent as well.

It is possible, as in the Language Choice HOOK example below, that you need to run a a HOOK before the standard state machine starts. This can be accomplished by adding a state -1 to the standard state machine and setting the state for event 0 to the HOOKed State machine ID.

What if you need different HOOKs for Different Domains? ...Indirect HOOKs

Setting HOOK directly on the records of a standard State Machine will act on every calling domain. The way to go around this problem is to use Indirect HOOK's. The technique consists in copying the records of a standard state machine into the same sysStMachines table, for example number 1, with a different ID, say for instance 501. For that you may use the followin SQL statement:

INSERT INTO sysStMachines ( StMachID, StateID, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, Pound, Star, DTMF_Count, Timeout, Invalid, PsEv1, PsEv2, PsEv3, PsEv4, Repeat_Limit, Hung_up )

SELECT 501, StateID, [0], [1], [2], [3], [4], [5], [6], [7], [8], [9], Pound, Star, DTMF_Count, Timeout, Invalid, PsEv1, PsEv2, PsEv3, PsEv4, Repeat_Limit, Hung_up

FROM sysStMachines
WHERE (StMachID = 1);

Then you insert the necessary HOOK's in State Machine 501 (not in State Machine 1 as before):

Now you create a very simple new state machine 500 which only has the single state 0:

The associated sequence to this state will be:

Is uses CmdID 1000 with parameters:

Login Mask 0x22 ; meaning to behave as a Direct Call to Function 1.

LoginStMachID 0; meaning to use standard Login state machine

MakeACallStMachID 501;meaning to use the "new' MakeACall state machine (the one with the HOOK)

The Indirect HOOK will execute when you specify function 500 in the FunctionID field of dia_InCh or if you specify -1 or -2 and the enter 500 in the Function field of the DNISLookup table.

FLOW CONROL

CmdID -1 <no parm>    (NOP)

No operation is performed

CmdID 0 <no parm>    (END)

Ends the State Machine no matter which event is thrown.

CmdID 1  <number of ms>    (SILENCE)

Do silence for the number of  milliseconds expressed in the parameter

CmdID 2  <no parm>    (STOP BLAST)

:When you trigger the OmniBlaster on a channel, the calls will be made one after the other, this is, the state machine ends and restarts in the next call until the Blast is stopped from the OmniMonitor or this command  is executed. This command not only terminates the currently running state machine but the blast as well. You may increment Register [9] on every call and have the Blast stop on at a specified count..

CmdID 3  <Timeout ms>    (SET T-OUT)

Sets the state machine timeout to the value in the parameter. This will affect not only the digit entry timeout but also the recording time for command 105,  the waiting time for a tone in command 113 and the max silence for the analyze sound command 104.

CmdID 4  <Event Number>   (THROW EVT)

This is the state machine equivalent to the BASIC "goto" only that a little more flexible because the event can be a variable, this is, a the contents of a register. Any event from 13 to 20 can be thrown. Any other value will throw event -1, which means "Wait for a Key or hang-up"

13. DTMF_Count
14. Timeout
15. Invalid
16. PsEv1
17. PsEv2
18. PsEv3
19. PsEv4
20. Repeat_Limit
21. Hung_up

There is another difference with the goto, it doesn't "jump" upon execution. If it is the last command for that state, then it works as a "goto", but if it is not, the rest of the commands will be executed and only when finished, is that it will "goto". This last form of usage will be reffered to as event setting instead of event throwing.

CmdID 5  <no parm>    (STANDBY)

Checks if the call has been ended, if so, it throws a Hung_up, if not,  it checks the associated channel (if exists) for disconnection, if so, it throws a PsEv1 If everything still connected throws nothing nor changes the default event. This command is used mainly while waiting for a call to end.

Example: Collect Digits and Send then in a message to the monitor

State 0 direct will transit to State1 only if voice is detected. State 1 will flush the digits buffer, set the the KeepEnterDigit flag to TRUE, set the Max Digit Count to 9 and prompt for digits. The only possible events playing a prompt are Invalid, PsEv1 or Hung_up. Invalid would mean a failure to get a voice resource for the job, so except for PsEv1 that will cause transition to State 2 the transit for the other two events will be to State 4 or simply the end of the state machine. 

State 2 sets the KeepEnterDigit flag to TRUE and goes to standby that will check if the call is finished and if so, will throw a Hung_up. If the call is dropped while waiting for a digit the State Machine will throw a Hung_up without the need of the STANDBY, but if the call were truncated, by a stop blast or a channel block or exclusion, then the STANDBY will know about it and throw the Hung_up.

CmdID 6  <1/0>    (STOP PROMPT)

Sets the StopPrompt flag. This flag is automatically set to TRUE by the system when a prompt is interrupted by a DTMF digit. When TRUE, prompts are not played.  It is common to find prompts made up of a sequence of smaller ones. For example:

"Your balance is..." + "two" + " dollars" + " and " + "fifty" + "three" + "cents"

The above prompt is built from 7 sub-prompts. It is important when playing a sequence of prompts that if  the user enters a key while playing, this key stops, not just the playing sub-prompt, but also the rest of sequence. Every time a new prompt  must be played after one that could have been truncated, the StopPrompt flag must be set to FALSE to make sure it plays. 

CmdID 7  <1/0>    (T-OUT_IS_VALID)

Set the TimeoutIsValid flag. If FALSE, every Timeout event increments the repeat count and  a "Hurry up" prompt is played, when this count get to 3 the Repeat_Limit event is thrown. If the flag is set to TRUE, the prompt is not played and the repeat count is not incremented.

To use the STANDBY command to wait for a call to finish or a key to be entered, a Timeout event will be issued every TO seconds without this meaning that the user must be "hurried up", in this case Timeout is a valid and normal event to expect, so the flag must be set to TRUE. Every Timeout event resets the flag, so it must be set back to TRUE every time.

Call Control

CmdID 10 <no parm>  (WINK/ACCEPT)  if R4 wink, if CCS then send the ACCEPT msg
CmdID 11 <no parm>  (ANSWER CALL)
CmdID 12  <cause>     (DROP CALL)

Drops the call being made. If the protocol being used for the inbound channel is a CCS (Common Channel Signaling like ISDN and SS7), then a cause is transmitted with the release message coded according to standard Q.931. You may specify any of the cause codes listed below

If you specify -1, Omnibox will automatically translate its result code into the Q.931 standard according to the following table:

CmdID 13  <PhNum; St Mach ID>  (MAKE A CALL) -if no parm then DNIS will be dialed 
CmdID 14  <no parm> (LOG PARTIAL)

Does partial logging. See more info about partial logging in Chapter 5 

CmdID 15  <no parm> (LOG CALL)

Before issuing this command, you must terminate the call you are about to log. This can be accomplished if you precede this command by: a 12 (Drop Call) with parameter -1 (cause to correspond to whatever the dial result was) and a 16 which is a Pseudo hang up.

CmdID 16  <no parm> (PSEUDO HANG-UP)

No real hang up, inbound call is not actually dropped, but all variables are set as if the call was actually terminated to the effect of logging and charging an account. This is necessary in an IVR if you are offering the caller a chance for another call, you must terminate the current one, log into the CDR and charge the account before proceeding to the next. 

Also, in the case when you are blasting, since there's no real inbound call, all you can do is a pseudo hang-up.

CmdID 17  <no parm> (PSEUDO CALL WAIT)
CmdID 18  <no parm> (PSEUDO SEIZURE)
CmdID 19  <no parm> (HANG-UP ASSOC) Hang up associated channel
CmdID 20  <no parm> (GET DNIS-ANI)
CmdID 21  <no parm> (FREE ASSOC CH)

Sound IO

CmdID 100 <Tone ID>                                  (PLAY TONE)  Play a tone or cadence

Plays a tone or cadence described in the dia_Tones table. The value of the field Tone_ID must be passed as parameter.

CmdID 101 <Prompt ID or Prompt Path>     (PROMPT) 

If parameter is a number, it plays the corresponding prompt described in the Prompts table. The number must be one between 0 to 999, OmniBox will add the Language offset of the acting account so that it will be played in the corresponding language. If the parameter has no numeric value, it will be interpreted as a path string for the prompt wav or vox file. If the IgnoreKey flag is set to FALSE, a DTMF from the caller can break it and set the corresponding Digit event, if the prompt finish playing PsEv1 will be set instead. 

CmdID 102  <integer>                                    (PROMPT INT) Prompts an integer number

Prompts the number in the parameter. Acceptable values go from 0 to 999

CmdID 103  <Dial String>                              (DIAL) - Digit String of digits

Dials a string of up to 32 DTMF or MF digits, whichever if set active with command 108. Default is DTMF. 

CmdID 104  <PAMD choice>                        (ANALYZE) Analyze the sound on the line - 

Analyzes the sound on the channel and throws events according to the result. The event table goes as follows:

BUSY and FAST BUSY                           PsEv3

NO_ANSWER:                                         PsEv2

NO_DIALTONE
NO_RINGBACK:                                    Timeout

HUNG_UP_WHILE_RINGING:
HUNG_UP_BEFORE_RINGBACK:
TRUNCATED:
DEST_CALL_DROP                                Hung_up

FAX_DETECTED:                                    PsEv4

HARDWARE ANSWER SUPERVISION:
VOICE_DETECTED                                PsEv1

RECORDING_DETECTED*:                    DTMF_Count

OPERATOR_INTERCEPT 

MAKE_CALL_ERROR:
MAKE_CALL_EXCEPTION:
CALL_ANALYSIS_ERROR                   Invalid

* Recording detection is disabled by default. To enable it, you must supply a parameter with one of the following values:

1. Full salutation analysis. Typical value

2. Quick salutation analysis. Then time primes over accuracy.

3. Accurate salutation analysis, longer but must accurate.

CmdID 105  <Path to file>                              (RECORD)

Beeps and records the sound in the line and stores it in a wav file. The path to the file must be supplied in the parameter. Sample rate is 11.25KHz. The command will set (not throw) an event according to how the recording finished:

5 second Silence               PsEv1

DTMF digit                       PsEv2

Maximum recording time    PsEv3

Caller hung up                    Hung_up

CmdID 106  <Language Offset>                    (SET LANG)

Overrides the language offset and won't allow it to be changed unless this command is called again with a negative parameter or the flag is initialized again by the next state machine. Below there's an example a user function that is HOOKed to the Login State Machine and will offer the caller a choice of languages. 

In this example the HOOK to state machine 100 shows in state -1 because you need that the state machine 100 runs even before the first sequence of the Login State Machine. It is quite obvious that the language choice must be given before the first prompt is played.

Language Choice HOOK

Below the HOOKed state machine 100:

.  

CmdID 108  <1/0>                                           (DIGIT TYPE)   0 DTMF, 1 MF

Sets the active digit type for command 103 or for making a call command 13.

CmdID 109   <no parm>                                  (FLUSH)

Cleans the dialogic internal digits buffer, making sure that there are no remaining digits from a past entry.

CmdID 110    <1/0>                                          (IGNORE KEY) Don't break the Prompts with users dtmf

By default, prompts are truncated by DTMF digits from the caller. If there are messages that you want the caller to listen in full, for instance a legal warning, an access denial message, etc, then you may instruct OmniBox to ignore any dtmf key by issuing command 110 with parameter set to 1 (TRUE). To restore the default mode, you may issue it again with 0 (FALSE) 

CmdID 111    <1/0>                                          (KEEP DIGIT)   

What to do with the digit that breaks the prompt, by default you keep it, this means that the digit is stored in the [ENTRY] Registry. You may choose to disregard these entries by issuing this command with parameter set to 0.

CmdID 112    <no parm>                                  (CLEAR ENTRY)  

Clears [ENTRY] without flushing the buffer. For instance, when you ask the caller to reenter, you must clean the [ENTRY} register first.

CmdID 113    <ToneID>                                  (WAIT TONE)  

Waits for a tone of the ones defined in the cdp files. The parameter must reference the TID: 

TID # 101 DIAL TONE
TID # 102 FAX
TID # 103 BUSY
TID # 104 SBUSY
TID # 105 RINGBACK1
TID # 106 RINGBACK2
TID # 107 FAX2 (MODEM)
TID # 108 DTMF
TID # 109 SIT

If the tone is detected a PsEv1 is thrown, if not then a PsEv2..

CmdID 114    <max digit count>                      (SET MAX DIGITS) Set max digits - 

When you prompt the caller to enter a number with an unknown count of digits, you must request that the entry be finished with pound, but if for instance, the entry is a Social Security or a Visa or Master card number, that you know they are 9 and 16 respectively, you don't. If you set the maximum digit count to the right values, you'll get the DTMF_Count event when the last number is hit.

For the case when PIN numbers have a fixed length, you don't need the ending pound sign either. The following example shows a HOOK for the Login State Machine that will set the maximum digit count to 10.

First a row for state -1 must be added to State Machine 0.

These are the states for State Machine 102

These are the commands to be executed in the only state transition of this state machine.

Step 10 sets the maximum digit count to 10 and step 20 throws a PsEv3 that will send state machine 0 to state 0 without waiting for a digit and the prompt will be heard right away.

Account Issues

CmdID 200  <charge>            (CHARGE ACCOUNT) - (if 0 charge the call sell value)
CmdID 201  <no parm>          (CLEAR LAST DIALED)
CmdID 202      <1/0>               (SET LOGIN STS)  0 for Not Logged in and 1 for logged in
CmdID 203  <RoutingSet>     (OVRD ROUTING SET)

Overrides the database loaded value for the routing set of the account 

CmdID 204  <Reg #;Field>              (ACC_FIELD_TO_REG)

The Register will be set to the value of the account field.  The account fields numbers are:

CmdID 205  <Account>           (CHANGE_ACCOUNT) Sets a different account
CmdID 206  <Client Type>     (OVRD_CLIENT_TYPE)

Overrides the current account's client type on the fly. The account will be charged according to new type for the present session, but won't be changed in the database. This feature is useful when offering the caller a routing choice, for instance, premium and economy long distance services together with command 203 OVRD ROUTING SET.  

This action of changing the client type won't be leaving an explicit trace in the CDR, just maybe the use of a "premium" outbound group together with a higher sell value. This meaning, that customer service disputes may become involved when using it.

CmdID 207  <NewValue;Field> (OVRD_ACC_FIELD)

Overrides the current value of an Account field with the New Value or, if the New Value is within brackets, the value stored in the register referenced by New Value.

Command 203 , 3 that overrides current Routing Set with a value of 3,  is equivalent to 207, 3;6. Also, command 206, 5 that overrides current Client type with the value 5, is equivalent to 207, 4;5.

CmdID 208  <Field;Reg #>     (CALL_INFO_TO_REG) 

Parameter Field is numeric and will specify the piece of call information requested to be stores in the register specified by the second parameter or into Reg[0] if not specified.

Meanings for the values of parameter Field:

*Each overridden field will contribute to the bitmap as follows 

Registers Commands

CmdID 300 <Obj1; Obj2>                     (COPY)

    An Obj can be a value or any register. Copy Obj1 to Obj2  Obj1 can be a number or register, Obj2 must be a register.

CmdID 301 <Obj1; Obj2>                     (SWAP) Swap Obj1<-> Obj2, where Obj can be a value or any register
CmdID 302  <SQL statement; RegNum>  (LOAD REG) if RegNum = 3, fields from SQL Statement will be read and load starting with 3

The SQL statement will be executed in the OmniBox database, it must have a "%s" everywhere the content of the registers must be inserted. Upon return, the fields will be loaded in the registers starting with RegNum. A call to a stores procedure consider the following example that calls proc_Name that takes two parameter, first one numeric and second a string starting with Reg3

302 {CALL proc_Name(%s, '%s')};3

CmdID 304  <SQL Statement; RegNum > (ACTION QUERY)   RegNum is the First Parameter

Same as above, only that no registers are loaded, sin no records are supposed to be returned by an action query.

CmdID 305  <MsgFrmStr; RegNum>  (SEND TO MON)  RegNum is first parm
CmdID 306  <Reg; Obj>                       (INCR)  Increment Register with Obj
CmdID 307  <Reg; Obj>                       (CONC)  Concatenate Obj to Register
CmdID 308  <Reg; Obj>                       (DECR)  Decrement Register in Obj
CmdID 309 <Obj1; Obj2>                     (COMP) Compare Obj1 with Obj2 if  =, PsEv1, if <, PsEv 2, if >, PsEv3, else evINVALID
CmdID 310 <RegNum>                        (ChNum) Load channel number into registry

High level commands

CmdID 1000 <Login Mask;

                        LoginStMachID;

                        MakeACallStMachID> (LD_PROCEDURE) 

Starts a long distance procedure invoking LDServiceProc. Omnibox Standard Functions  with ID's 1 ,2, 10, 11, 14, 15 and 17 call the same function LDServiceProc with diferent login modes. This procedure runs the Login state machine, if successful, it runs the MakeACall state machine, if the call finishes without a caller hang-up, this is by call failure, ##, or called party hang-up, then it the logs the CDR and runs the MakeACall state machine again. When the caller hangs-up after successfully terminating a call the procedure logs its CDR.

Login Mask:

Is a 7 bit map with the following meaning:

PIN Components: Different long distance service scenarios require different PIN compositions  Lets define the PIN as being formed by 4 components, namely 1, 2, 3 and the caller entry. If the fully formed PIN matches the Authorization Code, then the Login proceeds. Below, as examples, the Login Mask values to match the functionality of the OmniBox standard functions.

*requires that this command be preceded by a previous:: 300 <00dd, [DNIS]>, where dd is the domain ID.

LoginStMachID

By default, LDServiceProc runs the standard Login state machine, which is the one with ID = 0, this command allows to override this value with the ID of another state machine.

MakeACallStMachID

Similarly, by default, LDServiceProc runs the standard MakeACall state machine, which is the one with ID = 1, this command allows to override this value with the ID another state machine.

This command is used to implement Indirect HOOK's. This technique allows running standard state machines with different HOOKs for different Domains

CmdID 1020 <St Mach ID> (RUN ST MACH)

APPENDIX - A

To use the HOOKS technology you must become familiar with the standard state machines.

Login, Standard State Machine 0

State machine 0 and has six states as shown in the table below

State 0

In this state the AutoPIN is checked against the Authorization code, if there's an account match and balance is > $0 the PsEv1 is thrown doing transition to state 3.  Also there will be a Pay Phone check (protocol allowing), in case of any charges related to this the account will be charged and if there's any balance left or it is not a prepaid customer PsEv1 will be thrown. 

If of a match but  no balance in a prepaid account the, PsEv2 is thrown and the transition will go to state 5. If there's no match with the AutoPIN, then the caller will be prompted for the PIN (or Supplement of). ANY digits entered will cause DTMF_Count to be thrown and transition will go to state 1..If there's no entry, Timeout will be thrown transiting again to state 0. the caller will not only get the "Hurry up" message but also the prompts for digits again. I t gets to the three timeouts, the Repeat_Limit will be thrown producing transition to state 6.

State 1

Collects the PIN digits, the possible events are:

• (0-9), will return to State 1
• Pound, will terminate digit collection, transit to state 2
• Star, cleans the entry and goes back to State 0 (says the prompt again)
• Timeout, Plays the "Hurry up" message and returns to state 1.
• Repeat_Limit, Transit to state 6
• Hung up, Transit to state 6

State 2

    Checks entered PIN for a match with authorization code or, if the was non empty AutoPIN, check it as a supplement. Possible events are:

• PsEv1, match found, Transit to state 3
• PsEv2, match but no balance, Transit to 5
• Invalid. no match, "Invalid entry" message increment the count and back to state 0 
• Repeat_Limit, too many invalids or timeouts, transit to state 4. 

State 3

Sets the login flag to True and exits.

State 4

Plays the prompt 18, "Access Denied" and returns with Login flag set to False

State 5

Plays prompt 17,  "No Balance"  and returns with Login flag set to False

State 6

If caller has not disconnected, it plays prompt 6, or "Bye message" and returns with Login flag set to False.

State 3 to 6 have no possible events, that's why the content of the fields in its corresponding records is irrelevant.

Make A Call, Standard State Machine 1

This is a more complicated state machine, it not only deals with prompting for the number to dialed, but must validate this number, check the rates, calculate the maximum call length, prompt it if necessary, make the call and act according to the result. Also when the connection is established, it must keep watching for '##' and the time limit.

State 0

Plays the account's welcome prompt, if it is a prepaid client with a balance less than $1000 (or any other currency), it will play the balance and after that it will prompt for the number to be dialed. If a digit is hit, all the prompting will be skipped with PsEv1 thrown, if everything plays back to the end, same thing, PsEv1 will be thrown. The rest of the events, except for Hung_up that with always transit to State 15, can't happen, so the content of their field is irrelevant.

State 1

Plays a dial tone. You may set the dial tone to be silent by editing the record for Tone ID 103 from the standard American dial tone to the following values

 Possible events are:

• (0-9), Breaks the dial tone and proceeds to state 2
• Pound, transits to Digit validation in state 3
• Star, back to state 0 (no welcome played)
• Timeout, back to state 0 (no welcome played)
• Repeat_Limit, if already 3 invalid entries or timeouts, transits to state 15
• Hung_up, transits to state 15

State 2

Collect Digits: Possible events:

• (0-9),  stays in state 2
• Pound, transits to Digit validation in state 3
• Star, back to state 0 (no welcome played)
• Timeout, works as #, transits to Digit validation in state 3
• Hung_up, transits to state 15

State 3

Validate digits. First digits are processed for its number, if the customer hits #, with no other digits, the system will interpret it as a redial command, but it were are no digits to redial, then PsEv2 will be thrown transiting to state 4 (Invalid Dial). If it user hits a 0. with no other digits, this is a special command tha will terminate the call will end immediately. When only 2 digits and a pound are dialed, then Speed Dial will be interpreted, those two digits will be looked up in the stm_SpeedDial  table in the OmniBilling Database (se below) for the records corresponding to the current account and the result of the query will replace the 2 digit entry.

Possible events in state 3:

• SpEv1, Transition to State 5,  no enough balance to cover 1 minute to the dialed destination
• SpEv2, Transition to State 4, Invalid Dial: route index not found; no route defined or no rates for that destination;
• SpEv3, Transition to state 6: Make the call and wail for a dial result.
• Hung_up, Transition to State 15.

State 4

Play prompt 20, "Invalid Dial". Throws event PsEv1 to transit to state 0. The invalid count won't be incremented, this means that a caller can make any number of invalid dials. If this become a problem, a simple HOOK that changes the an Invalid instead of a PsEv2, will do the trick..

State 5

Plays prompt 23, "Insufficient funds", Throws event PsEv1 to transit to state 0. Funds may not be enough for the rates of dialed destination but may be right for a different one.

State 6

Makes the call and the event thrown will depend on the dial result as follows:

• PsEv3, Connected, transit to state 9.
• PsEv4, covers several results but will always transit to state 14 (end call with no hang up):
  • Busy detected, prompt 14 played, 
  • Ring no answering, prompt 15 played
  • No channel available, prompt 41 played
  • Any other failure, prompt 25 played
• PsEv2, Blocked number, transit to state 8
• PsEv1, Operator intercept, transit to state 7.
• Hung_up, the caller hung-up, transit to state 15 

State 7

Plays "Connection failed", prompt 25, throws PsEv1 to transit to State 14 (end call with no hang up)

State 8

Plays "Unauthorized number", prompt 24,  throws PsEv1 to transit to State 14 (end call with no hang up)

State 9

User is talking to its party and the state machine waits for a # sign or till there's a minute to the maximum call length or a hang-up. Here are the possible events:

• (0-9*), Again to state 9
• PsEv2, called party hung-up, transit to state 11
• PsEv1, play "One minute left', prompt 26, transit to state 12
• Pound, first # key, transit to state10
• Hung_up, calling party hung-up, transit to state 15
• Timeout, nothing happens, just talk, transit to state 16. This is a dummy state that is the same as to 9, it is easier this way to place a HOOK.

State 10

Waits for a second # key, possible events:

• (0-9*), Transit to state 9
• Timeout,  Transit to state 9
• Pound,  Transit to state 13
• Hung_up, Transit to state 15

State 11

Plays "Called party hung up", prompt 12, throws event PsEv1 to transit to state 14 (end call with no hang up)

State 12

One minute to go...

• (0-9*), Again to state 12
• PsEv2, called party hung-up, transit to state 11
• PsEv1, Balance hit zero, play "Bye message', prompt 6, transit to state 15
• Pound, first # key, transit to state10
• Hung_up, calling party hung-up, transit to state 15
• Timeout, Again to state 12

State 13

Plays "## detected", prompt 11 and ends call without hanging up.

State 14

Terminates the call without hanging up

State 15

Terminates call with hang up.