Routing script tutorial

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(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_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'.

1.  :call_field_name - The field name of the call to try to match
2.  :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./ )
3.  :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
4.  :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.

1.  :call_field_name - The field name of the call to remap
2.  :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/ )
3.  :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
4.  :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

'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

The route retry feature applies when more than one matching route is returned by the active routing script. The route retry algorithm works the following way:

• 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

A call attempt is considered failed in the following conditions:

• Call is terminated with an error cause before it's answered
• Timeout occurs before call reaches specified call state (this timeout is ignored when last matching route is attempted)

Route retry timeout can be customized using two parameters:

• Timeout delay in seconds before retry with next route (value of 0 makes timeout never occur)
• Minimum call state to reach before the specified timeout occurs:
  • Call accepted
  • Call progress received
  • Call alerted
  • Call answered

If the timeout delay is passed before the call reaches the specified state, call is considered failed and retry occurs. If the call reaches that state, timeout no longer apply.

Route retry global configuration

These route retry timeout parameters can be configured globally, per NAP, or per Route. Per-route value has precedence on per-NAP value, which has precedence on global value.

The global route retry timeout parameters are found in the Gateway application configuration page in the Toolpack Web Portal:

• Go to the Gateway->Configuration menu.
• Click on the Edit link of the configuration you wish modify.
• Expand the Advanced section
• Change values of 'Route retry mode' and 'Route retry timeout'

Route retry per-NAP configuration

The per-NAP route retry timeout parameters are configured by adding a custom 'NAP column':

• Go to the Gateway->Configuration menu.
• Click on the Edit link of the configuration you wish modify.
• Click on Create New Nap Column in the Editing Naps section

- In the Name text box, enter 'route_retry_mode'
- In the Type attributes text box, enter '|accept|call_progress|alert|answer'
- Leave the Default text box blank

• Click Save
• Click again on Create New Nap Column in the Editing Naps section

- In the Name text box, enter 'route_retry_timeout'
- In the Type attributes text box, enter 'integer'
- Leave the Default text box blank

• Click Save

Now that these columns have been created, each time you create or edit a NAP, route retry mode and timeout will be shown under Custom Params. Leaving empty value for a NAP will make global value to be used. Assigning a value in either of these parameters will override the global value for that parameter.

Route retry per-route configuration

The per-route route retry timeout parameters are configured by adding a custom 'Route column':

• Go to the Gateway->Configuration menu.
• Click on the Edit link of the configuration you wish modify.
• Click on Create New Route Column in the Editing Routes section

- In the Name text box, enter 'route_retry_mode'
- In the Type attributes text box, enter '|accept|call_progress|alert|answer'
- Leave the Default text box blank

• Click Save
• Click again on Create New Route Column in the Editing Routes section

- In the Name text box, enter 'route_retry_timeout'
- In the Type attributes text box, enter 'integer'
- Leave the Default text box blank

• Click Save

Now that these columns have been created, each time you create or edit a route, route retry mode and timeout will be shown under Custom Params. Leaving empty value for a route will make NAP value used (or global value if NAP value is also empty). Assigning a value in either of these parameters will override the NAP or global value for that parameter.

Customize route retry parameters from routing script

Any part of the routing script that has access to the route can modify these parameters by reading and writing from/to:

route[:route_retry_mode]
route[:route_retry_timeout]

These fields initially contain value read from the added 'Custom Route Columns' (as explained above), but can be overwritten by the routing script.

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

• script routing class tutorial
• 'route_order' tutorial
• 'route_match' tutorial
• 'route_remap' tutorial
• Pre-built routing scripts are also available through the Web Portal in the script routing menu

---

Back to the Scriptable Routing Engine page.