Routing script tutorial

From TBwiki
(Difference between revisions)
Jump to: navigation, search
(→Route retry)
(→'route_remap' method)
 
(14 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
== Introduction ==
+
== Introduction ==
−
Working with scripts requires you to define a class that will help you select one of your previously created routes. There are 3 mandatory things to define for your script to work:
+
  
−
# Define your new script routing class, which can contain one or many of these methods (route_order,route_match,route_remap)
+
Working with scripts requires you to define a class that will help you select one of your previously created routes. There are 3 mandatory things to define for your script to work:
−
# The 'init_routes' method
+
−
# The 'route' method
+
  
−
For more information about the parameters that can be used within a method, please see the [[Routing_script_tutorial:Mini_Development_Guide|mini development guide]]
+
#Define your new script routing class, which can contain one or many of these methods (route_order,route_match,route_remap)
 +
#The 'init_routes' method
 +
#The 'route' method
  
 +
For more information about the parameters that can be used within a method, please see the [[Routing script tutorial:Mini Development Guide|mini development guide]]
  
−
== Script routing class ==
+
<br>
−
The scripting class is used to define on which call/NAP parameters the call needs to match the route or to remap the call parameter. You also need to define all new methods required by your script routing class. It is highly recommended to derive your new class for the 'base_routing' class, because it provides you with more functionality.
+
  
 +
== Script routing class  ==
  
−
== What I need to define a script routing class ==
+
The scripting class is used to define on which call/NAP parameters the call needs to match the route or to remap the call parameter. You also need to define all new methods required by your script routing class. It is highly recommended to derive your new class for the 'base_routing' class, because it provides you with more functionality.
−
There are 3 methods that can be used:
+
−
# route_order
+
−
# route_match
+
−
# route_remap
+
  
 +
<br>
  
−
Please note that 'route_order' will be called before 'route_match', both of which will be called before 'route_remap'.
+
== What I need to define a script routing class  ==
  
 +
There are 3 methods that can be used:
  
−
=== 'route_order' method ===
+
#route_order  
 +
#route_match
 +
#route_remap
  
−
'route_order' allows to order routes using one of 3 possible arguments. It is only possible to call 'route_order' once.
+
<br> Please note that 'route_order' will be called before 'route_match', both of which will be called before 'route_remap'.  
−
# :route_field_name - The field name of the '''route''' to order with. The value of the route field should be an '''integer''' so that it can be compared.
+
−
# :proc - A user-supplied '''proc''' to call instead of trying to order internally. It should accept two arguments (route list, nap list) and return the sorted route list.
+
−
# :method - A user-supplied '''method''' to call instead of trying to order internally. It should accept two arguments (route list, nap list) and return the sorted route list.
+
  
−
base_routing pre-implemented ordering method:
+
<br>
−
* 'order_by_asr', this method will order the routes according to the asr(average success rate). This method requires adding a custom '''NAP''' parameter called ':asr_type'. Its value can be: global, last_24h, current_hour, last_hour. It can be used in your custom class like this:
+
  
−
  route_order :method => :order_by_asr
+
=== 'route_order' method ===
  
 +
'route_order' allows to order routes using one of 3 possible arguments. It is only possible to call 'route_order' once.
  
−
=== 'route_match' method ===
+
#&nbsp;:route_field_name - The field name of the '''route''' to order with. The value of the route field should be an '''integer''' so that it can be compared.  
−
'route_match' allows to match a call to one route using one of 4 possible arguments. It is possible to call 'route_match' multiple times to reduce the number of matching routes. Since 'route_match' will return the first matching route it find, there is a possibility that there is more than one route match, therefore it is important to order the routes or prioritize them using 'route_order'.
+
#&nbsp;:proc - A user-supplied '''proc''' to call instead of trying to order internally. It should accept two arguments (route list, nap list) and return the sorted route list.
 +
#&nbsp;:method - A user-supplied '''method''' to call instead of trying to order internally. It should accept two arguments (route list, nap list) and return the sorted route list.
  
−
# :call_field_name - The field name of the call to try to match
+
base_routing pre-implemented ordering method:  
−
# :route_field_name - The field name of the route to try to match with. The default is to use the call field name. If the value of the field is empty, the match is considered positive. The value of the route field can be a regular expression. (e.g., /555000./ )
+
−
# :proc - A user-supplied proc to call instead of trying to do the match internally. It should accept three arguments (route, call, nap list) and return a boolean to indicate the match
+
−
# :method - A user-supplied method to call instead of trying to do the match internally. It should accept three arguments (route, call, nap list) and return a boolean to indicate the match
+
  
−
base_routing pre-implemented matching method:
+
*'order_by_asr', this method will order the routes according to the [[ASR]] (answer seizure ratio). This method requires adding a custom '''NAP''' parameter called ':asr_type'. Its value can be: global, last_24h, current_hour, last_hour. It can be used in your custom class like this:
−
* 'match_nap_availability', this method will verify the availability through the nap status.
+
−
  route_match :method => :match_nap_availability
+
−
* 'match_asr_threshhold', this method will verify will match any route who's destination NAP has a higher asr than the threshold stored for that nap. This method requires adding 2 custom '''NAP''' parameters called. The first custom parameter is 'asr_threshhold_type'. Its values can be: global, last_24h, current_hour, last_hour. The second custom parameter is 'asr_threshhold'. Its value needs to be an '''integer''' between 0 and 100.
+
−
  route_match :method => :match_asr_threshhold
+
  
 +
  route_order&nbsp;:method =&gt;&nbsp;:order_by_asr
  
−
=== 'route_remap' method ===
+
<br>
−
'route_remap' allows to remap the parameter of the route or the call using one of the 4 possible arguments. There are actually 3 types of remapping that can be performed: via the :call_field_name/:route_field_name arguments; the :proc argument; and/or the :method argument.
+
  
−
# :call_field_name - The field name of the call to remap
+
=== 'route_match' method ===
−
# :route_field_name - The field name of the route to remap with. The default is to use the call field name. If the value of the field is empty, the incoming call's attribute is used. The value of the route field can be a regular expression remap. (e.g., /(555000.)/001\1/ )
+
−
# :proc - A user supplied proc to call instead of trying to do the remap internally. It should accept four arguments (route, call, nap list, remapped fields) and return a hash of remapped fields
+
−
# :method - A user supplied method to call instead of trying to do the match internally. It should accept four arguments (route, call, nap list, remapped fields) and return a hash of remapped fields
+
  
 +
'route_match' allows to match a call to one route using one of 4 possible arguments. It is possible to call 'route_match' multiple times to reduce the number of matching routes. Since 'route_match' will return the first matching route it find, there is a possibility that there is more than one route match, therefore it is important to order the routes or prioritize them using 'route_order'.
  
−
=== 'init_routes' method ===
+
====:call_field_name====
−
The 'init_routes' is a mandatory method that is call every time the script is loaded (i.e., think loading the configuration).
+
This option will compare the specified call attribute with the route attribute. For example, :call_field_name => :called will match the called number attribute.
−
It may be to your advantage to perform some pre-processing such as ordering your routes; that way the routes will not be re-ordered at every call that comes in.
+
  
 +
* A route that has empty value is considered "match everything".
 +
* A route that has a specific value will only match if the call has the same value
 +
* A route with a regular expression value will match if the regular expression from the route matches the value from the call
 +
** For example: /555000./ will match any number with 7 digits starting with 555000
 +
* This function supports a special case when matching SIP :calling or :called attributes: The format 'number@sip_host:sip_ort' can be used for matching calling/called number, the domain, and the port.
 +
** For example: 1234@abc.com:5060 will match only calls with number 1234, on SIP host 'abc.com' on port 5060.
 +
** For example: @abc.com will match any call on sip_host 'abc.com' on any port
  
−
=== 'route' method ===
+
====:route_field_name====
−
The 'route' is a mandatory method that is call at every call that comes in. This is where you can perform the dynamic routing part.
+
This option will specify an alternate route attribute name to match with the call attribute :call_field_name (in case the route attribute name differs from the call attribute name)
  
 +
====:proc====
 +
A user-supplied proc to call instead of trying to do the match internally. It should accept three arguments (route, call, nap list) and return a boolean to indicate the match
  
−
== Route retry ==
+
====:method====
−
As soon as more than one route matches an incoming call, route retry apply the following way:
+
A user-supplied method to call instead of trying to do the match internally. It should accept three arguments (route, call, nap list) and return a boolean to indicate the match
−
* An outgoing call will be made based on the first matching route
+
−
* If that outgoing call fails while there are other matching routes left, another outgoing call attempt is made using next matching route
+
−
* Outgoing call is considered failed if terminated with an error before being answered, or if not alerted within defined timeout (5 seconds by default).
+
  
−
Route retry timeout can be configured in the Gateway application configuration page of the Toolpack Web Portal configuration pages:
+
====base_routing pre-implemented matching method====
−
*Go to the '''Gateway->Configuration''' menu.
+
−
*Click on the '''Edit''' link of the configuration you wish modify.
+
−
*Expand the 'Advanced' section
+
−
*Change the value 'Route retry alerting timeout'
+
  
−
== What else? ==
+
*'match_nap_availability', this method will verify the availability through the nap status.
−
There are numerous possibilities:
+
−
* Add new methods for route selection
+
−
* Add new columns in the NAP or route
+
−
* Create scripts that include other scripts to help make the routing more modular
+
  
 +
  route_match&nbsp;:method =&gt;&nbsp;:match_nap_availability
  
−
=== Examples and tutorials ===
+
*'match_asr_threshhold', this method will verify will match any route who's destination NAP has a higher ASR than the threshold stored for that nap. This method requires adding 2 custom '''NAP''' parameters called. The first custom parameter is 'asr_threshhold_type'. Its values can be: global, last_24h, current_hour, last_hour. The second custom parameter is 'asr_threshhold'. Its value needs to be an '''integer''' between 0 and 100.
−
* [[Routing_script_tutorial:Routing_Class_Tutorial|script routing class tutorial]]
+
−
* [[Routing_script_tutorial:route_order_Tutorial|'route_order' tutorial]]
+
−
* [[Routing_script_tutorial:route_match_Tutorial|'route_match' tutorial]]
+
−
* [[Routing_script_tutorial:route_remap_Tutorial|'route_remap' tutorial]]
+
−
* Pre-built routing scripts are also available through the Web Portal in the script routing menu
+
  
 +
  route_match&nbsp;:method =&gt;&nbsp;:match_asr_threshhold
 +
 +
<br>
 +
 +
=== 'route_remap' method  ===
 +
 +
'route_remap' allows to remap the parameter of the route or the call using one of the 4 possible arguments. There are actually 3 types of remapping that can be performed: via the&nbsp;:call_field_name/:route_field_name arguments; the&nbsp;:proc argument; and/or the&nbsp;:method argument.
 +
 +
====:call_field_name====
 +
 +
The field name of the call to remap
 +
====:route_field_name====
 +
 +
The field name of the route to remap with. The default is to use the call field name. If the value of the field is empty, the incoming call's attribute is used. The value of the route field can be a regular expression remap. (e.g., /(555000.)/001\1/ )
 +
====:proc====
 +
A user supplied proc to call instead of trying to do the remap internally. It should accept four arguments (route, call object, nap list, call params) and return a hash of remapped fields
 +
 +
====:method====
 +
A user supplied method to call instead of trying to do the match internally. It should accept four arguments (route, call object, nap list, call params) and return a hash of remapped fields
 +
 +
<br>
 +
 +
=== 'init_routes' method  ===
 +
 +
The 'init_routes' is a mandatory method that is call every time the script is loaded (i.e., think loading the configuration). It may be to your advantage to perform some pre-processing such as ordering your routes; that way the routes will not be re-ordered at every call that comes in.
 +
 +
<br>
 +
 +
=== 'route' method  ===
 +
 +
The 'route' is a mandatory method that is call at every call that comes in. This is where you can perform the dynamic routing part.
 +
 +
<br>
 +
 +
== Route retry algorithm  ==
 +
Documentation on route retry algorithm can be found here:
 +
[[Route_retry]]
 +
 +
== What else?  ==
 +
 +
There are numerous possibilities:
 +
 +
*Add new methods for route selection
 +
*Add new columns in the NAP or route
 +
*Create scripts that include other scripts to help make the routing more modular
 +
 +
<br>
 +
 +
=== Examples and tutorials  ===
 +
 +
*[[Routing script tutorial:Routing Class Tutorial|Routing Script class tutorial]]
 +
*[[Routing script tutorial:route order Tutorial|'route_order' tutorial]]
 +
*[[Routing script tutorial:route match Tutorial|'route_match' tutorial]]
 +
*[[Routing script tutorial:route remap Tutorial|'route_remap' tutorial]]
 +
*Pre-built routing scripts are also available through the Web Portal in the script routing menu
 +
 +
<br>
  
 
----
 
----
−
Back to the [[Scriptable_Routing_Engine|Scriptable Routing Engine]] page.
+
 
 +
Back to the [[Scriptable Routing Engine|Scriptable Routing Engine]] page.
 +
 
 +
== Useful links ==
 +
*[[Tmedia_Routing|Tmedia Routing]]

Latest revision as of 11:42, 9 May 2018

Contents

Introduction

Working with scripts requires you to define a class that will help you select one of your previously created routes. There are 3 mandatory things to define for your script to work:

  1. Define your new script routing class, which can contain one or many of these methods (route_order,route_match,route_remap)
  2. The 'init_routes' method
  3. The 'route' method

For more information about the parameters that can be used within a method, please see the mini development guide


Script routing class

The scripting class is used to define on which call/NAP parameters the call needs to match the route or to remap the call parameter. You also need to define all new methods required by your script routing class. It is highly recommended to derive your new class for the 'base_routing' class, because it provides you with more functionality.


What I need to define a script routing class

There are 3 methods that can be used:

  1. route_order
  2. route_match
  3. route_remap


Please note that 'route_order' will be called before 'route_match', both of which will be called before 'route_remap'.


'route_order' method

'route_order' allows to order routes using one of 3 possible arguments. It is only possible to call 'route_order' once.

  1.  :route_field_name - The field name of the route to order with. The value of the route field should be an integer so that it can be compared.
  2.  :proc - A user-supplied proc to call instead of trying to order internally. It should accept two arguments (route list, nap list) and return the sorted route list.
  3.  :method - A user-supplied method to call instead of trying to order internally. It should accept two arguments (route list, nap list) and return the sorted route list.

base_routing pre-implemented ordering method:

  • 'order_by_asr', this method will order the routes according to the ASR (answer seizure ratio). This method requires adding a custom NAP parameter called ':asr_type'. Its value can be: global, last_24h, current_hour, last_hour. It can be used in your custom class like this: 
 route_order :method => :order_by_asr


'route_match' method

'route_match' allows to match a call to one route using one of 4 possible arguments. It is possible to call 'route_match' multiple times to reduce the number of matching routes. Since 'route_match' will return the first matching route it find, there is a possibility that there is more than one route match, therefore it is important to order the routes or prioritize them using 'route_order'.

:call_field_name

This option will compare the specified call attribute with the route attribute. For example, :call_field_name => :called will match the called number attribute.

  • A route that has empty value is considered "match everything".
  • A route that has a specific value will only match if the call has the same value
  • A route with a regular expression value will match if the regular expression from the route matches the value from the call
    • For example: /555000./ will match any number with 7 digits starting with 555000
  • This function supports a special case when matching SIP :calling or :called attributes: The format 'number@sip_host:sip_ort' can be used for matching calling/called number, the domain, and the port.
    • For example: 1234@abc.com:5060 will match only calls with number 1234, on SIP host 'abc.com' on port 5060.
    • For example: @abc.com will match any call on sip_host 'abc.com' on any port

:route_field_name

This option will specify an alternate route attribute name to match with the call attribute :call_field_name (in case the route attribute name differs from the call attribute name)

:proc

A user-supplied proc to call instead of trying to do the match internally. It should accept three arguments (route, call, nap list) and return a boolean to indicate the match

:method

A user-supplied method to call instead of trying to do the match internally. It should accept three arguments (route, call, nap list) and return a boolean to indicate the match

base_routing pre-implemented matching method

  • 'match_nap_availability', this method will verify the availability through the nap status. 
 route_match :method => :match_nap_availability
  • 'match_asr_threshhold', this method will verify will match any route who's destination NAP has a higher ASR than the threshold stored for that nap. This method requires adding 2 custom NAP parameters called. The first custom parameter is 'asr_threshhold_type'. Its values can be: global, last_24h, current_hour, last_hour. The second custom parameter is 'asr_threshhold'. Its value needs to be an integer between 0 and 100. 
 route_match :method => :match_asr_threshhold


'route_remap' method

'route_remap' allows to remap the parameter of the route or the call using one of the 4 possible arguments. There are actually 3 types of remapping that can be performed: via the :call_field_name/:route_field_name arguments; the :proc argument; and/or the :method argument.

:call_field_name

The field name of the call to remap

:route_field_name

The field name of the route to remap with. The default is to use the call field name. If the value of the field is empty, the incoming call's attribute is used. The value of the route field can be a regular expression remap. (e.g., /(555000.)/001\1/ )

:proc

A user supplied proc to call instead of trying to do the remap internally. It should accept four arguments (route, call object, nap list, call params) and return a hash of remapped fields

:method

A user supplied method to call instead of trying to do the match internally. It should accept four arguments (route, call object, nap list, call params) and return a hash of remapped fields


'init_routes' method

The 'init_routes' is a mandatory method that is call every time the script is loaded (i.e., think loading the configuration). It may be to your advantage to perform some pre-processing such as ordering your routes; that way the routes will not be re-ordered at every call that comes in.


'route' method

The 'route' is a mandatory method that is call at every call that comes in. This is where you can perform the dynamic routing part.


Route retry algorithm

Documentation on route retry algorithm can be found here: Route_retry

What else?

There are numerous possibilities:

  • Add new methods for route selection
  • Add new columns in the NAP or route
  • Create scripts that include other scripts to help make the routing more modular


Examples and tutorials


Back to the Scriptable Routing Engine page.

Useful links

Retrieved from "https://docs.telcobridges.com/mediawiki/index.php?title=Routing_script_tutorial&oldid=25565"
Personal tools