Actions

Tmedia Routing: Difference between revisions

(Updated to link filters)
(First draft of parameters description)
Line 276: Line 276:
     return params
     return params
   end
   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 diversion header will not have the "original_called_number" parameter present.
===='''call''' parameters include all the parameters here:====
[[Routing_script_tutorial:Mini_Development_Guide#Script_parameters_protocol_mapping|Routing Scripts variables]]
===='''routes''' 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="400" 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: [[Label_Routing]]
|-
| valign="top" |
nap 
| valign="top" |
NAP 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_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 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="400" 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: [[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 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. <br\>
out_call[0] maps the first set of parameters to be used for the first route. <br\>


=== Filter Scripts examples:  ===
=== Filter Scripts examples:  ===

Revision as of 16:28, 14 April 2020

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 diversion header will not have the "original_called_number" parameter present.

call parameters include all the parameters here:

Routing Scripts variables

routes parameters include:

Variable name Description

route_name

"Name" column in the routing table

routeset_name

Label name. Only used in label routing: Label_Routing

nap

NAP where the incoming call was received

called

called number of the incoming call

calling

calling number of the incoming 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 include:

Variable name Description

routeset_definition

pointer to routeset definition file if label routing is used: 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 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. <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


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: