Tmedia Routing

From TBwiki
(Difference between revisions)
Jump to: navigation, search
(rephrase route retry)
(Updated formatting)
 
(71 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
TelcoBridges has developed a simple and flexible call routing engine.
+
== Static routing table  ==
 +
<pre>Gateway -&gt; Routes
 +
</pre>
 +
<br>
 +
[[File:Gateway_Static_Routes.png|Static Routes]]
  
−
It is possible to represent the features of the call routing engine in 4 different sections:
+
=== Basic route matching ===
−
*Base Routing
+
The static routing table uses parameters from the incoming call to locate a route and then make a routing decision. These parameters are called incoming call attributes. Three parameters are verified:<br>
−
*Standard Routing Scripts
+
A route will match an incoming call if all the route matching parameters are met.
−
*Scriptable Routing
+
<br>
−
*Routing Tables
+
<br>
 +
Multiple routes may be a match for a call.
 +
<br>
 +
<br>
 +
The following criteria are available for basic route matching:
 +
*Called number
 +
*Calling number
 +
*Incoming Network Access Point (NAP)
  
 +
==== Calling / called number matching ====
 +
Calling / called number matching works as follows:
 +
*'''Field can be empty: '''this means any number will match
 +
*'''Field can be a specific number: '''this means the exact number must match
 +
*'''Field can be a regular expression match:'''
 +
*'''Field can be a sip user and sip host:''' such as user@sip_host:sip_port
 +
&nbsp;&nbsp;&nbsp; Number Routing filter example:<br>
 +
&nbsp;&nbsp;&nbsp;&nbsp; Ex. /^1?450[0-9]{7}$/<br>&nbsp;&nbsp;&nbsp;&nbsp; This number must match an optional 1, followed by 450, then 7 digits<br>
  
 +
&nbsp;&nbsp;&nbsp; SIP user/host routing example:<br>
 +
&nbsp;&nbsp;&nbsp;&nbsp; Ex. 5551212@abc.com<br>&nbsp;&nbsp;&nbsp;&nbsp; This number must match exactly 5551212 for sip host abc.com only <br> <br>
  
−
== Base Routing ==
+
==== NAP matching ====
−
The base routing is configured by default in the [[VoIP Gateway]].  
+
The Network Access Point can be SS7, ISDN, CAS or SIP.<br>
 +
<br>
  
−
It uses the parameters from the incoming call to find a route and make the routing decision.
+
=== Basic (per-route) call attributes remapping ===
 +
Once the route(s) have been chosen, some call parameters can be modified using the parameters of the route:
 +
==== Outgoing call parameters remapping ====
 +
*'''Remapped Called Number:''' New called number used on the outgoing calls
 +
*'''Remapped Calling Number: '''New calling number used on the outgoing calls
 +
*'''Remapped NAP:''' determines on which Network Access Point (NAP)&nbsp;the outgoing calls are sent.
 +
*'''Outgoing call remapped Profile: '''Select the profile to use with the outgoing call when this route is used, otherwise NAP's default profile is used.
  
−
Incoming call parameters used by base routing:
+
==== Source call leg parameters remapping ====
−
*[[NAP]]
+
Some parameters of the source call leg can also be modified:
−
*Called Number
+
*'''Source call remapped Profile: '''Select the profile to use with the source call leg when this route is used, otherwise the NAP's default profile is used.
−
*Calling Number
+
−
'''NOTE''':The route can filter the called and/or calling numbers using a specific number or use a regular expression.
+
  
−
Once there is a route match (subject to [[NAP]] availability), the [[TMG-CONTROL]] can remap those call parameters to create the outgoing call.  
+
==== Calling / called number remapping options ====
 +
Calling / called number remapping works as follows:
 +
*'''Field can be empty:''' In this case, the called/calling numbers from the incoming call are used for the outgoing call.
 +
*'''Field can be a specific number:''' This number will be used as called (or calling) number for the outgoing call.
 +
*'''Field can be a regular expression:''' Allows building the outgoing call's calling/called number through matching/replacement of incoming calling/called number. <br>
  
−
Here are the parameters that can be change for an outgoing calls:
+
&nbsp;&nbsp;&nbsp; For example, post routing translation (remap)<br>
−
*[[NAP]]
+
−
*[[Nap_Profile|Profile]]
+
−
*Called Number
+
−
*Calling Number
+
−
The called and calling number can be remapped by using a regular expression.
+
  
−
=== Route Retry ===
+
&nbsp;&nbsp;&nbsp;&nbsp; Ex. /^450([0-9]*)$/\514\2<br>
  
−
The routing engine returns all matching routes to the system. The [[TMG-CONTROL]] then generate an outgoing call using the first route of the list. If the call fails, the [[TMG-CONTROL]] may or may not generate another call according to the error code received.
+
&nbsp;&nbsp;&nbsp;&nbsp; This regular expression replaces 450 with 514<br>
  
−
The route retry will proceed with another route if the return code is:
+
For a complete example, refer to: [[Toolpack: How to Use RegEx in Remapped Called and Calling Number Mask|How To Use Regular Expressions]]
−
*Service unavailable
+
−
*No route to destination
+
−
*Etc.
+
  
−
The route retry will not proceed with another route if the return code is:
+
=== Multiple routes matching ===
−
*User busy
+
The remapping parameters above (both for incoming and outgoing calls) are independent for each route.<br>
−
*Unallocated number
+
This allows different routes to use different NAPs, and remap the calling/called numbers differently.<br>
−
*Etc.
+
  
−
It is worth noting that it is possible to modify when the route retry to and not to proceed using the [[Nap_Profile|nap profile]]. For more information see the [[Route_retry|route retry]] page.
+
==== Ordering the routes ====
 +
When multiple routes match the incoming call, the default routing script (simple_routing) will order by priority and weight.<br>
 +
* Note: older routing scripts did not have priority routing enabled by default, you may need to manually update your routing scripts to enable priority routing<br>
 +
<br>
 +
Each route has a "priority" attribute, and a "weight" attribute. All matching routes for a given call will be ordered by priority.<br>
 +
Load-sharing (based on each route's "weight") will be applied if multiple matching routes have the same priority.<br>
 +
<br>
  
−
'''NOTE''':The route retry feature is available to the other types of routing as well.
+
It's also possible to prioritize matching routes using others algorithms, by customizing routing scripts.
 +
A few examples:
 +
* Round robin
 +
* Least cost
 +
* Per period of the day
  
−
== Standard Routing Scripts ==
+
==== Route retry ====
 +
If multiple routes match for a call, call retry may be done on subsequent routes upon failure making outgoing call on a route. For more information about route retry, refer to the following page: [[Route_retry|Route Retry]].
  
−
[[TMG-CONTROL]] has a ready-to-use routing script that can address some of the most common routing needs.
+
=== Routes limitation ===
 +
<u>Up to 2000 routes</u> can be entered in the static routing table.
 +
<br>
 +
<br>
 +
Note: When the number of routes becomes large, this may be a sign that more advanced routing should be used.
 +
<br><br>
 +
For information about label route handling, refer to [[Tmedia_Routing#Label_routing|Label Routing]] or contact [[Support:Contacting_TelcoBridges_technical_support|TelcoBridges Support]]<br>
  
−
=== NAP Priority Routing ===
+
=== Exporting / importing routes ===
 +
You can import or export the static routing table using the web portal. Go to:
 +
<pre>Gateway -&gt; Routes -&gt; Route table actions -&gt; Export Static Routes </pre>
 +
or
 +
<pre>Gateway -&gt; Routes -&gt; Route table actions -&gt; Import Static Routes </pre>
 +
<br> This is the default configuration of the Media Gateway
  
−
*Choose the [[Route|route]] according to [[NAP]] priority.
+
== Standard Scripts<br>  ==
−
*Each [[NAP]] has its own priority setting
+
<pre>Gateway -&gt; Routing scripts </pre>
−
**[[NAP]] custom column: prio (the lower the value, the higher the priority)
+
Standard scripts are used to modify the behavior of the static routing.&nbsp; It allows for the prioritization of routes, load sharing amongst multiple endpoints, or the modification of some call parameters. It can be enabled on any system in just a few steps. The following is a list of Scripts supported today:<br>
−
*If more than 1 route matches, the [[Route|route]] with the highest [[NAP]] priority will be selected first
+
  
−
=== Route Priority Routing ===
+
*'''Simple routing (simple_routing.rb):''' Script used for the static routing table, and supports priority and weight routing per route or NAP.
 +
*'''Priority routing (priority_and_weight_load_balancer.rb):''' This script routes calls according to a priority setting of matching routes. Each route has its own priority setting (if not, taken from the outgoing call's NAP priority). The [:priority] field column needs to be added in the routes and NAPs page. A smaller [:priority] value has more priority. If more than 1 route matches, the route with the lowest NAP priority will be selected first. Routes with the same priority will be randomly ordered using the "weight" column so load is distributed among routes with same priority.
 +
*'''ASR routing (asr_routing.rb):''' This script routes calls according to the ASR values of the destination naps. This kind of routing will try to improve overall system ASR by always using the best NAPs. It will also improve client perception by cleanly dropping calls that would almost certainly fail anyway.
 +
*'''Nature of Address and Numbering plan indicator remapping (noa_npi_remap.rb): '''Enables the modification of the NOA and NPI values on outgoing calls.
 +
*'''Least Cost Routing (least_cost_routing.rb):''' This script routes calls according to the cost values (which may depend on the time) of the routes. This is useful for cases when a route's popularity (cost) depends on the time of the day. This is done by adding different columns to the static routing tables (for example [:cost_0_6]) and filling them up with values for each route.
  
−
*Choose the [[Route|route]] according to [[Route|route]] priority.
+
Learn how to setup Standard Scripts in your gateway by following these steps: [[How to Setup Standard Scripts|How to Setup Standard Scripts]]<br>
−
*Each [[Route|route]] has its own priority setting
+
−
**[[Route]] custom column: prio (the lower the value, the higher the priority)
+
−
*If more than 1 route matches, the [[Route|route]] with the highest [[Route|route]] priority will be selected first
+
  
−
=== Percentage Routing ===
+
Other standard routing scripts implement Filters and are covered in the next section.
  
−
*Load share traffic between multiple [[NAP|NAPs]]
+
== Filters  ==
−
*Each [[NAP]] has its own weight setting
+
<pre>Gateway -&gt; Routing scripts </pre>
−
**[[NAP]] custom column: percent_target (the higher the weight, the higher the traffic proportion)
+
Adds functionality to standard scripts. Filters can be added to any standard script in a few steps. For example, you may want to remove the '1' prefix for uniformed routing, select the SIP Request URI to route the call instead of the called number, and more.
−
*If more than 1 route matches, the outgoing will be generated according to weight and [[ASR]]
+
  
−
== Scriptable Routing ==
+
=== Types of filters ===
 +
The following type of filters can be attached to a routing script, and they are applied in the following order
 +
# before_filter  -> Analyze/modify the call attributes before other filters are applied
 +
# route_match    -> Eliminates routes based on some matching criteria
 +
# order_route    -> Change the order of matching routes
 +
# after_filter  -> Filters that are applied after matching routes have been selected and ordered. Can modify the incoming call attributes before the outgoing calls are created
 +
# route_remap    -> Called once per matching route. Perform per-route remapping of some call attributes, based on per-route attributes
 +
# after_remap    -> Last filters to be applied. Called once, but has access to list of matching routes, and list of "outgoing call" attributes. Can modify the outgoing calls.
  
−
For customers who requires more complex scenarios, it is possible to use the scriptable routing engine.
+
==== Before filter (before_filter) ====
 +
* Adds pre-processing on incoming parameters before other filters are applied
 +
* Calls a user-defined method that can modify incoming call's attributes before other filters process the call
  
−
Features of the scriptable routing engine
+
Example:
−
*Scripts are written in Ruby
+
In the main script, attach the filter:
−
*Can use the Web Portal for editing the scripts
+
  before_filter :method => :my_custom_before_filter, :my_param => "some value"
−
*Does complex routing and routing translation on a large amount of parameters:
+
In another script file, define the following methods:
−
**Calling Number, Called Number, NOA, NPI, Presentation, Screening, Redirecting Number, Original Called Number, etc.
+
  # Called once when the configuration is applied
−
*Can modify the ready-to-use routing script to add functionality
+
  # Used to prepare the filter, process routes, NAPs, etc.
−
*Can import and export routing scripts in .rb format
+
  def init_my_custom_before_filter( params )
−
*[[TMG-CONTROL]] upgrade doesn't will not modify scripts
+
    # params contains:
 +
    #  - The parameters you passed when attached this filter in your main script
 +
    #  - params[ :routes ]  Array of all routes in your configuration with all their attributes.
 +
    #                        Cannot be modified, though this function may clone them to another array if necessary.
 +
    #  - params[ :naps ]     Array of all NAPs in the configuration and their attributes.
 +
    #                        Cannot be modified, though this function may clone them to another array if necessary.
 +
  end
  
 +
  # Called once per incoming call
 +
  def my_custom_before_filter( params )
 +
    # params contains:
 +
    #  - The parameters you passed when attached this filter in your main script
 +
    #  - params[ :call]      Hash of call attributes of the incoming call to route.
 +
    #                        Can be modified. Will affect subsequent filters, and routing output.
 +
    #  - params[ :routes ]  Array of all routes in your configuration with all their attributes.
 +
    #                        Cannot be modified.
 +
    #  - params[ :naps ]    Array of all NAPs in the configuration and their attributes
 +
    #                        Cannot be modified.
  
−
== Routing Tables ==
+
    return params
 +
  end
  
−
The routing tables are useful for customers that needs to manage a very large number of phone numbers that can be accessible from one or more providers but cannot be easily expressed with a regular expression.
+
==== Route match (route_match) ====
 +
Eliminates routes based on some matching criteria.
  
−
The routing tables can be summarize by the following:
+
* Generally simply matching a call attribute with a route attribute.
−
*Breaks the provider/called number relationship (from a regular route) into 2 entities
+
* Any route with attribute not matching the corresponding call attribute is eliminated.
−
**Digit map
+
* A route with empty attribute is considered matching any call
−
**Routeset definition
+
−
*The digit map creates an association for each phone number to 1 or many destinations
+
−
*The Routeset definition creates an association for each provider to 1 or many destinations
+
  
−
NOTE: The routing tables support import/export of rouset definition and digit map in CSV file format.
+
Examples:
 +
* Match the call attribute :called with the route attribute with same name:
 +
  route_match :call_field_name => :called
 +
* Match the call attribute :private_address with the route attribute :calling
 +
  route_match :call_field_name => :private_address , call_field_name => :calling
  
 +
Custom methods can be attached.
 +
Example:
 +
In the main script, attach the filter:
 +
  route_match :method => :my_custom_matching, :my_param => "some value"
 +
In another script file, define the following methods:
 +
  # Called once when the configuration is applied
 +
  # Used to prepare the filter, process routes, NAPs, etc.
 +
  def init_my_custom_matching( params )
 +
    # (See init_my_custom_before_filter above for description of params)
 +
  end
  
−
[[Category:Tmedia Features|Routing]]
+
  # Called once per incoming call
 +
  # Must return true if route matches, false otherwise
 +
  def my_custom_matching( route, call, naps )
 +
    # route contains the route to match.
 +
    # call contains the incoming call attributes to match with the route.
 +
    # naps contains an array of all NAPs and their attributes.
 +
    return true
 +
  end
 +
 
 +
==== Order route (order_route) ====
 +
Change the order of matching routes based on a given route attribute.
 +
 
 +
Example:
 +
In the main script, attach the filter:
 +
  order_route :route_field_name => :priority
 +
 
 +
==== After filter (after_filter) ====
 +
* Filter that is applied after matching routes have been selected and ordered.
 +
* Can modify the incoming call attributes before the outgoing calls are created.
 +
* Calls a user-defined method that can modify incoming call's attribute
 +
 
 +
Example:
 +
In the main script, attach the filter:
 +
  after_filter :method => :my_custom_after_filter, :my_param => "some value"
 +
In another script file, define the following methods:
 +
  # Called once when the configuration is applied
 +
  # Used to prepare the filter, process routes, NAPs, etc.
 +
  def init_my_custom_after_filter( params )
 +
    # See init_my_custom_before_filter above for details about params
 +
  end
 +
 
 +
  # Called once per incoming call
 +
  def my_custom_after_filter( params )
 +
    # See my_custom_before_filter above for details about params
 +
 
 +
    return params
 +
  end
 +
 
 +
==== Route remap (route_remap) ====
 +
* Called once per matching route.
 +
* Perform per-route remapping of some call attributes, based on per-route attributes.
 +
 
 +
Examples:
 +
* Remap the call attribute :called with the route attribute :remapped_called
 +
  route_remap :call_field_name => :called, :route_field_name => :remapped_called
 +
 
 +
Custom methods can be attached.
 +
Example:
 +
In the main script, attach the filter:
 +
  route_remap :method => :my_custom_remap, :my_param => "some value"
 +
In another script file, define the following methods:
 +
  # Called once when the configuration is applied
 +
  # Used to prepare the filter, process routes, NAPs, etc.
 +
  def init_my_custom_remap( params )
 +
    # (See init_my_custom_before_filter above for description of params)
 +
  end
 +
 
 +
  # Called once per matching route for a given incoming call
 +
  def my_custom_remap( route, caf_call, naps, call )
 +
    # route contains the route to apply remapping for
 +
    # caf_call should be ignored (legacy)
 +
    # naps contains an array of all NAPs and their attributes.
 +
    # call contains the outgoing call attributes that can be remapped.
 +
 
 +
    return call
 +
  end
 +
 
 +
==== After remap (after_remap) ====
 +
* Last filters to be applied.
 +
* Called once, but has access to list of matching routes, and list of "outgoing call" attributes.
 +
* Can modify the outgoing calls.
 +
* Calls a user-defined method that can modify incoming call's attribute
 +
 
 +
Example:
 +
In the main script, attach the filter:
 +
  after_remap_filter :method => :my_custom_after_remap_filter, :my_param => "some value"
 +
In another script file, define the following methods:
 +
  # Called once when the configuration is applied
 +
  # Used to prepare the filter, process routes, NAPs, etc.
 +
  def init_my_custom_after_remap_filter( params )
 +
    # See init_my_custom_before_filter above for details about params
 +
  end
 +
 
 +
  # Called once per incoming call
 +
  def my_custom_after_remap_filter( params )
 +
    #  - params[ :call]      Hash of call attributes of the incoming call.
 +
    #                        Useless to modify, because has been copied to params[ :out_calls ] for each matching route
 +
    #  - params[ :out_calls ] Array of all outgoing call to be created (corresponding to each matching route).
 +
    #                        Can be modified to customize each outgoing call attempt.
 +
    #  - params[ :routes ]  Array of all routes in your configuration with all their attributes.
 +
    #                        Cannot be modified.
 +
    #  - params[ :naps ]    Array of all NAPs in the configuration and their attributes
 +
    #                        Cannot be modified.
 +
 
 +
    return params
 +
  end
 +
 
 +
=== Notes on parameters ===
 +
Parameters will be mapped to variables to be used in the script.<br\>
 +
For example the '''SIP:To - user-info''' will be mapped to the '''called''' parameter.<br\>
 +
Parameters will only appear in the structures if they are ''present''. For example a call without any SIP '''diversion''' header will not have the '''original_called_number''' parameter present.
 +
 
 +
===='''call''' parameters====
 +
'''call''' parameters include all the parameters here:
 +
[[Routing_script_tutorial:Mini_Development_Guide#Script_parameters_protocol_mapping|Routing Scripts variables]]
 +
 
 +
===='''routes''' parameters====
 +
'''routes''' parameters include all the parameters here:
 +
{| cellpadding="5" border="1" class="wikitable"
 +
|-
 +
! width="250" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | Variable name
 +
! width="500" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | Description
 +
|-
 +
| valign="top" |
 +
route_name
 +
| valign="top" |
 +
"Name" column in the routing table
 +
|-
 +
| valign="top" |
 +
routeset_name
 +
| valign="top" |
 +
Label name. Only used in label routing: see [[Label_Routing]]
 +
|-
 +
| valign="top" |
 +
nap 
 +
| valign="top" |
 +
NAP (Network Access Point) where the incoming call was received
 +
|-
 +
| valign="top" |
 +
called
 +
| valign="top" |
 +
called number of the incoming call
 +
|-
 +
| valign="top" |
 +
calling
 +
| valign="top" |
 +
calling number of the incoming call
 +
|-
 +
| valign="top" |
 +
remapped_nap
 +
| valign="top" |
 +
NAP of the outgoing call
 +
|-
 +
| valign="top" |
 +
remapped_called
 +
| valign="top" |
 +
called number of the outgoing call
 +
|-
 +
| valign="top" |
 +
remapped_calling 
 +
| valign="top" |
 +
calling number of the outgoing call
 +
|-
 +
| valign="top" |
 +
priority
 +
| valign="top" |
 +
used for setting the priority of the route - lowest value has highest priority
 +
|-
 +
| valign="top" |
 +
weight 
 +
| valign="top" |
 +
used for load sharing
 +
|-
 +
| valign="top" |
 +
custom route parameters
 +
| valign="top" |
 +
various parameters attached to a particular route that can be used in the routing scripts
 +
|}
 +
 
 +
===='''naps''' parameters ====
 +
'''naps''' parameters include:
 +
{| cellpadding="5" border="1" class="wikitable"
 +
|-
 +
! width="250" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | Variable name
 +
! width="500" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | Description
 +
|-
 +
| valign="top" |
 +
routeset_definition
 +
| valign="top" |
 +
pointer to routeset definition file if label routing is used: see [[Label_Routing]]
 +
|-
 +
| valign="top" |
 +
routeset_digitmap
 +
| valign="top" |
 +
pointer to routeset digitmap file if label routing is used: [[Label_Routing]]
 +
|-
 +
| valign="top" |
 +
custom NAP parameters
 +
| valign="top" |
 +
various parameters attached to a particular NAP, that can be used in the routing scripts
 +
|}
 +
 
 +
===='''out_calls''' parameters====
 +
'''out_calls''' parameters are the same as "call" parameters, but one set for each route.<br\>
 +
The list of parameters can be different for each route. This describes the call parameters for each one of them. <br\>
 +
out_call[0] maps the first set of parameters to be used for the first route. <br\>
 +
 
 +
=== Filter Scripts examples:  ===
 +
See  [[How to Setup Filters|How to setup Filters]]<br>
 +
 
 +
== <br>Label routing<br>  ==
 +
<pre>Gateway -&gt; Routing scripts
 +
Gateway -&gt; FileDb
 +
Gateway -&gt; Routesets </pre>
 +
<br>
 +
 
 +
Label routing was created because in some cases, regular expressions cannot be used on the called number to define a route.
 +
 
 +
Problem: Having thousands of destination numbers (N), and possibly one route per number per Network Provider (M), resulting in N*M routes<br>Solution: Create labels for each groups of numbers (L) and let the system determine the route, resulting in L*M routes, where L &lt; N
 +
 
 +
A Label is a virtual group of destination numbers. This virtual group has a list of numbers assigned to it in a CSV file.<br>This process does the routing in 2 stages:<br>1st stage - Find a Label: Find longest prefix match entry for the called number. This leads to only one destination Label. This is the Digitmap file.<br>2nd stage - Find the NAPs serving a Label: All routes tied to this Label are eligible for routing the call. This is the routeset definition file.
 +
 
 +
What are the advantages compared to static routing?<br>
 +
 
 +
*Can have thousands of numbers
 +
*It uses a non linear search algorithms; therefore, there is no overhead to having a large amount of numbers. Label routing was tested with 5 million entries.
 +
*Variables can be added to the routeset definition file to use other filter scripts and have even more flexibility.
 +
 
 +
<br>
 +
 
 +
Example usage:<br>
 +
 
 +
*NPA-NXX routing
 +
*Blacklisting
 +
*Tandem switch
 +
 
 +
<br>
 +
 
 +
See here for complete details: [[Routeset Routing|Label routing]] and [[Adding_Label_Routing_to_any_Routing_Script|Adding Label Routing to any Routing Script]]<br>
 +
 
 +
== <br>Custom Routing Scripts<br>  ==
 +
<pre>Gateway -&gt; Routing scripts </pre>
 +
Customers can create their own routing scripts using a Scriptable Routing Engine based on Ruby. These scripts can be imported and exported from the Web portal.<br>These scripts can run complex routing algorithms and post routing translation, as well as other advanced functions. It is also possible to modify standard Scripts, or filters, to satisfy more complex scenarios<br>The functions have control over many call parameters such as:<br>
 +
 
 +
*Calling
 +
*Called
 +
*Nature of Address
 +
*Calling Presentation
 +
*Calling Screening
 +
*Redirecting Number
 +
*Original Called Number, etc. <br>
 +
 
 +
<br>The complete list is in the [[Routing script tutorial:Mini Development Guide|Routing Script Tutorial]]<br>
 +
 
 +
Custom routing script are kept on software upgrades. Versionning of routing scripts needs to be handled by the operator of the unit. The new scripts (with the same names, but a new version) can be manually replaced directly in the routing script page.<br>It is possible to test routing scripts directly from the web portal before activating them in a live system.<br>For complete details, refer to [[Scriptable Routing Engine|Scriptable Routing Engine]]<br>
 +
 
 +
=== <br>Playing prompts<br>  ===
 +
You can use routing scripts to request for prompts playback at various states of the call. See  [[Routing_script_tutorial:Mini_Development_Guide#Playing_prompts_announcements_or_tones|Playing prompts announcements or tones]].
 +
 
 +
=== <br>Recording calls<br>  ===
 +
You can use routing scripts to request the recording of incoming and/or outgoing call legs to audio files. See  [[Routing_script_tutorial:Mini_Development_Guide#Recording_call_legs|Recording Calls]].
 +
 
 +
== <br>Route retry<br>  ==
 +
 
 +
The routing engine returns all matching routes to the system. The TMG-CONTROL then generates an outgoing call using the first route in the list. If the call fails, the TMG-CONTROL may or may not generate another call, according to the error code received.
 +
 
 +
The route retry will proceed with another route, if the return code is:<br>
 +
 
 +
*Service unavailable
 +
*Circuit not available
 +
*and more...
 +
 
 +
The route retry will not proceed with another route, if the return code is:<br>
 +
 
 +
*User busy
 +
*Unallocated number
 +
*and more...
 +
 
 +
<br>
 +
 
 +
You can modify the route-retry sequence (continue or discontinue) to handle unsuccessful routes. For more information, refer to the NAP profile. For more details see the route retry page.<br>These parameters can be modified here:<br>
 +
<pre>Profiles -&gt; default [Edit] -&gt; Edit Reason Cause mapping </pre>
 +
<br>
 +
 
 +
Route retry is enabled by default. Timers and conditions on route retry can be adjusted from the configuration:<br>
 +
<pre>Gateway -&gt; Configurations -&gt; Advanced </pre>
 +
NOTE: The route-retry feature is available for other types of routing as well.
 +
 
 +
<br>
 +
 
 +
For more details, see the [[Route retry|Route Retry]] page<br>
 +
 
 +
<br>
 +
 
 +
[[category:Tmedia_Features]]
 +
 
 +
== Related actions ==
 +
'''Refer to the appropriate Toolpack release:'''
 +
*[[Toolpack:Tsbc_Call_Routes_Settings_3.1|Call Routes Settings v3.1]]
 +
*[[Toolpack:Call_Routes_Settings_D|Call Routes Settings v3.0]]
 +
*[[Toolpack:Call_Routes_Settings_C|Call Routes Settings v2.10]]
 +
*[[Toolpack:Call_Routes_Settings_B|Call Routes Settings v2.9]]
 +
<div class="mw-collapsible mw-collapsed" data-collapsetext="other versions" data-expandtext="Click here for other versions" style="width: 400px;">
 +
*[[Toolpack:Call_Routes_Settings_A|Call Routes Settings v2.8]]
 +
*[[Web_Portal_Tutorial_Guide_v2.7#Routes|Web Portal v2.7: Routes Configuration]]
 +
*[[Web_Portal_Tutorial_Guide_v2.6#Routes|Web Portal v2.6: Routes Configuration]]
 +
</div>

Latest revision as of 16:02, 14 April 2020

Contents

Static routing table 

Gateway -> Routes


Static Routes

Basic route matching

The static routing table uses parameters from the incoming call to locate a route and then make a routing decision. These parameters are called incoming call attributes. Three parameters are verified:
A route will match an incoming call if all the route matching parameters are met.

Multiple routes may be a match for a call.

The following criteria are available for basic route matching:

  • Called number
  • Calling number
  • Incoming Network Access Point (NAP)

Calling / called number matching

Calling / called number matching works as follows:

  • Field can be empty: this means any number will match
  • Field can be a specific number: this means the exact number must match
  • Field can be a regular expression match:
  • Field can be a sip user and sip host: such as user@sip_host:sip_port

    Number Routing filter example:
     Ex. /^1?450[0-9]{7}$/
     This number must match an optional 1, followed by 450, then 7 digits

    SIP user/host routing example:
     Ex. 5551212@abc.com
     This number must match exactly 5551212 for sip host abc.com only

NAP matching

The Network Access Point can be SS7, ISDN, CAS or SIP.

Basic (per-route) call attributes remapping

Once the route(s) have been chosen, some call parameters can be modified using the parameters of the route:

Outgoing call parameters remapping

  • Remapped Called Number: New called number used on the outgoing calls
  • Remapped Calling Number: New calling number used on the outgoing calls
  • Remapped NAP: determines on which Network Access Point (NAP) the outgoing calls are sent.
  • Outgoing call remapped Profile: Select the profile to use with the outgoing call when this route is used, otherwise NAP's default profile is used.

Source call leg parameters remapping

Some parameters of the source call leg can also be modified:

  • Source call remapped Profile: Select the profile to use with the source call leg when this route is used, otherwise the NAP's default profile is used.

Calling / called number remapping options

Calling / called number remapping works as follows:

  • Field can be empty: In this case, the called/calling numbers from the incoming call are used for the outgoing call.
  • Field can be a specific number: This number will be used as called (or calling) number for the outgoing call.
  • Field can be a regular expression: Allows building the outgoing call's calling/called number through matching/replacement of incoming calling/called number.

    For example, post routing translation (remap)

     Ex. /^450([0-9]*)$/\514\2

     This regular expression replaces 450 with 514

For a complete example, refer to: How To Use Regular Expressions

Multiple routes matching

The remapping parameters above (both for incoming and outgoing calls) are independent for each route.
This allows different routes to use different NAPs, and remap the calling/called numbers differently.

Ordering the routes

When multiple routes match the incoming call, the default routing script (simple_routing) will order by priority and weight.

  • Note: older routing scripts did not have priority routing enabled by default, you may need to manually update your routing scripts to enable priority routing


Each route has a "priority" attribute, and a "weight" attribute. All matching routes for a given call will be ordered by priority.
Load-sharing (based on each route's "weight") will be applied if multiple matching routes have the same priority.

It's also possible to prioritize matching routes using others algorithms, by customizing routing scripts. A few examples:

  • Round robin
  • Least cost
  • Per period of the day

Route retry

If multiple routes match for a call, call retry may be done on subsequent routes upon failure making outgoing call on a route. For more information about route retry, refer to the following page: Route Retry.

Routes limitation

Up to 2000 routes can be entered in the static routing table.

Note: When the number of routes becomes large, this may be a sign that more advanced routing should be used. 

For information about label route handling, refer to Label Routing or contact TelcoBridges Support

Exporting / importing routes

You can import or export the static routing table using the web portal. Go to: 

Gateway -> Routes -> Route table actions -> Export Static Routes

or 

Gateway -> Routes -> Route table actions -> Import Static Routes


This is the default configuration of the Media Gateway

Standard Scripts

Gateway -> Routing scripts

Standard scripts are used to modify the behavior of the static routing.  It allows for the prioritization of routes, load sharing amongst multiple endpoints, or the modification of some call parameters. It can be enabled on any system in just a few steps. The following is a list of Scripts supported today:

  • Simple routing (simple_routing.rb): Script used for the static routing table, and supports priority and weight routing per route or NAP.
  • Priority routing (priority_and_weight_load_balancer.rb): This script routes calls according to a priority setting of matching routes. Each route has its own priority setting (if not, taken from the outgoing call's NAP priority). The [:priority] field column needs to be added in the routes and NAPs page. A smaller [:priority] value has more priority. If more than 1 route matches, the route with the lowest NAP priority will be selected first. Routes with the same priority will be randomly ordered using the "weight" column so load is distributed among routes with same priority.
  • ASR routing (asr_routing.rb): This script routes calls according to the ASR values of the destination naps. This kind of routing will try to improve overall system ASR by always using the best NAPs. It will also improve client perception by cleanly dropping calls that would almost certainly fail anyway.
  • Nature of Address and Numbering plan indicator remapping (noa_npi_remap.rb): Enables the modification of the NOA and NPI values on outgoing calls.
  • Least Cost Routing (least_cost_routing.rb): This script routes calls according to the cost values (which may depend on the time) of the routes. This is useful for cases when a route's popularity (cost) depends on the time of the day. This is done by adding different columns to the static routing tables (for example [:cost_0_6]) and filling them up with values for each route.

Learn how to setup Standard Scripts in your gateway by following these steps: How to Setup Standard Scripts

Other standard routing scripts implement Filters and are covered in the next section.

Filters 

Gateway -> Routing scripts

Adds functionality to standard scripts. Filters can be added to any standard script in a few steps. For example, you may want to remove the '1' prefix for uniformed routing, select the SIP Request URI to route the call instead of the called number, and more.

Types of filters

The following type of filters can be attached to a routing script, and they are applied in the following order

  1. before_filter -> Analyze/modify the call attributes before other filters are applied
  2. route_match -> Eliminates routes based on some matching criteria
  3. order_route -> Change the order of matching routes
  4. after_filter -> Filters that are applied after matching routes have been selected and ordered. Can modify the incoming call attributes before the outgoing calls are created
  5. route_remap -> Called once per matching route. Perform per-route remapping of some call attributes, based on per-route attributes
  6. after_remap -> Last filters to be applied. Called once, but has access to list of matching routes, and list of "outgoing call" attributes. Can modify the outgoing calls.

Before filter (before_filter)

  • Adds pre-processing on incoming parameters before other filters are applied
  • Calls a user-defined method that can modify incoming call's attributes before other filters process the call

Example: In the main script, attach the filter: 

 before_filter :method => :my_custom_before_filter, :my_param => "some value"

In another script file, define the following methods: 

 # Called once when the configuration is applied
 # Used to prepare the filter, process routes, NAPs, etc.
 def init_my_custom_before_filter( params )
   # params contains:
   #  - The parameters you passed when attached this filter in your main script
   #  - params[ :routes ]   Array of all routes in your configuration with all their attributes.
   #                        Cannot be modified, though this function may clone them to another array if necessary.
   #  - params[ :naps ]     Array of all NAPs in the configuration and their attributes.
   #                        Cannot be modified, though this function may clone them to another array if necessary.
 end

 # Called once per incoming call
 def my_custom_before_filter( params )
   # params contains:
   #  - The parameters you passed when attached this filter in your main script
   #  - params[ :call]      Hash of call attributes of the incoming call to route.
   #                        Can be modified. Will affect subsequent filters, and routing output.
   #  - params[ :routes ]   Array of all routes in your configuration with all their attributes.
   #                        Cannot be modified.
   #  - params[ :naps ]     Array of all NAPs in the configuration and their attributes
   #                        Cannot be modified.

   return params
 end

Route match (route_match)

Eliminates routes based on some matching criteria.

  • Generally simply matching a call attribute with a route attribute.
  • Any route with attribute not matching the corresponding call attribute is eliminated.
  • A route with empty attribute is considered matching any call

Examples:

  • Match the call attribute :called with the route attribute with same name: 
 route_match :call_field_name => :called
  • Match the call attribute :private_address with the route attribute :calling 
 route_match :call_field_name => :private_address , call_field_name => :calling

Custom methods can be attached. Example: In the main script, attach the filter: 

 route_match :method => :my_custom_matching, :my_param => "some value"

In another script file, define the following methods: 

 # Called once when the configuration is applied
 # Used to prepare the filter, process routes, NAPs, etc.
 def init_my_custom_matching( params )
   # (See init_my_custom_before_filter above for description of params)
 end

 # Called once per incoming call
 # Must return true if route matches, false otherwise
 def my_custom_matching( route, call, naps )
   # route contains the route to match.
   # call contains the incoming call attributes to match with the route.
   # naps contains an array of all NAPs and their attributes.
   return true
 end

Order route (order_route)

Change the order of matching routes based on a given route attribute.

Example: In the main script, attach the filter: 

 order_route :route_field_name => :priority

After filter (after_filter)

  • Filter that is applied after matching routes have been selected and ordered.
  • Can modify the incoming call attributes before the outgoing calls are created.
  • Calls a user-defined method that can modify incoming call's attribute

Example: In the main script, attach the filter: 

 after_filter :method => :my_custom_after_filter, :my_param => "some value"

In another script file, define the following methods: 

 # Called once when the configuration is applied
 # Used to prepare the filter, process routes, NAPs, etc.
 def init_my_custom_after_filter( params )
   # See init_my_custom_before_filter above for details about params
 end

 # Called once per incoming call
 def my_custom_after_filter( params )
   # See my_custom_before_filter above for details about params

   return params
 end

Route remap (route_remap)

  • Called once per matching route.
  • Perform per-route remapping of some call attributes, based on per-route attributes.

Examples:

  • Remap the call attribute :called with the route attribute :remapped_called 
 route_remap :call_field_name => :called, :route_field_name => :remapped_called

Custom methods can be attached. Example: In the main script, attach the filter: 

 route_remap :method => :my_custom_remap, :my_param => "some value"

In another script file, define the following methods: 

 # Called once when the configuration is applied
 # Used to prepare the filter, process routes, NAPs, etc.
 def init_my_custom_remap( params )
   # (See init_my_custom_before_filter above for description of params)
 end

 # Called once per matching route for a given incoming call
 def my_custom_remap( route, caf_call, naps, call )
   # route contains the route to apply remapping for
   # caf_call should be ignored (legacy)
   # naps contains an array of all NAPs and their attributes.
   # call contains the outgoing call attributes that can be remapped.

   return call
 end

After remap (after_remap)

  • Last filters to be applied.
  • Called once, but has access to list of matching routes, and list of "outgoing call" attributes.
  • Can modify the outgoing calls.
  • Calls a user-defined method that can modify incoming call's attribute

Example: In the main script, attach the filter: 

 after_remap_filter :method => :my_custom_after_remap_filter, :my_param => "some value"

In another script file, define the following methods: 

 # Called once when the configuration is applied
 # Used to prepare the filter, process routes, NAPs, etc.
 def init_my_custom_after_remap_filter( params )
   # See init_my_custom_before_filter above for details about params
 end

 # Called once per incoming call
 def my_custom_after_remap_filter( params )
   #  - params[ :call]      Hash of call attributes of the incoming call.
   #                        Useless to modify, because has been copied to params[ :out_calls ] for each matching route
   #  - params[ :out_calls ] Array of all outgoing call to be created (corresponding to each matching route).
   #                        Can be modified to customize each outgoing call attempt.
   #  - params[ :routes ]   Array of all routes in your configuration with all their attributes.
   #                        Cannot be modified.
   #  - params[ :naps ]     Array of all NAPs in the configuration and their attributes
   #                        Cannot be modified.

   return params
 end

Notes on parameters

Parameters will be mapped to variables to be used in the script.
For example the SIP:To - user-info will be mapped to the called parameter.
Parameters will only appear in the structures if they are present. For example a call without any SIP diversion header will not have the original_called_number parameter present.

call parameters

call parameters include all the parameters here: Routing Scripts variables

routes parameters

routes parameters include all the parameters here:

Variable name Description

route_name

"Name" column in the routing table

routeset_name

Label name. Only used in label routing: see Label_Routing

nap

NAP (Network Access Point) where the incoming call was received

called

called number of the incoming call

calling

calling number of the incoming call

remapped_nap

NAP of the outgoing call

remapped_called

called number of the outgoing call

remapped_calling

calling number of the outgoing call

priority

used for setting the priority of the route - lowest value has highest priority

weight

used for load sharing

custom route parameters

various parameters attached to a particular route that can be used in the routing scripts

naps parameters

naps parameters include:

Variable name Description

routeset_definition

pointer to routeset definition file if label routing is used: see Label_Routing

routeset_digitmap

pointer to routeset digitmap file if label routing is used: Label_Routing

custom NAP parameters

various parameters attached to a particular NAP, that can be used in the routing scripts

out_calls parameters

out_calls parameters are the same as "call" parameters, but one set for each route.
The list of parameters can be different for each route. This describes the call parameters for each one of them.
out_call[0] maps the first set of parameters to be used for the first route.

Filter Scripts examples:

See How to setup Filters


Label routing

Gateway -> Routing scripts
Gateway -> FileDb
Gateway -> Routesets


Label routing was created because in some cases, regular expressions cannot be used on the called number to define a route.

Problem: Having thousands of destination numbers (N), and possibly one route per number per Network Provider (M), resulting in N*M routes
Solution: Create labels for each groups of numbers (L) and let the system determine the route, resulting in L*M routes, where L < N

A Label is a virtual group of destination numbers. This virtual group has a list of numbers assigned to it in a CSV file.
This process does the routing in 2 stages:
1st stage - Find a Label: Find longest prefix match entry for the called number. This leads to only one destination Label. This is the Digitmap file.
2nd stage - Find the NAPs serving a Label: All routes tied to this Label are eligible for routing the call. This is the routeset definition file.

What are the advantages compared to static routing?

  • Can have thousands of numbers
  • It uses a non linear search algorithms; therefore, there is no overhead to having a large amount of numbers. Label routing was tested with 5 million entries.
  • Variables can be added to the routeset definition file to use other filter scripts and have even more flexibility.


Example usage:

  • NPA-NXX routing
  • Blacklisting
  • Tandem switch


See here for complete details: Label routing and Adding Label Routing to any Routing Script


Custom Routing Scripts

Gateway -> Routing scripts

Customers can create their own routing scripts using a Scriptable Routing Engine based on Ruby. These scripts can be imported and exported from the Web portal.
These scripts can run complex routing algorithms and post routing translation, as well as other advanced functions. It is also possible to modify standard Scripts, or filters, to satisfy more complex scenarios
The functions have control over many call parameters such as:

  • Calling
  • Called
  • Nature of Address
  • Calling Presentation
  • Calling Screening
  • Redirecting Number
  • Original Called Number, etc.


The complete list is in the Routing Script Tutorial

Custom routing script are kept on software upgrades. Versionning of routing scripts needs to be handled by the operator of the unit. The new scripts (with the same names, but a new version) can be manually replaced directly in the routing script page.
It is possible to test routing scripts directly from the web portal before activating them in a live system.
For complete details, refer to Scriptable Routing Engine


Playing prompts

You can use routing scripts to request for prompts playback at various states of the call. See Playing prompts announcements or tones.


Recording calls

You can use routing scripts to request the recording of incoming and/or outgoing call legs to audio files. See Recording Calls.


Route retry

The routing engine returns all matching routes to the system. The TMG-CONTROL then generates an outgoing call using the first route in the list. If the call fails, the TMG-CONTROL may or may not generate another call, according to the error code received.

The route retry will proceed with another route, if the return code is:

  • Service unavailable
  • Circuit not available
  • and more...

The route retry will not proceed with another route, if the return code is:

  • User busy
  • Unallocated number
  • and more...


You can modify the route-retry sequence (continue or discontinue) to handle unsuccessful routes. For more information, refer to the NAP profile. For more details see the route retry page.
These parameters can be modified here:

Profiles -> default [Edit] -> Edit Reason Cause mapping


Route retry is enabled by default. Timers and conditions on route retry can be adjusted from the configuration:

Gateway -> Configurations -> Advanced

NOTE: The route-retry feature is available for other types of routing as well.


For more details, see the Route Retry page


Related actions

Refer to the appropriate Toolpack release:

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