Friday, February 14, 2020

Asterisk Dynamic Routes module examples

The Dynamic Routes module for FreePBX lets you route based database lookups, asterisk variables, agi 's.  The version I'm testing with is in the ISSABEL distro.

For these examples, i created an extension "1000" in the PBX, most of the examples here are based on this.  Feel free to try, just substitute 1000 for an extension in your PBX.

If I were to do a mySQL lookup this was the return in my example

+-----------+----------+--------+-----------+-----------+---------+----------+
| extension | password | name   | voicemail | ringtimer | sipname | mohclass |
+-----------+----------+--------+-----------+-----------+---------+----------+
|   1000      |               | Agent1 | novm    |             0 |               | default  |
+-----------+----------+--------+-----------+-----------+---------+----------+

(full disclosure I've reduced the number of columns displayed for space reasons)
The above shows that the ONLY extension is 1000

EXAMPLE 1:
Hardcoded SQL LOOKUP
This will do a hardcoded lookup for a value.  In this case the system will see if the hard value of "1000" exists in the extension column of the "USER" table in the "ASTERISK" database.

I'm doing lookups in the SQL database that exists, but you could easily make a table and put in your own values.  

Here is what my Dynamic Route looks like for a hardcoded SQL data lookup.


The script is executed and will always look for extension 1000.

select * from users where extension = 1000

The result of this will be a match, and the ECHO TEST will be executed.

IF the SQL statement were to change to hardcoded value "1001"

select * from users where extension = 1001

If the script were run, this script would FAIL because 1001 does not match, and it would DIAL VOICEMAIL.

EXAMPLE 2:
DYNAMIC SQL lookup based a caller entry in an IVR. 
This would be useful for something like a user needing to input their ClientID # or a password or something.

When this script is activated, the caller enters input into the IVR (DTMF tones), then matching the input and routing.

So this example you enter the dynamic route, enter in 1000# (1000 is saved in variable 'extension'

The INPUT VARIABLE is "extension"
When the user enter is 1000#
The system executes the query
select * from users where extension = '[extension]'
(note the '[varname]' that you enclose the value with a single quote and square bracket.

when its run, the system will search for the value entered into the IVR, in this example, 1000, the system will do a mySQL search with "1000" and they would hear an ECHO test.  

The system will respond as a match, and will play an echo test because it will match.

EXAMPLE 3:
ROUTE BASED ON ASTERISK VARIABLE

Here the system will route based on the internal asterisk variable "AMPUSER" which is the extension of the person making the call.

We set the SOURCE TYPE to be asterisk variable

In the Variable String we put in the asterisk string ${AMPUSER}

The system will route based on the value of that id.  
If i make the call from extension 1000, the "ECHO TEST" will play.
IF I make a call from extension 1001, the system will play "SYSTEM CLOCK"

If there is no match, the system will play "DIAL VOICEMAIL"

EXAMPLE 4:
Route based on a URL result

This one is a little more strict, has quite a few limitations, basically you can only use it for text returns from a URL that are very simple.

If you go to this URL (put in the IP of your server)

You should get something like : "The selected menu is not valid"

So, if you get data from a really SIMPLE site, you can route on the return!

You'll notice that i've set SOURCE TYPE to URL, and put in the URL into the URL box.
https://10.1.80.193/help/frameRight.php

Now I've copy and pasted the EXACT return into the box, that if the system matches, it will activate the SPEAKING CLOCK

The selected menu is not valid.

Now when I run this, it will goto that URL, there SHOULD be a match, and then it will play the clock.

For troubleshooting, if you put in a URL, and then run the script, you'll see a log entry like this:

 -- Executing [s@dynroute-2:7] Set("SIP/1000-0000002e", "dynroute=The selected menu is not valid.") in new stack

Notice how "dynroute=" the data the url will return.

This is as far as I've taken the URL at this point.  

EXAMPLE 4:
Route based on a AGI result

I haven't done a lot with the AGI, but here is a demo config of kind of how it would work

We set the value as AGI.
AGI Script and parameters we point to an AGI script.  There is a test one that you can use
/var/www/html/admin/modules/dynroute/test.agi

I haven't really gone through this AGI, so i'm not 100% sure how it even works.  Anyone reading this who can shed light on how it works I would love to know, leave a comment!

AGI result variable set to dynroute

When you call the AGI and pass it paremeters, the data will come back.

  -- Executing [s@dynroute-2:1] AGI("SIP/1000-0000004b", "/var/www/html/admin/modules/dynroute/test.agi") in new stack
    -- Launched AGI Script /var/www/html/admin/modules/dynroute/test.agi
    -- <SIP/1000-0000004b>AGI Script /var/www/html/admin/modules/dynroute/test.agi completed, returning 0
    -- Executing [s@dynroute-2:2] Set("SIP/1000-0000004b", "dynroute=0") in new stack

In the above example, we call the AGI, it returns with the hardcoded variable DYNROUTE value of 0

We can then put the values we expect and route.  In the example, we send the call to "ECHO TEST" if it returns a 0.


CONFIG PARAMETERS


Dynamic Route
The following information documents how to fill in the fields of a Dynamic Route. This documentation refers to the V13 functionality. Not all options are available in previous versions.
Field name
Comment
Dynamic Route Name
The name of the dynamic route. This can be chosen at will. It is used to identify the route when selecting it as a destination from other applications or inbound routes.
Dynamic Route Description
Optional description text for the Dynamic Route. This is for documentation purposes only
Enable DTMF Input
Setting: Yes or No. Default: No. If set to yes the call waits for input on the touch tone keypad. This can be used to capture caller input (for example a customer number).
Announcement
The system recording to be played back. If Enable DTMF input is set to Yes then playback takes place before waiting for DTMF input.
Timeout
Timeout in seconds to wait for DTMF input. This value is only used if Enable DTMF Input is set to Yes. If no value is given for timeout, the default for the channel is used. It is best to set an explicit value to avoid doubts.
Validation
Validation rules using a Asterisk regular expression (see Asterisk REGEX). For example to ensure the input is between 3 and 4 digits long you could use ^[0-9]\{3,4\}$
Invalid Retries
Number of times to retry if DTMF input does not match validation rules.
Invalid Retry Recording
Recording to play if DTMF input does not match validation rules.
Invalid Recording
Recording to play if DTMF input does not match validation rules and Invalid Retries have been exhausted.
Invalid Destination
The destination to send the call to if DTMF input does not match the validation rules and Invalid Retries ahve been exhausted. The call is sent to this destination after playing the Invalid Recording if it is defined.
Saved input variable name
Name of variable in which to save DTMF input for future use in the dial plan or further dynamic routes. This is available as [name] in the query/lookup where name is the name of the variable you specify here. To use the variable in the dial plan (e.g. custom applications) it is necessary to prefix it with DYNROUTE_ e.g. DYNROUTE_name
Saved result variable name
Name of variable in which to save lookup result for future use in the dial plan or further dynamic routes. This is available as [name] in the query/lookup where name is the name of the variable you specify here. To use the variable in the dial plan (e.g. custom applications) it is necessary to prefix it with DYNROUTE_ e.g. DYNROUTE_name
Source Type
The type of lookup (see under Source types below for further information
Default Destination
Destination to send the call to if the lookup result does not match one of the match values in the Dynamic Route Entries section or if the lookup fails. This is optional but is strongly recommended. If there is no default destination defined, then in the case of a lookup failure or if the lookup result does not match one of the defined values, the call will be disconnected. If this is not what is required, define the default destination with the desired behaviour.
Dynamic Route Entries
Zero or more entries to be matched by the lookup result. If the lookup matches, then the call is routed to the chosen destination. Each match is tried in the order given until one matches. If no match is found then the call is sent to the Default Destination. Additional rows may be added by clicking the + symbol. Entries may be deleted by cancelling the value in the Match field.
Source Type
The following are the currently available source types for lookups. Each source type has its own specific fields for defining the lookup parameters.
Source Type
Comment
none
No lookup is carried out. The call is sent to the default destination
MySQL
A lookup is done to a MySQL database. The parameters used are:
·         MySQL hostname: hostname of server
·         MySQL database: database name
·         MySQL username: username
·         MySQL password: password
·         MySQL query: the SQL to be used. It can contain substitutions as indicated in the table below. Example: select destination from callerid_table where calleridnum like '%[NUMBER]'
ODBC
A lookup is done to an Asterisk ODBC data source. The parameters used are:
·         ODBC function: the Asterisk ODBC function name that has been configured
·         ODBC query: the query. It can contain substitutions as indicated in the table below. Example: select destination from callerid_table where calleridnum like '%[NUMBER]'
For information about setting up ODBC see this article
URL
A lookup is done to a URL. The parameters used are:
·         URL Looup: the URL to be used for the lookup. The results must be text only. HTML, XML and JSON is not supported. The URL may contains parameters and the parameter values may include the substitutions indicated in the following table. Example: http://localhost/test.php?param1=4&param2=[NUMBER]
AGI
A lookup is done by launching an Asterisk AGI script. The parameters used are:
·         AGI Lookup: the name of the Asterisk AGI script to be launched.
·         AGI Result Variable: the name of the variable that the script uses to communicate the result. The script should execute a SET VARIABLE command using this variable name at the end of execution in order to pass back the lookup result. An example script is given in the installation directory (test.agi).
Asterisk Variable
The lookup value is read from an Asterisk Variable. The parameters used are:
·         Asterisk Variable: the variable name from which to read the result. Example: ${xxx}. Complex expressions may also be written provided they use valid Asterisk functions, for example: ${REGEX("^1.3$" ${DYNROUTE_dtmf})} would check that the DTMF input was in the range 1000-1999 (providing that the Saved input variable name was set to "dtmf")
Substitutions
In the lookup
When defining the query field for the lookup, the following Variable Names will be substituted by the corresponding value at the time of the call routing.
Variable Name
Substituted by
[INPUT]
The DTMF input by the caller on the touchtone keypad
[NUMBER]
The callerid of the incoming call
[DID]
The called number
[name]
Where "name" is the value of one of these two fields: Saved input varibale name or Saved result varibale name. In the case of Saved input variable name, the DTMF input is saved under this name. This is useful if you are using two levels of Dynamic Route so that you can save the DTMF from the previous Dynamic Route in a uniquely named variable and use that variable in the lookup of the second Dynamic Route. In the case of Saved result variable name, the result returned from the lookup is saved to the variable name and can be used in a later Dynamic Route.

If you want to use a variable created outside Dynamic Routes in the lookup, then name the variable with a DYNROUTE_ prefix. Then [name] will be substituted by the value of the asterisk variable DYNROUTE_name. There is currently no way of reading an arbitrarily named asterisk variable, except for the lookup type "Asterisk variable".
In custom dial plan or other FreePBX modules
Variable Name
Substituted by
DYNROUTE_name
Where "name" is the value of one of these two fields: Saved input varibale name or Saved result varibale name. In the case of Saved input variable name, the DTMF input is saved under this name. This is useful if you need to use the value in a custom dial plan application or another FreePBX module. In the case of Saved result variable name, the result returned from the lookup is saved to the variable name and can be used in a custom dial plan application or another FreePBX module. To obtain the value of the variable named name, use ${DYNROUTE_name} in the Asterisk dial plan.


No comments:

Post a Comment