TBwiki - User contributions [en]

Lawful Interception

2019-06-20T10:51:02Z

Abrassard: /* References */

Lawful intercept is a feature provided by service providers to law enforcement agencies (FBI, Interpol, RCMP, etc.) that allows law enforcement agencies to intercept calls by receiving a copy of the audio of both parties and call information records.

==Overview==

[[Image:Lawful-intercept-details.png|thumb|360px|Schematic showing interception of a call already routed with a Tmedia]]

* Lawful Interception (process of intercepting a conversation)
* Interception target (someone under investigation by a law enforcement agency, and for whom the agency wants to intercept the calls)
* Law enforcement agency ( an agency that has, by law, the power to request the interception of calls to or from targets)
* A law enforcement agency sends to the service provider a list of targets to intercept (phone numbers)
* Service provider configures its equipment to intercept the target phone numbers
* When service provider equipment detects a call that involves a target to intercept, it
** Forwards a copy of call audio (both directions) to the agency through forked calls (Content of Communication link (CC link) - a call toward the agency, carrying intercepted audio)
** Sends information records ([[IRI]] records) to the agency
* The Telcobridges Lawful Interception implementation is based on specification ETSI ES 201 671 v2.1.1 (2001-09), and not CALEA, PCES, and ANSI T1.678

==Lawful Interception Requirements==

* Detecting target
** Law enforcement agency provides a list of targets (Type of intercepted targets can be from: PSTN, ISDN, GSM (CS), TETRA, GPRS (PD), UMTS (CS))
*** LIID (Lawful Intercept Identifier, unique identifier assigned to a target by an agency) for the target
*** Phone number of the target
*** Start and end dates and times for the interception
** Service provider updates targets in its equipment and equipment detects a matching calling or called number, and activates the interception
* Intercepting targets
** In a call, each call leg can be an interception target
** When a leg is an interception target, it's intercepted:
*** Audio <<from>> this leg is forked to a new outgoing call
*** Audio <<to>> this leg is forked to a new outgoing call
*** [[IRI]] records are generated for this interception
* Intercepting multiple targets
** Both legs may be independently and simultaneously intercepted
*** 2 pairs of forked audio outgoing calls
*** 2 sets of [[IRI]] records

==Intercepting Audio==

* For each direction (audio <<from>> and <<to>> the target):
** A new outgoing call leg is made, toward the agency
** Audio is <<forked>> (half-duplex joined)
* These outgoing call legs are made toward:
** An outgoing NAP explicitly assigned to the agency
** optionally, using specified calling/called numbers
* Forking does NOT require DSPs
* Audio forking is done as soon as possible
** Immediately for the audio <<from>> the target (this may include even the ring back tone, or may include audio from an incoming call during ringing)
** Upon joining with another active leg for the audio <<to>> the target

==IRI records==

The call data (known as Intercept Related Information or [[IRI]] in Europe and Call Data or CD in the US) consists of information about the targeted communications, including destination of a voice call (e.g., called party’s telephone number), source of a call (caller’s phone number), time of the call, duration, and more.
Intercept Related Information record (IRI record) is a CDR-style record that contains IRI information on an intercepted call

===Types of IRI records===

# IRI-BEGIN: Indicates that the interception is starting at first event of the communication attempt, opening the IRI transaction
# IRI-CONTINUE: Indicates call state change at any time during the communication attempt within the IRI transaction
# IRI-END: Indicates the end of the interception at the end of the communication attempt, closing the IRI transaction
# IRI-REPORT: General use for any non-communication related events

For information related to an existing communication case, the record types 1 to 3 shall be used. They form an IRI
transaction for each communication case or communication attempt, which corresponds directly with the communication
phase (set-up, active or release). 

For some packet-oriented data services such as GPRS, the first event of a communication attempt is the Packet Data Protocol (PDP)
context activation or a similar event and an IRI-BEGIN record is issued. The end of the communication attempt
shall be the PDP context deactivation or a similar event and an IRI-END record shall be issued. While a PDP context is
active, IRI-CONTINUE records are used for CC relevant IRI data records, IRI-REPORT records otherwise. 

Record type 4 is used for non-communication related subscriber action, like Subscriber Controlled Input (SCI) for
service activation. For simple cases, it can also be used for reporting unsuccessful communication attempts. 
The record type is an explicit part of the record. The 4 record types are defined independently of target communication
events. The actual indication of one or several communication events, which caused the generation of an IRI record, is
part of further parameters in the record's information content. Consequently, the record types of the IRI
transactions are not related to specific messages of the signalling protocols of a communication case, and are therefore
independent of future enhancements of the intercepted services and of network specific features. Any transport level
information (i.e. higher-level services) on the target communication-state or other target communication related
information is contained in the information content of the IRI records. 

For some packet oriented data services such as GPRS, if Lawful Interception (LI) is being activated during an already established PDP
context or similar, an IRI-BEGIN record will mark the start of the interception. If LI is being deactivated during an
established PDP context or similar, no IRI-END record will be transmitted. The end of interception can be
communicated to the LEA a Handover Interface Port 1 (HI1)(for Administrative Information); whereas Handover Interface Port 2 (HI2) transports IRI information and Handover Interface Port 3 (HI3) transports Content of Communication information).

===Typical information found in an IRI record===

* Record type (Start, Continue, End, Report)
* LIID
* CIN (communication identity number)
* Operator identifier
* Direction (target is originating, or terminating)
* Call state (idle, setup, connected)
* Duration of ring and conversation states
* Calling / called party numbers
* Release reason
* CC link state (setup, active, released, lack of resources)
* CC link release reason

==IRI records generating==

* IRI records are generated at various states of the interception
* They provide information on the interception, and call state
* In a call, each call leg can be an interception target
* When a leg is an interception target, it's intercepted:
** Audio «from» this leg is forked to a new outgoing call toward the agency
** Audio «to» this leg is forked to a new outgoing call toward the agency
** IRI records are generated for this interception
* Both legs may be independently and simultaneously intercepted
** 2 pairs of forked audio outgoing calls
** 2 sets of IRI records

==IRI records encoding==

* IRI records are encoded in ASN.1 (a binary encoding standard that is used by IRI records) format and using the basic encoding rules (BER).
* ASN.1 IDs and objects hierarchy for encoding IRI records is provided by ETSI specifications

==IRI records values and files specification==

* IRI records values can be
** Mandatory in each record
** In one record only for the whole call
** optional (in some records only, or none at all)
* IRI record files can
** Contain only one IRI record (one file per record)
** Contain multiple IRI records (grouped)

==IRI records uploading to the agency==

* As files, using the FTP protocol
* Telcobridges also supports SFTP as file transfer method

==Configuring Lawful Interception==

* Configure Lawful Agencies
** Summary of information required
*** NAP to use for CC links
*** FTP (or SFTP) server info (IP, port, user, password, folder)
*** IRI upload mode (per record, grouped)
** Multiple agencies can be configured
** Note: SFTP requires password-less login to be configured (through exchange of keys between servers)
* Provide the list of intercepted targets
** The list of intercepted targets is provided as a CSV file
*** Uploaded in the <<File DB>> section of the Web Portal
*** Required columns:
**** liid
**** number
*** Optional columns
**** start
**** end
** Example 
<pre>
liid,number,start,end
John Smith,555-0001,2012-10-24T00:00:00-05:00,2012-10-24T23:59:59-05:00
Joe Dalton,333-3007,2012-01-01T00:00:00-05:00,2012-12-31T23:59:59-05:00
Ben Laden,022-44-66-33-11
Ben Yi,450-621-1990
</pre>
*[[Toolpack:Enable Lawful Interception in Routing Script B|Enable Lawful Interception in a Routing Scripts]] ([[Toolpack:Enable Lawful Interception in Routing Script A|For Toolpack 2.7]])
** The <<lawful interception>> routing script filter is provided with toolpack
** Users only need to <<include>> it in their current routing script 
<pre>
require 'lawful_intercept'
(...)
include LawfulIntercept
(...)
after_filter :method => :enable_lawful_intercept
</pre>
* For more information on Routing Scripts, please see [[Routing script tutorial:Mini Development Guide|mini development guide]]

==Lawful Interception Statistics==

* Live statistics and statistics history
** The Web Portal provides Lawful Interception statistics
*** Global
*** Per agency
** Available statistics are
*** Total / current intercepted calls
*** Total IRI records generated
*** Total IRI records dropped
*** Total failed interceptions
*** IRI records upload queue length and state
*** ... and a few more

==IRI records decoding==
As IRI record is encoded in ASN.1 format, some online ASN.1 decoders are also available to check the IRI record. Upload a message/PDU/record file, and the decoded data can be downloaded as a text file in the ASN.1 Value Notation format.

== References ==

* [http://en.wikipedia.org/wiki/Lawful_interception Wikipedia lawful intercept article]
* [https://www.etsi.org/deliver/etsi_es/201600_201699/201671/03.02.01_60/es_201671v030201p.pdf ETSI ES 201 671 V3.2.1 (2018-05)]
* [http://asn1-playground.oss.com/ ASN.1 Playground - learn, play, test]
* [https://www.marben-products.com/asn.1/services/decoder-asn1-security.html Free Online Security ASN.1 Messages Decoder]
* [https://holtstrom.com/michael/tools/asn1decoder.php ASN.1 decoder]

[[category:Tmedia_Features]]

Tmedia Routing

2019-05-30T19:29:17Z

Abrassard: /* After remap (after_remap) */

== Static routing table ==
<pre>Gateway -> Routes
</pre>
 
[[File:Gateway_Static_Routes.png|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: [[Toolpack: How to Use RegEx in Remapped Called and Calling Number Mask|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|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 [[Tmedia_Routing#Label_routing|Label Routing]] or contact [[Support:Contacting_TelcoBridges_technical_support|TelcoBridges Support]] 

=== Exporting / importing routes ===
You can import or export the static routing table using the web portal. Go to:
<pre>Gateway -> Routes -> Route table actions -> Export Static Routes </pre>
or
<pre>Gateway -> Routes -> Route table actions -> Import Static Routes </pre>
 This is the default configuration of the Media Gateway

== Standard Scripts ==
<pre>Gateway -> Routing scripts </pre>
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|How to Setup Standard Scripts]] 

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

== Filters ==
<pre>Gateway -> Routing scripts </pre>
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
# 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.

==== 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

=== Filter Scripts examples: ===

*'''priority_and_weight_load_balancer.rb:''' After filter that will reorder routes by priority and weight (load sharing per weight for routes with the same priority)
*'''forward_sip_domain.rb:''' Route remap filter that will, per route, control forwarding of sip domain of various SIP headers (forward domains, else replace by local IP / proxy IP)
*'''sip_header_params.rb:''' After remap filter that will add specified parameters to specified SIP headers
*'''Black and White listing (black_white_listing.rb):''' With this script, any called or calling number prefix can be blacklisted or whitelisted. This script can be assigned globally, or per NAP. It reads a .csv file which has the called and calling number list. See [[Adding White or Black listing to Routing Script]]
*'''lawful_intercept.rb:''' Script that will identify some calls to perform lawful interception on (by calling/called number matching from a .csv file)

Learn how to add a Filter to normal scripts: [[How to Setup Filters|How to setup Filters]] 

== Label routing ==
<pre>Gateway -> Routing scripts
Gateway -> FileDb
Gateway -> Routesets </pre>
 

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: [[Routeset Routing|Label routing]] and [[Adding_Label_Routing_to_any_Routing_Script|Adding Label Routing to any Routing Script]] 

== Custom Routing Scripts ==
<pre>Gateway -> 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. 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:Mini Development Guide|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|Scriptable Routing Engine]] 

=== Playing prompts ===
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]].

=== Recording calls ===
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]].

== 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: 
<pre>Profiles -> default [Edit] -> Edit Reason Cause mapping </pre>
 

Route retry is enabled by default. Timers and conditions on route retry can be adjusted from the configuration: 
<pre>Gateway -> Configurations -> Advanced </pre>
NOTE: The route-retry feature is available for other types of routing as well.

 

For more details, see the [[Route retry|Route Retry]] page 

 

[[category:Tmedia_Features]]

== Related actions ==
'''Refer to the appropriate Toolpack release:'''

*[[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]]
*[[Toolpack:Call_Routes_Settings_A|Call Routes Settings v2.8]]
<div class="mw-collapsible mw-collapsed" data-collapsetext="other versions" data-expandtext="Click here for other versions" style="width: 400px;">
*[[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>

Tmedia Routing

2019-05-30T19:28:18Z

Abrassard: /* After filter (after_filter) */

== Static routing table ==
<pre>Gateway -> Routes
</pre>
 
[[File:Gateway_Static_Routes.png|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: [[Toolpack: How to Use RegEx in Remapped Called and Calling Number Mask|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|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 [[Tmedia_Routing#Label_routing|Label Routing]] or contact [[Support:Contacting_TelcoBridges_technical_support|TelcoBridges Support]] 

=== Exporting / importing routes ===
You can import or export the static routing table using the web portal. Go to:
<pre>Gateway -> Routes -> Route table actions -> Export Static Routes </pre>
or
<pre>Gateway -> Routes -> Route table actions -> Import Static Routes </pre>
 This is the default configuration of the Media Gateway

== Standard Scripts ==
<pre>Gateway -> Routing scripts </pre>
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|How to Setup Standard Scripts]] 

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

== Filters ==
<pre>Gateway -> Routing scripts </pre>
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
# 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.

==== 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[ :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

=== Filter Scripts examples: ===

*'''priority_and_weight_load_balancer.rb:''' After filter that will reorder routes by priority and weight (load sharing per weight for routes with the same priority)
*'''forward_sip_domain.rb:''' Route remap filter that will, per route, control forwarding of sip domain of various SIP headers (forward domains, else replace by local IP / proxy IP)
*'''sip_header_params.rb:''' After remap filter that will add specified parameters to specified SIP headers
*'''Black and White listing (black_white_listing.rb):''' With this script, any called or calling number prefix can be blacklisted or whitelisted. This script can be assigned globally, or per NAP. It reads a .csv file which has the called and calling number list. See [[Adding White or Black listing to Routing Script]]
*'''lawful_intercept.rb:''' Script that will identify some calls to perform lawful interception on (by calling/called number matching from a .csv file)

Learn how to add a Filter to normal scripts: [[How to Setup Filters|How to setup Filters]] 

== Label routing ==
<pre>Gateway -> Routing scripts
Gateway -> FileDb
Gateway -> Routesets </pre>
 

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: [[Routeset Routing|Label routing]] and [[Adding_Label_Routing_to_any_Routing_Script|Adding Label Routing to any Routing Script]] 

== Custom Routing Scripts ==
<pre>Gateway -> 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. 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:Mini Development Guide|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|Scriptable Routing Engine]] 

=== Playing prompts ===
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]].

=== Recording calls ===
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]].

== 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: 
<pre>Profiles -> default [Edit] -> Edit Reason Cause mapping </pre>
 

Route retry is enabled by default. Timers and conditions on route retry can be adjusted from the configuration: 
<pre>Gateway -> Configurations -> Advanced </pre>
NOTE: The route-retry feature is available for other types of routing as well.

 

For more details, see the [[Route retry|Route Retry]] page 

 

[[category:Tmedia_Features]]

== Related actions ==
'''Refer to the appropriate Toolpack release:'''

*[[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]]
*[[Toolpack:Call_Routes_Settings_A|Call Routes Settings v2.8]]
<div class="mw-collapsible mw-collapsed" data-collapsetext="other versions" data-expandtext="Click here for other versions" style="width: 400px;">
*[[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>

Routing script tutorial:Mini Development Guide

2019-05-15T13:00:58Z

Abrassard: /* Script parameters protocol mapping */

== Call object ==

=== Get ===

This function is used to get the call parameters. The possible parameters are described in the section "Call parameters"

called_number = caf_call.get :called

=== List_params ===

This function is used to retrieve the list of supported call parameters. For example to extract all the possible call parameters from the the call object and put it in hash.

caf_call.list_params.each {|param| call[param] = caf_call.get param }

=== Accept ===

This function is used to accept a call. It actually creates one outgoing route that the gateway application will use to bridge the incoming call leg. If more than one outgoing route is "accepted", the gateway will try them one by one in the same order that they were accepted. If an outgoing call leg fails (according to 'route retry' parameters), the next route in line will be used.

This method takes 2 arguments, the call parameters (hash) and the route parameters (hash). Note that calling this method does NOT stop the flow of the script.

Apply route remapping rules

caf_call.accept out_call, route

=== Refuse ===

This function is used to set the reason code for the incoming call leg refusal. However, this function does NOT stop the flow of the script.

caf_call.refuse :reason => :temporary_failure

To immediately refuse the incoming call leg and stop processing the script, the script must raise an exception. Exiting the script by raising the exception overwrites any reason cause previously stored using refuse().

raise RoutingException, :no_route

The supported refusal cause values for both refuse() and raise() are described in the section "[[Routing_script_tutorial:Mini_Development_Guide#Reason_values|Reason values]]".

=== Script parameters protocol mapping ===

The following call parameters are available in the call object. For example:

called_number = call[:called]

For information on how to use and remap call parameters, see [[Toolpack:_How_to_Use_RegEx_in_Remapped_Called_and_Calling_Number_Mask | How to use regex in Remapped Called and Calling Number Mask]]

{| cellspacing="1" cellpadding="1" border="1" style="width: 921px; height: 805px;"
|-
! scope="col" | '''Script parameter name'''
! scope="col" | '''ISDN '''
! scope="col" | '''R2 CAS''' 
! scope="col" | '''SS7 '''
! scope="col" | '''SIP '''
! scope="col" | '''Comment '''
! scope="col" | '''Toolpack version '''
|-
| leg_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Leg ID 
| 
|-
| session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Session ID 
| 
|-
| original_session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Original Session ID (before call transfer or redirections) 
| 
|-
| calling 
| Q931: 'Calling party number' IE - Number digits 
| ANI (Group B) 
| Q763: 'Calling party number' IE - address signals (*) 
| SIP:From - user-info 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead. 
| 
|-
| calling_sip_host 
| N/A 
| N/A 
| N/A 
| SIP:From - host (domain or IP) 
| For example : The 'telcobridges.com' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| calling_sip_port 
| N/A 
| N/A 
| N/A 
| SIP:From - port 
| For example : The '6060' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| calling_noa 
| Q931: 'Calling party number' IE - Type of number 
| N/A 
| Q763: 'Calling party number' IE - nature of address indicator (*) 
| N/A 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead 
| 
|-
| calling_npi 
| Q931: 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: 'Calling party number' IE - numbering plan indicator (*) 
| N/A 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead 
| 
|-
| calling_display 
| Q931: 'Display' IE - Display information 
Q931: 'Facility CNAM' IE when presentation is allowed for DMS/NI2 variants 
| N/A 
| Q763
ITU97: 'Display information' IE - display information
ANSI95: 'Generic name' IE - display information
| SIP:From - display-name 
| 
| 
|-
| calling_display_type 
| Q931: 'Display' IE - Display information (present and/or first byte) 
| N/A 
| Q763: 'Display information' IE - present or not 
| N/A 
| 
| 
|-
| calling_presentation 
| Q931: 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: 'Calling party number' IE - address presentation restricted indicator 
|
SIP:From - display-name (displays 'anonymous' or not)

SIP:Remote-party-id - privacy 

| 
| 
|-
| calling_screening 
| Q931: 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: 'Calling party number' IE - screening 
| SIP:Remote-party-id - screen 
| 
| 
|-
| calling_category 
| N/A 
| Call party category (Group A) 
| Q763: 'Calling party's category' IE - calling party's category 
|
SIP:From - cpc

SIP:P-asserted-identity - cpc 

| 
| 
|-
| calling_subscriber
(Generic Number / NDS) 
| Q931: 2nd 'Calling party number' IE - Number digits 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - Number digits 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| Requires option 'support 2 calling number IE' in the profile. This variable has priority over 'private_address' in the outgoing direction. 
| 
|-
| calling_subscriber_noa 
| Q931: 2nd 'Calling party number' IE - Type of number 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - nature of address indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_npi 
| Q931: 2nd 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - numbering plan indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
 
| 
|-
| calling_subscriber_presentation 
| Q931: 2nd 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - presentation restricted indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_screening 
| Q931: 2nd 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - screening 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| private_display 
| Q931: 'Facility CNAM' IE when presentation is restricted for DMS/NI2 variants 
| N/A 
| N/A 
|
SIP:P-asserted-identity - display-name 

SIP:Remote-party-id - display-name 

| 
| 
|-
| private_display_type 
| N/A 
| N/A 
| N/A 
| N/A 
| Indicate presence or not of the private calling information 
| 
|-
| private_address 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 

| For example : The 'fluffy' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_sip_host 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - host (domain or IP)

SIP:Remote-party-id - host (domain or IP) 

| For example : The 'telcobridges.com' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_sip_port 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - port

SIP:Remote-party-id - port 

| For example : The '6060' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| called 
| Q931: 'Called party number' IE - Number digits 
| DNIS (Group A) 
| Q763: 'Called party number' IE - address signals 
| SIP:To - user-info and host 
| 
| 
|-
| called_sip_host 
| N/A 
| N/A 
| N/A 
| SIP:To - host 
| For example : The 'telcobridges.com' in To: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| called_sip_port 
| N/A 
| N/A 
| N/A 
| SIP:To - port number 
| For example : The '6060' in To: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| called_noa 
| Q931: 'Called party number' IE - Type of number 
| N/A 
| Q763: 'Called party number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| called_npi 
| Q931: 'Called party number' IE - Numbering plan identification 
| N/A 
| Q763: 'Called party number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| charge_number 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - address signals 
| N/A 
| 
| 
|-
| charge_number_noa 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| charge_number_npi 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| redirecting_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default redirecting number and original called number forwarding behavior from incoming to outgoing leg 
| 
|-
| redirecting_number 
| Q931: 'Redirecting number' 1st IE - Number digits 
| N/A 
| Q763: 'Redirecting number' IE - address signals 
| SIP:Diversion (2nd header) - display-name 
| 
| 
|-
| redirecting_number_noa 
| Q931: 'Redirecting number' 1st IE - Type of number 
| N/A 
| Q763: 'Redirecting number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| redirecting_number_npi 
| Q931: 'Redirecting number' 1st IE - Numbering plan identification 
| N/A 
| Q763: 'Redirecting number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| redirecting_number_presentation 
| Q931: 'Redirecting number' 1st IE - Presentation indicator 
| N/A 
| Q763: 'Redirecting number' IE - address presentation restricted indicator 
| SIP:Diversion (2nd header) - diversion-privacy 
| 
| 
|-
| redirecting_number_indicator 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirecting indicator 
| N/A 
| 
| 
|-
| redirecting_number_reason 
| Q931: 'Redirecting number' 1st IE - Reason for redirection 
| N/A 
| Q763: 'Redirection information' IE - redirecting reason 
| SIP:Diversion (2nd header) - diversion-reason 
| 
| 
|-
| redirecting_number_counter 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirection counter 
| SIP:Diversion (2nd header) - diversion-counter 
| 
| 
|-
| original_called_number
(OCN) 
| Q931: 'Redirecting number' 2nd IE - Number digits 
| N/A 
| Q763: 'Redirection number' IE - address signals 
| SIP:Diversion  (1st header) - display-name 
| 
| 
|-
| original_called_number_noa 
| Q931: 'Redirecting number' 2nd IE - Type of number 
| N/A 
| Q763: 'Redirection number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| original_called_number_npi 
| Q931: 'Redirecting number' 2nd IE - Numbering plan identification 
| N/A 
| Q763: 'Redirection number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| original_called_number_presentation 
| Q931: 'Redirecting number' 2nd IE - Presentation indicator 
| N/A 
| Q763: 'Redirection number' IE - address presentation restricted indicator 
| SIP:Diversion (1st header) - diversion-privacy 
| 
| 
|-
| original_called_number_reason 
| Q931: 'Redirecting number' 2nd IE - Reason for redirection 
| N/A 
| Q763: 'Redirection information' IE - original redirection reason 
| SIP:Diversion (1st header) - diversion-reason 
| 
| 
|-
| original_called_number_counter 
| N/A 
| N/A 
| N/A 
| SIP:Diversion (1st header) - diversion-counter 
| 
| 
|-
| ported_number_npdi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - with qualifier=Ported number is present 
| SIP:RequestURI - npdi=yes is present 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number 
| N/A 
| N/A 
| Q763: 'Generic number' IE - address signals with qualifier=Ported number 
| SIP:RequestURI - to user part when rn is present 
| rn is stored in the called number 
| 
|-
| ported_number_noa 
| N/A 
| N/A 
| Q763: 'Generic number' IE - nature of address indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number_npi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - numbering plan indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| oli
(Originating line information) 
| 5ESS Codeset 6 OLI - Value 
| N/A 
| ANSI: 'Originating line information' IE - OLI 
|
SIP:From - oli

SIP:P-asserted-identity - oli 

| 
| 
|-
| request_uri 
| N/A 
| N/A 
| N/A 
| Complete Request URI string 
| 
| 
|-
| request_uri_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default URI forwarding behavior from incoming to outgoing leg 
| 
|-
| sip_header 
| N/A 
| N/A 
| N/A 
| Any header 
| Requires option 'Forward custom headers' in Profiles->SIP 
| 2.7.63 
|-
| nap
(Network Access Point) 
| N/A 
| N/A 
| N/A 
| N/A 
| Incoming leg NAP name (read-only) 
| 
|-
| type_of_network_identification 
| Q931: 'Transit network selection' IE - Type of network identification 
| N/A 
| Q763: 'Transit network selection' IE - Type of network identification 
| N/A 
| 
| 2.7 
|-
| network_identification 
| Q931: 'Transit network selection' IE - Network identification 
| N/A 
| Q763: 'Transit network selection' IE - Network identification 
| SIP: Request-Line - cic 
| 
| 2.7 
|-
| network_identification_plan 
| Q931: 'Transit network selection' IE - Network identification plan 
| N/A 
| Q763: 'Transit network selection' IE - Network identification plan 
| N/A 
| 
| 2.7 
|-
| location_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default location number forwarding behavior from incoming to outgoing leg 
| 2.7 
|-
| location_number 
| N/A 
| N/A 
| Q763: 'Location number' IE - address signals 
| N/A 
| 
| 2.7 
|-
| location_number_noa 
| N/A 
| N/A 
| Q763: 'Location number' IE - nature of address indicator 
| N/A 
| 
| 2.7 
|-
| location_number_npi 
| N/A 
| N/A 
| Q763: 'Location number' IE - numbering plan indicator 
| N/A 
| 
| 2.7 
|-
| location_number_presentation 
| N/A 
| N/A 
| Q763: 'Location number' IE - presentation restricted indicator 
| N/A 
| 
| 2.7 
|-
| location_number_screening 
| N/A 
| N/A 
| Q763: 'Location number' IE - screening 
| N/A 
| 
| 2.7 
|-
| mlpp_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| A script needs to set this to true if it wants to overwrite MLPP information in the outgoing leg. Otherwise, profile relay 'outgoing mode' applies automatically. 
| 2.7 
|-
| mlpp_look_for_busy 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - look ahead for busy 
| N/A 
| 
| 2.7 
|-
| mlpp_precedence_level 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - precedence level 
| SIP:Resource-Priority - q735 
| 
| 2.7 
|-
| mlpp_network_identity 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - network identity 
| N/A 
| 
| 2.7 
|-
| mlpp_service_domain 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - MLPP service domain 
| N/A 
| 
| 2.7 
|-
| called_isub 
| Q931: 'Called party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub parameter 
| 
| 2.7 
|-
| called_isub_type 
| Q931: 'Called party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub-encoding parameter 
| 
| 2.7 
|-
| calling_isub 
| Q931: 'Calling party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub 
| 
| 2.7 
|-
| calling_isub_type 
| Q931: 'Callinf party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub-encoding 
| 
| 2.7 
|-
| ss7_fci_default 
| N/A 
| N/A 
| Default forward call indicator (FCI) value. 
| N/A 
| Toolpack will overwrite FCI bits A, D, F, I and M with appropriate values according to call conditions 
| 2.7 
|-
| ss7_fci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_fci_default that must be forced. 
| N/A 
| Bits from ss7_fci_default which corresponding bit in ss7_fci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| ss7_bci_default 
| N/A 
| N/A 
| Default backward call indicator (BCI) value. 
| N/A 
| Toolpack will overwrite BCI bits AB, I, K, M and N with appropriate values according to call conditions 
| 2.7 
|-
| ss7_bci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_bci_default that must be forced. 
| N/A 
| Bits from ss7_bci_default which corresponding bit in ss7_bci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| tdm_ls_name_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable line service and timeslot selection to create the outgoing leg. tdm_ls_name and tdm_timeslot_nb must be defined along with tdm_ls_name_forward_enabled 
| 3.0 
|-
| tdm_ls_name
(Line Service or T1/E1 trunk) 
| Incoming leg line service name 
| Incoming leg line service name 
| Incoming leg line service name 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this line service name to create outgoing leg 
| 2.7 
|-
| tdm_timeslot_nb 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this timeslot number to create outgoing leg 
| 2.7 
|-
| rtp_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP port 
| (read-only) 
| 2.7 
|-
| rtp_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP port 
| (read-only) 
| 2.7 
|-
| ss7_cot_enabled 
| N/A 
| N/A 
| Requests SS7 in-call continuity test for this outgoing SS7 call 
| N/A 
| Toolpack will request a continuity test on the timeslot before making the outgoing call. If COT fails, the call will be dropped (then another route may be attempted) 
| 2.8 
|-
| reverse_charging_indication 
| Incoming leg Reverse charging indication IE present 
| N/A 
| N/A 
| N/A 
| If set in routing script, will add Reverse charging indication IE in outgoing leg (also use reverse_charging_indication_forward_enabled) 
| 2.8.12 
|-
| reverse_charging_indication_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable forwarding of reverse charging indication from incoming to outgoing leg 
| 2.8.12 
|-
| sip_call_id 
| N/A 
| N/A 
| N/A 
| Incoming leg SIP Call-Id 
| (read-only) 
| 2.9.112 / 3.0.131 
|-
| sip_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP port 
| (read-only) 
| 2.8.13 
|-
| sip_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP port 
| (read-only) 
| 2.8.13 
|}

 

=== Noa values ===
The text below represents the value normally used by routing script. 
Incase it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 
Example numeric values for the SS7 protocol are shown in parenthesis. 
 
*<tt>unknown_number (0x2)</tt>
*<tt>international_number (0x4)</tt>
*<tt>national_number (0x3)</tt>
*<tt>subscriber_number (0x1)</tt>
*<tt>network_specific (0x5)</tt>
*<tt>network_routing_national_format (0x7)</tt>
*<tt>network_routing_international_format (0x8)</tt>
*<tt>abbreviated_number (0x6)</tt>
*<tt>subscriber_number_operator_requested (0x71)</tt>
*<tt>national_number_operator_requested (0x72)</tt>
*<tt>international_number_operator_requested (0x73)</tt>
*<tt>no_number_present_operator_requested (0x74)</tt>
*<tt>no_number_present_cut_through_call_to_carrier (0x75)</tt>
*<tt>test_line_test_code (0x77)</tt>
*<tt>non_unique_subscriber_number (0x71)</tt>
*<tt>non_unique_national_number (0x73)</tt>
*<tt>non_unique_international_number (0x74)</tt>
*<tt>call_950_numbe (0x76)</tt>
*<tt>special_number (0x73)</tt>
*<tt>national_number_with_transit_network_selection (0x74)</tt>
*<tt>international_number_with_transit_network_selection (0x75)</tt>

Those values will be remapped to the protocol specific NOA value. To provide protocol specific value:

*<tt>call_params[:called_noa] = 0x70</tt>

or

*<tt>call_params[:called_noa] = 112</tt>

=== Npi values ===

*<tt>unknown_number</tt>
*<tt>isdn</tt>
*<tt>telephony</tt>
*<tt>private</tt>
*<tt>data</tt>
*<tt>telex</tt>
*<tt>national</tt>

=== Calling Display Type values ===

*<tt>unspecified</tt> => Type is unspecified.
*<tt>calling_party_name</tt> => Type is 0xB1.

Those values will be remapped to the protocol specific Display Information Type value. To provide protocol specific value:

*<tt>call_params[:calling_display_type] = 0xB1</tt>

or

*<tt>call_params[:calling_display_type] = 177</tt>

=== Calling Display value ===

*<tt>call_params[:calling_display] = "Roger Fluffy"</tt>

=== Presentation values for Calling number, Calling Subscriber (Generic Number), Redirecting Number, Original Called Number (OCN) and Location Number ===
The text below represents the value normally used by routing script. 
Incase it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 
Example numeric values for the SS7 protocol are shown in parenthesis. 
 
*<tt>unspecified</tt>
*<tt>not_available (0x2)</tt>
*<tt>allowed (0x0)</tt>
*<tt>restricted (0x1)</tt>
*<tt>addr_restricted</tt>
*<tt>name_restricted</tt>

=== Calling Party Category ===
The text below represents the value normally used by routing script. 
In case it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 

Mapping from routing script to SS7/CAS R2/SIP
{| cellspacing="1" cellpadding="1" border="1"
|-
! scope="col" | '''Routing Script string '''
! scope="col" | '''SS7 raw value '''
! scope="col" | '''R2 CAS scripts''' 
! scope="col" | '''Default Rx CAS''' 
! scope="col" | '''default Tx CAS''' 
! scope="col" | '''SIP "cpc=" '''
|-
| subscriber 
| 0xa 
| CATEGORY_SUBSCRIBER 
| 1 and 7 
| 7 
| ordinary 
|-
| subscriber_with_priority 
| 0xb 
| CATEGORY_SUBSCRIBER_WITH_PRIORITY 
| 2 and 9 
| 2 
| priority 
|-
| operator_french 
| 0x1 
| CATEGORY_OPERATOR_FRENCH 
| 5 
| 5 
| operator 
|-
| operator_english 
| 0x2 
| CATEGORY_OPERATOR_ENGLISH (5) 
| 5 
| 5 
| operator 
|-
| operator_german 
| 0x3 
| CATEGORY_OPERATOR_GERMAN (5) 
| 5 
| 5 
| operator 
|-
| operator_russian 
| 0x4 
| CATEGORY_OPERATOR_RUSSIAN (5) 
| 5 
| 5 
| operator 
|-
| operator_spanish 
| 0x5 
| CATEGORY_OPERATOR_SPANISH (5) 
| 5 
| 5 
| operator 
|-
| data 
| 0xc 
| CATEGORY_DATA 
| 6 and 8 
| 6 
| datacall 
|-
| test 
| 0xd 
| CATEGORY_TEST 
| 3 
| 3 
| test 
|-
| payphone 
| 0xf 
| CATEGORY_PAYPHONE 
| none 
| 7 
| payphone 
|-
| unknown 
| 0x0 
| CATEGORY_UNKNOWN 
| 4, 11 to 15 
| 7 
| unknown 
|-
| unspecified 
| 0xa 
| invalid 
| none 
| none 
| invalid 
|}
[[CAS_R2_scripting#Category_meanings|Link to calling party categories used in CAS R2 scripts]]

=== Screening values for Calling number, Calling Subscriber (Generic Number), and Location Number ===
The text below represents the value normally used by routing script. 
Incase it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 
Example numeric values for the SS7 protocol are shown in parenthesis. 
 
*<tt>unspecified</tt>
*<tt>no (0x0)</tt>
*<tt>pass (0x1)</tt>
*<tt>fail (0x2)</tt>
*<tt>network_provided (0x3)</tt>

=== Redirecting indicator values ===

SS7:

*<tt>no_redirection</tt>
*<tt>call_rerouted</tt>
*<tt>call_rerouted_all_restricted</tt>
*<tt>call_diverted</tt>
*<tt>call_diverted_all_restricted</tt>
*<tt>call_rerouted_restricted</tt>
*<tt>call_diverted_restricted</tt>
*<tt>spare</tt>

=== Redirecting number, Original Called Number and Diversion Reason ===

ISDN:

*<tt>unknown</tt>
*<tt>busy</tt>
*<tt>no_reply</tt>
*<tt>deflection</tt>
*<tt>dte_out_of_order</tt>
*<tt>forwarding_by_called_dte</tt>
*<tt>unconditional</tt>

SS7:

*<tt>unknown</tt>
*<tt>busy (SIP: user-busy)</tt>
*<tt>no_reply (SIP: no-answer)</tt>
*<tt>unconditional</tt>
*<tt>deflection</tt>
*<tt>deflection_immediate</tt>
*<tt>mobile_not_reachable</tt>

=== OLI (originating line information) values ===

The OLI parameter is a string that represents an integer value from 0 to 255.

=== Information Transfer Capability values ===

information_transfer_capability:

*<tt>digital</tt>
*<tt>restricted_digital</tt>
*<tt>digital_with_tones</tt>
*<tt>speech</tt>
*<tt>3_1_khz_audio</tt>
*<tt>video</tt>

=== redirecting_number_forward_enabled values ===

Controls forwarding or discarding of redirecting number (SIP: diversion header) to the outgoing call leg.

Values for this parameter are "0", "1", "false" or "true.
*0/false: Redirecting number (and original called number) is not forwarded to outgoing call leg
*1/true: Redirecting number (and original called number) is forwarded to outgoing call leg

The value for this parameter at the input of the routing script depends on the "Forward redirecting number" parameter in the "Advanced" section of the Gateway configuration page of the Web Portal. The script may change this value to override the Gateway configuration.

Note: To "insert" a new redirecting number value on the outgoing leg, redirecting_number_forward_enabled must also be set to true.

=== request_uri ===

Enables access to the Request-Line URI. 

For example, if the Request-Line is:
<pre>Request-Line: INVITE sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0</pre>
Then the retrieved request_uri will be "sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0". 

In the routing scripts, to retrieve only the called number, this script can be used: 
<pre> if call_params[:request_uri] && call_params[:request_uri] =~ /sip:(.*)@.*/
call_params[:called] = $1
end
</pre>
==== request_uri_forward_enabled ====

This call parameter controls forwarding or discarding of request uri to outgoing call leg.The request uri is the information in the "Request-Line:" of the SIP INVITE message. 

Values for this parameter are "0", "1", "false" or "true. 

* 0/false: Request uri is not forwarded to outgoing call leg 

* 1/true: Request uri is forwarded to outgoing call leg 

The default value for this parameters is false. 

==== sip_scheme ====
(Available in Toolpack 3.1+)
This call parameters indicates the scheme (generally "sip" or "sips") of the incoming call.

This also allows to control the scheme used for the outgoing call (regardless if request_uri_forward_enabled is used or not)

Note: sips scheme must only be used on TLS NAPs (will cause call routing failure if NAP has only UDP or TCP transport types).

=== sip_header values ===
Contains custom sip headers from the inbound call leg. Any custom sip header can be added to an outgoing call leg: 

'''Note:'''

The SIP header is in string format.

'''string format:'''
<pre>call[ :sip_header ] = "P-my-custom-header:value1 \nP-my-custom-header2:value2 \nP-my-custom-header3:value3"
</pre>
(Note: \n above are actual newline characters, not '\' followed by 'n')

* PCAP sample: [[File:TB_Custom_SIP_Headers.pcap]]

List of sip headers that will not appear in call[:sip_header] since they are already processed by the SIP stack:
<pre>
Accept Error-Info Remote-Party-ID
Accept-Contact Event Replaces
Accept-Encoding Expires Reply-To
Accept-Language From Request-Disposition
Alert-Info In-Reply-To Subject
Allow Max-Forwards Subscription-State
Allow-Events MIME-version Supported
Also Min-Expires Timestamp
Anonymity Min-SE To
Authorization Organization Unsupported
Authentication-Info Path User-Agent
Call-ID Priority Via
Call-Info Privacy Warning
Contact Proxy-Authenticate WWW-Authenticate
Content-Disposition Proxy-Authorization Require
Content-Encoding Proxy-Require Response-Key
Content-Language P-Media-Authorization Retry-After
Content-Length P-Preferred-Identity RPID-Privacy
Content-Type P-Asserted-Identity Route
CSeq RAck RSeq
RAck Reason Security-Client
Reason Record-Route Security-Server
Date Refer-To Security-Verify
Diversion Referred-By Server
Encryption Reject-Contact Service-Route
Session-Expires
</pre>

=== sip header parameters ===
The routing script can read (and modify) some SIP header parameters (user parameters, URI parameters or header parameters) from some SIP headers (To, From, P-Asserted-Identity, Remote-Party-ID, Contact).

==== Available parameters ====
* '''call[ :calling_parameters ]''' (SIP "From" header)
* '''call[ :called_parameters ]''' (SIP "To" header)
* '''call[ :private_address_parameters ]''' (SIP "P-Asserted-Identity" or "Remote-Party-ID" header)
* '''call[ :contact_parameters ]''' (SIP "Contact" header)

These parameters (if present) contain a hash with 3 keys: user_param, uri_param and header_param.
Each of this key points to a string that contains all the parameters found in the corresponding SIP header.
* '''User parameters''' (parameters between the user name/number and the host). Example <sip:alice;'''param=value'''@somewhere.com>
* '''URI parameters''' (parameters at the end of the URI). Example <sip:alice@somewhere.com;'''param=value'''>
* '''Header parameters''' (outside the URI). Example <sip:alice@somewhere.com>;'''param=value'''
Example to print all parameters of SIP "To" header:
call[ :called_parameters ].inspect -> '{ :user_param => "name1=value1;name2=value2", :uri_param => "name=value", :header_param => "name=value;example_param_without_value" }'
Example to modify (replace) the URI parameters of SIP "To" header:
call[ :called_parameters ][ :uri_param ] = "user=phone"

==== Exceptions ====
'''Note:''' Some parameters are reported as their own call attribute (oli, isub, cpc, transport) so they have the same representation for all protocols (SS7, IDSN, SIP). They won't appear present in the generic SIP header parameters structures above.

==== Forwarding from inbound to outbound call ====

==== Legacy behavior ====
(For base_routing version 1.32 or older)
By default, the parameters are not forwarded in a SIP to SIP call flow. The parameters '''will be forwarded''' when:
* accessed (read) from either the inbound or outbound call parameters
* written in either the inbound or outbound call parameters

==== Current behavior ====
(For Toolpack 3.0.118+, with base_routing version 1.33+)
SIP headers host and parameters are forwarded by default.

A route attribute "forward_sip_domain" (along with filter script "forward_sip_domain.rb") will control, per route, if SIP headers host+parameters must be forwarded.

==== Example usage ====
Example to print the user parameters:
<pre>
if call[:calling_parameters]
puts "user parameters = #{call[:calling_parameters][:user_param].inspect}"
end
</pre>

Example SIP "From" header:
From:<sip:123456782;test1=val1;test2=val2@something.com;test3=val3;test4=val4>;test5=val5;test6=val6
And the resulting content in the routing script:
call[:calling_parameters].inspect -> {:user_param=>"test1=val1;test2=val2", :uri_param=>"test3=val3;test4=val4", :header_param=>"test5=val5;test6=val6"}

Example to overwrite inbound leg calling parameters with new parameters for the outbound leg:
<pre>
call [:calling_parameters] = {
:user_param => "user_param7=7;user_param8=8",
:uri_param => "uri_param9=value9",
:header_param => "header_paramA=A" }
</pre>

Example to add user=phone and keep all other uri parameters.
<pre>
call[:calling_parameters] ||= {} # Create a hash if not already present
call[:calling_parameters][:uri_param] ||= "" # Create a string if not already present
call[:calling_parameters][:uri_param] += ";" if call[:calling_parameters][:uri_param] != ""
call[:calling_parameters][:uri_param] += "user=phone"
</pre>

=== MLPP Precedence values ===

mlpp_look_for_busy:

*<tt>allowed</tt>
*<tt>path_reserved</tt>
*<tt>not_allowed</tt>

mlpp_precedence_level:

*<tt>flash_override</tt>
*<tt>flash</tt>
*<tt>immediate</tt>
*<tt>priority</tt>
*<tt>routine</tt>

mlpp_network_identity:

3 digits value from 0 to 999

mlpp_service_domain:

24 bits value from 0 to 16777215

=== ISUB subaddress information values ===

called_isub_type:
calling_isub_type:

*<tt>nsap</tt>
*<tt>nsap_ia5</tt>
*<tt>nsap_bcd</tt>
*<tt>user</tt>

called_isub:
calling_isub:

Digits for the subaddress information.

=== Network Identification Plan ===

network_identification_plan:

*<tt>Unknown</tt> (value 0)
*<tt>cic</tt> (3 digits carrier identification code plus circuit code, value 1, SS7 or ISDN)
*<tt>user</tt> (User, value 2, ISDN only)
*<tt>cic4</tt> (4 digits carrier identification code plus circuit code, value 2, SS7 only)
*<tt>dnic</tt> (public Data Network ID, value 3, SS7 only)
*<tt>mnic</tt> (public land mobile network, value 6, SS7 only)

=== Registered Users Information ===
Routing script can access information about registered users (when either the calling or called user is a known registered user).
When these fields are empty, it means that the calling/called (SIP from/to) does not correspond to a known registered user (routing script may still decide to route the call based on static routes).

Information for the called user:
params[:registered_user]
Information for the calling user:
params[:calling_registered_user]

These parameters are a hash of key/values that provide information about the contact.
{
:contact_list=>
[
{
:contact=>"<sip:user_name_or_number@hostname:7070;transport=UDP>", -> Full contact
:expires=>"60", -> Contact expiry time (seconds)
:host=>"hostname", -> host name from the contact header
:name=>"user_name_or_number", -> user name from the contact header
:nap_in=>"NAP_NAME", -> NAP that the contact has registered from
:port=>"7070", -> Port from the contact header
:transport=>"UDP" -> Transport type from the contact header
:q_value=>"0.00", -> Q-value for the contact (for contact ordering)
:src_host=>"10.0.0.10", -> Actual source IP address that the contact has registered from
:src_port=>"7070", -> Actual source port that the contact has registered from
:src_transport=>"UDP", -> Actual protocol that the contact has been registering with
}
]
}

== Route parameters ==

All route may have these parameters:

*calling
*called
*nap
*remapped_calling
*remapped_called
*remapped_nap
*remapped_destination_leg_profile (called remapped_profile prior to Toolpack 2.9)
*remapped_source_leg_profile (called remapped_incoming_profile prior to Toolpack 2.9)

Example:

route[:remapped_nap]

Additionally it is possible to add dynamic route attributes in the web portal. These can be referenced by their name.
For example:
*priority
*weight

== Routing calls toward registered users ==
Static routes normally chose an outbound NAP to forward the call to.

But it's also possible to create routes which outbound NAP is dynamically chosen by matching a registered user (when using [[Sip_registration_forwarding|SIP registration forwarding]]).

More information can be found [[Sip_registration_forwarding#SIP_Calls_routing|here]] about the way to control the [[Sip_registration_forwarding#SIP_Calls_routing|priority of "dynamic" vs "static" routes]].

More information can be found [[#Registered_Users_Information|here]] about using routing scripts to access registered users information during call routing.

== Playing prompts announcements or tones ==

New feature in release 2.6, all bridges may have these parameters. These can be used to play IVR prompts (audio files) in different states of the call flow.

*'''announcement_tone''' (played before outgoing call is routed)
*'''ring_tone''' (played after when waiting for outgoing call to answer)
*'''busy_tone''' (played if outgoing call failed)
*'''disconnect_tone''' (played after the call has reached it's maximum duration)

Example to play an announcement to incoming call (before routing outgoing call, regardless if a matching route is found or not):
bridge[:announcement_tone ] = "my_announcement.wav"

Example to play a ring-tone while the outgoing call is ringing:
bridge[:ring_tone] = "my_ring_tone.wav"

Example to play an audio file when outgoing call fails (no route, or outgoing call is refused):
bridge[:busy_tone] = "my_busy_tone.wav"

Example to play an audio file when call has reached the maximum allowed duration:
bridge[:disconnect_tone] = "your_account_balance_is_empty.wav"

=== Announcement file path format and options ===

All file plabyacks (:announcement_tone, :busy_tone, :ring_tone, :disconnect_tone) inside bridge parameters use this format.
<pre>"file1.wav:repeat:start_off:end_off,file2.wav:repeat:start_off:end_off,file3.wav:repeat:start_off:end_off"
</pre>
Optional parameters:
* repeat: number of times to play the file (0 and 1 have the same result)
* start_off: Start offset in milliseconds
* end_off: End offset in milliseconds

Http and other path formats are described here: [[Customer_application_framework:play_audio_files#Play_path_format|Path format]]

==== Example 1 ====
The following example will play file1.wav once, and then play file2.wav in loop:
"file1.wav,file2.wav:-1"

==== Example 2 ====
The following example will play file1.wav from start offset of 1 second to end offset of 3 seconds, then twice file2.wav from second 5 to second 10.
"file1.wav:0:1000:3000,file2.wav:2:5000:10000"

==== Example 3 ====
The following example will play file1.wav once, ending at offset of 30 seconds.
"file1.wav:0:0:30000"

=== announcement_tone ===

params[:bridge][:announcement_tone] = "announcement.wav"

Audio file played on the incoming call before any outgoing call is placed. The outgoing call occurs when the file finished playing.

==== announcement_tone options ====
===== announcement_tone_answer =====
params[:bridge][:announcement_tone_answer] = "yes"

Forces an answer of the call before playing the announcement. Default if argument not provided is "no", in which case call is only alerted with in-band media.

===== announcement_code_detect =====
This option allows that the tone detection is enabled during the announcement play.

Collected digits can be inserted into the CDR logs (radius attribute "Telcob-CollectedDigits", or text CDR variable @{CollectedDigits}).

Collected digits can also be sent back to routing script, which is called again with the same call attributes, except that the called number is replaced by the collected digits.

Code detect has multiple options, as shown in the following code:
code_detect = {
:type => :DTMF, # :DTMF or :MFR1 tone detection.
# Default is MFR1.
:prefix => "", # Prefix (digits) that is removed from collected digits.
# Default is empty.
:suffix => "", # Suffix (digits) that is removed from collected digits
# and causes routing script to be immediately called.
# Default is empty.
:suffix_removal => false, # Controls the removal of the suffix from the collected digit string that's reported to routing script.
# Default is false
:timeout => 0, # Inter-digit timeout (ms) after which collected digits are passed to the routing script.
# Use 0 for "no timeout".
# Default is 1000ms
:barge_in_interruption => true, # When enabled, playing announcement is stopped as soon as first digit is collected.
# Default is true.
:proceed_on_play_done => false, # When true: Outgoing call is made after announcement finishes playing.
# Routing script is not called again.
# When false: Outgoing call is never made.
# Digits are collected until timeout or suffix match,
# then routing script is called again.
# Default is false.
:cas_on_hook => false, # Specific for CAS-R1 calls. Makes CAS bits switch to "on-hook" when announcement finished playing
# (but the call is not "terminated" from Toolpack point of view)
# Default is false.
:cas_on_hook_delay => 0, # Duration of cas bits "on-hook" state.
# Only effective if cas_on_hook is set to true.
# Value of 0 stands for "infinite delay".
# Default is 0.
:repeat_delay => 0, # Delay between repetition of the announcement. The announcement will repeat
# itself every "repeat_delay" until a code is detected (suffix match or timetout).
# Value of 0 stands for "infinite delay" (no repeating).
# Default is 0.
}
'''Example 1''': Collect DTMF digits, and call routing script again with collected digits upon timeout or suffix match.
code_detect = { :type => :DTMF, :suffix => "#", :timeout => 5000 }
params[:bridge][:announcement_code_detect] = code_detect

'''Example 2''': Collect digits during the announcement (for CDR logs), then proceed (make outgoing call) after announcement finishes playing
code_detect = { :type => :DTMF, :timeout => 0, :barge_in_interruption => false, :proceed_on_play_done => true }
params[:bridge][:announcement_code_detect] = code_detect

==== Controlling what happens after announcement ====
The routing script can control what happens with the call after the announcement finishes playing:
* An outgoing call is made
* Incoming call is hung-up
* Do nothing (wait for the incoming call to hang-up)
===== An outgoing call is made =====
This happens when the script has returned matching routes (and did not raise RoutingException)

===== Incoming call is hung-up =====
This happens when the script returns no routes (in which case base_routing will raise RoutingException with cause :no_route).

It also happens when the script explicitly raises RoutingException.

The incoming call will be terminated with the specified cause.
For example
raise RoutingException, :temporary_failure
(See "Reason values" section in this page for list of available causes)

===== Do nothing (wait for the incoming call to hang-up) =====
If a filter raises RoutingException with code :ok, then the incoming call will not be terminated at the end of the announcement play.
Announcement digit collection will remain active if appropriate.
For example:
raise RoutingException, :ok

=== ring_tone ===
params[:bridge][:ring_tone] = "ringing.wav"

Audio file played on the incoming call while waiting for the outgoing call to be answered.

Ring tone playback can also be configured in the Web Portal, from the incoming call's profile (under "Tones and Call Progress Options").

Routing script has precedence over profile (a routing script that fills params[:bridge][:ring_tone] will override the profile's ring tone behavior).

==== ring_tone options ====
===== ring_tone_state =====
params[:bridge][:ring_tone_state] = :alerted

Call state from which ring tone is being played. Available values are:
* '''immediately''': Ring tone starts playing immediately on the incoming leg
* '''accepted''': Ring tone starts playing as soon as outgoing call is accepted
* '''callprogress''': Ring tone starts playing as soon as "call progress" is received on the outgoing call
* '''alerted''' (default): Ring tone starts playing only once outgoing call is alerted (but won't play if alert indicates early media from outgoing call)

This option also apply when params[:bridge][:ring_tone] is not used, because it also apply to ring tone playback configured in the Web Portal, from the incoming call's profile.

=== busy_tone ===
Toolpack 2.8 and above:
params[:bridge][:busy_tone] = "no_route.wav"

Note: Obsolete name (toolpack 2.7.153 and earlier, but still supported in recent releases):
params[:bridge][:call_progress_tone] = "no_route.wav"

Audio file played on the incoming call when outgoing call fails (never answered).

Note that announcement_tone, if used, is played before the outgoing call attempt is made, and thus before the busy_tone.

Busy tone playback can also be configured in the Web Portal, from the incoming call's profile (under "Tones and Call Progress Options").

Routing script has precedence over profile (a routing script that fills params[:bridge][:busy_tone] will override the profile's busy tone behavior).

Special value '''"none"''' can be used by routing script to force playing nothing (as empty string would default to profile's behavior)

==== busy_tone options ====
===== busy_tone_answer =====
params[:bridge][:busy_tone_answer] = "yes"

Forces an answer of the call before playing the busy tone. Default if argument not provided is "no", in which case call is only alerted with in-band media.

=== disconnect_tone ===
params[:bridge][:disconnect_tone] = "max_duration.wav"

Audio file played on the incoming call when call duration (:max_call_duration) is reached. Then the leg will be terminated with specified reason (:call_duration_reason).

==== disconnect_tone options ====
===== max_call_duration =====
params[:bridge][:max_call_duration] = "60000"

Maximum call duration in millisecond. This timer is started when entering answer state.

===== call_duration_reason =====
params[:bridge][:call_duration_reason] = :resource_unavailable

Drop both legs with this reason when call duration (:max_call_duration) is reached.

=== Managing audio prompts through Web Portal ===
Audio prompts can be uploaded or deleted from the TMedia unit through the Web Portal:
[[Toolpack:Configuring_Audio_Prompts_A|Managing audio prompts]]

Prompts management must be done using the Web Portal of the primary server (in systems with redundant TMedia units or redundant host servers).
The file will automatically get replicated to the secondary server.

=== Managing audio prompts manually ===
Any file on the TMedia host file system can be played. This means it's possible to manage prompts through ssh/scp.

==== The default (replicated) prompts folder ====
By default, when playing a prompt, Toolpack will look in the default prompts folder:
/lib/tb/toolpack/pkg/prompts
The root of this "prompts" directory is automatically replicated to secondary unit of redundant setups (1+1, N+1, redundant hosts). Sub-folders won't be replicated.

Any prompt play request without explicit file path will map to this folder. For example:
params[:bridge][:busy_tone] = "no_route.wav"
This will correspond to file /lib/tb/toolpack/pkg/prompts/no_route.wav

==== Relative file paths ====
Any file path that begins with "file://" is considered relative to the tbstreamserver application's working directory:
/lib/tb/toolpack/setup/12358/2.8/apps/tbstreamserver/
(Where "2.8" may be replaced by the current major version of your system)

For example:
params[:bridge][:busy_tone] = "file://my_folder/no_route.wav"
This will correspond to file /lib/tb/toolpack/setup/12358/2.8/apps/tbstreamserver/my_folder/no_route.wav

==== Absolute file paths ====
Absolute paths can also be provided.
For example:
params[:bridge][:busy_tone] = "file:///root/my_folder/no_route.wav"
This will correspond to file /root/my_folder/no_route.wav

== Recording call legs ==
Introduced in release 2.6.44, it's now possible to use routing scripts to ask for recording incoming and/or outgoing call legs.

See example filter script "call_recording" (created by default in Web Portal routing scripts starting with 2.6.44) for an example.

=== Recording the incoming call leg ===
To record the incoming call leg, the routing script (in a "after filter" for example) has to set the following parameter:

bridge[ :record_incoming ] = ""

=== Recording the outgoing call leg ===
To record the outgoing call leg, the routing script (in a "after filter" for example) has to set the following parameter, per route (the decision to record or not, or the file name to record to, can be set per matching route):

# Need to clone the routes in order to have the right to modify them
routes = clone_routes params[:routes]
routes.each do |route|
route[ :record_outgoing ] = ""
end
# Store modified routes back to the parameters for this outgoing call
params[:routes] = routes

=== Record the outgoing call leg within incoming leg's recorded file (mixing) ===
[...]
route[ :record_outgoing ] = "@{MixWithIncoming}"
[...]

=== Choosing file path to record to ===
The value assigned to ":record_incoming" or ":record_outgoing" is the path to record the file to.

The paths can be absolute, or relative. When relative, they are relative to the "tbstreamserver" application working directory, for example:
/lib/tb/toolpack/setup/12358/2.7/apps/tbstreamserver/

* Empty file name will default to a name that contains various information about the call:
** ''LinkId'': Id common between all legs of this call bridge
** ''LegId'': Unique Id for this leg
** ''Nap'': Current NAP name this call leg is from
** ''Direction'': "IN" or "OUT" (depends if call leg is incoming or outgoing leg)
** ''Calling'': The calling number of this call leg
** ''Called'': The called number of this call leg
** ''Protocol'': The signaling protocol of this call leg (SS7, ISDN, CAS, SIP)
** ''Media info'': Codec + IP/Port for SIP calls, Trunk/Timeslot for TDM calls
* To record outgoing call leg in the same audio file as incoming call leg (mixing), use the following:
** @{MixWithIncoming}: Record outgoing legs in same file as incoming legs
* Variables can be used to insert in the recording path information that's not already available from routing scripts:
** @{CURRENT_PKG}: Version of current package
*** Example: 2.6.45
** @{DATE format}: Prints the date, where 'format' is expressed as described for the 'strftime' function
*** Example: @{DATE %Y-%m-%d} => 2013-01-28
** @{DefaultName}: Replaced by the default file name for recording, which contains:
*** LinkId: Id common between all legs of this call bridge
*** LegId: Unique Id for this leg
*** Nap: Current NAP name this call leg is from
*** Direction: "IN" or "OUT" (depends if call leg is incoming or outgoing leg)
*** Calling: Calling number
*** Called: Called number
*** Protocol: Protocol type of this call (SS7, ISDN, CASR2, SIP)
*** Media info: Codec + IP/Port for SIP calls, Trunk/Timeslot for TDM calls
*** Example: "73EBA698-F3D67B4B-NAP_SS7-IN-5550000-5550001-SS7-TRUNK_BELL_11-24.wav"
*** Example: "73EBA698-73EBA698-NAP_SIP-OUT-5550000-5550001-SIP-G723-10.3.10.101-1050.wav"
** @{DefaultPath}: Default recording folder and file name: "@{RECORD_PATH}/@{DATE %Y-%m-%d}/@{DefaultName}"
*** Example: "/lib/tb/toolpack/setup/12358/recorded_calls/73EBA698-F3D67B4B-NAP_SS7-IN-5550000-5550001-SS7-TRUNK_BELL_11-24.wav"
*** Example: "/lib/tb/toolpack/setup/12358/recorded_calls/73EBA698-73EBA698-NAP_SIP-OUT-5550000-5550001-SIP-G723-10.3.10.101-1050.wav"
** @{Direction}: Direction of current leg (IN our OUT)
*** Example: IN
** @{LegId}: Current LegId (Unique Id for this leg)
*** Example: F3D67B4B
** @{LinkId}: Current LinkId (Id common between all legs of this call bridge)
*** Example: 73EBA698
** @{PKG_HOME}: Path where packages are stored.
*** Note: It's not recomended to use that path on redundant systems, package file replication may cause confusion in recorded files.
*** Example: /lib/tb/toolpack/pkg
** @{PROMPT_PATH}: Default path where audio prompts are stored
*** Note: It's not recomended to use that path on redundant systems, package file replication may cause confusion in recorded files.
*** Example: /lib/tb/toolpack/pkg/prompts
** @{Protocol}: Protocol of current leg
*** Example: SS7
** @{RECORD_PATH}: Default recording folder: "@{TB_SETUP_HOME}/recorded_calls/"
** @{TBX_GW_PORT}: Current "System Id" (also called "Gateway Port")
*** Example: 12358
** And all variables listed here: [[Customer_application_framework:play_audio_files#Helpful_variables_to_build_play_or_record_file_paths|Building play or record file path]]

== Controlling UUI (user-to-user information) relay ==
UUI (user-to-user information) can be present in different messages received by either call leg during a call. For example, information can be carried during the initial invite, other information can be carried when the call is alerted, answered, or terminated.

Routing scripts can control if the UUI received from one leg through the call will be forwarded to the other call leg:
*uui_forward_enabled

Routing scripts can also read and modify the UUI received with the incoming call leg, before it gets forwarded upon creation of the outgoing call leg:
*uui

=== UUI (user-to-user indication) values ===

Byte array represented as ruby String. Use ''bridge=params[:bridge]'', then ''bridge[:uui]'' to access the data.

To access the bytes in Ruby, use ruby String operator []. For example: bridge[:uui][0] will return the binary value of the first UUI byte.

Function each_byte can also be useful to iterate through all bytes of the UUI.

=== uui_forward_enabled values ===

Controls forwarding or discarding of UUI to outgoing call leg.

Values for this parameter are "0", "1", "false" or "true.
* 0/false: UUI is not forwarded between call legs
* 1/true: UUI is forwarded between call legs

The value for this parameter at input of routing script depends on the "Forward UUI" parameter in the "Advanced" section of the Gateway configuration page of the Web Portal. The script may change this value to override the Gateway configuration.

== Authorization ==
Starting with release 2.7, it is possible to issue RADIUS authorization requests from routing scripts. To do so, the params[:authorization] object must be filled with the required RADIUS attributes and [[#Refuse|an exception must be raised]] with reason :authorization_required.

When the authorization is completed, the routing script is called again with the result. The params[:authorization] object will be filled with the RADIUS attributes from the response. The params[:authorization][:result] field will also contain a string indicating the result of the authorization:

* ''accept'': The authorization was successful.
* ''reject'': The authorization was refused.
* ''challenge'': The authorization was challenged.
* ''timeout'': The authorization was not answered.

== Call diversion options ==
It's possible to control the call flow when a call diversion information is received in the alerting state.

Two fields are available: bridge[ :diversion ] and bridge[ :diversion_reason ]

The internal release cause TOOLPACK_DIVERT_NOT_ALLOWED is used by gateway application to terminate both legs.

bridge[ :diversion ] = :allowed
The alert message will not be analyzed and the call will be progressed. Default behavior.
bridge[ :diversion ] = :not_allowed
If the alert message indicates that the call is diverted, the call will be released no matter the In-band information to allow
early media.
bridge[ :diversion ] = :not_allowed_w_early_media
The call will be released If the alert message indicates that the call is diverted with in-band information to allow early media.
bridge[ :diversion_reason ] = "*"
If the diversion is not allowed, the gateway will drop the call for any redirecting reason.
bridge[ :diversion_reason ] = "0,1,2"
or
bridge[ :diversion_reason ] = "unknown,busy,no_reply"
If the diversion is not allowed, the redirecting reason will be analyzed and the call will only be dropped for the configured cases.

See section [[Routing_script_tutorial:Mini_Development_Guide#Redirecting_number,_Original_Called_Number_and_Diversion_Reason|Redirecting number reason values]].

== Call transfer requests ==
Toolpack allows that [[Call transfer]] requests are relayed from one leg to the other, or to process them locally (making another outgoing call to replace the call that requested the call transfer).

If the chosen [[Call transfer]] mode is to process requests locally, upon reception of a call transfer request (SIP REFER or ISDN Facility), routing script will be called once again, to select the routes for the new outgoing call (call transfer target).

=== How to route call transfer request ===
Routing of a call transfer request is done exactly like routing of a normal incoming call.
The routing script generally does not need any modification to support that.

In some cases, the routing script may want to use information related to the transfer request to perform routing, or to insert information in the outgoing call leg.
Additional information is provided to the routing script, allowing routing decisions using information from the call transfer request (SIP REFER or ISDN Facility).
See below...

=== params[ :call ] content during transfer request ===
When processing a call transfer request, the params[ :call ] hash contains the information from the inbound call (same as was passed to the routing script upon arrival of the inbound call)
call = params[ :call ] -> Information from original inbound call, with exception of call[ :called ]

One exception (convenient because it allows a unmodified routing script to process call transfer request the same way as any other routing request):
call[ :called ] -> Replaced by the called number from the call transfer request (also called "redirection number")
Complementary information:
call[ :original_called_number ] -> Contains the called number that was initially received from the incoming call, prior to call transfer request
call[ :redirecting_number ] -> Number of the call from which the call transfer request was received (generally equals to original_called_number)

These fields will also be included in the outgoing call made after routing:
* original called number and redirecting number are existing fields on SS7 and ISDN calls
* SIP "diversion" header is used for SIP calls

=== params[ :transfer ] content ===
(this if valid only for release 2.7.102 and above) 
When processing a call transfer request, information from the call transfer request message (SIP REFER, ISDN Facility) is provided in params[ :transfer ]:
transfer = params[ :transfer ]
The following field is always present:
transfer[ :original_nap ] -> Contains the NAP of the first call from which a call transfer request was received
transfer[ :redirecting_nap ] -> Contains the NAP of the call from which the current call transfer request was received
(same as :original_nap for the first call transfer, different for subsequent transfers)
Examples of other fields that may be present, when appropriate:
transfer[ :uui ] -> The UUI (user-to-user information) found in the call transfer request
transfer[ :sip_header ] -> Contains custom SIP headers from the call transfer request
transfer[ :request_uri ] -> Contains the SIP Request URI

These fields are 'read-only'. They will not be included in the outgoing call, as they represent the contents of the call transfer request, and not the outgoing call to be made.

To insert/modify attributes of the outgoing call, the parameters from params[ :call ] must be edited instead.

== Redirection ==
In release 2.8 and above, redirection contacts are obtained from the routing engine in the following format:

contacts = params[ :contacts ]
contacts = {
:index=>"3",
:list=>[
{:called_number=>"6660", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"", :raw_data=>"", :expiration=>"3600"},
{:called_number=>"6661", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6661@192.168.215.127", :raw_data=>"<sip:6661@192.168.215.127>", :expiration=>"3600"}
{:called_number=>"6662", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6662@192.168.215.128", :raw_data=>"<sip:6662@192.168.215.128>", :expiration=>"3600"},
{:called_number=>"6663", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6663@192.168.215.129", :raw_data=>"<sip:6663@192.168.215.129>", :expiration=>"3600"},
{:called_number=>"6664", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6664@192.168.215.150", :raw_data=>"<sip:6664@192.168.215.150>", :expiration=>"3600"}
],
:source_indexes=>"nil,0,0,0,2"
}

* <code>params[:contacts][:list]</code> contains the contact log. Each contact within the list has the following fields:
** <code>:called_number</code> - the called number
** <code>:is_number_ported</code> - if the called number has been ported (for SIP: if the npdi parameter is present)
** <code>:ported_number</code> - the called number that was ported (for SIP: the rn parameter value, if available)
** <code>:sip_uri</code> - the SIP URI of the contact, without the contact-params section (without the expires and q contact parameters)
** <code>:raw_data</code> - the raw data representing the contact in the signaling protocol. For SIP, this is the full SIP URI (including the expires and q contact parameters).
** <code>:priority</code> - the priority of the contact [0-1000]
** <code>:expiration</code> - the expiration time in seconds of the contact
* <code>params[:contacts][:index]</code> contains the index of the contact that is currently being routed.
* <code>params[:contacts][:source_indexes]</code> contains a comma-separated list of indexes from <code>params[:contacts][:list]</code>. Each index represents the contact from which the contact in the list was obtained from.

To get more information, see:
*[[Routing_script_tutorial:SIP_Redirection_Contacts|SIP Redirection Contacts Parameters in a Call Flow]]

== Connected number ==
Insert a connected number in the answer message of the call flow.

Routing script example:
bridge = params[ :bridge ]
bridge [ :connected_number ] = "3335577"
bridge [ :connected_number_noa ] = :national_number
bridge [ :connected_number_npi ] = :private
bridge [ :connected_number_presentation ] = :allowed
bridge [ :connected_number_screening ] = :pass

== Terminating calls ==
In release 2.8, it is now possible to terminate a call through the routing scripts. The [[#Reason values|reason code]] must be specified in <code>params[:bridge][:reason]</code>. The <code>:terminate</code> hash must be created and copied into <code>params</code>:
terminate = {}
params[:terminate] = terminate
The following fields can then be set in <code>:terminate</code>:
* <code>:sip_header</code>
* <code>:contacts</code> # list of contacts as described in the [[#Redirection|redirection]] section
* <code>:isup_raw</code>
* <code>:isup_raw_variant</code>
* <code>:redirecting_number</code>
* <code>:redirecting_number_noa</code>
* <code>:redirecting_number_npi</code>
* <code>:redirecting_number_presentation</code>
* <code>:redirecting_number_reason</code>
* <code>:redirecting_number_counter</code>
* <code>:redirecting_number_indicator</code>
* <code>:original_called_number</code>
* <code>:original_called_number_noa</code>
* <code>:original_called_number_npi</code>
* <code>:original_called_number_presentation</code>
* <code>:original_called_number_reason</code>
* <code>:original_called_number_counter</code>

== Reason values ==

Check here for Termination Reason Cause codes: 

[[Termination_cause_codes|Termination Reason Cause codes]]
 

Example to refuse an incoming call leg.
raise RoutingException, :no_route

Reason cause strings available inside routing scripts:

List of Q.850 reason causes:
:unallocated_number
:no_route_to_network
:no_route_to_destination
:send_special_tone
:misdialled_trunk_prefix
:channel_unacceptable
:call_awarded_in_established_channel
:preemption
:reattempt
:qor_ported_number
:normal_call_clearing
:user_busy
:no_user_responding
:no_answer_from_user
:subscriber_absent
:call_rejected
:number_changed
:redirection
:exchange_routing_error
:non_selected_user_clearing
:destination_out_of_order
:address_incomplete
:facility_rejected
:response_to_status_enquiry
:normal_unspecified
:no_circuit_available
:network_out_of_order
:frame_mode_out_of_service
:frame_mode_connection_operational
:temporary_failure
:switching_equipment_congestion
:access_information_discarded
:requested_circuit_not_available
:precedence_call_blocked
:resource_unavailable
:quality_of_service_not_available
:requested_facility_not_subscribed
:outgoing_calls_barred
:outgoing_calls_barred_within_cug
:incoming_calls_barred
:incoming_calls_barred_within_cug
:bearer_cap_not_authorized
:bearer_cap_not_available
:inconsistency_access_info
:service_not_available
:bearer_cap_not_implemented
:channel_type_not_implemented
:requested_facility_not_implemented
:only_restricted_digital_info
:service_not_implemented
:invalid_call_reference
:channel_does_not_exist
:call_identity_does_not_exist
:call_identity_in_use
:no_call_suspended
:call_has_been_cleared
:user_not_member_of_cug
:incompatible_destination
:non_existant_cug
:invalid_transit_network
:invalid_message_unspecified
:mandatory_ie_missing
:message_type_non_existent
:message_not_compatible_with_call_state
:ie_non_existent
:invalid_ie_content
:msg_not_compatible_with_call_state
:recovery_on_timer_expiry
:parameter_non_existent_passed_on
:message_with_non_recognized_parameters_discarded
:protocol_error
:interworking_unspecified

List of toolpack reason causes:

:toolpack_normal or :normal
:toolpack_resource_error or :resource_error
:toolpack_timeout or :timeout
:toolpack_no_route or :no_route
:toolpack_call_collision or :call_collision
:toolpack_sync_drop or :sync_drop
:toolpack_signaling_error or :signaling_error
:toolpack_locally_rejected or :locally_rejected
:toolpack_interface_not_available or :interface_not_available
:toolpack_reset_in_progress or :reset_in_progress
:toolpack_adapter_reject or :adapter_reject
:toolpack_missing_or_invalid_ie or :missing_or_invalid_ie
:toolpack_incoming_only or :incoming_only
:toolpack_system_configuration_changed or :system_configuration_changed
:toolpack_resource_no_more_available or :resource_no_more_available
:toolpack_incompatible_media or :incompatible_media
:toolpack_resource_allocation_failed or :resource_allocation_failed
:toolpack_data_path_not_available or :data_path_not_available
:toolpack_local_congestion or :local_congestion
:toolpack_authorization_required or :authorization_required
:toolpack_call_divert_is_not_allowed or :call_divert_is_not_allowed

List of SIP reason causes: 
Reason causes starting with a digit must use the following syntax (can't use : as prefix).

'300_multiple_choices'
'301_moved_permanently'
'302_moved_temporarily'
'305_use_proxy'
'380_alternative_service'
'400_bad_request'
'401_unauthorized'
'402_payment_required'
'403_forbidden'
'404_not_found'
'405_method_not_allowed'
'406_not_acceptable'
'407_proxy_authentication_required'
'408_request_timeout'
'409_conflict'
'410_gone'
'413_request_entity_too_large'
'414_request_URI_too_long'
'415_unsupported_media'
'416_unsupported_URI_scheme'
'420_bad_extension'
'421_extension_required'
'422_session_timer_too_small'
'423_interval_too_brief'
'429_referrer_identity_error'
'480_temporary_unavailable'
'481_call_or_transaction_does_not_exist'
'482_loop_detected'
'483_too_many_hops'
'484_address_incomplete'
'485_ambiguous'
'486_busy_here'
'487_request_terminated'
'488_not_acceptable_here'
'489_bad_event'
'491_retry_after'
'500_server_internal_error'
'501_not_implemented'
'502_bad_gateway'
'503_service_unavailable'
'504_server_timeout'
'505_version_unsupported'
'513_message_too_large'
'600_busy_everywhere'
'603_decline'
'604_not_exist_anywhere'
'606_not_acceptable'

== Nap status ==

All the status fields of the NAPs are provided for use by the routing scripts. See the nap status provider for more details on which fields are available in the CEngineStatTransNap.hpp file.

'''Notice:''' These values may change between major release.

Routing script call attribute name Description
--------------------------------------------------------------------------------------------
"name" NAP name.
"signaling_type" Signaling type (SS7, ISDN, CASR2, SIP)
"profile" Profile name.
"sip_destination_ip" Destination IP address.
"sip_destination_port" Destination IP port.
"sip_transport_type" SIP transport type (:udp, :tcp, or :tls) (Toolpack 3.1 and more)
"inst_incoming_call_cnt" Instantaneous Count of incoming calls.
"inst_outgoing_call_cnt" Instantaneous Count of outgoing calls.
"available_cnt" Number of available circuits or channels.
"unavailable_cnt" Number of unavailable circuits or channels.
"availability_percent" Percentage of available circuits or channels.
"usage_percent" Percentage of used circuits or channels.
"unused_shared_percent" Percentage of used circuits or channels of this NAP available to make new calls with (taking into account shared with other NAPs)
"total_incoming_call_cnt" Total Count of incoming calls.
"global_asr_percent" Global calculated ASR percentage.
"total_outgoing_call_cnt" Total Count of outgoing calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_outgoing_call_cnt" Last 24 hours outgoing calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_outgoing_call_cnt" Current hour outgoing calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_outgoing_call_cnt" Last hour outgoing calls.
"poll_remote_proxy" Remote proxy polling enabled
"is_available" Remote proxy actually available or not
"time_since_polling" Time since the last availibility polling
"time_available_seconds" Number of seconds since the NAP is available
"time_unavailable_seconds" Number of seconds since the NAP is unavailable
"register_to_proxy" Register to proxy enabled
"registered" Actually registered or not
"time_since_refresh" Time since the last refresh
"time_registered_seconds" Number of seconds since the NAP is registered
"time_not_registered_seconds" Number of seconds since the NAP is not registered
"asr_stats_incoming_struct" Detailed Answer-Seizure Rate incoming statistics.
{
"global_asr_percent" Global calculated ASR percentage.
"total_call_cnt" Total count of calls.
"total_accepted_call_cnt" Total count of accepted calls (not dropped due to congestion or rate-limiting).
"total_answered_call_cnt" Total count of answered calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_call_cnt" Last 24 hours count of calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_call_cnt" Current hour count of calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_call_cnt" Last hour count of calls.
}
"asr_stats_outgoing_struct" Detailed Answer-Seizure Rate outgoing statistics.
{
"global_asr_percent" Global calculated ASR percentage.
"total_call_cnt" Total count of calls.
"total_accepted_call_cnt" Total count of accepted calls (not dropped due to congestion or rate-limiting).
"total_answered_call_cnt" Total count of answered calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_call_cnt" Last 24 hours count of calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_call_cnt" Current hour count of calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_call_cnt" Last hour count of calls.
}
"mos_struct" Detailed Mean Opinion Score statistics.
{
"last_24h_ingress" Last 24 hours calculated MOS for incoming RTP packets.
"last_24h_egress" Last 24 hours calculated MOS for outgoing RTP packets.
"current_hour_ingress" Current hour calculated MOS for incoming RTP packets.
"current_hour_egress" Current hour calculated MOS for outgoing RTP packets.
"last_hour_ingress" Last hour calculated MOS for incoming RTP packets.
"last_hour_egress" Last hour calculated MOS for outgoing RTP packets.
}
"network_quality_struct" Detailed network quality statistics.
{
"last_24h_ingress" Last 24 hours network quality percentage for incoming RTP packets.
"last_24h_egress" Last 24 hours network quality percentage for outgoing RTP packets.
"current_hour_ingress" Current hour network quality percentage for incoming RTP packets.
"current_hour_egress" Current hour network quality percentage for outgoing RTP packets.
"last_hour_ingress" Last hour network quality percentage for incoming RTP packets.
"last_hour_egress" Last hour network quality percentage for outgoing RTP packets.
}

 If the nap status is part of a substructure, the substructure will be a hash containing all subfield elements.

Example to access the signaling type and the number of incoming call count for the NAP of the current call:

incoming_nap = params[:naps][ params[:call][ :nap ].to_sym]
log_trace 4,"Incoming NAP parameters=" + incoming_nap.inspect
log_trace 4,"Incoming NAP signaling type=" + incoming_nap[:signaling_type].inspect
log_trace 4,"Incoming NAP call cnt=" + incoming_nap[:asr_stats_incoming_struct][:total_call_cnt].inspect

 It is also possible to add dynamic nap attributes in the web portal. These can be referenced by their name.

== Telephony Services ==
In release 2.10 and the above, telephony services (CNAM Request) can be manage from the routing engine in the following format:

params[:telephony_services].each do |service| -> Array of telephony services
service[:name] -> Customer telephony service name
service[:type] -> For now only "CNAM Request"
service[:enabled] -> Indicate if the service is enabled (true) or not (false)
(Only the telephony service define in the profile associated to the NAP is enabled)
(The others telephony services define in others profiles are disabled)
(If we are in the case where we return in the routing script with a response, it is important to set :enabled to false in order to avoid repeating the same query)
serviceParams = service[:params]
serviceParams[:return_to_script] -> Indicates to Gateway if we must return to the routing script after receiving the CNAM response
(It is important to set back to false this field to avoid an infinite loop)
serviceQuery = service[:query]
serviceQuery[:phone] -> 10 digits of calling number from the incoming call to send to the CNAM server
serviceQuery[:timeout] -> Timeout in millisecond to wait a CNAM response from CNAM server
(Default value from profile configuration)
serviceResponse = service[:response]
serviceResponse[:success] -> Indicates if we received a good CNAM response from the CNAM Server (Only present if :return_to_script is set to true)
serviceResponse[:caller_name] -> The caller name received in the CNAM response from the CNAM Server (Only present if :return_to_script is set to true)

== Custom user context ==
The routing script may '''save per-call information within the call context''', that will be available if routing is called again later during the call flow.

Cases where routing is called multiple time for the same call are:
- Call transfer requests
- SIP redirect requests
- Radius Authorization result
- Announcement server with digit collection

The routing script can save a recursive hash of attributes here:
params[:user_context]

For example
params[:user_context] = { "SomeKey" => "Some value I want to retrieve upon next routing for this call", "OtherVal" => { "subkey" => "subval" } }

Upon first call to routing script, params[:user_context] will be nil.
Upon subsequent calls to routing script, it will contain whatever the script had stored upon previous call (or nil if it was not set)

Note: This feature is available starting from release 2.9.85, 2.10.31 and 3.0.15 (in respective branches 2.9, 2.10 or 3.0)

== Routing Script Tests ==
The Web portal features a tool for Testing Scripts. The user must enter parameters to simulate the incoming call and after pressing the Test button, will output selected routes and numbers. You do not need to activate the new routes, or the new scripts to use this test tool: It can be used to test the routing scripts and routing table before activating it.
This is available in the Routing Scripts section of the Web portal.

=== Test parameters ===
==== @call_params ====

That variable should contain a hash of call parameters that will be passed to the routing script. This is equivalent to the incoming call parameters.

 

==== @nap_list ====

A list of the hash containing the nap statuses. This is equivalent to the nap statuses at the time the call is to be routed.

'''The nap list is hashed by the nap names in UPPERCASE.''' It is important to consider this when creating new dynamic route or nap attributes that may nap names that will be used to fetch a status.

 

==== @params ====

A hash of hashes containing parameters. This hash contains bridge parameters and other kind of parameter groups may be added in the future.

@params = {
:bridge => {:announcement_tone, "announcement.wav"},
:contacts => {
:index=>"1",
:list=>[
{:called_number=>"6660", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"",
:raw_data=>"", :expiration=>"3600"},
{:called_number=>"6661", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6661@192.168.215.127",
:raw_data=>"<sip:6661@192.168.215.127>", :expiration=>"3600"}
],
:source_indexes=>"nil,0"
}
}

 

----

 Back to [[Routing script tutorial|Routing Script Tutorial]].

Routing script tutorial:Mini Development Guide

2019-04-30T13:49:07Z

Abrassard: /* Example usage */

== Call object ==

=== Get ===

This function is used to get the call parameters. The possible parameters are described in the section "Call parameters"

called_number = caf_call.get :called

=== List_params ===

This function is used to retrieve the list of supported call parameters. For example to extract all the possible call parameters from the the call object and put it in hash.

caf_call.list_params.each {|param| call[param] = caf_call.get param }

=== Accept ===

This function is used to accept a call. It actually creates one outgoing route that the gateway application will use to bridge the incoming call leg. If more than one outgoing route is "accepted", the gateway will try them one by one in the same order that they were accepted. If an outgoing call leg fails (according to 'route retry' parameters), the next route in line will be used.

This method takes 2 arguments, the call parameters (hash) and the route parameters (hash). Note that calling this method does NOT stop the flow of the script.

Apply route remapping rules

caf_call.accept out_call, route

=== Refuse ===

This function is used to set the reason code for the incoming call leg refusal. However, this function does NOT stop the flow of the script.

caf_call.refuse :reason => :temporary_failure

To immediately refuse the incoming call leg and stop processing the script, the script must raise an exception. Exiting the script by raising the exception overwrites any reason cause previously stored using refuse().

raise RoutingException, :no_route

The supported refusal cause values for both refuse() and raise() are described in the section "[[Routing_script_tutorial:Mini_Development_Guide#Reason_values|Reason values]]".

=== Script parameters protocol mapping ===

The following call parameters are available in the call object. For example:

called_number = call[:called]

For information on how to use and remap call parameters, see [[Toolpack:_How_to_Use_RegEx_in_Remapped_Called_and_Calling_Number_Mask | How to use regex in Remapped Called and Calling Number Mask]]

{| cellspacing="1" cellpadding="1" border="1" style="width: 921px; height: 805px;"
|-
! scope="col" | '''Script parameter name'''
! scope="col" | '''ISDN '''
! scope="col" | '''R2 CAS''' 
! scope="col" | '''SS7 '''
! scope="col" | '''SIP '''
! scope="col" | '''Comment '''
! scope="col" | '''Toolpack version '''
|-
| leg_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Leg ID 
| 
|-
| session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Session ID 
| 
|-
| original_session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Original Session ID (before call transfer or redirections) 
| 
|-
| calling 
| Q931: 'Calling party number' IE - Number digits 
| ANI (Group B) 
| Q763: 'Calling party number' IE - address signals (*) 
| SIP:From - user-info 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead. 
| 
|-
| calling_sip_host 
| N/A 
| N/A 
| N/A 
| SIP:From - host (domain or IP) 
| For example : The 'telcobridges.com' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| calling_sip_port 
| N/A 
| N/A 
| N/A 
| SIP:From - port 
| For example : The '6060' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| calling_noa 
| Q931: 'Calling party number' IE - Type of number 
| N/A 
| Q763: 'Calling party number' IE - nature of address indicator (*) 
| N/A 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead 
| 
|-
| calling_npi 
| Q931: 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: 'Calling party number' IE - numbering plan indicator (*) 
| N/A 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead 
| 
|-
| calling_display 
| Q931: 'Display' IE - Display information 
Q931: 'Facility CNAM' IE when presentation is allowed for DMS/NI2 variants 
| N/A 
| Q763
ITU97: 'Display information' IE - display information
ANSI95: 'Generic name' IE - display information
| SIP:From - display-name 
| 
| 
|-
| calling_display_type 
| Q931: 'Display' IE - Display information (present and/or first byte) 
| N/A 
| Q763: 'Display information' IE - present or not 
| N/A 
| 
| 
|-
| calling_presentation 
| Q931: 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: 'Calling party number' IE - address presentation restricted indicator 
|
SIP:From - display-name (displays 'anonymous' or not)

SIP:Remote-party-id - privacy 

| 
| 
|-
| calling_screening 
| Q931: 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: 'Calling party number' IE - screening 
| SIP:Remote-party-id - screen 
| 
| 
|-
| calling_category 
| N/A 
| Call party category (Group A) 
| Q763: 'Calling party's category' IE - calling party's category 
|
SIP:From - cpc

SIP:P-asserted-identity - cpc 

| 
| 
|-
| calling_subscriber
(Generic Number / NDS) 
| Q931: 2nd 'Calling party number' IE - Number digits 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - Number digits 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| Requires option 'support 2 calling number IE' in the profile. This variable has priority over 'private_address' in the outgoing direction. 
| 
|-
| calling_subscriber_noa 
| Q931: 2nd 'Calling party number' IE - Type of number 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - nature of address indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_npi 
| Q931: 2nd 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - numbering plan indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
 
| 
|-
| calling_subscriber_presentation 
| Q931: 2nd 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - presentation restricted indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_screening 
| Q931: 2nd 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - screening 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| private_display 
| Q931: 'Facility CNAM' IE when presentation is restricted for DMS/NI2 variants 
| N/A 
| N/A 
|
SIP:P-asserted-identity - display-name 

SIP:Remote-party-id - display-name 

| 
| 
|-
| private_display_type 
| N/A 
| N/A 
| N/A 
| N/A 
| Indicate presence or not of the private calling information 
| 
|-
| private_address 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 

| For example : The 'fluffy' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_sip_host 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - host (domain or IP)

SIP:Remote-party-id - host (domain or IP) 

| For example : The 'telcobridges.com' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_sip_port 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - port

SIP:Remote-party-id - port 

| For example : The '6060' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| called 
| Q931: 'Called party number' IE - Number digits 
| DNIS (Group A) 
| Q763: 'Called party number' IE - address signals 
| SIP:To - user-info and host 
| 
| 
|-
| called_sip_host 
| N/A 
| N/A 
| N/A 
| SIP:To - host 
| For example : The 'telcobridges.com' in To: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| called_sip_port 
| N/A 
| N/A 
| N/A 
| SIP:To - port number 
| For example : The '6060' in To: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| called_noa 
| Q931: 'Called party number' IE - Type of number 
| N/A 
| Q763: 'Called party number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| called_npi 
| Q931: 'Called party number' IE - Numbering plan identification 
| N/A 
| Q763: 'Called party number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| charge_number 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - address signals 
| N/A 
| 
| 
|-
| charge_number_noa 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| charge_number_npi 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| redirecting_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default redirecting number and original called number forwarding behavior from incoming to outgoing leg 
| 
|-
| redirecting_number 
| Q931: 'Redirecting number' 1st IE - Number digits 
| N/A 
| Q763: 'Redirecting number' IE - address signals 
| SIP:Diversion (2nd header) - display-name 
| 
| 
|-
| redirecting_number_noa 
| Q931: 'Redirecting number' 1st IE - Type of number 
| N/A 
| Q763: 'Redirecting number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| redirecting_number_npi 
| Q931: 'Redirecting number' 1st IE - Numbering plan identification 
| N/A 
| Q763: 'Redirecting number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| redirecting_number_presentation 
| Q931: 'Redirecting number' 1st IE - Presentation indicator 
| N/A 
| Q763: 'Redirecting number' IE - address presentation restricted indicator 
| SIP:Diversion (2nd header) - diversion-privacy 
| 
| 
|-
| redirecting_number_indicator 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirecting indicator 
| N/A 
| 
| 
|-
| redirecting_number_reason 
| Q931: 'Redirecting number' 1st IE - Reason for redirection 
| N/A 
| Q763: 'Redirection information' IE - redirecting reason 
| SIP:Diversion (2nd header) - diversion-reason 
| 
| 
|-
| redirecting_number_counter 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirection counter 
| SIP:Diversion (2nd header) - diversion-counter 
| 
| 
|-
| original_called_number
(OCN) 
| Q931: 'Redirecting number' 2nd IE - Number digits 
| N/A 
| Q763: 'Redirection number' IE - address signals 
| SIP:Diversion  (1st header) - display-name 
| 
| 
|-
| original_called_number_noa 
| Q931: 'Redirecting number' 2nd IE - Type of number 
| N/A 
| Q763: 'Redirection number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| original_called_number_npi 
| Q931: 'Redirecting number' 2nd IE - Numbering plan identification 
| N/A 
| Q763: 'Redirection number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| original_called_number_presentation 
| Q931: 'Redirecting number' 2nd IE - Presentation indicator 
| N/A 
| Q763: 'Redirection number' IE - address presentation restricted indicator 
| SIP:Diversion (1st header) - diversion-privacy 
| 
| 
|-
| original_called_number_reason 
| Q931: 'Redirecting number' 2nd IE - Reason for redirection 
| N/A 
| Q763: 'Redirection information' IE - original redirection reason 
| SIP:Diversion (1st header) - diversion-reason 
| 
| 
|-
| original_called_number_counter 
| N/A 
| N/A 
| N/A 
| SIP:Diversion (1st header) - diversion-counter 
| 
| 
|-
| ported_number_npdi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - with qualifier=Ported number is present 
| SIP:RequestURI - npdi=yes is present 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number 
| N/A 
| N/A 
| Q763: 'Generic number' IE - address signals with qualifier=Ported number 
| SIP:RequestURI - to user part when rn is present 
| rn is stored in the called number 
| 
|-
| ported_number_noa 
| N/A 
| N/A 
| Q763: 'Generic number' IE - nature of address indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number_npi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - numbering plan indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| oli
(Originating line information) 
| 5ESS Codeset 6 OLI - Value 
| N/A 
| ANSI: 'Originating line information' IE - OLI 
|
SIP:From - oli

SIP:P-asserted-identity - oli 

| 
| 
|-
| request_uri 
| N/A 
| N/A 
| N/A 
| Complete Request URI string 
| 
| 
|-
| request_uri_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default URI forwarding behavior from incoming to outgoing leg 
| 
|-
| sip_header 
| N/A 
| N/A 
| N/A 
| Any header 
| Requires option 'Forward custom headers' in Profiles->SIP 
| 2.7.63 
|-
| nap
(Network Access Point) 
| N/A 
| N/A 
| N/A 
| N/A 
| Incoming leg NAP name (read-only) 
| 
|-
| type_of_network_identification 
| Q931: 'Transit network selection' IE - Type of network identification 
| N/A 
| Q763: 'Transit network selection' IE - Type of network identification 
| N/A 
| 
| 2.7 
|-
| network_identification 
| Q931: 'Transit network selection' IE - Network identification 
| N/A 
| Q763: 'Transit network selection' IE - Network identification 
| SIP: Request-Line - cic 
| 
| 2.7 
|-
| network_identification_plan 
| Q931: 'Transit network selection' IE - Network identification plan 
| N/A 
| Q763: 'Transit network selection' IE - Network identification plan 
| N/A 
| 
| 2.7 
|-
| location_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default location number forwarding behavior from incoming to outgoing leg 
| 2.7 
|-
| location_number 
| N/A 
| N/A 
| Q763: 'Location number' IE - address signals 
| N/A 
| 
| 2.7 
|-
| location_number_noa 
| N/A 
| N/A 
| Q763: 'Location number' IE - nature of address indicator 
| N/A 
| 
| 2.7 
|-
| location_number_npi 
| N/A 
| N/A 
| Q763: 'Location number' IE - numbering plan indicator 
| N/A 
| 
| 2.7 
|-
| location_number_presentation 
| N/A 
| N/A 
| Q763: 'Location number' IE - presentation restricted indicator 
| N/A 
| 
| 2.7 
|-
| location_number_screening 
| N/A 
| N/A 
| Q763: 'Location number' IE - screening 
| N/A 
| 
| 2.7 
|-
| mlpp_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| A script needs to set this to true if it wants to overwrite MLPP information in the outgoing leg. Otherwise, profile relay 'outgoing mode' applies automatically. 
| 2.7 
|-
| mlpp_look_for_busy 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - look ahead for busy 
| N/A 
| 
| 2.7 
|-
| mlpp_precedence_level 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - precedence level 
| SIP:Resource-Priority - q735 
| 
| 2.7 
|-
| mlpp_network_identity 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - network identity 
| N/A 
| 
| 2.7 
|-
| mlpp_service_domain 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - MLPP service domain 
| N/A 
| 
| 2.7 
|-
| called_isub 
| Q931: 'Called party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub parameter 
| 
| 2.7 
|-
| called_isub_type 
| Q931: 'Called party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub-encoding parameter 
| 
| 2.7 
|-
| calling_isub 
| Q931: 'Calling party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub 
| 
| 2.7 
|-
| calling_isub_type 
| Q931: 'Callinf party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub-encoding 
| 
| 2.7 
|-
| ss7_fci_default 
| N/A 
| N/A 
| Default forward call indicator (FCI) value. 
| N/A 
| Toolpack will overwrite FCI bits A, D, F, I and M with appropriate values according to call conditions 
| 2.7 
|-
| ss7_fci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_fci_default that must be forced. 
| N/A 
| Bits from ss7_fci_default which corresponding bit in ss7_fci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| ss7_bci_default 
| N/A 
| N/A 
| Default backward call indicator (BCI) value. 
| N/A 
| Toolpack will overwrite BCI bits AB, I, K, M and N with appropriate values according to call conditions 
| 2.7 
|-
| ss7_bci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_bci_default that must be forced. 
| N/A 
| Bits from ss7_bci_default which corresponding bit in ss7_bci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| tdm_ls_name_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable line service and timeslot selection to create the outgoing leg 
| 3.0 
|-
| tdm_ls_name
(Line Service or T1/E1 trunk) 
| Incoming leg line service name 
| Incoming leg line service name 
| Incoming leg line service name 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this line service name to create outgoing leg 
| 2.7 
|-
| tdm_timeslot_nb 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this timeslot number to create outgoing leg 
| 2.7 
|-
| rtp_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP port 
| (read-only) 
| 2.7 
|-
| rtp_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP port 
| (read-only) 
| 2.7 
|-
| ss7_cot_enabled 
| N/A 
| N/A 
| Requests SS7 in-call continuity test for this outgoing SS7 call 
| N/A 
| Toolpack will request a continuity test on the timeslot before making the outgoing call. If COT fails, the call will be dropped (then another route may be attempted) 
| 2.8 
|-
| reverse_charging_indication 
| Incoming leg Reverse charging indication IE present 
| N/A 
| N/A 
| N/A 
| If set in routing script, will add Reverse charging indication IE in outgoing leg (also use reverse_charging_indication_forward_enabled) 
| 2.8.12 
|-
| reverse_charging_indication_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable forwarding of reverse charging indication from incoming to outgoing leg 
| 2.8.12 
|-
| sip_call_id 
| N/A 
| N/A 
| N/A 
| Incoming leg SIP Call-Id 
| (read-only) 
| 2.9.112 / 3.0.131 
|-
| sip_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP port 
| (read-only) 
| 2.8.13 
|-
| sip_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP port 
| (read-only) 
| 2.8.13 
|}

 

=== Noa values ===
The text below represents the value normally used by routing script. 
Incase it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 
Example numeric values for the SS7 protocol are shown in parenthesis. 
 
*<tt>unknown_number (0x2)</tt>
*<tt>international_number (0x4)</tt>
*<tt>national_number (0x3)</tt>
*<tt>subscriber_number (0x1)</tt>
*<tt>network_specific (0x5)</tt>
*<tt>network_routing_national_format (0x7)</tt>
*<tt>network_routing_international_format (0x8)</tt>
*<tt>abbreviated_number (0x6)</tt>
*<tt>subscriber_number_operator_requested (0x71)</tt>
*<tt>national_number_operator_requested (0x72)</tt>
*<tt>international_number_operator_requested (0x73)</tt>
*<tt>no_number_present_operator_requested (0x74)</tt>
*<tt>no_number_present_cut_through_call_to_carrier (0x75)</tt>
*<tt>test_line_test_code (0x77)</tt>
*<tt>non_unique_subscriber_number (0x71)</tt>
*<tt>non_unique_national_number (0x73)</tt>
*<tt>non_unique_international_number (0x74)</tt>
*<tt>call_950_numbe (0x76)</tt>
*<tt>special_number (0x73)</tt>
*<tt>national_number_with_transit_network_selection (0x74)</tt>
*<tt>international_number_with_transit_network_selection (0x75)</tt>

Those values will be remapped to the protocol specific NOA value. To provide protocol specific value:

*<tt>call_params[:called_noa] = 0x70</tt>

or

*<tt>call_params[:called_noa] = 112</tt>

=== Npi values ===

*<tt>unknown_number</tt>
*<tt>isdn</tt>
*<tt>telephony</tt>
*<tt>private</tt>
*<tt>data</tt>
*<tt>telex</tt>
*<tt>national</tt>

=== Calling Display Type values ===

*<tt>unspecified</tt> => Type is unspecified.
*<tt>calling_party_name</tt> => Type is 0xB1.

Those values will be remapped to the protocol specific Display Information Type value. To provide protocol specific value:

*<tt>call_params[:calling_display_type] = 0xB1</tt>

or

*<tt>call_params[:calling_display_type] = 177</tt>

=== Calling Display value ===

*<tt>call_params[:calling_display] = "Roger Fluffy"</tt>

=== Presentation values for Calling number, Calling Subscriber (Generic Number), Redirecting Number, Original Called Number (OCN) and Location Number ===
The text below represents the value normally used by routing script. 
Incase it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 
Example numeric values for the SS7 protocol are shown in parenthesis. 
 
*<tt>unspecified</tt>
*<tt>not_available (0x2)</tt>
*<tt>allowed (0x0)</tt>
*<tt>restricted (0x1)</tt>
*<tt>addr_restricted</tt>
*<tt>name_restricted</tt>

=== Calling Party Category ===
The text below represents the value normally used by routing script. 
In case it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 

Mapping from routing script to SS7/CAS R2/SIP
{| cellspacing="1" cellpadding="1" border="1"
|-
! scope="col" | '''Routing Script string '''
! scope="col" | '''SS7 raw value '''
! scope="col" | '''R2 CAS scripts''' 
! scope="col" | '''Default Rx CAS''' 
! scope="col" | '''default Tx CAS''' 
! scope="col" | '''SIP "cpc=" '''
|-
| subscriber 
| 0xa 
| CATEGORY_SUBSCRIBER 
| 1 and 7 
| 7 
| ordinary 
|-
| subscriber_with_priority 
| 0xb 
| CATEGORY_SUBSCRIBER_WITH_PRIORITY 
| 2 and 9 
| 2 
| priority 
|-
| operator_french 
| 0x1 
| CATEGORY_OPERATOR_FRENCH 
| 5 
| 5 
| operator 
|-
| operator_english 
| 0x2 
| CATEGORY_OPERATOR_ENGLISH (5) 
| 5 
| 5 
| operator 
|-
| operator_german 
| 0x3 
| CATEGORY_OPERATOR_GERMAN (5) 
| 5 
| 5 
| operator 
|-
| operator_russian 
| 0x4 
| CATEGORY_OPERATOR_RUSSIAN (5) 
| 5 
| 5 
| operator 
|-
| operator_spanish 
| 0x5 
| CATEGORY_OPERATOR_SPANISH (5) 
| 5 
| 5 
| operator 
|-
| data 
| 0xc 
| CATEGORY_DATA 
| 6 and 8 
| 6 
| datacall 
|-
| test 
| 0xd 
| CATEGORY_TEST 
| 3 
| 3 
| test 
|-
| payphone 
| 0xf 
| CATEGORY_PAYPHONE 
| none 
| 7 
| payphone 
|-
| unknown 
| 0x0 
| CATEGORY_UNKNOWN 
| 4, 11 to 15 
| 7 
| unknown 
|-
| unspecified 
| 0xa 
| invalid 
| none 
| none 
| invalid 
|}
[[CAS_R2_scripting#Category_meanings|Link to calling party categories used in CAS R2 scripts]]

=== Screening values for Calling number, Calling Subscriber (Generic Number), and Location Number ===
The text below represents the value normally used by routing script. 
Incase it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 
Example numeric values for the SS7 protocol are shown in parenthesis. 
 
*<tt>unspecified</tt>
*<tt>no (0x0)</tt>
*<tt>pass (0x1)</tt>
*<tt>fail (0x2)</tt>
*<tt>network_provided (0x3)</tt>

=== Redirecting indicator values ===

SS7:

*<tt>no_redirection</tt>
*<tt>call_rerouted</tt>
*<tt>call_rerouted_all_restricted</tt>
*<tt>call_diverted</tt>
*<tt>call_diverted_all_restricted</tt>
*<tt>call_rerouted_restricted</tt>
*<tt>call_diverted_restricted</tt>
*<tt>spare</tt>

=== Redirecting number, Original Called Number and Diversion Reason ===

ISDN:

*<tt>unknown</tt>
*<tt>busy</tt>
*<tt>no_reply</tt>
*<tt>deflection</tt>
*<tt>dte_out_of_order</tt>
*<tt>forwarding_by_called_dte</tt>
*<tt>unconditional</tt>

SS7:

*<tt>unknown</tt>
*<tt>busy (SIP: user-busy)</tt>
*<tt>no_reply (SIP: no-answer)</tt>
*<tt>unconditional</tt>
*<tt>deflection</tt>
*<tt>deflection_immediate</tt>
*<tt>mobile_not_reachable</tt>

=== OLI (originating line information) values ===

The OLI parameter is a string that represents an integer value from 0 to 255.

=== Information Transfer Capability values ===

information_transfer_capability:

*<tt>digital</tt>
*<tt>restricted_digital</tt>
*<tt>digital_with_tones</tt>
*<tt>speech</tt>
*<tt>3_1_khz_audio</tt>
*<tt>video</tt>

=== redirecting_number_forward_enabled values ===

Controls forwarding or discarding of redirecting number (SIP: diversion header) to the outgoing call leg.

Values for this parameter are "0", "1", "false" or "true.
*0/false: Redirecting number (and original called number) is not forwarded to outgoing call leg
*1/true: Redirecting number (and original called number) is forwarded to outgoing call leg

The value for this parameter at the input of the routing script depends on the "Forward redirecting number" parameter in the "Advanced" section of the Gateway configuration page of the Web Portal. The script may change this value to override the Gateway configuration.

Note: To "insert" a new redirecting number value on the outgoing leg, redirecting_number_forward_enabled must also be set to true.

=== request_uri ===

Enables access to the Request-Line URI. 

For example, if the Request-Line is:
<pre>Request-Line: INVITE sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0</pre>
Then the retrieved request_uri will be "sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0". 

In the routing scripts, to retrieve only the called number, this script can be used: 
<pre> if call_params[:request_uri] && call_params[:request_uri] =~ /sip:(.*)@.*/
call_params[:called] = $1
end
</pre>
==== request_uri_forward_enabled ====

This call parameter controls forwarding or discarding of request uri to outgoing call leg.The request uri is the information in the "Request-Line:" of the SIP INVITE message. 

Values for this parameter are "0", "1", "false" or "true. 

* 0/false: Request uri is not forwarded to outgoing call leg 

* 1/true: Request uri is forwarded to outgoing call leg 

The default value for this parameters is false. 

==== sip_scheme ====
(Available in Toolpack 3.1+)
This call parameters indicates the scheme (generally "sip" or "sips") of the incoming call.

This also allows to control the scheme used for the outgoing call (regardless if request_uri_forward_enabled is used or not)

Note: sips scheme must only be used on TLS NAPs (will cause call routing failure if NAP has only UDP or TCP transport types).

=== sip_header values ===
Contains custom sip headers from the inbound call leg. Any custom sip header can be added to an outgoing call leg: 

'''Note:'''

The SIP header is in string format.

'''string format:'''
<pre>call[ :sip_header ] = "P-my-custom-header:value1 \nP-my-custom-header2:value2 \nP-my-custom-header3:value3"
</pre>
(Note: \n above are actual newline characters, not '\' followed by 'n')

* PCAP sample: [[File:TB_Custom_SIP_Headers.pcap]]

List of sip headers that will not appear in call[:sip_header] since they are already processed by the SIP stack:
<pre>
Accept Error-Info Remote-Party-ID
Accept-Contact Event Replaces
Accept-Encoding Expires Reply-To
Accept-Language From Request-Disposition
Alert-Info In-Reply-To Subject
Allow Max-Forwards Subscription-State
Allow-Events MIME-version Supported
Also Min-Expires Timestamp
Anonymity Min-SE To
Authorization Organization Unsupported
Authentication-Info Path User-Agent
Call-ID Priority Via
Call-Info Privacy Warning
Contact Proxy-Authenticate WWW-Authenticate
Content-Disposition Proxy-Authorization Require
Content-Encoding Proxy-Require Response-Key
Content-Language P-Media-Authorization Retry-After
Content-Length P-Preferred-Identity RPID-Privacy
Content-Type P-Asserted-Identity Route
CSeq RAck RSeq
RAck Reason Security-Client
Reason Record-Route Security-Server
Date Refer-To Security-Verify
Diversion Referred-By Server
Encryption Reject-Contact Service-Route
Session-Expires
</pre>

=== sip header parameters ===
The routing script can read (and modify) some SIP header parameters (user parameters, URI parameters or header parameters) from some SIP headers (To, From, P-Asserted-Identity, Remote-Party-ID, Contact).

==== Available parameters ====
* '''call[ :calling_parameters ]''' (SIP "From" header)
* '''call[ :called_parameters ]''' (SIP "To" header)
* '''call[ :private_address_parameters ]''' (SIP "P-Asserted-Identity" or "Remote-Party-ID" header)
* '''call[ :contact_parameters ]''' (SIP "Contact" header)

These parameters (if present) contain a hash with 3 keys: user_param, uri_param and header_param.
Each of this key points to a string that contains all the parameters found in the corresponding SIP header.
* '''User parameters''' (parameters between the user name/number and the host). Example <sip:alice;'''param=value'''@somewhere.com>
* '''URI parameters''' (parameters at the end of the URI). Example <sip:alice@somewhere.com;'''param=value'''>
* '''Header parameters''' (outside the URI). Example <sip:alice@somewhere.com>;'''param=value'''
Example to print all parameters of SIP "To" header:
call[ :called_parameters ].inspect -> '{ :user_param => "name1=value1;name2=value2", :uri_param => "name=value", :header_param => "name=value;example_param_without_value" }'
Example to modify (replace) the URI parameters of SIP "To" header:
call[ :called_parameters ][ :uri_param ] = "user=phone"

==== Exceptions ====
'''Note:''' Some parameters are reported as their own call attribute (oli, isub, cpc, transport) so they have the same representation for all protocols (SS7, IDSN, SIP). They won't appear present in the generic SIP header parameters structures above.

==== Forwarding from inbound to outbound call ====

==== Legacy behavior ====
(For base_routing version 1.32 or older)
By default, the parameters are not forwarded in a SIP to SIP call flow. The parameters '''will be forwarded''' when:
* accessed (read) from either the inbound or outbound call parameters
* written in either the inbound or outbound call parameters

==== Current behavior ====
(For Toolpack 3.0.118+, with base_routing version 1.33+)
SIP headers host and parameters are forwarded by default.

A route attribute "forward_sip_domain" (along with filter script "forward_sip_domain.rb") will control, per route, if SIP headers host+parameters must be forwarded.

==== Example usage ====
Example to print the user parameters:
<pre>
if call[:calling_parameters]
puts "user parameters = #{call[:calling_parameters][:user_param].inspect}"
end
</pre>

Example SIP "From" header:
From:<sip:123456782;test1=val1;test2=val2@something.com;test3=val3;test4=val4>;test5=val5;test6=val6
And the resulting content in the routing script:
call[:calling_parameters].inspect -> {:user_param=>"test1=val1;test2=val2", :uri_param=>"test3=val3;test4=val4", :header_param=>"test5=val5;test6=val6"}

Example to overwrite inbound leg calling parameters with new parameters for the outbound leg:
<pre>
call [:calling_parameters] = {
:user_param => "user_param7=7;user_param8=8",
:uri_param => "uri_param9=value9",
:header_param => "header_paramA=A" }
</pre>

Example to add user=phone and keep all other uri parameters.
<pre>
call[:calling_parameters] ||= {} # Create a hash if not already present
call[:calling_parameters][:uri_param] ||= "" # Create a string if not already present
call[:calling_parameters][:uri_param] += ";" if call[:calling_parameters][:uri_param] != ""
call[:calling_parameters][:uri_param] += "user=phone"
</pre>

=== MLPP Precedence values ===

mlpp_look_for_busy:

*<tt>allowed</tt>
*<tt>path_reserved</tt>
*<tt>not_allowed</tt>

mlpp_precedence_level:

*<tt>flash_override</tt>
*<tt>flash</tt>
*<tt>immediate</tt>
*<tt>priority</tt>
*<tt>routine</tt>

mlpp_network_identity:

3 digits value from 0 to 999

mlpp_service_domain:

24 bits value from 0 to 16777215

=== ISUB subaddress information values ===

called_isub_type:
calling_isub_type:

*<tt>nsap</tt>
*<tt>nsap_ia5</tt>
*<tt>nsap_bcd</tt>
*<tt>user</tt>

called_isub:
calling_isub:

Digits for the subaddress information.

=== Network Identification Plan ===

network_identification_plan:

*<tt>Unknown</tt> (value 0)
*<tt>cic</tt> (3 digits carrier identification code plus circuit code, value 1, SS7 or ISDN)
*<tt>user</tt> (User, value 2, ISDN only)
*<tt>cic4</tt> (4 digits carrier identification code plus circuit code, value 2, SS7 only)
*<tt>dnic</tt> (public Data Network ID, value 3, SS7 only)
*<tt>mnic</tt> (public land mobile network, value 6, SS7 only)

=== Registered Users Information ===
Routing script can access information about registered users (when either the calling or called user is a known registered user).
When these fields are empty, it means that the calling/called (SIP from/to) does not correspond to a known registered user (routing script may still decide to route the call based on static routes).

Information for the called user:
params[:registered_user]
Information for the calling user:
params[:calling_registered_user]

These parameters are a hash of key/values that provide information about the contact.
{
:contact_list=>
[
{
:contact=>"<sip:user_name_or_number@hostname:7070;transport=UDP>", -> Full contact
:expires=>"60", -> Contact expiry time (seconds)
:host=>"hostname", -> host name from the contact header
:name=>"user_name_or_number", -> user name from the contact header
:nap_in=>"NAP_NAME", -> NAP that the contact has registered from
:port=>"7070", -> Port from the contact header
:transport=>"UDP" -> Transport type from the contact header
:q_value=>"0.00", -> Q-value for the contact (for contact ordering)
:src_host=>"10.0.0.10", -> Actual source IP address that the contact has registered from
:src_port=>"7070", -> Actual source port that the contact has registered from
:src_transport=>"UDP", -> Actual protocol that the contact has been registering with
}
]
}

== Route parameters ==

All route may have these parameters:

*calling
*called
*nap
*remapped_calling
*remapped_called
*remapped_nap
*remapped_destination_leg_profile (called remapped_profile prior to Toolpack 2.9)
*remapped_source_leg_profile (called remapped_incoming_profile prior to Toolpack 2.9)

Example:

route[:remapped_nap]

Additionally it is possible to add dynamic route attributes in the web portal. These can be referenced by their name.
For example:
*priority
*weight

== Routing calls toward registered users ==
Static routes normally chose an outbound NAP to forward the call to.

But it's also possible to create routes which outbound NAP is dynamically chosen by matching a registered user (when using [[Sip_registration_forwarding|SIP registration forwarding]]).

More information can be found [[Sip_registration_forwarding#SIP_Calls_routing|here]] about the way to control the [[Sip_registration_forwarding#SIP_Calls_routing|priority of "dynamic" vs "static" routes]].

More information can be found [[#Registered_Users_Information|here]] about using routing scripts to access registered users information during call routing.

== Playing prompts announcements or tones ==

New feature in release 2.6, all bridges may have these parameters. These can be used to play IVR prompts (audio files) in different states of the call flow.

*'''announcement_tone''' (played before outgoing call is routed)
*'''ring_tone''' (played after when waiting for outgoing call to answer)
*'''busy_tone''' (played if outgoing call failed)
*'''disconnect_tone''' (played after the call has reached it's maximum duration)

Example to play an announcement to incoming call (before routing outgoing call, regardless if a matching route is found or not):
bridge[:announcement_tone ] = "my_announcement.wav"

Example to play a ring-tone while the outgoing call is ringing:
bridge[:ring_tone] = "my_ring_tone.wav"

Example to play an audio file when outgoing call fails (no route, or outgoing call is refused):
bridge[:busy_tone] = "my_busy_tone.wav"

Example to play an audio file when call has reached the maximum allowed duration:
bridge[:disconnect_tone] = "your_account_balance_is_empty.wav"

=== Announcement file path format and options ===

All file plabyacks (:announcement_tone, :busy_tone, :ring_tone, :disconnect_tone) inside bridge parameters use this format.
<pre>"file1.wav:repeat:start_off:end_off,file2.wav:repeat:start_off:end_off,file3.wav:repeat:start_off:end_off"
</pre>
Optional parameters:
* repeat: number of times to play the file (0 and 1 have the same result)
* start_off: Start offset in milliseconds
* end_off: End offset in milliseconds

Http and other path formats are described here: [[Customer_application_framework:play_audio_files#Play_path_format|Path format]]

==== Example 1 ====
The following example will play file1.wav once, and then play file2.wav in loop:
"file1.wav,file2.wav:-1"

==== Example 2 ====
The following example will play file1.wav from start offset of 1 second to end offset of 3 seconds, then twice file2.wav from second 5 to second 10.
"file1.wav:0:1000:3000,file2.wav:2:5000:10000"

==== Example 3 ====
The following example will play file1.wav once, ending at offset of 30 seconds.
"file1.wav:0:0:30000"

=== announcement_tone ===

params[:bridge][:announcement_tone] = "announcement.wav"

Audio file played on the incoming call before any outgoing call is placed. The outgoing call occurs when the file finished playing.

==== announcement_tone options ====
===== announcement_tone_answer =====
params[:bridge][:announcement_tone_answer] = "yes"

Forces an answer of the call before playing the announcement. Default if argument not provided is "no", in which case call is only alerted with in-band media.

===== announcement_code_detect =====
This option allows that the tone detection is enabled during the announcement play.

Collected digits can be inserted into the CDR logs (radius attribute "Telcob-CollectedDigits", or text CDR variable @{CollectedDigits}).

Collected digits can also be sent back to routing script, which is called again with the same call attributes, except that the called number is replaced by the collected digits.

Code detect has multiple options, as shown in the following code:
code_detect = {
:type => :DTMF, # :DTMF or :MFR1 tone detection.
# Default is MFR1.
:prefix => "", # Prefix (digits) that is removed from collected digits.
# Default is empty.
:suffix => "", # Suffix (digits) that is removed from collected digits
# and causes routing script to be immediately called.
# Default is empty.
:suffix_removal => false, # Controls the removal of the suffix from the collected digit string that's reported to routing script.
# Default is false
:timeout => 0, # Inter-digit timeout (ms) after which collected digits are passed to the routing script.
# Use 0 for "no timeout".
# Default is 1000ms
:barge_in_interruption => true, # When enabled, playing announcement is stopped as soon as first digit is collected.
# Default is true.
:proceed_on_play_done => false, # When true: Outgoing call is made after announcement finishes playing.
# Routing script is not called again.
# When false: Outgoing call is never made.
# Digits are collected until timeout or suffix match,
# then routing script is called again.
# Default is false.
:cas_on_hook => false, # Specific for CAS-R1 calls. Makes CAS bits switch to "on-hook" when announcement finished playing
# (but the call is not "terminated" from Toolpack point of view)
# Default is false.
:cas_on_hook_delay => 0, # Duration of cas bits "on-hook" state.
# Only effective if cas_on_hook is set to true.
# Value of 0 stands for "infinite delay".
# Default is 0.
:repeat_delay => 0, # Delay between repetition of the announcement. The announcement will repeat
# itself every "repeat_delay" until a code is detected (suffix match or timetout).
# Value of 0 stands for "infinite delay" (no repeating).
# Default is 0.
}
'''Example 1''': Collect DTMF digits, and call routing script again with collected digits upon timeout or suffix match.
code_detect = { :type => :DTMF, :suffix => "#", :timeout => 5000 }
params[:bridge][:announcement_code_detect] = code_detect

'''Example 2''': Collect digits during the announcement (for CDR logs), then proceed (make outgoing call) after announcement finishes playing
code_detect = { :type => :DTMF, :timeout => 0, :barge_in_interruption => false, :proceed_on_play_done => true }
params[:bridge][:announcement_code_detect] = code_detect

==== Controlling what happens after announcement ====
The routing script can control what happens with the call after the announcement finishes playing:
* An outgoing call is made
* Incoming call is hung-up
* Do nothing (wait for the incoming call to hang-up)
===== An outgoing call is made =====
This happens when the script has returned matching routes (and did not raise RoutingException)

===== Incoming call is hung-up =====
This happens when the script returns no routes (in which case base_routing will raise RoutingException with cause :no_route).

It also happens when the script explicitly raises RoutingException.

The incoming call will be terminated with the specified cause.
For example
raise RoutingException, :temporary_failure
(See "Reason values" section in this page for list of available causes)

===== Do nothing (wait for the incoming call to hang-up) =====
If a filter raises RoutingException with code :ok, then the incoming call will not be terminated at the end of the announcement play.
Announcement digit collection will remain active if appropriate.
For example:
raise RoutingException, :ok

=== ring_tone ===
params[:bridge][:ring_tone] = "ringing.wav"

Audio file played on the incoming call while waiting for the outgoing call to be answered.

Ring tone playback can also be configured in the Web Portal, from the incoming call's profile (under "Tones and Call Progress Options").

Routing script has precedence over profile (a routing script that fills params[:bridge][:ring_tone] will override the profile's ring tone behavior).

==== ring_tone options ====
===== ring_tone_state =====
params[:bridge][:ring_tone_state] = :alerted

Call state from which ring tone is being played. Available values are:
* '''immediately''': Ring tone starts playing immediately on the incoming leg
* '''accepted''': Ring tone starts playing as soon as outgoing call is accepted
* '''callprogress''': Ring tone starts playing as soon as "call progress" is received on the outgoing call
* '''alerted''' (default): Ring tone starts playing only once outgoing call is alerted (but won't play if alert indicates early media from outgoing call)

This option also apply when params[:bridge][:ring_tone] is not used, because it also apply to ring tone playback configured in the Web Portal, from the incoming call's profile.

=== busy_tone ===
Toolpack 2.8 and above:
params[:bridge][:busy_tone] = "no_route.wav"

Note: Obsolete name (toolpack 2.7.153 and earlier, but still supported in recent releases):
params[:bridge][:call_progress_tone] = "no_route.wav"

Audio file played on the incoming call when outgoing call fails (never answered).

Note that announcement_tone, if used, is played before the outgoing call attempt is made, and thus before the busy_tone.

Busy tone playback can also be configured in the Web Portal, from the incoming call's profile (under "Tones and Call Progress Options").

Routing script has precedence over profile (a routing script that fills params[:bridge][:busy_tone] will override the profile's busy tone behavior).

Special value '''"none"''' can be used by routing script to force playing nothing (as empty string would default to profile's behavior)

==== busy_tone options ====
===== busy_tone_answer =====
params[:bridge][:busy_tone_answer] = "yes"

Forces an answer of the call before playing the busy tone. Default if argument not provided is "no", in which case call is only alerted with in-band media.

=== disconnect_tone ===
params[:bridge][:disconnect_tone] = "max_duration.wav"

Audio file played on the incoming call when call duration (:max_call_duration) is reached. Then the leg will be terminated with specified reason (:call_duration_reason).

==== disconnect_tone options ====
===== max_call_duration =====
params[:bridge][:max_call_duration] = "60000"

Maximum call duration in millisecond. This timer is started when entering answer state.

===== call_duration_reason =====
params[:bridge][:call_duration_reason] = :resource_unavailable

Drop both legs with this reason when call duration (:max_call_duration) is reached.

=== Managing audio prompts through Web Portal ===
Audio prompts can be uploaded or deleted from the TMedia unit through the Web Portal:
[[Toolpack:Configuring_Audio_Prompts_A|Managing audio prompts]]

Prompts management must be done using the Web Portal of the primary server (in systems with redundant TMedia units or redundant host servers).
The file will automatically get replicated to the secondary server.

=== Managing audio prompts manually ===
Any file on the TMedia host file system can be played. This means it's possible to manage prompts through ssh/scp.

==== The default (replicated) prompts folder ====
By default, when playing a prompt, Toolpack will look in the default prompts folder:
/lib/tb/toolpack/pkg/prompts
The root of this "prompts" directory is automatically replicated to secondary unit of redundant setups (1+1, N+1, redundant hosts). Sub-folders won't be replicated.

Any prompt play request without explicit file path will map to this folder. For example:
params[:bridge][:busy_tone] = "no_route.wav"
This will correspond to file /lib/tb/toolpack/pkg/prompts/no_route.wav

==== Relative file paths ====
Any file path that begins with "file://" is considered relative to the tbstreamserver application's working directory:
/lib/tb/toolpack/setup/12358/2.8/apps/tbstreamserver/
(Where "2.8" may be replaced by the current major version of your system)

For example:
params[:bridge][:busy_tone] = "file://my_folder/no_route.wav"
This will correspond to file /lib/tb/toolpack/setup/12358/2.8/apps/tbstreamserver/my_folder/no_route.wav

==== Absolute file paths ====
Absolute paths can also be provided.
For example:
params[:bridge][:busy_tone] = "file:///root/my_folder/no_route.wav"
This will correspond to file /root/my_folder/no_route.wav

== Recording call legs ==
Introduced in release 2.6.44, it's now possible to use routing scripts to ask for recording incoming and/or outgoing call legs.

See example filter script "call_recording" (created by default in Web Portal routing scripts starting with 2.6.44) for an example.

=== Recording the incoming call leg ===
To record the incoming call leg, the routing script (in a "after filter" for example) has to set the following parameter:

bridge[ :record_incoming ] = ""

=== Recording the outgoing call leg ===
To record the outgoing call leg, the routing script (in a "after filter" for example) has to set the following parameter, per route (the decision to record or not, or the file name to record to, can be set per matching route):

# Need to clone the routes in order to have the right to modify them
routes = clone_routes params[:routes]
routes.each do |route|
route[ :record_outgoing ] = ""
end
# Store modified routes back to the parameters for this outgoing call
params[:routes] = routes

=== Record the outgoing call leg within incoming leg's recorded file (mixing) ===
[...]
route[ :record_outgoing ] = "@{MixWithIncoming}"
[...]

=== Choosing file path to record to ===
The value assigned to ":record_incoming" or ":record_outgoing" is the path to record the file to.

The paths can be absolute, or relative. When relative, they are relative to the "tbstreamserver" application working directory, for example:
/lib/tb/toolpack/setup/12358/2.7/apps/tbstreamserver/

* Empty file name will default to a name that contains various information about the call:
** ''LinkId'': Id common between all legs of this call bridge
** ''LegId'': Unique Id for this leg
** ''Nap'': Current NAP name this call leg is from
** ''Direction'': "IN" or "OUT" (depends if call leg is incoming or outgoing leg)
** ''Calling'': The calling number of this call leg
** ''Called'': The called number of this call leg
** ''Protocol'': The signaling protocol of this call leg (SS7, ISDN, CAS, SIP)
** ''Media info'': Codec + IP/Port for SIP calls, Trunk/Timeslot for TDM calls
* To record outgoing call leg in the same audio file as incoming call leg (mixing), use the following:
** @{MixWithIncoming}: Record outgoing legs in same file as incoming legs
* Variables can be used to insert in the recording path information that's not already available from routing scripts:
** @{CURRENT_PKG}: Version of current package
*** Example: 2.6.45
** @{DATE format}: Prints the date, where 'format' is expressed as described for the 'strftime' function
*** Example: @{DATE %Y-%m-%d} => 2013-01-28
** @{DefaultName}: Replaced by the default file name for recording, which contains:
*** LinkId: Id common between all legs of this call bridge
*** LegId: Unique Id for this leg
*** Nap: Current NAP name this call leg is from
*** Direction: "IN" or "OUT" (depends if call leg is incoming or outgoing leg)
*** Calling: Calling number
*** Called: Called number
*** Protocol: Protocol type of this call (SS7, ISDN, CASR2, SIP)
*** Media info: Codec + IP/Port for SIP calls, Trunk/Timeslot for TDM calls
*** Example: "73EBA698-F3D67B4B-NAP_SS7-IN-5550000-5550001-SS7-TRUNK_BELL_11-24.wav"
*** Example: "73EBA698-73EBA698-NAP_SIP-OUT-5550000-5550001-SIP-G723-10.3.10.101-1050.wav"
** @{DefaultPath}: Default recording folder and file name: "@{RECORD_PATH}/@{DATE %Y-%m-%d}/@{DefaultName}"
*** Example: "/lib/tb/toolpack/setup/12358/recorded_calls/73EBA698-F3D67B4B-NAP_SS7-IN-5550000-5550001-SS7-TRUNK_BELL_11-24.wav"
*** Example: "/lib/tb/toolpack/setup/12358/recorded_calls/73EBA698-73EBA698-NAP_SIP-OUT-5550000-5550001-SIP-G723-10.3.10.101-1050.wav"
** @{Direction}: Direction of current leg (IN our OUT)
*** Example: IN
** @{LegId}: Current LegId (Unique Id for this leg)
*** Example: F3D67B4B
** @{LinkId}: Current LinkId (Id common between all legs of this call bridge)
*** Example: 73EBA698
** @{PKG_HOME}: Path where packages are stored.
*** Note: It's not recomended to use that path on redundant systems, package file replication may cause confusion in recorded files.
*** Example: /lib/tb/toolpack/pkg
** @{PROMPT_PATH}: Default path where audio prompts are stored
*** Note: It's not recomended to use that path on redundant systems, package file replication may cause confusion in recorded files.
*** Example: /lib/tb/toolpack/pkg/prompts
** @{Protocol}: Protocol of current leg
*** Example: SS7
** @{RECORD_PATH}: Default recording folder: "@{TB_SETUP_HOME}/recorded_calls/"
** @{TBX_GW_PORT}: Current "System Id" (also called "Gateway Port")
*** Example: 12358
** And all variables listed here: [[Customer_application_framework:play_audio_files#Helpful_variables_to_build_play_or_record_file_paths|Building play or record file path]]

== Controlling UUI (user-to-user information) relay ==
UUI (user-to-user information) can be present in different messages received by either call leg during a call. For example, information can be carried during the initial invite, other information can be carried when the call is alerted, answered, or terminated.

Routing scripts can control if the UUI received from one leg through the call will be forwarded to the other call leg:
*uui_forward_enabled

Routing scripts can also read and modify the UUI received with the incoming call leg, before it gets forwarded upon creation of the outgoing call leg:
*uui

=== UUI (user-to-user indication) values ===

Byte array represented as ruby String. Use ''bridge=params[:bridge]'', then ''bridge[:uui]'' to access the data.

To access the bytes in Ruby, use ruby String operator []. For example: bridge[:uui][0] will return the binary value of the first UUI byte.

Function each_byte can also be useful to iterate through all bytes of the UUI.

=== uui_forward_enabled values ===

Controls forwarding or discarding of UUI to outgoing call leg.

Values for this parameter are "0", "1", "false" or "true.
* 0/false: UUI is not forwarded between call legs
* 1/true: UUI is forwarded between call legs

The value for this parameter at input of routing script depends on the "Forward UUI" parameter in the "Advanced" section of the Gateway configuration page of the Web Portal. The script may change this value to override the Gateway configuration.

== Authorization ==
Starting with release 2.7, it is possible to issue RADIUS authorization requests from routing scripts. To do so, the params[:authorization] object must be filled with the required RADIUS attributes and [[#Refuse|an exception must be raised]] with reason :authorization_required.

When the authorization is completed, the routing script is called again with the result. The params[:authorization] object will be filled with the RADIUS attributes from the response. The params[:authorization][:result] field will also contain a string indicating the result of the authorization:

* ''accept'': The authorization was successful.
* ''reject'': The authorization was refused.
* ''challenge'': The authorization was challenged.
* ''timeout'': The authorization was not answered.

== Call diversion options ==
It's possible to control the call flow when a call diversion information is received in the alerting state.

Two fields are available: bridge[ :diversion ] and bridge[ :diversion_reason ]

The internal release cause TOOLPACK_DIVERT_NOT_ALLOWED is used by gateway application to terminate both legs.

bridge[ :diversion ] = :allowed
The alert message will not be analyzed and the call will be progressed. Default behavior.
bridge[ :diversion ] = :not_allowed
If the alert message indicates that the call is diverted, the call will be released no matter the In-band information to allow
early media.
bridge[ :diversion ] = :not_allowed_w_early_media
The call will be released If the alert message indicates that the call is diverted with in-band information to allow early media.
bridge[ :diversion_reason ] = "*"
If the diversion is not allowed, the gateway will drop the call for any redirecting reason.
bridge[ :diversion_reason ] = "0,1,2"
or
bridge[ :diversion_reason ] = "unknown,busy,no_reply"
If the diversion is not allowed, the redirecting reason will be analyzed and the call will only be dropped for the configured cases.

See section [[Routing_script_tutorial:Mini_Development_Guide#Redirecting_number,_Original_Called_Number_and_Diversion_Reason|Redirecting number reason values]].

== Call transfer requests ==
Toolpack allows that [[Call transfer]] requests are relayed from one leg to the other, or to process them locally (making another outgoing call to replace the call that requested the call transfer).

If the chosen [[Call transfer]] mode is to process requests locally, upon reception of a call transfer request (SIP REFER or ISDN Facility), routing script will be called once again, to select the routes for the new outgoing call (call transfer target).

=== How to route call transfer request ===
Routing of a call transfer request is done exactly like routing of a normal incoming call.
The routing script generally does not need any modification to support that.

In some cases, the routing script may want to use information related to the transfer request to perform routing, or to insert information in the outgoing call leg.
Additional information is provided to the routing script, allowing routing decisions using information from the call transfer request (SIP REFER or ISDN Facility).
See below...

=== params[ :call ] content during transfer request ===
When processing a call transfer request, the params[ :call ] hash contains the information from the inbound call (same as was passed to the routing script upon arrival of the inbound call)
call = params[ :call ] -> Information from original inbound call, with exception of call[ :called ]

One exception (convenient because it allows a unmodified routing script to process call transfer request the same way as any other routing request):
call[ :called ] -> Replaced by the called number from the call transfer request (also called "redirection number")
Complementary information:
call[ :original_called_number ] -> Contains the called number that was initially received from the incoming call, prior to call transfer request
call[ :redirecting_number ] -> Number of the call from which the call transfer request was received (generally equals to original_called_number)

These fields will also be included in the outgoing call made after routing:
* original called number and redirecting number are existing fields on SS7 and ISDN calls
* SIP "diversion" header is used for SIP calls

=== params[ :transfer ] content ===
(this if valid only for release 2.7.102 and above) 
When processing a call transfer request, information from the call transfer request message (SIP REFER, ISDN Facility) is provided in params[ :transfer ]:
transfer = params[ :transfer ]
The following field is always present:
transfer[ :original_nap ] -> Contains the NAP of the first call from which a call transfer request was received
transfer[ :redirecting_nap ] -> Contains the NAP of the call from which the current call transfer request was received
(same as :original_nap for the first call transfer, different for subsequent transfers)
Examples of other fields that may be present, when appropriate:
transfer[ :uui ] -> The UUI (user-to-user information) found in the call transfer request
transfer[ :sip_header ] -> Contains custom SIP headers from the call transfer request
transfer[ :request_uri ] -> Contains the SIP Request URI

These fields are 'read-only'. They will not be included in the outgoing call, as they represent the contents of the call transfer request, and not the outgoing call to be made.

To insert/modify attributes of the outgoing call, the parameters from params[ :call ] must be edited instead.

== Redirection ==
In release 2.8 and above, redirection contacts are obtained from the routing engine in the following format:

contacts = params[ :contacts ]
contacts = {
:index=>"3",
:list=>[
{:called_number=>"6660", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"", :raw_data=>"", :expiration=>"3600"},
{:called_number=>"6661", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6661@192.168.215.127", :raw_data=>"<sip:6661@192.168.215.127>", :expiration=>"3600"}
{:called_number=>"6662", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6662@192.168.215.128", :raw_data=>"<sip:6662@192.168.215.128>", :expiration=>"3600"},
{:called_number=>"6663", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6663@192.168.215.129", :raw_data=>"<sip:6663@192.168.215.129>", :expiration=>"3600"},
{:called_number=>"6664", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6664@192.168.215.150", :raw_data=>"<sip:6664@192.168.215.150>", :expiration=>"3600"}
],
:source_indexes=>"nil,0,0,0,2"
}

* <code>params[:contacts][:list]</code> contains the contact log. Each contact within the list has the following fields:
** <code>:called_number</code> - the called number
** <code>:is_number_ported</code> - if the called number has been ported (for SIP: if the npdi parameter is present)
** <code>:ported_number</code> - the called number that was ported (for SIP: the rn parameter value, if available)
** <code>:sip_uri</code> - the SIP URI of the contact, without the contact-params section (without the expires and q contact parameters)
** <code>:raw_data</code> - the raw data representing the contact in the signaling protocol. For SIP, this is the full SIP URI (including the expires and q contact parameters).
** <code>:priority</code> - the priority of the contact [0-1000]
** <code>:expiration</code> - the expiration time in seconds of the contact
* <code>params[:contacts][:index]</code> contains the index of the contact that is currently being routed.
* <code>params[:contacts][:source_indexes]</code> contains a comma-separated list of indexes from <code>params[:contacts][:list]</code>. Each index represents the contact from which the contact in the list was obtained from.

To get more information, see:
*[[Routing_script_tutorial:SIP_Redirection_Contacts|SIP Redirection Contacts Parameters in a Call Flow]]

== Connected number ==
Insert a connected number in the answer message of the call flow.

Routing script example:
bridge = params[ :bridge ]
bridge [ :connected_number ] = "3335577"
bridge [ :connected_number_noa ] = :national_number
bridge [ :connected_number_npi ] = :private
bridge [ :connected_number_presentation ] = :allowed
bridge [ :connected_number_screening ] = :pass

== Terminating calls ==
In release 2.8, it is now possible to terminate a call through the routing scripts. The [[#Reason values|reason code]] must be specified in <code>params[:bridge][:reason]</code>. The <code>:terminate</code> hash must be created and copied into <code>params</code>:
terminate = {}
params[:terminate] = terminate
The following fields can then be set in <code>:terminate</code>:
* <code>:sip_header</code>
* <code>:contacts</code> # list of contacts as described in the [[#Redirection|redirection]] section
* <code>:isup_raw</code>
* <code>:isup_raw_variant</code>
* <code>:redirecting_number</code>
* <code>:redirecting_number_noa</code>
* <code>:redirecting_number_npi</code>
* <code>:redirecting_number_presentation</code>
* <code>:redirecting_number_reason</code>
* <code>:redirecting_number_counter</code>
* <code>:redirecting_number_indicator</code>
* <code>:original_called_number</code>
* <code>:original_called_number_noa</code>
* <code>:original_called_number_npi</code>
* <code>:original_called_number_presentation</code>
* <code>:original_called_number_reason</code>
* <code>:original_called_number_counter</code>

== Reason values ==

Check here for Termination Reason Cause codes: 

[[Termination_cause_codes|Termination Reason Cause codes]]
 

Example to refuse an incoming call leg.
raise RoutingException, :no_route

Reason cause strings available inside routing scripts:

List of Q.850 reason causes:
:unallocated_number
:no_route_to_network
:no_route_to_destination
:send_special_tone
:misdialled_trunk_prefix
:channel_unacceptable
:call_awarded_in_established_channel
:preemption
:reattempt
:qor_ported_number
:normal_call_clearing
:user_busy
:no_user_responding
:no_answer_from_user
:subscriber_absent
:call_rejected
:number_changed
:redirection
:exchange_routing_error
:non_selected_user_clearing
:destination_out_of_order
:address_incomplete
:facility_rejected
:response_to_status_enquiry
:normal_unspecified
:no_circuit_available
:network_out_of_order
:frame_mode_out_of_service
:frame_mode_connection_operational
:temporary_failure
:switching_equipment_congestion
:access_information_discarded
:requested_circuit_not_available
:precedence_call_blocked
:resource_unavailable
:quality_of_service_not_available
:requested_facility_not_subscribed
:outgoing_calls_barred
:outgoing_calls_barred_within_cug
:incoming_calls_barred
:incoming_calls_barred_within_cug
:bearer_cap_not_authorized
:bearer_cap_not_available
:inconsistency_access_info
:service_not_available
:bearer_cap_not_implemented
:channel_type_not_implemented
:requested_facility_not_implemented
:only_restricted_digital_info
:service_not_implemented
:invalid_call_reference
:channel_does_not_exist
:call_identity_does_not_exist
:call_identity_in_use
:no_call_suspended
:call_has_been_cleared
:user_not_member_of_cug
:incompatible_destination
:non_existant_cug
:invalid_transit_network
:invalid_message_unspecified
:mandatory_ie_missing
:message_type_non_existent
:message_not_compatible_with_call_state
:ie_non_existent
:invalid_ie_content
:msg_not_compatible_with_call_state
:recovery_on_timer_expiry
:parameter_non_existent_passed_on
:message_with_non_recognized_parameters_discarded
:protocol_error
:interworking_unspecified

List of toolpack reason causes:

:toolpack_normal or :normal
:toolpack_resource_error or :resource_error
:toolpack_timeout or :timeout
:toolpack_no_route or :no_route
:toolpack_call_collision or :call_collision
:toolpack_sync_drop or :sync_drop
:toolpack_signaling_error or :signaling_error
:toolpack_locally_rejected or :locally_rejected
:toolpack_interface_not_available or :interface_not_available
:toolpack_reset_in_progress or :reset_in_progress
:toolpack_adapter_reject or :adapter_reject
:toolpack_missing_or_invalid_ie or :missing_or_invalid_ie
:toolpack_incoming_only or :incoming_only
:toolpack_system_configuration_changed or :system_configuration_changed
:toolpack_resource_no_more_available or :resource_no_more_available
:toolpack_incompatible_media or :incompatible_media
:toolpack_resource_allocation_failed or :resource_allocation_failed
:toolpack_data_path_not_available or :data_path_not_available
:toolpack_local_congestion or :local_congestion
:toolpack_authorization_required or :authorization_required
:toolpack_call_divert_is_not_allowed or :call_divert_is_not_allowed

List of SIP reason causes: 
Reason causes starting with a digit must use the following syntax (can't use : as prefix).

'300_multiple_choices'
'301_moved_permanently'
'302_moved_temporarily'
'305_use_proxy'
'380_alternative_service'
'400_bad_request'
'401_unauthorized'
'402_payment_required'
'403_forbidden'
'404_not_found'
'405_method_not_allowed'
'406_not_acceptable'
'407_proxy_authentication_required'
'408_request_timeout'
'409_conflict'
'410_gone'
'413_request_entity_too_large'
'414_request_URI_too_long'
'415_unsupported_media'
'416_unsupported_URI_scheme'
'420_bad_extension'
'421_extension_required'
'422_session_timer_too_small'
'423_interval_too_brief'
'429_referrer_identity_error'
'480_temporary_unavailable'
'481_call_or_transaction_does_not_exist'
'482_loop_detected'
'483_too_many_hops'
'484_address_incomplete'
'485_ambiguous'
'486_busy_here'
'487_request_terminated'
'488_not_acceptable_here'
'489_bad_event'
'491_retry_after'
'500_server_internal_error'
'501_not_implemented'
'502_bad_gateway'
'503_service_unavailable'
'504_server_timeout'
'505_version_unsupported'
'513_message_too_large'
'600_busy_everywhere'
'603_decline'
'604_not_exist_anywhere'
'606_not_acceptable'

== Nap status ==

All the status fields of the NAPs are provided for use by the routing scripts. See the nap status provider for more details on which fields are available in the CEngineStatTransNap.hpp file.

'''Notice:''' These values may change between major release.

Routing script call attribute name Description
--------------------------------------------------------------------------------------------
"name" NAP name.
"signaling_type" Signaling type (SS7, ISDN, CASR2, SIP)
"profile" Profile name.
"sip_destination_ip" Destination IP address.
"sip_destination_port" Destination IP port.
"sip_transport_type" SIP transport type (:udp, :tcp, or :tls) (Toolpack 3.1 and more)
"inst_incoming_call_cnt" Instantaneous Count of incoming calls.
"inst_outgoing_call_cnt" Instantaneous Count of outgoing calls.
"available_cnt" Number of available circuits or channels.
"unavailable_cnt" Number of unavailable circuits or channels.
"availability_percent" Percentage of available circuits or channels.
"usage_percent" Percentage of used circuits or channels.
"unused_shared_percent" Percentage of used circuits or channels of this NAP available to make new calls with (taking into account shared with other NAPs)
"total_incoming_call_cnt" Total Count of incoming calls.
"global_asr_percent" Global calculated ASR percentage.
"total_outgoing_call_cnt" Total Count of outgoing calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_outgoing_call_cnt" Last 24 hours outgoing calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_outgoing_call_cnt" Current hour outgoing calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_outgoing_call_cnt" Last hour outgoing calls.
"poll_remote_proxy" Remote proxy polling enabled
"is_available" Remote proxy actually available or not
"time_since_polling" Time since the last availibility polling
"time_available_seconds" Number of seconds since the NAP is available
"time_unavailable_seconds" Number of seconds since the NAP is unavailable
"register_to_proxy" Register to proxy enabled
"registered" Actually registered or not
"time_since_refresh" Time since the last refresh
"time_registered_seconds" Number of seconds since the NAP is registered
"time_not_registered_seconds" Number of seconds since the NAP is not registered
"asr_stats_incoming_struct" Detailed Answer-Seizure Rate incoming statistics.
{
"global_asr_percent" Global calculated ASR percentage.
"total_call_cnt" Total count of calls.
"total_accepted_call_cnt" Total count of accepted calls (not dropped due to congestion or rate-limiting).
"total_answered_call_cnt" Total count of answered calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_call_cnt" Last 24 hours count of calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_call_cnt" Current hour count of calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_call_cnt" Last hour count of calls.
}
"asr_stats_outgoing_struct" Detailed Answer-Seizure Rate outgoing statistics.
{
"global_asr_percent" Global calculated ASR percentage.
"total_call_cnt" Total count of calls.
"total_accepted_call_cnt" Total count of accepted calls (not dropped due to congestion or rate-limiting).
"total_answered_call_cnt" Total count of answered calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_call_cnt" Last 24 hours count of calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_call_cnt" Current hour count of calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_call_cnt" Last hour count of calls.
}
"mos_struct" Detailed Mean Opinion Score statistics.
{
"last_24h_ingress" Last 24 hours calculated MOS for incoming RTP packets.
"last_24h_egress" Last 24 hours calculated MOS for outgoing RTP packets.
"current_hour_ingress" Current hour calculated MOS for incoming RTP packets.
"current_hour_egress" Current hour calculated MOS for outgoing RTP packets.
"last_hour_ingress" Last hour calculated MOS for incoming RTP packets.
"last_hour_egress" Last hour calculated MOS for outgoing RTP packets.
}
"network_quality_struct" Detailed network quality statistics.
{
"last_24h_ingress" Last 24 hours network quality percentage for incoming RTP packets.
"last_24h_egress" Last 24 hours network quality percentage for outgoing RTP packets.
"current_hour_ingress" Current hour network quality percentage for incoming RTP packets.
"current_hour_egress" Current hour network quality percentage for outgoing RTP packets.
"last_hour_ingress" Last hour network quality percentage for incoming RTP packets.
"last_hour_egress" Last hour network quality percentage for outgoing RTP packets.
}

 If the nap status is part of a substructure, the substructure will be a hash containing all subfield elements.

Example to access the signaling type and the number of incoming call count for the NAP of the current call:

incoming_nap = params[:naps][ params[:call][ :nap ].to_sym]
log_trace 4,"Incoming NAP parameters=" + incoming_nap.inspect
log_trace 4,"Incoming NAP signaling type=" + incoming_nap[:signaling_type].inspect
log_trace 4,"Incoming NAP call cnt=" + incoming_nap[:asr_stats_incoming_struct][:total_call_cnt].inspect

 It is also possible to add dynamic nap attributes in the web portal. These can be referenced by their name.

== Telephony Services ==
In release 2.10 and the above, telephony services (CNAM Request) can be manage from the routing engine in the following format:

params[:telephony_services].each do |service| -> Array of telephony services
service[:name] -> Customer telephony service name
service[:type] -> For now only "CNAM Request"
service[:enabled] -> Indicate if the service is enabled (true) or not (false)
(Only the telephony service define in the profile associated to the NAP is enabled)
(The others telephony services define in others profiles are disabled)
(If we are in the case where we return in the routing script with a response, it is important to set :enabled to false in order to avoid repeating the same query)
serviceParams = service[:params]
serviceParams[:return_to_script] -> Indicates to Gateway if we must return to the routing script after receiving the CNAM response
(It is important to set back to false this field to avoid an infinite loop)
serviceQuery = service[:query]
serviceQuery[:phone] -> 10 digits of calling number from the incoming call to send to the CNAM server
serviceQuery[:timeout] -> Timeout in millisecond to wait a CNAM response from CNAM server
(Default value from profile configuration)
serviceResponse = service[:response]
serviceResponse[:success] -> Indicates if we received a good CNAM response from the CNAM Server (Only present if :return_to_script is set to true)
serviceResponse[:caller_name] -> The caller name received in the CNAM response from the CNAM Server (Only present if :return_to_script is set to true)

== Custom user context ==
The routing script may '''save per-call information within the call context''', that will be available if routing is called again later during the call flow.

Cases where routing is called multiple time for the same call are:
- Call transfer requests
- SIP redirect requests
- Radius Authorization result
- Announcement server with digit collection

The routing script can save a recursive hash of attributes here:
params[:user_context]

For example
params[:user_context] = { "SomeKey" => "Some value I want to retrieve upon next routing for this call", "OtherVal" => { "subkey" => "subval" } }

Upon first call to routing script, params[:user_context] will be nil.
Upon subsequent calls to routing script, it will contain whatever the script had stored upon previous call (or nil if it was not set)

Note: This feature is available starting from release 2.9.85, 2.10.31 and 3.0.15 (in respective branches 2.9, 2.10 or 3.0)

== Routing Script Tests ==
The Web portal features a tool for Testing Scripts. The user must enter parameters to simulate the incoming call and after pressing the Test button, will output selected routes and numbers. You do not need to activate the new routes, or the new scripts to use this test tool: It can be used to test the routing scripts and routing table before activating it.
This is available in the Routing Scripts section of the Web portal.

=== Test parameters ===
==== @call_params ====

That variable should contain a hash of call parameters that will be passed to the routing script. This is equivalent to the incoming call parameters.

 

==== @nap_list ====

A list of the hash containing the nap statuses. This is equivalent to the nap statuses at the time the call is to be routed.

'''The nap list is hashed by the nap names in UPPERCASE.''' It is important to consider this when creating new dynamic route or nap attributes that may nap names that will be used to fetch a status.

 

==== @params ====

A hash of hashes containing parameters. This hash contains bridge parameters and other kind of parameter groups may be added in the future.

@params = {
:bridge => {:announcement_tone, "announcement.wav"},
:contacts => {
:index=>"1",
:list=>[
{:called_number=>"6660", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"",
:raw_data=>"", :expiration=>"3600"},
{:called_number=>"6661", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6661@192.168.215.127",
:raw_data=>"<sip:6661@192.168.215.127>", :expiration=>"3600"}
],
:source_indexes=>"nil,0"
}
}

 

----

 Back to [[Routing script tutorial|Routing Script Tutorial]].

Routing script tutorial:Mini Development Guide

2019-04-30T13:48:51Z

Abrassard: /* Example usage */

== Call object ==

=== Get ===

This function is used to get the call parameters. The possible parameters are described in the section "Call parameters"

called_number = caf_call.get :called

=== List_params ===

This function is used to retrieve the list of supported call parameters. For example to extract all the possible call parameters from the the call object and put it in hash.

caf_call.list_params.each {|param| call[param] = caf_call.get param }

=== Accept ===

This function is used to accept a call. It actually creates one outgoing route that the gateway application will use to bridge the incoming call leg. If more than one outgoing route is "accepted", the gateway will try them one by one in the same order that they were accepted. If an outgoing call leg fails (according to 'route retry' parameters), the next route in line will be used.

This method takes 2 arguments, the call parameters (hash) and the route parameters (hash). Note that calling this method does NOT stop the flow of the script.

Apply route remapping rules

caf_call.accept out_call, route

=== Refuse ===

This function is used to set the reason code for the incoming call leg refusal. However, this function does NOT stop the flow of the script.

caf_call.refuse :reason => :temporary_failure

To immediately refuse the incoming call leg and stop processing the script, the script must raise an exception. Exiting the script by raising the exception overwrites any reason cause previously stored using refuse().

raise RoutingException, :no_route

The supported refusal cause values for both refuse() and raise() are described in the section "[[Routing_script_tutorial:Mini_Development_Guide#Reason_values|Reason values]]".

=== Script parameters protocol mapping ===

The following call parameters are available in the call object. For example:

called_number = call[:called]

For information on how to use and remap call parameters, see [[Toolpack:_How_to_Use_RegEx_in_Remapped_Called_and_Calling_Number_Mask | How to use regex in Remapped Called and Calling Number Mask]]

{| cellspacing="1" cellpadding="1" border="1" style="width: 921px; height: 805px;"
|-
! scope="col" | '''Script parameter name'''
! scope="col" | '''ISDN '''
! scope="col" | '''R2 CAS''' 
! scope="col" | '''SS7 '''
! scope="col" | '''SIP '''
! scope="col" | '''Comment '''
! scope="col" | '''Toolpack version '''
|-
| leg_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Leg ID 
| 
|-
| session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Session ID 
| 
|-
| original_session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Original Session ID (before call transfer or redirections) 
| 
|-
| calling 
| Q931: 'Calling party number' IE - Number digits 
| ANI (Group B) 
| Q763: 'Calling party number' IE - address signals (*) 
| SIP:From - user-info 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead. 
| 
|-
| calling_sip_host 
| N/A 
| N/A 
| N/A 
| SIP:From - host (domain or IP) 
| For example : The 'telcobridges.com' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| calling_sip_port 
| N/A 
| N/A 
| N/A 
| SIP:From - port 
| For example : The '6060' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| calling_noa 
| Q931: 'Calling party number' IE - Type of number 
| N/A 
| Q763: 'Calling party number' IE - nature of address indicator (*) 
| N/A 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead 
| 
|-
| calling_npi 
| Q931: 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: 'Calling party number' IE - numbering plan indicator (*) 
| N/A 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead 
| 
|-
| calling_display 
| Q931: 'Display' IE - Display information 
Q931: 'Facility CNAM' IE when presentation is allowed for DMS/NI2 variants 
| N/A 
| Q763
ITU97: 'Display information' IE - display information
ANSI95: 'Generic name' IE - display information
| SIP:From - display-name 
| 
| 
|-
| calling_display_type 
| Q931: 'Display' IE - Display information (present and/or first byte) 
| N/A 
| Q763: 'Display information' IE - present or not 
| N/A 
| 
| 
|-
| calling_presentation 
| Q931: 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: 'Calling party number' IE - address presentation restricted indicator 
|
SIP:From - display-name (displays 'anonymous' or not)

SIP:Remote-party-id - privacy 

| 
| 
|-
| calling_screening 
| Q931: 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: 'Calling party number' IE - screening 
| SIP:Remote-party-id - screen 
| 
| 
|-
| calling_category 
| N/A 
| Call party category (Group A) 
| Q763: 'Calling party's category' IE - calling party's category 
|
SIP:From - cpc

SIP:P-asserted-identity - cpc 

| 
| 
|-
| calling_subscriber
(Generic Number / NDS) 
| Q931: 2nd 'Calling party number' IE - Number digits 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - Number digits 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| Requires option 'support 2 calling number IE' in the profile. This variable has priority over 'private_address' in the outgoing direction. 
| 
|-
| calling_subscriber_noa 
| Q931: 2nd 'Calling party number' IE - Type of number 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - nature of address indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_npi 
| Q931: 2nd 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - numbering plan indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
 
| 
|-
| calling_subscriber_presentation 
| Q931: 2nd 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - presentation restricted indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_screening 
| Q931: 2nd 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - screening 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| private_display 
| Q931: 'Facility CNAM' IE when presentation is restricted for DMS/NI2 variants 
| N/A 
| N/A 
|
SIP:P-asserted-identity - display-name 

SIP:Remote-party-id - display-name 

| 
| 
|-
| private_display_type 
| N/A 
| N/A 
| N/A 
| N/A 
| Indicate presence or not of the private calling information 
| 
|-
| private_address 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 

| For example : The 'fluffy' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_sip_host 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - host (domain or IP)

SIP:Remote-party-id - host (domain or IP) 

| For example : The 'telcobridges.com' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_sip_port 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - port

SIP:Remote-party-id - port 

| For example : The '6060' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| called 
| Q931: 'Called party number' IE - Number digits 
| DNIS (Group A) 
| Q763: 'Called party number' IE - address signals 
| SIP:To - user-info and host 
| 
| 
|-
| called_sip_host 
| N/A 
| N/A 
| N/A 
| SIP:To - host 
| For example : The 'telcobridges.com' in To: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| called_sip_port 
| N/A 
| N/A 
| N/A 
| SIP:To - port number 
| For example : The '6060' in To: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| called_noa 
| Q931: 'Called party number' IE - Type of number 
| N/A 
| Q763: 'Called party number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| called_npi 
| Q931: 'Called party number' IE - Numbering plan identification 
| N/A 
| Q763: 'Called party number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| charge_number 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - address signals 
| N/A 
| 
| 
|-
| charge_number_noa 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| charge_number_npi 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| redirecting_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default redirecting number and original called number forwarding behavior from incoming to outgoing leg 
| 
|-
| redirecting_number 
| Q931: 'Redirecting number' 1st IE - Number digits 
| N/A 
| Q763: 'Redirecting number' IE - address signals 
| SIP:Diversion (2nd header) - display-name 
| 
| 
|-
| redirecting_number_noa 
| Q931: 'Redirecting number' 1st IE - Type of number 
| N/A 
| Q763: 'Redirecting number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| redirecting_number_npi 
| Q931: 'Redirecting number' 1st IE - Numbering plan identification 
| N/A 
| Q763: 'Redirecting number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| redirecting_number_presentation 
| Q931: 'Redirecting number' 1st IE - Presentation indicator 
| N/A 
| Q763: 'Redirecting number' IE - address presentation restricted indicator 
| SIP:Diversion (2nd header) - diversion-privacy 
| 
| 
|-
| redirecting_number_indicator 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirecting indicator 
| N/A 
| 
| 
|-
| redirecting_number_reason 
| Q931: 'Redirecting number' 1st IE - Reason for redirection 
| N/A 
| Q763: 'Redirection information' IE - redirecting reason 
| SIP:Diversion (2nd header) - diversion-reason 
| 
| 
|-
| redirecting_number_counter 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirection counter 
| SIP:Diversion (2nd header) - diversion-counter 
| 
| 
|-
| original_called_number
(OCN) 
| Q931: 'Redirecting number' 2nd IE - Number digits 
| N/A 
| Q763: 'Redirection number' IE - address signals 
| SIP:Diversion  (1st header) - display-name 
| 
| 
|-
| original_called_number_noa 
| Q931: 'Redirecting number' 2nd IE - Type of number 
| N/A 
| Q763: 'Redirection number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| original_called_number_npi 
| Q931: 'Redirecting number' 2nd IE - Numbering plan identification 
| N/A 
| Q763: 'Redirection number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| original_called_number_presentation 
| Q931: 'Redirecting number' 2nd IE - Presentation indicator 
| N/A 
| Q763: 'Redirection number' IE - address presentation restricted indicator 
| SIP:Diversion (1st header) - diversion-privacy 
| 
| 
|-
| original_called_number_reason 
| Q931: 'Redirecting number' 2nd IE - Reason for redirection 
| N/A 
| Q763: 'Redirection information' IE - original redirection reason 
| SIP:Diversion (1st header) - diversion-reason 
| 
| 
|-
| original_called_number_counter 
| N/A 
| N/A 
| N/A 
| SIP:Diversion (1st header) - diversion-counter 
| 
| 
|-
| ported_number_npdi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - with qualifier=Ported number is present 
| SIP:RequestURI - npdi=yes is present 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number 
| N/A 
| N/A 
| Q763: 'Generic number' IE - address signals with qualifier=Ported number 
| SIP:RequestURI - to user part when rn is present 
| rn is stored in the called number 
| 
|-
| ported_number_noa 
| N/A 
| N/A 
| Q763: 'Generic number' IE - nature of address indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number_npi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - numbering plan indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| oli
(Originating line information) 
| 5ESS Codeset 6 OLI - Value 
| N/A 
| ANSI: 'Originating line information' IE - OLI 
|
SIP:From - oli

SIP:P-asserted-identity - oli 

| 
| 
|-
| request_uri 
| N/A 
| N/A 
| N/A 
| Complete Request URI string 
| 
| 
|-
| request_uri_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default URI forwarding behavior from incoming to outgoing leg 
| 
|-
| sip_header 
| N/A 
| N/A 
| N/A 
| Any header 
| Requires option 'Forward custom headers' in Profiles->SIP 
| 2.7.63 
|-
| nap
(Network Access Point) 
| N/A 
| N/A 
| N/A 
| N/A 
| Incoming leg NAP name (read-only) 
| 
|-
| type_of_network_identification 
| Q931: 'Transit network selection' IE - Type of network identification 
| N/A 
| Q763: 'Transit network selection' IE - Type of network identification 
| N/A 
| 
| 2.7 
|-
| network_identification 
| Q931: 'Transit network selection' IE - Network identification 
| N/A 
| Q763: 'Transit network selection' IE - Network identification 
| SIP: Request-Line - cic 
| 
| 2.7 
|-
| network_identification_plan 
| Q931: 'Transit network selection' IE - Network identification plan 
| N/A 
| Q763: 'Transit network selection' IE - Network identification plan 
| N/A 
| 
| 2.7 
|-
| location_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default location number forwarding behavior from incoming to outgoing leg 
| 2.7 
|-
| location_number 
| N/A 
| N/A 
| Q763: 'Location number' IE - address signals 
| N/A 
| 
| 2.7 
|-
| location_number_noa 
| N/A 
| N/A 
| Q763: 'Location number' IE - nature of address indicator 
| N/A 
| 
| 2.7 
|-
| location_number_npi 
| N/A 
| N/A 
| Q763: 'Location number' IE - numbering plan indicator 
| N/A 
| 
| 2.7 
|-
| location_number_presentation 
| N/A 
| N/A 
| Q763: 'Location number' IE - presentation restricted indicator 
| N/A 
| 
| 2.7 
|-
| location_number_screening 
| N/A 
| N/A 
| Q763: 'Location number' IE - screening 
| N/A 
| 
| 2.7 
|-
| mlpp_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| A script needs to set this to true if it wants to overwrite MLPP information in the outgoing leg. Otherwise, profile relay 'outgoing mode' applies automatically. 
| 2.7 
|-
| mlpp_look_for_busy 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - look ahead for busy 
| N/A 
| 
| 2.7 
|-
| mlpp_precedence_level 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - precedence level 
| SIP:Resource-Priority - q735 
| 
| 2.7 
|-
| mlpp_network_identity 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - network identity 
| N/A 
| 
| 2.7 
|-
| mlpp_service_domain 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - MLPP service domain 
| N/A 
| 
| 2.7 
|-
| called_isub 
| Q931: 'Called party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub parameter 
| 
| 2.7 
|-
| called_isub_type 
| Q931: 'Called party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub-encoding parameter 
| 
| 2.7 
|-
| calling_isub 
| Q931: 'Calling party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub 
| 
| 2.7 
|-
| calling_isub_type 
| Q931: 'Callinf party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub-encoding 
| 
| 2.7 
|-
| ss7_fci_default 
| N/A 
| N/A 
| Default forward call indicator (FCI) value. 
| N/A 
| Toolpack will overwrite FCI bits A, D, F, I and M with appropriate values according to call conditions 
| 2.7 
|-
| ss7_fci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_fci_default that must be forced. 
| N/A 
| Bits from ss7_fci_default which corresponding bit in ss7_fci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| ss7_bci_default 
| N/A 
| N/A 
| Default backward call indicator (BCI) value. 
| N/A 
| Toolpack will overwrite BCI bits AB, I, K, M and N with appropriate values according to call conditions 
| 2.7 
|-
| ss7_bci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_bci_default that must be forced. 
| N/A 
| Bits from ss7_bci_default which corresponding bit in ss7_bci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| tdm_ls_name_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable line service and timeslot selection to create the outgoing leg 
| 3.0 
|-
| tdm_ls_name
(Line Service or T1/E1 trunk) 
| Incoming leg line service name 
| Incoming leg line service name 
| Incoming leg line service name 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this line service name to create outgoing leg 
| 2.7 
|-
| tdm_timeslot_nb 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this timeslot number to create outgoing leg 
| 2.7 
|-
| rtp_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP port 
| (read-only) 
| 2.7 
|-
| rtp_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP port 
| (read-only) 
| 2.7 
|-
| ss7_cot_enabled 
| N/A 
| N/A 
| Requests SS7 in-call continuity test for this outgoing SS7 call 
| N/A 
| Toolpack will request a continuity test on the timeslot before making the outgoing call. If COT fails, the call will be dropped (then another route may be attempted) 
| 2.8 
|-
| reverse_charging_indication 
| Incoming leg Reverse charging indication IE present 
| N/A 
| N/A 
| N/A 
| If set in routing script, will add Reverse charging indication IE in outgoing leg (also use reverse_charging_indication_forward_enabled) 
| 2.8.12 
|-
| reverse_charging_indication_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable forwarding of reverse charging indication from incoming to outgoing leg 
| 2.8.12 
|-
| sip_call_id 
| N/A 
| N/A 
| N/A 
| Incoming leg SIP Call-Id 
| (read-only) 
| 2.9.112 / 3.0.131 
|-
| sip_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP port 
| (read-only) 
| 2.8.13 
|-
| sip_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP port 
| (read-only) 
| 2.8.13 
|}

 

=== Noa values ===
The text below represents the value normally used by routing script. 
Incase it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 
Example numeric values for the SS7 protocol are shown in parenthesis. 
 
*<tt>unknown_number (0x2)</tt>
*<tt>international_number (0x4)</tt>
*<tt>national_number (0x3)</tt>
*<tt>subscriber_number (0x1)</tt>
*<tt>network_specific (0x5)</tt>
*<tt>network_routing_national_format (0x7)</tt>
*<tt>network_routing_international_format (0x8)</tt>
*<tt>abbreviated_number (0x6)</tt>
*<tt>subscriber_number_operator_requested (0x71)</tt>
*<tt>national_number_operator_requested (0x72)</tt>
*<tt>international_number_operator_requested (0x73)</tt>
*<tt>no_number_present_operator_requested (0x74)</tt>
*<tt>no_number_present_cut_through_call_to_carrier (0x75)</tt>
*<tt>test_line_test_code (0x77)</tt>
*<tt>non_unique_subscriber_number (0x71)</tt>
*<tt>non_unique_national_number (0x73)</tt>
*<tt>non_unique_international_number (0x74)</tt>
*<tt>call_950_numbe (0x76)</tt>
*<tt>special_number (0x73)</tt>
*<tt>national_number_with_transit_network_selection (0x74)</tt>
*<tt>international_number_with_transit_network_selection (0x75)</tt>

Those values will be remapped to the protocol specific NOA value. To provide protocol specific value:

*<tt>call_params[:called_noa] = 0x70</tt>

or

*<tt>call_params[:called_noa] = 112</tt>

=== Npi values ===

*<tt>unknown_number</tt>
*<tt>isdn</tt>
*<tt>telephony</tt>
*<tt>private</tt>
*<tt>data</tt>
*<tt>telex</tt>
*<tt>national</tt>

=== Calling Display Type values ===

*<tt>unspecified</tt> => Type is unspecified.
*<tt>calling_party_name</tt> => Type is 0xB1.

Those values will be remapped to the protocol specific Display Information Type value. To provide protocol specific value:

*<tt>call_params[:calling_display_type] = 0xB1</tt>

or

*<tt>call_params[:calling_display_type] = 177</tt>

=== Calling Display value ===

*<tt>call_params[:calling_display] = "Roger Fluffy"</tt>

=== Presentation values for Calling number, Calling Subscriber (Generic Number), Redirecting Number, Original Called Number (OCN) and Location Number ===
The text below represents the value normally used by routing script. 
Incase it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 
Example numeric values for the SS7 protocol are shown in parenthesis. 
 
*<tt>unspecified</tt>
*<tt>not_available (0x2)</tt>
*<tt>allowed (0x0)</tt>
*<tt>restricted (0x1)</tt>
*<tt>addr_restricted</tt>
*<tt>name_restricted</tt>

=== Calling Party Category ===
The text below represents the value normally used by routing script. 
In case it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 

Mapping from routing script to SS7/CAS R2/SIP
{| cellspacing="1" cellpadding="1" border="1"
|-
! scope="col" | '''Routing Script string '''
! scope="col" | '''SS7 raw value '''
! scope="col" | '''R2 CAS scripts''' 
! scope="col" | '''Default Rx CAS''' 
! scope="col" | '''default Tx CAS''' 
! scope="col" | '''SIP "cpc=" '''
|-
| subscriber 
| 0xa 
| CATEGORY_SUBSCRIBER 
| 1 and 7 
| 7 
| ordinary 
|-
| subscriber_with_priority 
| 0xb 
| CATEGORY_SUBSCRIBER_WITH_PRIORITY 
| 2 and 9 
| 2 
| priority 
|-
| operator_french 
| 0x1 
| CATEGORY_OPERATOR_FRENCH 
| 5 
| 5 
| operator 
|-
| operator_english 
| 0x2 
| CATEGORY_OPERATOR_ENGLISH (5) 
| 5 
| 5 
| operator 
|-
| operator_german 
| 0x3 
| CATEGORY_OPERATOR_GERMAN (5) 
| 5 
| 5 
| operator 
|-
| operator_russian 
| 0x4 
| CATEGORY_OPERATOR_RUSSIAN (5) 
| 5 
| 5 
| operator 
|-
| operator_spanish 
| 0x5 
| CATEGORY_OPERATOR_SPANISH (5) 
| 5 
| 5 
| operator 
|-
| data 
| 0xc 
| CATEGORY_DATA 
| 6 and 8 
| 6 
| datacall 
|-
| test 
| 0xd 
| CATEGORY_TEST 
| 3 
| 3 
| test 
|-
| payphone 
| 0xf 
| CATEGORY_PAYPHONE 
| none 
| 7 
| payphone 
|-
| unknown 
| 0x0 
| CATEGORY_UNKNOWN 
| 4, 11 to 15 
| 7 
| unknown 
|-
| unspecified 
| 0xa 
| invalid 
| none 
| none 
| invalid 
|}
[[CAS_R2_scripting#Category_meanings|Link to calling party categories used in CAS R2 scripts]]

=== Screening values for Calling number, Calling Subscriber (Generic Number), and Location Number ===
The text below represents the value normally used by routing script. 
Incase it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 
Example numeric values for the SS7 protocol are shown in parenthesis. 
 
*<tt>unspecified</tt>
*<tt>no (0x0)</tt>
*<tt>pass (0x1)</tt>
*<tt>fail (0x2)</tt>
*<tt>network_provided (0x3)</tt>

=== Redirecting indicator values ===

SS7:

*<tt>no_redirection</tt>
*<tt>call_rerouted</tt>
*<tt>call_rerouted_all_restricted</tt>
*<tt>call_diverted</tt>
*<tt>call_diverted_all_restricted</tt>
*<tt>call_rerouted_restricted</tt>
*<tt>call_diverted_restricted</tt>
*<tt>spare</tt>

=== Redirecting number, Original Called Number and Diversion Reason ===

ISDN:

*<tt>unknown</tt>
*<tt>busy</tt>
*<tt>no_reply</tt>
*<tt>deflection</tt>
*<tt>dte_out_of_order</tt>
*<tt>forwarding_by_called_dte</tt>
*<tt>unconditional</tt>

SS7:

*<tt>unknown</tt>
*<tt>busy (SIP: user-busy)</tt>
*<tt>no_reply (SIP: no-answer)</tt>
*<tt>unconditional</tt>
*<tt>deflection</tt>
*<tt>deflection_immediate</tt>
*<tt>mobile_not_reachable</tt>

=== OLI (originating line information) values ===

The OLI parameter is a string that represents an integer value from 0 to 255.

=== Information Transfer Capability values ===

information_transfer_capability:

*<tt>digital</tt>
*<tt>restricted_digital</tt>
*<tt>digital_with_tones</tt>
*<tt>speech</tt>
*<tt>3_1_khz_audio</tt>
*<tt>video</tt>

=== redirecting_number_forward_enabled values ===

Controls forwarding or discarding of redirecting number (SIP: diversion header) to the outgoing call leg.

Values for this parameter are "0", "1", "false" or "true.
*0/false: Redirecting number (and original called number) is not forwarded to outgoing call leg
*1/true: Redirecting number (and original called number) is forwarded to outgoing call leg

The value for this parameter at the input of the routing script depends on the "Forward redirecting number" parameter in the "Advanced" section of the Gateway configuration page of the Web Portal. The script may change this value to override the Gateway configuration.

Note: To "insert" a new redirecting number value on the outgoing leg, redirecting_number_forward_enabled must also be set to true.

=== request_uri ===

Enables access to the Request-Line URI. 

For example, if the Request-Line is:
<pre>Request-Line: INVITE sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0</pre>
Then the retrieved request_uri will be "sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0". 

In the routing scripts, to retrieve only the called number, this script can be used: 
<pre> if call_params[:request_uri] && call_params[:request_uri] =~ /sip:(.*)@.*/
call_params[:called] = $1
end
</pre>
==== request_uri_forward_enabled ====

This call parameter controls forwarding or discarding of request uri to outgoing call leg.The request uri is the information in the "Request-Line:" of the SIP INVITE message. 

Values for this parameter are "0", "1", "false" or "true. 

* 0/false: Request uri is not forwarded to outgoing call leg 

* 1/true: Request uri is forwarded to outgoing call leg 

The default value for this parameters is false. 

==== sip_scheme ====
(Available in Toolpack 3.1+)
This call parameters indicates the scheme (generally "sip" or "sips") of the incoming call.

This also allows to control the scheme used for the outgoing call (regardless if request_uri_forward_enabled is used or not)

Note: sips scheme must only be used on TLS NAPs (will cause call routing failure if NAP has only UDP or TCP transport types).

=== sip_header values ===
Contains custom sip headers from the inbound call leg. Any custom sip header can be added to an outgoing call leg: 

'''Note:'''

The SIP header is in string format.

'''string format:'''
<pre>call[ :sip_header ] = "P-my-custom-header:value1 \nP-my-custom-header2:value2 \nP-my-custom-header3:value3"
</pre>
(Note: \n above are actual newline characters, not '\' followed by 'n')

* PCAP sample: [[File:TB_Custom_SIP_Headers.pcap]]

List of sip headers that will not appear in call[:sip_header] since they are already processed by the SIP stack:
<pre>
Accept Error-Info Remote-Party-ID
Accept-Contact Event Replaces
Accept-Encoding Expires Reply-To
Accept-Language From Request-Disposition
Alert-Info In-Reply-To Subject
Allow Max-Forwards Subscription-State
Allow-Events MIME-version Supported
Also Min-Expires Timestamp
Anonymity Min-SE To
Authorization Organization Unsupported
Authentication-Info Path User-Agent
Call-ID Priority Via
Call-Info Privacy Warning
Contact Proxy-Authenticate WWW-Authenticate
Content-Disposition Proxy-Authorization Require
Content-Encoding Proxy-Require Response-Key
Content-Language P-Media-Authorization Retry-After
Content-Length P-Preferred-Identity RPID-Privacy
Content-Type P-Asserted-Identity Route
CSeq RAck RSeq
RAck Reason Security-Client
Reason Record-Route Security-Server
Date Refer-To Security-Verify
Diversion Referred-By Server
Encryption Reject-Contact Service-Route
Session-Expires
</pre>

=== sip header parameters ===
The routing script can read (and modify) some SIP header parameters (user parameters, URI parameters or header parameters) from some SIP headers (To, From, P-Asserted-Identity, Remote-Party-ID, Contact).

==== Available parameters ====
* '''call[ :calling_parameters ]''' (SIP "From" header)
* '''call[ :called_parameters ]''' (SIP "To" header)
* '''call[ :private_address_parameters ]''' (SIP "P-Asserted-Identity" or "Remote-Party-ID" header)
* '''call[ :contact_parameters ]''' (SIP "Contact" header)

These parameters (if present) contain a hash with 3 keys: user_param, uri_param and header_param.
Each of this key points to a string that contains all the parameters found in the corresponding SIP header.
* '''User parameters''' (parameters between the user name/number and the host). Example <sip:alice;'''param=value'''@somewhere.com>
* '''URI parameters''' (parameters at the end of the URI). Example <sip:alice@somewhere.com;'''param=value'''>
* '''Header parameters''' (outside the URI). Example <sip:alice@somewhere.com>;'''param=value'''
Example to print all parameters of SIP "To" header:
call[ :called_parameters ].inspect -> '{ :user_param => "name1=value1;name2=value2", :uri_param => "name=value", :header_param => "name=value;example_param_without_value" }'
Example to modify (replace) the URI parameters of SIP "To" header:
call[ :called_parameters ][ :uri_param ] = "user=phone"

==== Exceptions ====
'''Note:''' Some parameters are reported as their own call attribute (oli, isub, cpc, transport) so they have the same representation for all protocols (SS7, IDSN, SIP). They won't appear present in the generic SIP header parameters structures above.

==== Forwarding from inbound to outbound call ====

==== Legacy behavior ====
(For base_routing version 1.32 or older)
By default, the parameters are not forwarded in a SIP to SIP call flow. The parameters '''will be forwarded''' when:
* accessed (read) from either the inbound or outbound call parameters
* written in either the inbound or outbound call parameters

==== Current behavior ====
(For Toolpack 3.0.118+, with base_routing version 1.33+)
SIP headers host and parameters are forwarded by default.

A route attribute "forward_sip_domain" (along with filter script "forward_sip_domain.rb") will control, per route, if SIP headers host+parameters must be forwarded.

==== Example usage ====
Example to print the user parameters:
<pre>
if call[:calling_parameters]
puts "user parameters = #{call[:calling_parameters][:user_param].inspect}"
end
</pre>

Example SIP "From" header:
From:<sip:123456782;test1=val1;test2=val2@something.com;test3=val3;test4=val4>;test5=val5;test6=val6
And the resulting content in the routing script:
call[:calling_parameters].inspect -> {:user_param=>"test1=val1;test2=val2", :uri_param=>"test3=val3;test4=val4", :header_param=>"test5=val5;test6=val6"}

'''Note''' that printing the inbound or outbound call parameters is considered as a "read" action and would result in forwarding the parameter on the outbound leg.

Example to overwrite inbound leg calling parameters with new parameters for the outbound leg:
<pre>
call [:calling_parameters] = {
:user_param => "user_param7=7;user_param8=8",
:uri_param => "uri_param9=value9",
:header_param => "header_paramA=A" }
</pre>

Example to add user=phone and keep all other uri parameters.
<pre>
call[:calling_parameters] ||= {} # Create a hash if not already present
call[:calling_parameters][:uri_param] ||= "" # Create a string if not already present
call[:calling_parameters][:uri_param] += ";" if call[:calling_parameters][:uri_param] != ""
call[:calling_parameters][:uri_param] += "user=phone"
</pre>

=== MLPP Precedence values ===

mlpp_look_for_busy:

*<tt>allowed</tt>
*<tt>path_reserved</tt>
*<tt>not_allowed</tt>

mlpp_precedence_level:

*<tt>flash_override</tt>
*<tt>flash</tt>
*<tt>immediate</tt>
*<tt>priority</tt>
*<tt>routine</tt>

mlpp_network_identity:

3 digits value from 0 to 999

mlpp_service_domain:

24 bits value from 0 to 16777215

=== ISUB subaddress information values ===

called_isub_type:
calling_isub_type:

*<tt>nsap</tt>
*<tt>nsap_ia5</tt>
*<tt>nsap_bcd</tt>
*<tt>user</tt>

called_isub:
calling_isub:

Digits for the subaddress information.

=== Network Identification Plan ===

network_identification_plan:

*<tt>Unknown</tt> (value 0)
*<tt>cic</tt> (3 digits carrier identification code plus circuit code, value 1, SS7 or ISDN)
*<tt>user</tt> (User, value 2, ISDN only)
*<tt>cic4</tt> (4 digits carrier identification code plus circuit code, value 2, SS7 only)
*<tt>dnic</tt> (public Data Network ID, value 3, SS7 only)
*<tt>mnic</tt> (public land mobile network, value 6, SS7 only)

=== Registered Users Information ===
Routing script can access information about registered users (when either the calling or called user is a known registered user).
When these fields are empty, it means that the calling/called (SIP from/to) does not correspond to a known registered user (routing script may still decide to route the call based on static routes).

Information for the called user:
params[:registered_user]
Information for the calling user:
params[:calling_registered_user]

These parameters are a hash of key/values that provide information about the contact.
{
:contact_list=>
[
{
:contact=>"<sip:user_name_or_number@hostname:7070;transport=UDP>", -> Full contact
:expires=>"60", -> Contact expiry time (seconds)
:host=>"hostname", -> host name from the contact header
:name=>"user_name_or_number", -> user name from the contact header
:nap_in=>"NAP_NAME", -> NAP that the contact has registered from
:port=>"7070", -> Port from the contact header
:transport=>"UDP" -> Transport type from the contact header
:q_value=>"0.00", -> Q-value for the contact (for contact ordering)
:src_host=>"10.0.0.10", -> Actual source IP address that the contact has registered from
:src_port=>"7070", -> Actual source port that the contact has registered from
:src_transport=>"UDP", -> Actual protocol that the contact has been registering with
}
]
}

== Route parameters ==

All route may have these parameters:

*calling
*called
*nap
*remapped_calling
*remapped_called
*remapped_nap
*remapped_destination_leg_profile (called remapped_profile prior to Toolpack 2.9)
*remapped_source_leg_profile (called remapped_incoming_profile prior to Toolpack 2.9)

Example:

route[:remapped_nap]

Additionally it is possible to add dynamic route attributes in the web portal. These can be referenced by their name.
For example:
*priority
*weight

== Routing calls toward registered users ==
Static routes normally chose an outbound NAP to forward the call to.

But it's also possible to create routes which outbound NAP is dynamically chosen by matching a registered user (when using [[Sip_registration_forwarding|SIP registration forwarding]]).

More information can be found [[Sip_registration_forwarding#SIP_Calls_routing|here]] about the way to control the [[Sip_registration_forwarding#SIP_Calls_routing|priority of "dynamic" vs "static" routes]].

More information can be found [[#Registered_Users_Information|here]] about using routing scripts to access registered users information during call routing.

== Playing prompts announcements or tones ==

New feature in release 2.6, all bridges may have these parameters. These can be used to play IVR prompts (audio files) in different states of the call flow.

*'''announcement_tone''' (played before outgoing call is routed)
*'''ring_tone''' (played after when waiting for outgoing call to answer)
*'''busy_tone''' (played if outgoing call failed)
*'''disconnect_tone''' (played after the call has reached it's maximum duration)

Example to play an announcement to incoming call (before routing outgoing call, regardless if a matching route is found or not):
bridge[:announcement_tone ] = "my_announcement.wav"

Example to play a ring-tone while the outgoing call is ringing:
bridge[:ring_tone] = "my_ring_tone.wav"

Example to play an audio file when outgoing call fails (no route, or outgoing call is refused):
bridge[:busy_tone] = "my_busy_tone.wav"

Example to play an audio file when call has reached the maximum allowed duration:
bridge[:disconnect_tone] = "your_account_balance_is_empty.wav"

=== Announcement file path format and options ===

All file plabyacks (:announcement_tone, :busy_tone, :ring_tone, :disconnect_tone) inside bridge parameters use this format.
<pre>"file1.wav:repeat:start_off:end_off,file2.wav:repeat:start_off:end_off,file3.wav:repeat:start_off:end_off"
</pre>
Optional parameters:
* repeat: number of times to play the file (0 and 1 have the same result)
* start_off: Start offset in milliseconds
* end_off: End offset in milliseconds

Http and other path formats are described here: [[Customer_application_framework:play_audio_files#Play_path_format|Path format]]

==== Example 1 ====
The following example will play file1.wav once, and then play file2.wav in loop:
"file1.wav,file2.wav:-1"

==== Example 2 ====
The following example will play file1.wav from start offset of 1 second to end offset of 3 seconds, then twice file2.wav from second 5 to second 10.
"file1.wav:0:1000:3000,file2.wav:2:5000:10000"

==== Example 3 ====
The following example will play file1.wav once, ending at offset of 30 seconds.
"file1.wav:0:0:30000"

=== announcement_tone ===

params[:bridge][:announcement_tone] = "announcement.wav"

Audio file played on the incoming call before any outgoing call is placed. The outgoing call occurs when the file finished playing.

==== announcement_tone options ====
===== announcement_tone_answer =====
params[:bridge][:announcement_tone_answer] = "yes"

Forces an answer of the call before playing the announcement. Default if argument not provided is "no", in which case call is only alerted with in-band media.

===== announcement_code_detect =====
This option allows that the tone detection is enabled during the announcement play.

Collected digits can be inserted into the CDR logs (radius attribute "Telcob-CollectedDigits", or text CDR variable @{CollectedDigits}).

Collected digits can also be sent back to routing script, which is called again with the same call attributes, except that the called number is replaced by the collected digits.

Code detect has multiple options, as shown in the following code:
code_detect = {
:type => :DTMF, # :DTMF or :MFR1 tone detection.
# Default is MFR1.
:prefix => "", # Prefix (digits) that is removed from collected digits.
# Default is empty.
:suffix => "", # Suffix (digits) that is removed from collected digits
# and causes routing script to be immediately called.
# Default is empty.
:suffix_removal => false, # Controls the removal of the suffix from the collected digit string that's reported to routing script.
# Default is false
:timeout => 0, # Inter-digit timeout (ms) after which collected digits are passed to the routing script.
# Use 0 for "no timeout".
# Default is 1000ms
:barge_in_interruption => true, # When enabled, playing announcement is stopped as soon as first digit is collected.
# Default is true.
:proceed_on_play_done => false, # When true: Outgoing call is made after announcement finishes playing.
# Routing script is not called again.
# When false: Outgoing call is never made.
# Digits are collected until timeout or suffix match,
# then routing script is called again.
# Default is false.
:cas_on_hook => false, # Specific for CAS-R1 calls. Makes CAS bits switch to "on-hook" when announcement finished playing
# (but the call is not "terminated" from Toolpack point of view)
# Default is false.
:cas_on_hook_delay => 0, # Duration of cas bits "on-hook" state.
# Only effective if cas_on_hook is set to true.
# Value of 0 stands for "infinite delay".
# Default is 0.
:repeat_delay => 0, # Delay between repetition of the announcement. The announcement will repeat
# itself every "repeat_delay" until a code is detected (suffix match or timetout).
# Value of 0 stands for "infinite delay" (no repeating).
# Default is 0.
}
'''Example 1''': Collect DTMF digits, and call routing script again with collected digits upon timeout or suffix match.
code_detect = { :type => :DTMF, :suffix => "#", :timeout => 5000 }
params[:bridge][:announcement_code_detect] = code_detect

'''Example 2''': Collect digits during the announcement (for CDR logs), then proceed (make outgoing call) after announcement finishes playing
code_detect = { :type => :DTMF, :timeout => 0, :barge_in_interruption => false, :proceed_on_play_done => true }
params[:bridge][:announcement_code_detect] = code_detect

==== Controlling what happens after announcement ====
The routing script can control what happens with the call after the announcement finishes playing:
* An outgoing call is made
* Incoming call is hung-up
* Do nothing (wait for the incoming call to hang-up)
===== An outgoing call is made =====
This happens when the script has returned matching routes (and did not raise RoutingException)

===== Incoming call is hung-up =====
This happens when the script returns no routes (in which case base_routing will raise RoutingException with cause :no_route).

It also happens when the script explicitly raises RoutingException.

The incoming call will be terminated with the specified cause.
For example
raise RoutingException, :temporary_failure
(See "Reason values" section in this page for list of available causes)

===== Do nothing (wait for the incoming call to hang-up) =====
If a filter raises RoutingException with code :ok, then the incoming call will not be terminated at the end of the announcement play.
Announcement digit collection will remain active if appropriate.
For example:
raise RoutingException, :ok

=== ring_tone ===
params[:bridge][:ring_tone] = "ringing.wav"

Audio file played on the incoming call while waiting for the outgoing call to be answered.

Ring tone playback can also be configured in the Web Portal, from the incoming call's profile (under "Tones and Call Progress Options").

Routing script has precedence over profile (a routing script that fills params[:bridge][:ring_tone] will override the profile's ring tone behavior).

==== ring_tone options ====
===== ring_tone_state =====
params[:bridge][:ring_tone_state] = :alerted

Call state from which ring tone is being played. Available values are:
* '''immediately''': Ring tone starts playing immediately on the incoming leg
* '''accepted''': Ring tone starts playing as soon as outgoing call is accepted
* '''callprogress''': Ring tone starts playing as soon as "call progress" is received on the outgoing call
* '''alerted''' (default): Ring tone starts playing only once outgoing call is alerted (but won't play if alert indicates early media from outgoing call)

This option also apply when params[:bridge][:ring_tone] is not used, because it also apply to ring tone playback configured in the Web Portal, from the incoming call's profile.

=== busy_tone ===
Toolpack 2.8 and above:
params[:bridge][:busy_tone] = "no_route.wav"

Note: Obsolete name (toolpack 2.7.153 and earlier, but still supported in recent releases):
params[:bridge][:call_progress_tone] = "no_route.wav"

Audio file played on the incoming call when outgoing call fails (never answered).

Note that announcement_tone, if used, is played before the outgoing call attempt is made, and thus before the busy_tone.

Busy tone playback can also be configured in the Web Portal, from the incoming call's profile (under "Tones and Call Progress Options").

Routing script has precedence over profile (a routing script that fills params[:bridge][:busy_tone] will override the profile's busy tone behavior).

Special value '''"none"''' can be used by routing script to force playing nothing (as empty string would default to profile's behavior)

==== busy_tone options ====
===== busy_tone_answer =====
params[:bridge][:busy_tone_answer] = "yes"

Forces an answer of the call before playing the busy tone. Default if argument not provided is "no", in which case call is only alerted with in-band media.

=== disconnect_tone ===
params[:bridge][:disconnect_tone] = "max_duration.wav"

Audio file played on the incoming call when call duration (:max_call_duration) is reached. Then the leg will be terminated with specified reason (:call_duration_reason).

==== disconnect_tone options ====
===== max_call_duration =====
params[:bridge][:max_call_duration] = "60000"

Maximum call duration in millisecond. This timer is started when entering answer state.

===== call_duration_reason =====
params[:bridge][:call_duration_reason] = :resource_unavailable

Drop both legs with this reason when call duration (:max_call_duration) is reached.

=== Managing audio prompts through Web Portal ===
Audio prompts can be uploaded or deleted from the TMedia unit through the Web Portal:
[[Toolpack:Configuring_Audio_Prompts_A|Managing audio prompts]]

Prompts management must be done using the Web Portal of the primary server (in systems with redundant TMedia units or redundant host servers).
The file will automatically get replicated to the secondary server.

=== Managing audio prompts manually ===
Any file on the TMedia host file system can be played. This means it's possible to manage prompts through ssh/scp.

==== The default (replicated) prompts folder ====
By default, when playing a prompt, Toolpack will look in the default prompts folder:
/lib/tb/toolpack/pkg/prompts
The root of this "prompts" directory is automatically replicated to secondary unit of redundant setups (1+1, N+1, redundant hosts). Sub-folders won't be replicated.

Any prompt play request without explicit file path will map to this folder. For example:
params[:bridge][:busy_tone] = "no_route.wav"
This will correspond to file /lib/tb/toolpack/pkg/prompts/no_route.wav

==== Relative file paths ====
Any file path that begins with "file://" is considered relative to the tbstreamserver application's working directory:
/lib/tb/toolpack/setup/12358/2.8/apps/tbstreamserver/
(Where "2.8" may be replaced by the current major version of your system)

For example:
params[:bridge][:busy_tone] = "file://my_folder/no_route.wav"
This will correspond to file /lib/tb/toolpack/setup/12358/2.8/apps/tbstreamserver/my_folder/no_route.wav

==== Absolute file paths ====
Absolute paths can also be provided.
For example:
params[:bridge][:busy_tone] = "file:///root/my_folder/no_route.wav"
This will correspond to file /root/my_folder/no_route.wav

== Recording call legs ==
Introduced in release 2.6.44, it's now possible to use routing scripts to ask for recording incoming and/or outgoing call legs.

See example filter script "call_recording" (created by default in Web Portal routing scripts starting with 2.6.44) for an example.

=== Recording the incoming call leg ===
To record the incoming call leg, the routing script (in a "after filter" for example) has to set the following parameter:

bridge[ :record_incoming ] = ""

=== Recording the outgoing call leg ===
To record the outgoing call leg, the routing script (in a "after filter" for example) has to set the following parameter, per route (the decision to record or not, or the file name to record to, can be set per matching route):

# Need to clone the routes in order to have the right to modify them
routes = clone_routes params[:routes]
routes.each do |route|
route[ :record_outgoing ] = ""
end
# Store modified routes back to the parameters for this outgoing call
params[:routes] = routes

=== Record the outgoing call leg within incoming leg's recorded file (mixing) ===
[...]
route[ :record_outgoing ] = "@{MixWithIncoming}"
[...]

=== Choosing file path to record to ===
The value assigned to ":record_incoming" or ":record_outgoing" is the path to record the file to.

The paths can be absolute, or relative. When relative, they are relative to the "tbstreamserver" application working directory, for example:
/lib/tb/toolpack/setup/12358/2.7/apps/tbstreamserver/

* Empty file name will default to a name that contains various information about the call:
** ''LinkId'': Id common between all legs of this call bridge
** ''LegId'': Unique Id for this leg
** ''Nap'': Current NAP name this call leg is from
** ''Direction'': "IN" or "OUT" (depends if call leg is incoming or outgoing leg)
** ''Calling'': The calling number of this call leg
** ''Called'': The called number of this call leg
** ''Protocol'': The signaling protocol of this call leg (SS7, ISDN, CAS, SIP)
** ''Media info'': Codec + IP/Port for SIP calls, Trunk/Timeslot for TDM calls
* To record outgoing call leg in the same audio file as incoming call leg (mixing), use the following:
** @{MixWithIncoming}: Record outgoing legs in same file as incoming legs
* Variables can be used to insert in the recording path information that's not already available from routing scripts:
** @{CURRENT_PKG}: Version of current package
*** Example: 2.6.45
** @{DATE format}: Prints the date, where 'format' is expressed as described for the 'strftime' function
*** Example: @{DATE %Y-%m-%d} => 2013-01-28
** @{DefaultName}: Replaced by the default file name for recording, which contains:
*** LinkId: Id common between all legs of this call bridge
*** LegId: Unique Id for this leg
*** Nap: Current NAP name this call leg is from
*** Direction: "IN" or "OUT" (depends if call leg is incoming or outgoing leg)
*** Calling: Calling number
*** Called: Called number
*** Protocol: Protocol type of this call (SS7, ISDN, CASR2, SIP)
*** Media info: Codec + IP/Port for SIP calls, Trunk/Timeslot for TDM calls
*** Example: "73EBA698-F3D67B4B-NAP_SS7-IN-5550000-5550001-SS7-TRUNK_BELL_11-24.wav"
*** Example: "73EBA698-73EBA698-NAP_SIP-OUT-5550000-5550001-SIP-G723-10.3.10.101-1050.wav"
** @{DefaultPath}: Default recording folder and file name: "@{RECORD_PATH}/@{DATE %Y-%m-%d}/@{DefaultName}"
*** Example: "/lib/tb/toolpack/setup/12358/recorded_calls/73EBA698-F3D67B4B-NAP_SS7-IN-5550000-5550001-SS7-TRUNK_BELL_11-24.wav"
*** Example: "/lib/tb/toolpack/setup/12358/recorded_calls/73EBA698-73EBA698-NAP_SIP-OUT-5550000-5550001-SIP-G723-10.3.10.101-1050.wav"
** @{Direction}: Direction of current leg (IN our OUT)
*** Example: IN
** @{LegId}: Current LegId (Unique Id for this leg)
*** Example: F3D67B4B
** @{LinkId}: Current LinkId (Id common between all legs of this call bridge)
*** Example: 73EBA698
** @{PKG_HOME}: Path where packages are stored.
*** Note: It's not recomended to use that path on redundant systems, package file replication may cause confusion in recorded files.
*** Example: /lib/tb/toolpack/pkg
** @{PROMPT_PATH}: Default path where audio prompts are stored
*** Note: It's not recomended to use that path on redundant systems, package file replication may cause confusion in recorded files.
*** Example: /lib/tb/toolpack/pkg/prompts
** @{Protocol}: Protocol of current leg
*** Example: SS7
** @{RECORD_PATH}: Default recording folder: "@{TB_SETUP_HOME}/recorded_calls/"
** @{TBX_GW_PORT}: Current "System Id" (also called "Gateway Port")
*** Example: 12358
** And all variables listed here: [[Customer_application_framework:play_audio_files#Helpful_variables_to_build_play_or_record_file_paths|Building play or record file path]]

== Controlling UUI (user-to-user information) relay ==
UUI (user-to-user information) can be present in different messages received by either call leg during a call. For example, information can be carried during the initial invite, other information can be carried when the call is alerted, answered, or terminated.

Routing scripts can control if the UUI received from one leg through the call will be forwarded to the other call leg:
*uui_forward_enabled

Routing scripts can also read and modify the UUI received with the incoming call leg, before it gets forwarded upon creation of the outgoing call leg:
*uui

=== UUI (user-to-user indication) values ===

Byte array represented as ruby String. Use ''bridge=params[:bridge]'', then ''bridge[:uui]'' to access the data.

To access the bytes in Ruby, use ruby String operator []. For example: bridge[:uui][0] will return the binary value of the first UUI byte.

Function each_byte can also be useful to iterate through all bytes of the UUI.

=== uui_forward_enabled values ===

Controls forwarding or discarding of UUI to outgoing call leg.

Values for this parameter are "0", "1", "false" or "true.
* 0/false: UUI is not forwarded between call legs
* 1/true: UUI is forwarded between call legs

The value for this parameter at input of routing script depends on the "Forward UUI" parameter in the "Advanced" section of the Gateway configuration page of the Web Portal. The script may change this value to override the Gateway configuration.

== Authorization ==
Starting with release 2.7, it is possible to issue RADIUS authorization requests from routing scripts. To do so, the params[:authorization] object must be filled with the required RADIUS attributes and [[#Refuse|an exception must be raised]] with reason :authorization_required.

When the authorization is completed, the routing script is called again with the result. The params[:authorization] object will be filled with the RADIUS attributes from the response. The params[:authorization][:result] field will also contain a string indicating the result of the authorization:

* ''accept'': The authorization was successful.
* ''reject'': The authorization was refused.
* ''challenge'': The authorization was challenged.
* ''timeout'': The authorization was not answered.

== Call diversion options ==
It's possible to control the call flow when a call diversion information is received in the alerting state.

Two fields are available: bridge[ :diversion ] and bridge[ :diversion_reason ]

The internal release cause TOOLPACK_DIVERT_NOT_ALLOWED is used by gateway application to terminate both legs.

bridge[ :diversion ] = :allowed
The alert message will not be analyzed and the call will be progressed. Default behavior.
bridge[ :diversion ] = :not_allowed
If the alert message indicates that the call is diverted, the call will be released no matter the In-band information to allow
early media.
bridge[ :diversion ] = :not_allowed_w_early_media
The call will be released If the alert message indicates that the call is diverted with in-band information to allow early media.
bridge[ :diversion_reason ] = "*"
If the diversion is not allowed, the gateway will drop the call for any redirecting reason.
bridge[ :diversion_reason ] = "0,1,2"
or
bridge[ :diversion_reason ] = "unknown,busy,no_reply"
If the diversion is not allowed, the redirecting reason will be analyzed and the call will only be dropped for the configured cases.

See section [[Routing_script_tutorial:Mini_Development_Guide#Redirecting_number,_Original_Called_Number_and_Diversion_Reason|Redirecting number reason values]].

== Call transfer requests ==
Toolpack allows that [[Call transfer]] requests are relayed from one leg to the other, or to process them locally (making another outgoing call to replace the call that requested the call transfer).

If the chosen [[Call transfer]] mode is to process requests locally, upon reception of a call transfer request (SIP REFER or ISDN Facility), routing script will be called once again, to select the routes for the new outgoing call (call transfer target).

=== How to route call transfer request ===
Routing of a call transfer request is done exactly like routing of a normal incoming call.
The routing script generally does not need any modification to support that.

In some cases, the routing script may want to use information related to the transfer request to perform routing, or to insert information in the outgoing call leg.
Additional information is provided to the routing script, allowing routing decisions using information from the call transfer request (SIP REFER or ISDN Facility).
See below...

=== params[ :call ] content during transfer request ===
When processing a call transfer request, the params[ :call ] hash contains the information from the inbound call (same as was passed to the routing script upon arrival of the inbound call)
call = params[ :call ] -> Information from original inbound call, with exception of call[ :called ]

One exception (convenient because it allows a unmodified routing script to process call transfer request the same way as any other routing request):
call[ :called ] -> Replaced by the called number from the call transfer request (also called "redirection number")
Complementary information:
call[ :original_called_number ] -> Contains the called number that was initially received from the incoming call, prior to call transfer request
call[ :redirecting_number ] -> Number of the call from which the call transfer request was received (generally equals to original_called_number)

These fields will also be included in the outgoing call made after routing:
* original called number and redirecting number are existing fields on SS7 and ISDN calls
* SIP "diversion" header is used for SIP calls

=== params[ :transfer ] content ===
(this if valid only for release 2.7.102 and above) 
When processing a call transfer request, information from the call transfer request message (SIP REFER, ISDN Facility) is provided in params[ :transfer ]:
transfer = params[ :transfer ]
The following field is always present:
transfer[ :original_nap ] -> Contains the NAP of the first call from which a call transfer request was received
transfer[ :redirecting_nap ] -> Contains the NAP of the call from which the current call transfer request was received
(same as :original_nap for the first call transfer, different for subsequent transfers)
Examples of other fields that may be present, when appropriate:
transfer[ :uui ] -> The UUI (user-to-user information) found in the call transfer request
transfer[ :sip_header ] -> Contains custom SIP headers from the call transfer request
transfer[ :request_uri ] -> Contains the SIP Request URI

These fields are 'read-only'. They will not be included in the outgoing call, as they represent the contents of the call transfer request, and not the outgoing call to be made.

To insert/modify attributes of the outgoing call, the parameters from params[ :call ] must be edited instead.

== Redirection ==
In release 2.8 and above, redirection contacts are obtained from the routing engine in the following format:

contacts = params[ :contacts ]
contacts = {
:index=>"3",
:list=>[
{:called_number=>"6660", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"", :raw_data=>"", :expiration=>"3600"},
{:called_number=>"6661", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6661@192.168.215.127", :raw_data=>"<sip:6661@192.168.215.127>", :expiration=>"3600"}
{:called_number=>"6662", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6662@192.168.215.128", :raw_data=>"<sip:6662@192.168.215.128>", :expiration=>"3600"},
{:called_number=>"6663", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6663@192.168.215.129", :raw_data=>"<sip:6663@192.168.215.129>", :expiration=>"3600"},
{:called_number=>"6664", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6664@192.168.215.150", :raw_data=>"<sip:6664@192.168.215.150>", :expiration=>"3600"}
],
:source_indexes=>"nil,0,0,0,2"
}

* <code>params[:contacts][:list]</code> contains the contact log. Each contact within the list has the following fields:
** <code>:called_number</code> - the called number
** <code>:is_number_ported</code> - if the called number has been ported (for SIP: if the npdi parameter is present)
** <code>:ported_number</code> - the called number that was ported (for SIP: the rn parameter value, if available)
** <code>:sip_uri</code> - the SIP URI of the contact, without the contact-params section (without the expires and q contact parameters)
** <code>:raw_data</code> - the raw data representing the contact in the signaling protocol. For SIP, this is the full SIP URI (including the expires and q contact parameters).
** <code>:priority</code> - the priority of the contact [0-1000]
** <code>:expiration</code> - the expiration time in seconds of the contact
* <code>params[:contacts][:index]</code> contains the index of the contact that is currently being routed.
* <code>params[:contacts][:source_indexes]</code> contains a comma-separated list of indexes from <code>params[:contacts][:list]</code>. Each index represents the contact from which the contact in the list was obtained from.

To get more information, see:
*[[Routing_script_tutorial:SIP_Redirection_Contacts|SIP Redirection Contacts Parameters in a Call Flow]]

== Connected number ==
Insert a connected number in the answer message of the call flow.

Routing script example:
bridge = params[ :bridge ]
bridge [ :connected_number ] = "3335577"
bridge [ :connected_number_noa ] = :national_number
bridge [ :connected_number_npi ] = :private
bridge [ :connected_number_presentation ] = :allowed
bridge [ :connected_number_screening ] = :pass

== Terminating calls ==
In release 2.8, it is now possible to terminate a call through the routing scripts. The [[#Reason values|reason code]] must be specified in <code>params[:bridge][:reason]</code>. The <code>:terminate</code> hash must be created and copied into <code>params</code>:
terminate = {}
params[:terminate] = terminate
The following fields can then be set in <code>:terminate</code>:
* <code>:sip_header</code>
* <code>:contacts</code> # list of contacts as described in the [[#Redirection|redirection]] section
* <code>:isup_raw</code>
* <code>:isup_raw_variant</code>
* <code>:redirecting_number</code>
* <code>:redirecting_number_noa</code>
* <code>:redirecting_number_npi</code>
* <code>:redirecting_number_presentation</code>
* <code>:redirecting_number_reason</code>
* <code>:redirecting_number_counter</code>
* <code>:redirecting_number_indicator</code>
* <code>:original_called_number</code>
* <code>:original_called_number_noa</code>
* <code>:original_called_number_npi</code>
* <code>:original_called_number_presentation</code>
* <code>:original_called_number_reason</code>
* <code>:original_called_number_counter</code>

== Reason values ==

Check here for Termination Reason Cause codes: 

[[Termination_cause_codes|Termination Reason Cause codes]]
 

Example to refuse an incoming call leg.
raise RoutingException, :no_route

Reason cause strings available inside routing scripts:

List of Q.850 reason causes:
:unallocated_number
:no_route_to_network
:no_route_to_destination
:send_special_tone
:misdialled_trunk_prefix
:channel_unacceptable
:call_awarded_in_established_channel
:preemption
:reattempt
:qor_ported_number
:normal_call_clearing
:user_busy
:no_user_responding
:no_answer_from_user
:subscriber_absent
:call_rejected
:number_changed
:redirection
:exchange_routing_error
:non_selected_user_clearing
:destination_out_of_order
:address_incomplete
:facility_rejected
:response_to_status_enquiry
:normal_unspecified
:no_circuit_available
:network_out_of_order
:frame_mode_out_of_service
:frame_mode_connection_operational
:temporary_failure
:switching_equipment_congestion
:access_information_discarded
:requested_circuit_not_available
:precedence_call_blocked
:resource_unavailable
:quality_of_service_not_available
:requested_facility_not_subscribed
:outgoing_calls_barred
:outgoing_calls_barred_within_cug
:incoming_calls_barred
:incoming_calls_barred_within_cug
:bearer_cap_not_authorized
:bearer_cap_not_available
:inconsistency_access_info
:service_not_available
:bearer_cap_not_implemented
:channel_type_not_implemented
:requested_facility_not_implemented
:only_restricted_digital_info
:service_not_implemented
:invalid_call_reference
:channel_does_not_exist
:call_identity_does_not_exist
:call_identity_in_use
:no_call_suspended
:call_has_been_cleared
:user_not_member_of_cug
:incompatible_destination
:non_existant_cug
:invalid_transit_network
:invalid_message_unspecified
:mandatory_ie_missing
:message_type_non_existent
:message_not_compatible_with_call_state
:ie_non_existent
:invalid_ie_content
:msg_not_compatible_with_call_state
:recovery_on_timer_expiry
:parameter_non_existent_passed_on
:message_with_non_recognized_parameters_discarded
:protocol_error
:interworking_unspecified

List of toolpack reason causes:

:toolpack_normal or :normal
:toolpack_resource_error or :resource_error
:toolpack_timeout or :timeout
:toolpack_no_route or :no_route
:toolpack_call_collision or :call_collision
:toolpack_sync_drop or :sync_drop
:toolpack_signaling_error or :signaling_error
:toolpack_locally_rejected or :locally_rejected
:toolpack_interface_not_available or :interface_not_available
:toolpack_reset_in_progress or :reset_in_progress
:toolpack_adapter_reject or :adapter_reject
:toolpack_missing_or_invalid_ie or :missing_or_invalid_ie
:toolpack_incoming_only or :incoming_only
:toolpack_system_configuration_changed or :system_configuration_changed
:toolpack_resource_no_more_available or :resource_no_more_available
:toolpack_incompatible_media or :incompatible_media
:toolpack_resource_allocation_failed or :resource_allocation_failed
:toolpack_data_path_not_available or :data_path_not_available
:toolpack_local_congestion or :local_congestion
:toolpack_authorization_required or :authorization_required
:toolpack_call_divert_is_not_allowed or :call_divert_is_not_allowed

List of SIP reason causes: 
Reason causes starting with a digit must use the following syntax (can't use : as prefix).

'300_multiple_choices'
'301_moved_permanently'
'302_moved_temporarily'
'305_use_proxy'
'380_alternative_service'
'400_bad_request'
'401_unauthorized'
'402_payment_required'
'403_forbidden'
'404_not_found'
'405_method_not_allowed'
'406_not_acceptable'
'407_proxy_authentication_required'
'408_request_timeout'
'409_conflict'
'410_gone'
'413_request_entity_too_large'
'414_request_URI_too_long'
'415_unsupported_media'
'416_unsupported_URI_scheme'
'420_bad_extension'
'421_extension_required'
'422_session_timer_too_small'
'423_interval_too_brief'
'429_referrer_identity_error'
'480_temporary_unavailable'
'481_call_or_transaction_does_not_exist'
'482_loop_detected'
'483_too_many_hops'
'484_address_incomplete'
'485_ambiguous'
'486_busy_here'
'487_request_terminated'
'488_not_acceptable_here'
'489_bad_event'
'491_retry_after'
'500_server_internal_error'
'501_not_implemented'
'502_bad_gateway'
'503_service_unavailable'
'504_server_timeout'
'505_version_unsupported'
'513_message_too_large'
'600_busy_everywhere'
'603_decline'
'604_not_exist_anywhere'
'606_not_acceptable'

== Nap status ==

All the status fields of the NAPs are provided for use by the routing scripts. See the nap status provider for more details on which fields are available in the CEngineStatTransNap.hpp file.

'''Notice:''' These values may change between major release.

Routing script call attribute name Description
--------------------------------------------------------------------------------------------
"name" NAP name.
"signaling_type" Signaling type (SS7, ISDN, CASR2, SIP)
"profile" Profile name.
"sip_destination_ip" Destination IP address.
"sip_destination_port" Destination IP port.
"sip_transport_type" SIP transport type (:udp, :tcp, or :tls) (Toolpack 3.1 and more)
"inst_incoming_call_cnt" Instantaneous Count of incoming calls.
"inst_outgoing_call_cnt" Instantaneous Count of outgoing calls.
"available_cnt" Number of available circuits or channels.
"unavailable_cnt" Number of unavailable circuits or channels.
"availability_percent" Percentage of available circuits or channels.
"usage_percent" Percentage of used circuits or channels.
"unused_shared_percent" Percentage of used circuits or channels of this NAP available to make new calls with (taking into account shared with other NAPs)
"total_incoming_call_cnt" Total Count of incoming calls.
"global_asr_percent" Global calculated ASR percentage.
"total_outgoing_call_cnt" Total Count of outgoing calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_outgoing_call_cnt" Last 24 hours outgoing calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_outgoing_call_cnt" Current hour outgoing calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_outgoing_call_cnt" Last hour outgoing calls.
"poll_remote_proxy" Remote proxy polling enabled
"is_available" Remote proxy actually available or not
"time_since_polling" Time since the last availibility polling
"time_available_seconds" Number of seconds since the NAP is available
"time_unavailable_seconds" Number of seconds since the NAP is unavailable
"register_to_proxy" Register to proxy enabled
"registered" Actually registered or not
"time_since_refresh" Time since the last refresh
"time_registered_seconds" Number of seconds since the NAP is registered
"time_not_registered_seconds" Number of seconds since the NAP is not registered
"asr_stats_incoming_struct" Detailed Answer-Seizure Rate incoming statistics.
{
"global_asr_percent" Global calculated ASR percentage.
"total_call_cnt" Total count of calls.
"total_accepted_call_cnt" Total count of accepted calls (not dropped due to congestion or rate-limiting).
"total_answered_call_cnt" Total count of answered calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_call_cnt" Last 24 hours count of calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_call_cnt" Current hour count of calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_call_cnt" Last hour count of calls.
}
"asr_stats_outgoing_struct" Detailed Answer-Seizure Rate outgoing statistics.
{
"global_asr_percent" Global calculated ASR percentage.
"total_call_cnt" Total count of calls.
"total_accepted_call_cnt" Total count of accepted calls (not dropped due to congestion or rate-limiting).
"total_answered_call_cnt" Total count of answered calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_call_cnt" Last 24 hours count of calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_call_cnt" Current hour count of calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_call_cnt" Last hour count of calls.
}
"mos_struct" Detailed Mean Opinion Score statistics.
{
"last_24h_ingress" Last 24 hours calculated MOS for incoming RTP packets.
"last_24h_egress" Last 24 hours calculated MOS for outgoing RTP packets.
"current_hour_ingress" Current hour calculated MOS for incoming RTP packets.
"current_hour_egress" Current hour calculated MOS for outgoing RTP packets.
"last_hour_ingress" Last hour calculated MOS for incoming RTP packets.
"last_hour_egress" Last hour calculated MOS for outgoing RTP packets.
}
"network_quality_struct" Detailed network quality statistics.
{
"last_24h_ingress" Last 24 hours network quality percentage for incoming RTP packets.
"last_24h_egress" Last 24 hours network quality percentage for outgoing RTP packets.
"current_hour_ingress" Current hour network quality percentage for incoming RTP packets.
"current_hour_egress" Current hour network quality percentage for outgoing RTP packets.
"last_hour_ingress" Last hour network quality percentage for incoming RTP packets.
"last_hour_egress" Last hour network quality percentage for outgoing RTP packets.
}

 If the nap status is part of a substructure, the substructure will be a hash containing all subfield elements.

Example to access the signaling type and the number of incoming call count for the NAP of the current call:

incoming_nap = params[:naps][ params[:call][ :nap ].to_sym]
log_trace 4,"Incoming NAP parameters=" + incoming_nap.inspect
log_trace 4,"Incoming NAP signaling type=" + incoming_nap[:signaling_type].inspect
log_trace 4,"Incoming NAP call cnt=" + incoming_nap[:asr_stats_incoming_struct][:total_call_cnt].inspect

 It is also possible to add dynamic nap attributes in the web portal. These can be referenced by their name.

== Telephony Services ==
In release 2.10 and the above, telephony services (CNAM Request) can be manage from the routing engine in the following format:

params[:telephony_services].each do |service| -> Array of telephony services
service[:name] -> Customer telephony service name
service[:type] -> For now only "CNAM Request"
service[:enabled] -> Indicate if the service is enabled (true) or not (false)
(Only the telephony service define in the profile associated to the NAP is enabled)
(The others telephony services define in others profiles are disabled)
(If we are in the case where we return in the routing script with a response, it is important to set :enabled to false in order to avoid repeating the same query)
serviceParams = service[:params]
serviceParams[:return_to_script] -> Indicates to Gateway if we must return to the routing script after receiving the CNAM response
(It is important to set back to false this field to avoid an infinite loop)
serviceQuery = service[:query]
serviceQuery[:phone] -> 10 digits of calling number from the incoming call to send to the CNAM server
serviceQuery[:timeout] -> Timeout in millisecond to wait a CNAM response from CNAM server
(Default value from profile configuration)
serviceResponse = service[:response]
serviceResponse[:success] -> Indicates if we received a good CNAM response from the CNAM Server (Only present if :return_to_script is set to true)
serviceResponse[:caller_name] -> The caller name received in the CNAM response from the CNAM Server (Only present if :return_to_script is set to true)

== Custom user context ==
The routing script may '''save per-call information within the call context''', that will be available if routing is called again later during the call flow.

Cases where routing is called multiple time for the same call are:
- Call transfer requests
- SIP redirect requests
- Radius Authorization result
- Announcement server with digit collection

The routing script can save a recursive hash of attributes here:
params[:user_context]

For example
params[:user_context] = { "SomeKey" => "Some value I want to retrieve upon next routing for this call", "OtherVal" => { "subkey" => "subval" } }

Upon first call to routing script, params[:user_context] will be nil.
Upon subsequent calls to routing script, it will contain whatever the script had stored upon previous call (or nil if it was not set)

Note: This feature is available starting from release 2.9.85, 2.10.31 and 3.0.15 (in respective branches 2.9, 2.10 or 3.0)

== Routing Script Tests ==
The Web portal features a tool for Testing Scripts. The user must enter parameters to simulate the incoming call and after pressing the Test button, will output selected routes and numbers. You do not need to activate the new routes, or the new scripts to use this test tool: It can be used to test the routing scripts and routing table before activating it.
This is available in the Routing Scripts section of the Web portal.

=== Test parameters ===
==== @call_params ====

That variable should contain a hash of call parameters that will be passed to the routing script. This is equivalent to the incoming call parameters.

 

==== @nap_list ====

A list of the hash containing the nap statuses. This is equivalent to the nap statuses at the time the call is to be routed.

'''The nap list is hashed by the nap names in UPPERCASE.''' It is important to consider this when creating new dynamic route or nap attributes that may nap names that will be used to fetch a status.

 

==== @params ====

A hash of hashes containing parameters. This hash contains bridge parameters and other kind of parameter groups may be added in the future.

@params = {
:bridge => {:announcement_tone, "announcement.wav"},
:contacts => {
:index=>"1",
:list=>[
{:called_number=>"6660", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"",
:raw_data=>"", :expiration=>"3600"},
{:called_number=>"6661", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6661@192.168.215.127",
:raw_data=>"<sip:6661@192.168.215.127>", :expiration=>"3600"}
],
:source_indexes=>"nil,0"
}
}

 

----

 Back to [[Routing script tutorial|Routing Script Tutorial]].

Routing script tutorial:Mini Development Guide

2019-04-30T13:48:30Z

Abrassard: /* Forwarding from inbound to outbound call */

== Call object ==

=== Get ===

This function is used to get the call parameters. The possible parameters are described in the section "Call parameters"

called_number = caf_call.get :called

=== List_params ===

This function is used to retrieve the list of supported call parameters. For example to extract all the possible call parameters from the the call object and put it in hash.

caf_call.list_params.each {|param| call[param] = caf_call.get param }

=== Accept ===

This function is used to accept a call. It actually creates one outgoing route that the gateway application will use to bridge the incoming call leg. If more than one outgoing route is "accepted", the gateway will try them one by one in the same order that they were accepted. If an outgoing call leg fails (according to 'route retry' parameters), the next route in line will be used.

This method takes 2 arguments, the call parameters (hash) and the route parameters (hash). Note that calling this method does NOT stop the flow of the script.

Apply route remapping rules

caf_call.accept out_call, route

=== Refuse ===

This function is used to set the reason code for the incoming call leg refusal. However, this function does NOT stop the flow of the script.

caf_call.refuse :reason => :temporary_failure

To immediately refuse the incoming call leg and stop processing the script, the script must raise an exception. Exiting the script by raising the exception overwrites any reason cause previously stored using refuse().

raise RoutingException, :no_route

The supported refusal cause values for both refuse() and raise() are described in the section "[[Routing_script_tutorial:Mini_Development_Guide#Reason_values|Reason values]]".

=== Script parameters protocol mapping ===

The following call parameters are available in the call object. For example:

called_number = call[:called]

For information on how to use and remap call parameters, see [[Toolpack:_How_to_Use_RegEx_in_Remapped_Called_and_Calling_Number_Mask | How to use regex in Remapped Called and Calling Number Mask]]

{| cellspacing="1" cellpadding="1" border="1" style="width: 921px; height: 805px;"
|-
! scope="col" | '''Script parameter name'''
! scope="col" | '''ISDN '''
! scope="col" | '''R2 CAS''' 
! scope="col" | '''SS7 '''
! scope="col" | '''SIP '''
! scope="col" | '''Comment '''
! scope="col" | '''Toolpack version '''
|-
| leg_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Leg ID 
| 
|-
| session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Session ID 
| 
|-
| original_session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Original Session ID (before call transfer or redirections) 
| 
|-
| calling 
| Q931: 'Calling party number' IE - Number digits 
| ANI (Group B) 
| Q763: 'Calling party number' IE - address signals (*) 
| SIP:From - user-info 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead. 
| 
|-
| calling_sip_host 
| N/A 
| N/A 
| N/A 
| SIP:From - host (domain or IP) 
| For example : The 'telcobridges.com' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| calling_sip_port 
| N/A 
| N/A 
| N/A 
| SIP:From - port 
| For example : The '6060' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| calling_noa 
| Q931: 'Calling party number' IE - Type of number 
| N/A 
| Q763: 'Calling party number' IE - nature of address indicator (*) 
| N/A 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead 
| 
|-
| calling_npi 
| Q931: 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: 'Calling party number' IE - numbering plan indicator (*) 
| N/A 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead 
| 
|-
| calling_display 
| Q931: 'Display' IE - Display information 
Q931: 'Facility CNAM' IE when presentation is allowed for DMS/NI2 variants 
| N/A 
| Q763
ITU97: 'Display information' IE - display information
ANSI95: 'Generic name' IE - display information
| SIP:From - display-name 
| 
| 
|-
| calling_display_type 
| Q931: 'Display' IE - Display information (present and/or first byte) 
| N/A 
| Q763: 'Display information' IE - present or not 
| N/A 
| 
| 
|-
| calling_presentation 
| Q931: 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: 'Calling party number' IE - address presentation restricted indicator 
|
SIP:From - display-name (displays 'anonymous' or not)

SIP:Remote-party-id - privacy 

| 
| 
|-
| calling_screening 
| Q931: 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: 'Calling party number' IE - screening 
| SIP:Remote-party-id - screen 
| 
| 
|-
| calling_category 
| N/A 
| Call party category (Group A) 
| Q763: 'Calling party's category' IE - calling party's category 
|
SIP:From - cpc

SIP:P-asserted-identity - cpc 

| 
| 
|-
| calling_subscriber
(Generic Number / NDS) 
| Q931: 2nd 'Calling party number' IE - Number digits 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - Number digits 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| Requires option 'support 2 calling number IE' in the profile. This variable has priority over 'private_address' in the outgoing direction. 
| 
|-
| calling_subscriber_noa 
| Q931: 2nd 'Calling party number' IE - Type of number 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - nature of address indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_npi 
| Q931: 2nd 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - numbering plan indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
 
| 
|-
| calling_subscriber_presentation 
| Q931: 2nd 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - presentation restricted indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_screening 
| Q931: 2nd 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - screening 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| private_display 
| Q931: 'Facility CNAM' IE when presentation is restricted for DMS/NI2 variants 
| N/A 
| N/A 
|
SIP:P-asserted-identity - display-name 

SIP:Remote-party-id - display-name 

| 
| 
|-
| private_display_type 
| N/A 
| N/A 
| N/A 
| N/A 
| Indicate presence or not of the private calling information 
| 
|-
| private_address 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 

| For example : The 'fluffy' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_sip_host 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - host (domain or IP)

SIP:Remote-party-id - host (domain or IP) 

| For example : The 'telcobridges.com' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_sip_port 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - port

SIP:Remote-party-id - port 

| For example : The '6060' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| called 
| Q931: 'Called party number' IE - Number digits 
| DNIS (Group A) 
| Q763: 'Called party number' IE - address signals 
| SIP:To - user-info and host 
| 
| 
|-
| called_sip_host 
| N/A 
| N/A 
| N/A 
| SIP:To - host 
| For example : The 'telcobridges.com' in To: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| called_sip_port 
| N/A 
| N/A 
| N/A 
| SIP:To - port number 
| For example : The '6060' in To: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| called_noa 
| Q931: 'Called party number' IE - Type of number 
| N/A 
| Q763: 'Called party number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| called_npi 
| Q931: 'Called party number' IE - Numbering plan identification 
| N/A 
| Q763: 'Called party number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| charge_number 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - address signals 
| N/A 
| 
| 
|-
| charge_number_noa 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| charge_number_npi 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| redirecting_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default redirecting number and original called number forwarding behavior from incoming to outgoing leg 
| 
|-
| redirecting_number 
| Q931: 'Redirecting number' 1st IE - Number digits 
| N/A 
| Q763: 'Redirecting number' IE - address signals 
| SIP:Diversion (2nd header) - display-name 
| 
| 
|-
| redirecting_number_noa 
| Q931: 'Redirecting number' 1st IE - Type of number 
| N/A 
| Q763: 'Redirecting number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| redirecting_number_npi 
| Q931: 'Redirecting number' 1st IE - Numbering plan identification 
| N/A 
| Q763: 'Redirecting number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| redirecting_number_presentation 
| Q931: 'Redirecting number' 1st IE - Presentation indicator 
| N/A 
| Q763: 'Redirecting number' IE - address presentation restricted indicator 
| SIP:Diversion (2nd header) - diversion-privacy 
| 
| 
|-
| redirecting_number_indicator 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirecting indicator 
| N/A 
| 
| 
|-
| redirecting_number_reason 
| Q931: 'Redirecting number' 1st IE - Reason for redirection 
| N/A 
| Q763: 'Redirection information' IE - redirecting reason 
| SIP:Diversion (2nd header) - diversion-reason 
| 
| 
|-
| redirecting_number_counter 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirection counter 
| SIP:Diversion (2nd header) - diversion-counter 
| 
| 
|-
| original_called_number
(OCN) 
| Q931: 'Redirecting number' 2nd IE - Number digits 
| N/A 
| Q763: 'Redirection number' IE - address signals 
| SIP:Diversion  (1st header) - display-name 
| 
| 
|-
| original_called_number_noa 
| Q931: 'Redirecting number' 2nd IE - Type of number 
| N/A 
| Q763: 'Redirection number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| original_called_number_npi 
| Q931: 'Redirecting number' 2nd IE - Numbering plan identification 
| N/A 
| Q763: 'Redirection number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| original_called_number_presentation 
| Q931: 'Redirecting number' 2nd IE - Presentation indicator 
| N/A 
| Q763: 'Redirection number' IE - address presentation restricted indicator 
| SIP:Diversion (1st header) - diversion-privacy 
| 
| 
|-
| original_called_number_reason 
| Q931: 'Redirecting number' 2nd IE - Reason for redirection 
| N/A 
| Q763: 'Redirection information' IE - original redirection reason 
| SIP:Diversion (1st header) - diversion-reason 
| 
| 
|-
| original_called_number_counter 
| N/A 
| N/A 
| N/A 
| SIP:Diversion (1st header) - diversion-counter 
| 
| 
|-
| ported_number_npdi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - with qualifier=Ported number is present 
| SIP:RequestURI - npdi=yes is present 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number 
| N/A 
| N/A 
| Q763: 'Generic number' IE - address signals with qualifier=Ported number 
| SIP:RequestURI - to user part when rn is present 
| rn is stored in the called number 
| 
|-
| ported_number_noa 
| N/A 
| N/A 
| Q763: 'Generic number' IE - nature of address indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number_npi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - numbering plan indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| oli
(Originating line information) 
| 5ESS Codeset 6 OLI - Value 
| N/A 
| ANSI: 'Originating line information' IE - OLI 
|
SIP:From - oli

SIP:P-asserted-identity - oli 

| 
| 
|-
| request_uri 
| N/A 
| N/A 
| N/A 
| Complete Request URI string 
| 
| 
|-
| request_uri_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default URI forwarding behavior from incoming to outgoing leg 
| 
|-
| sip_header 
| N/A 
| N/A 
| N/A 
| Any header 
| Requires option 'Forward custom headers' in Profiles->SIP 
| 2.7.63 
|-
| nap
(Network Access Point) 
| N/A 
| N/A 
| N/A 
| N/A 
| Incoming leg NAP name (read-only) 
| 
|-
| type_of_network_identification 
| Q931: 'Transit network selection' IE - Type of network identification 
| N/A 
| Q763: 'Transit network selection' IE - Type of network identification 
| N/A 
| 
| 2.7 
|-
| network_identification 
| Q931: 'Transit network selection' IE - Network identification 
| N/A 
| Q763: 'Transit network selection' IE - Network identification 
| SIP: Request-Line - cic 
| 
| 2.7 
|-
| network_identification_plan 
| Q931: 'Transit network selection' IE - Network identification plan 
| N/A 
| Q763: 'Transit network selection' IE - Network identification plan 
| N/A 
| 
| 2.7 
|-
| location_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default location number forwarding behavior from incoming to outgoing leg 
| 2.7 
|-
| location_number 
| N/A 
| N/A 
| Q763: 'Location number' IE - address signals 
| N/A 
| 
| 2.7 
|-
| location_number_noa 
| N/A 
| N/A 
| Q763: 'Location number' IE - nature of address indicator 
| N/A 
| 
| 2.7 
|-
| location_number_npi 
| N/A 
| N/A 
| Q763: 'Location number' IE - numbering plan indicator 
| N/A 
| 
| 2.7 
|-
| location_number_presentation 
| N/A 
| N/A 
| Q763: 'Location number' IE - presentation restricted indicator 
| N/A 
| 
| 2.7 
|-
| location_number_screening 
| N/A 
| N/A 
| Q763: 'Location number' IE - screening 
| N/A 
| 
| 2.7 
|-
| mlpp_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| A script needs to set this to true if it wants to overwrite MLPP information in the outgoing leg. Otherwise, profile relay 'outgoing mode' applies automatically. 
| 2.7 
|-
| mlpp_look_for_busy 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - look ahead for busy 
| N/A 
| 
| 2.7 
|-
| mlpp_precedence_level 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - precedence level 
| SIP:Resource-Priority - q735 
| 
| 2.7 
|-
| mlpp_network_identity 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - network identity 
| N/A 
| 
| 2.7 
|-
| mlpp_service_domain 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - MLPP service domain 
| N/A 
| 
| 2.7 
|-
| called_isub 
| Q931: 'Called party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub parameter 
| 
| 2.7 
|-
| called_isub_type 
| Q931: 'Called party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub-encoding parameter 
| 
| 2.7 
|-
| calling_isub 
| Q931: 'Calling party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub 
| 
| 2.7 
|-
| calling_isub_type 
| Q931: 'Callinf party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub-encoding 
| 
| 2.7 
|-
| ss7_fci_default 
| N/A 
| N/A 
| Default forward call indicator (FCI) value. 
| N/A 
| Toolpack will overwrite FCI bits A, D, F, I and M with appropriate values according to call conditions 
| 2.7 
|-
| ss7_fci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_fci_default that must be forced. 
| N/A 
| Bits from ss7_fci_default which corresponding bit in ss7_fci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| ss7_bci_default 
| N/A 
| N/A 
| Default backward call indicator (BCI) value. 
| N/A 
| Toolpack will overwrite BCI bits AB, I, K, M and N with appropriate values according to call conditions 
| 2.7 
|-
| ss7_bci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_bci_default that must be forced. 
| N/A 
| Bits from ss7_bci_default which corresponding bit in ss7_bci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| tdm_ls_name_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable line service and timeslot selection to create the outgoing leg 
| 3.0 
|-
| tdm_ls_name
(Line Service or T1/E1 trunk) 
| Incoming leg line service name 
| Incoming leg line service name 
| Incoming leg line service name 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this line service name to create outgoing leg 
| 2.7 
|-
| tdm_timeslot_nb 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this timeslot number to create outgoing leg 
| 2.7 
|-
| rtp_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP port 
| (read-only) 
| 2.7 
|-
| rtp_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP port 
| (read-only) 
| 2.7 
|-
| ss7_cot_enabled 
| N/A 
| N/A 
| Requests SS7 in-call continuity test for this outgoing SS7 call 
| N/A 
| Toolpack will request a continuity test on the timeslot before making the outgoing call. If COT fails, the call will be dropped (then another route may be attempted) 
| 2.8 
|-
| reverse_charging_indication 
| Incoming leg Reverse charging indication IE present 
| N/A 
| N/A 
| N/A 
| If set in routing script, will add Reverse charging indication IE in outgoing leg (also use reverse_charging_indication_forward_enabled) 
| 2.8.12 
|-
| reverse_charging_indication_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable forwarding of reverse charging indication from incoming to outgoing leg 
| 2.8.12 
|-
| sip_call_id 
| N/A 
| N/A 
| N/A 
| Incoming leg SIP Call-Id 
| (read-only) 
| 2.9.112 / 3.0.131 
|-
| sip_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP port 
| (read-only) 
| 2.8.13 
|-
| sip_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP port 
| (read-only) 
| 2.8.13 
|}

 

=== Noa values ===
The text below represents the value normally used by routing script. 
Incase it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 
Example numeric values for the SS7 protocol are shown in parenthesis. 
 
*<tt>unknown_number (0x2)</tt>
*<tt>international_number (0x4)</tt>
*<tt>national_number (0x3)</tt>
*<tt>subscriber_number (0x1)</tt>
*<tt>network_specific (0x5)</tt>
*<tt>network_routing_national_format (0x7)</tt>
*<tt>network_routing_international_format (0x8)</tt>
*<tt>abbreviated_number (0x6)</tt>
*<tt>subscriber_number_operator_requested (0x71)</tt>
*<tt>national_number_operator_requested (0x72)</tt>
*<tt>international_number_operator_requested (0x73)</tt>
*<tt>no_number_present_operator_requested (0x74)</tt>
*<tt>no_number_present_cut_through_call_to_carrier (0x75)</tt>
*<tt>test_line_test_code (0x77)</tt>
*<tt>non_unique_subscriber_number (0x71)</tt>
*<tt>non_unique_national_number (0x73)</tt>
*<tt>non_unique_international_number (0x74)</tt>
*<tt>call_950_numbe (0x76)</tt>
*<tt>special_number (0x73)</tt>
*<tt>national_number_with_transit_network_selection (0x74)</tt>
*<tt>international_number_with_transit_network_selection (0x75)</tt>

Those values will be remapped to the protocol specific NOA value. To provide protocol specific value:

*<tt>call_params[:called_noa] = 0x70</tt>

or

*<tt>call_params[:called_noa] = 112</tt>

=== Npi values ===

*<tt>unknown_number</tt>
*<tt>isdn</tt>
*<tt>telephony</tt>
*<tt>private</tt>
*<tt>data</tt>
*<tt>telex</tt>
*<tt>national</tt>

=== Calling Display Type values ===

*<tt>unspecified</tt> => Type is unspecified.
*<tt>calling_party_name</tt> => Type is 0xB1.

Those values will be remapped to the protocol specific Display Information Type value. To provide protocol specific value:

*<tt>call_params[:calling_display_type] = 0xB1</tt>

or

*<tt>call_params[:calling_display_type] = 177</tt>

=== Calling Display value ===

*<tt>call_params[:calling_display] = "Roger Fluffy"</tt>

=== Presentation values for Calling number, Calling Subscriber (Generic Number), Redirecting Number, Original Called Number (OCN) and Location Number ===
The text below represents the value normally used by routing script. 
Incase it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 
Example numeric values for the SS7 protocol are shown in parenthesis. 
 
*<tt>unspecified</tt>
*<tt>not_available (0x2)</tt>
*<tt>allowed (0x0)</tt>
*<tt>restricted (0x1)</tt>
*<tt>addr_restricted</tt>
*<tt>name_restricted</tt>

=== Calling Party Category ===
The text below represents the value normally used by routing script. 
In case it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 

Mapping from routing script to SS7/CAS R2/SIP
{| cellspacing="1" cellpadding="1" border="1"
|-
! scope="col" | '''Routing Script string '''
! scope="col" | '''SS7 raw value '''
! scope="col" | '''R2 CAS scripts''' 
! scope="col" | '''Default Rx CAS''' 
! scope="col" | '''default Tx CAS''' 
! scope="col" | '''SIP "cpc=" '''
|-
| subscriber 
| 0xa 
| CATEGORY_SUBSCRIBER 
| 1 and 7 
| 7 
| ordinary 
|-
| subscriber_with_priority 
| 0xb 
| CATEGORY_SUBSCRIBER_WITH_PRIORITY 
| 2 and 9 
| 2 
| priority 
|-
| operator_french 
| 0x1 
| CATEGORY_OPERATOR_FRENCH 
| 5 
| 5 
| operator 
|-
| operator_english 
| 0x2 
| CATEGORY_OPERATOR_ENGLISH (5) 
| 5 
| 5 
| operator 
|-
| operator_german 
| 0x3 
| CATEGORY_OPERATOR_GERMAN (5) 
| 5 
| 5 
| operator 
|-
| operator_russian 
| 0x4 
| CATEGORY_OPERATOR_RUSSIAN (5) 
| 5 
| 5 
| operator 
|-
| operator_spanish 
| 0x5 
| CATEGORY_OPERATOR_SPANISH (5) 
| 5 
| 5 
| operator 
|-
| data 
| 0xc 
| CATEGORY_DATA 
| 6 and 8 
| 6 
| datacall 
|-
| test 
| 0xd 
| CATEGORY_TEST 
| 3 
| 3 
| test 
|-
| payphone 
| 0xf 
| CATEGORY_PAYPHONE 
| none 
| 7 
| payphone 
|-
| unknown 
| 0x0 
| CATEGORY_UNKNOWN 
| 4, 11 to 15 
| 7 
| unknown 
|-
| unspecified 
| 0xa 
| invalid 
| none 
| none 
| invalid 
|}
[[CAS_R2_scripting#Category_meanings|Link to calling party categories used in CAS R2 scripts]]

=== Screening values for Calling number, Calling Subscriber (Generic Number), and Location Number ===
The text below represents the value normally used by routing script. 
Incase it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 
Example numeric values for the SS7 protocol are shown in parenthesis. 
 
*<tt>unspecified</tt>
*<tt>no (0x0)</tt>
*<tt>pass (0x1)</tt>
*<tt>fail (0x2)</tt>
*<tt>network_provided (0x3)</tt>

=== Redirecting indicator values ===

SS7:

*<tt>no_redirection</tt>
*<tt>call_rerouted</tt>
*<tt>call_rerouted_all_restricted</tt>
*<tt>call_diverted</tt>
*<tt>call_diverted_all_restricted</tt>
*<tt>call_rerouted_restricted</tt>
*<tt>call_diverted_restricted</tt>
*<tt>spare</tt>

=== Redirecting number, Original Called Number and Diversion Reason ===

ISDN:

*<tt>unknown</tt>
*<tt>busy</tt>
*<tt>no_reply</tt>
*<tt>deflection</tt>
*<tt>dte_out_of_order</tt>
*<tt>forwarding_by_called_dte</tt>
*<tt>unconditional</tt>

SS7:

*<tt>unknown</tt>
*<tt>busy (SIP: user-busy)</tt>
*<tt>no_reply (SIP: no-answer)</tt>
*<tt>unconditional</tt>
*<tt>deflection</tt>
*<tt>deflection_immediate</tt>
*<tt>mobile_not_reachable</tt>

=== OLI (originating line information) values ===

The OLI parameter is a string that represents an integer value from 0 to 255.

=== Information Transfer Capability values ===

information_transfer_capability:

*<tt>digital</tt>
*<tt>restricted_digital</tt>
*<tt>digital_with_tones</tt>
*<tt>speech</tt>
*<tt>3_1_khz_audio</tt>
*<tt>video</tt>

=== redirecting_number_forward_enabled values ===

Controls forwarding or discarding of redirecting number (SIP: diversion header) to the outgoing call leg.

Values for this parameter are "0", "1", "false" or "true.
*0/false: Redirecting number (and original called number) is not forwarded to outgoing call leg
*1/true: Redirecting number (and original called number) is forwarded to outgoing call leg

The value for this parameter at the input of the routing script depends on the "Forward redirecting number" parameter in the "Advanced" section of the Gateway configuration page of the Web Portal. The script may change this value to override the Gateway configuration.

Note: To "insert" a new redirecting number value on the outgoing leg, redirecting_number_forward_enabled must also be set to true.

=== request_uri ===

Enables access to the Request-Line URI. 

For example, if the Request-Line is:
<pre>Request-Line: INVITE sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0</pre>
Then the retrieved request_uri will be "sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0". 

In the routing scripts, to retrieve only the called number, this script can be used: 
<pre> if call_params[:request_uri] && call_params[:request_uri] =~ /sip:(.*)@.*/
call_params[:called] = $1
end
</pre>
==== request_uri_forward_enabled ====

This call parameter controls forwarding or discarding of request uri to outgoing call leg.The request uri is the information in the "Request-Line:" of the SIP INVITE message. 

Values for this parameter are "0", "1", "false" or "true. 

* 0/false: Request uri is not forwarded to outgoing call leg 

* 1/true: Request uri is forwarded to outgoing call leg 

The default value for this parameters is false. 

==== sip_scheme ====
(Available in Toolpack 3.1+)
This call parameters indicates the scheme (generally "sip" or "sips") of the incoming call.

This also allows to control the scheme used for the outgoing call (regardless if request_uri_forward_enabled is used or not)

Note: sips scheme must only be used on TLS NAPs (will cause call routing failure if NAP has only UDP or TCP transport types).

=== sip_header values ===
Contains custom sip headers from the inbound call leg. Any custom sip header can be added to an outgoing call leg: 

'''Note:'''

The SIP header is in string format.

'''string format:'''
<pre>call[ :sip_header ] = "P-my-custom-header:value1 \nP-my-custom-header2:value2 \nP-my-custom-header3:value3"
</pre>
(Note: \n above are actual newline characters, not '\' followed by 'n')

* PCAP sample: [[File:TB_Custom_SIP_Headers.pcap]]

List of sip headers that will not appear in call[:sip_header] since they are already processed by the SIP stack:
<pre>
Accept Error-Info Remote-Party-ID
Accept-Contact Event Replaces
Accept-Encoding Expires Reply-To
Accept-Language From Request-Disposition
Alert-Info In-Reply-To Subject
Allow Max-Forwards Subscription-State
Allow-Events MIME-version Supported
Also Min-Expires Timestamp
Anonymity Min-SE To
Authorization Organization Unsupported
Authentication-Info Path User-Agent
Call-ID Priority Via
Call-Info Privacy Warning
Contact Proxy-Authenticate WWW-Authenticate
Content-Disposition Proxy-Authorization Require
Content-Encoding Proxy-Require Response-Key
Content-Language P-Media-Authorization Retry-After
Content-Length P-Preferred-Identity RPID-Privacy
Content-Type P-Asserted-Identity Route
CSeq RAck RSeq
RAck Reason Security-Client
Reason Record-Route Security-Server
Date Refer-To Security-Verify
Diversion Referred-By Server
Encryption Reject-Contact Service-Route
Session-Expires
</pre>

=== sip header parameters ===
The routing script can read (and modify) some SIP header parameters (user parameters, URI parameters or header parameters) from some SIP headers (To, From, P-Asserted-Identity, Remote-Party-ID, Contact).

==== Available parameters ====
* '''call[ :calling_parameters ]''' (SIP "From" header)
* '''call[ :called_parameters ]''' (SIP "To" header)
* '''call[ :private_address_parameters ]''' (SIP "P-Asserted-Identity" or "Remote-Party-ID" header)
* '''call[ :contact_parameters ]''' (SIP "Contact" header)

These parameters (if present) contain a hash with 3 keys: user_param, uri_param and header_param.
Each of this key points to a string that contains all the parameters found in the corresponding SIP header.
* '''User parameters''' (parameters between the user name/number and the host). Example <sip:alice;'''param=value'''@somewhere.com>
* '''URI parameters''' (parameters at the end of the URI). Example <sip:alice@somewhere.com;'''param=value'''>
* '''Header parameters''' (outside the URI). Example <sip:alice@somewhere.com>;'''param=value'''
Example to print all parameters of SIP "To" header:
call[ :called_parameters ].inspect -> '{ :user_param => "name1=value1;name2=value2", :uri_param => "name=value", :header_param => "name=value;example_param_without_value" }'
Example to modify (replace) the URI parameters of SIP "To" header:
call[ :called_parameters ][ :uri_param ] = "user=phone"

==== Exceptions ====
'''Note:''' Some parameters are reported as their own call attribute (oli, isub, cpc, transport) so they have the same representation for all protocols (SS7, IDSN, SIP). They won't appear present in the generic SIP header parameters structures above.

==== Forwarding from inbound to outbound call ====

==== Legacy behavior ====
(For base_routing version 1.32 or older)
By default, the parameters are not forwarded in a SIP to SIP call flow. The parameters '''will be forwarded''' when:
* accessed (read) from either the inbound or outbound call parameters
* written in either the inbound or outbound call parameters

==== Current behavior ====
(For Toolpack 3.0.118+, with base_routing version 1.33+)
SIP headers host and parameters are forwarded by default.

A route attribute "forward_sip_domain" (along with filter script "forward_sip_domain.rb") will control, per route, if SIP headers host+parameters must be forwarded.

==== Example usage ====
Example to print the user parameters:
<pre>
if call[:calling_parameters]
puts "user parameters = #{call[:calling_parameters][:user_param].inspect}"
end
</pre>

Example SIP "From" header:
From:<sip:123456782;test1=val1;test2=val2@something.com;test3=val3;test4=val4>;test5=val5;test6=val6
And the resulting content in the routing script:
calling_param.inspect -> {:user_param=>"test1=val1;test2=val2", :uri_param=>"test3=val3;test4=val4", :header_param=>"test5=val5;test6=val6"}

'''Note''' that printing the inbound or outbound call parameters is considered as a "read" action and would result in forwarding the parameter on the outbound leg.

Example to overwrite inbound leg calling parameters with new parameters for the outbound leg:
<pre>
call [:calling_parameters] = {
:user_param => "user_param7=7;user_param8=8",
:uri_param => "uri_param9=value9",
:header_param => "header_paramA=A" }
</pre>

Example to add user=phone and keep all other uri parameters.
<pre>
call[:calling_parameters] ||= {} # Create a hash if not already present
call[:calling_parameters][:uri_param] ||= "" # Create a string if not already present
call[:calling_parameters][:uri_param] += ";" if call[:calling_parameters][:uri_param] != ""
call[:calling_parameters][:uri_param] += "user=phone"
</pre>

=== MLPP Precedence values ===

mlpp_look_for_busy:

*<tt>allowed</tt>
*<tt>path_reserved</tt>
*<tt>not_allowed</tt>

mlpp_precedence_level:

*<tt>flash_override</tt>
*<tt>flash</tt>
*<tt>immediate</tt>
*<tt>priority</tt>
*<tt>routine</tt>

mlpp_network_identity:

3 digits value from 0 to 999

mlpp_service_domain:

24 bits value from 0 to 16777215

=== ISUB subaddress information values ===

called_isub_type:
calling_isub_type:

*<tt>nsap</tt>
*<tt>nsap_ia5</tt>
*<tt>nsap_bcd</tt>
*<tt>user</tt>

called_isub:
calling_isub:

Digits for the subaddress information.

=== Network Identification Plan ===

network_identification_plan:

*<tt>Unknown</tt> (value 0)
*<tt>cic</tt> (3 digits carrier identification code plus circuit code, value 1, SS7 or ISDN)
*<tt>user</tt> (User, value 2, ISDN only)
*<tt>cic4</tt> (4 digits carrier identification code plus circuit code, value 2, SS7 only)
*<tt>dnic</tt> (public Data Network ID, value 3, SS7 only)
*<tt>mnic</tt> (public land mobile network, value 6, SS7 only)

=== Registered Users Information ===
Routing script can access information about registered users (when either the calling or called user is a known registered user).
When these fields are empty, it means that the calling/called (SIP from/to) does not correspond to a known registered user (routing script may still decide to route the call based on static routes).

Information for the called user:
params[:registered_user]
Information for the calling user:
params[:calling_registered_user]

These parameters are a hash of key/values that provide information about the contact.
{
:contact_list=>
[
{
:contact=>"<sip:user_name_or_number@hostname:7070;transport=UDP>", -> Full contact
:expires=>"60", -> Contact expiry time (seconds)
:host=>"hostname", -> host name from the contact header
:name=>"user_name_or_number", -> user name from the contact header
:nap_in=>"NAP_NAME", -> NAP that the contact has registered from
:port=>"7070", -> Port from the contact header
:transport=>"UDP" -> Transport type from the contact header
:q_value=>"0.00", -> Q-value for the contact (for contact ordering)
:src_host=>"10.0.0.10", -> Actual source IP address that the contact has registered from
:src_port=>"7070", -> Actual source port that the contact has registered from
:src_transport=>"UDP", -> Actual protocol that the contact has been registering with
}
]
}

== Route parameters ==

All route may have these parameters:

*calling
*called
*nap
*remapped_calling
*remapped_called
*remapped_nap
*remapped_destination_leg_profile (called remapped_profile prior to Toolpack 2.9)
*remapped_source_leg_profile (called remapped_incoming_profile prior to Toolpack 2.9)

Example:

route[:remapped_nap]

Additionally it is possible to add dynamic route attributes in the web portal. These can be referenced by their name.
For example:
*priority
*weight

== Routing calls toward registered users ==
Static routes normally chose an outbound NAP to forward the call to.

But it's also possible to create routes which outbound NAP is dynamically chosen by matching a registered user (when using [[Sip_registration_forwarding|SIP registration forwarding]]).

More information can be found [[Sip_registration_forwarding#SIP_Calls_routing|here]] about the way to control the [[Sip_registration_forwarding#SIP_Calls_routing|priority of "dynamic" vs "static" routes]].

More information can be found [[#Registered_Users_Information|here]] about using routing scripts to access registered users information during call routing.

== Playing prompts announcements or tones ==

New feature in release 2.6, all bridges may have these parameters. These can be used to play IVR prompts (audio files) in different states of the call flow.

*'''announcement_tone''' (played before outgoing call is routed)
*'''ring_tone''' (played after when waiting for outgoing call to answer)
*'''busy_tone''' (played if outgoing call failed)
*'''disconnect_tone''' (played after the call has reached it's maximum duration)

Example to play an announcement to incoming call (before routing outgoing call, regardless if a matching route is found or not):
bridge[:announcement_tone ] = "my_announcement.wav"

Example to play a ring-tone while the outgoing call is ringing:
bridge[:ring_tone] = "my_ring_tone.wav"

Example to play an audio file when outgoing call fails (no route, or outgoing call is refused):
bridge[:busy_tone] = "my_busy_tone.wav"

Example to play an audio file when call has reached the maximum allowed duration:
bridge[:disconnect_tone] = "your_account_balance_is_empty.wav"

=== Announcement file path format and options ===

All file plabyacks (:announcement_tone, :busy_tone, :ring_tone, :disconnect_tone) inside bridge parameters use this format.
<pre>"file1.wav:repeat:start_off:end_off,file2.wav:repeat:start_off:end_off,file3.wav:repeat:start_off:end_off"
</pre>
Optional parameters:
* repeat: number of times to play the file (0 and 1 have the same result)
* start_off: Start offset in milliseconds
* end_off: End offset in milliseconds

Http and other path formats are described here: [[Customer_application_framework:play_audio_files#Play_path_format|Path format]]

==== Example 1 ====
The following example will play file1.wav once, and then play file2.wav in loop:
"file1.wav,file2.wav:-1"

==== Example 2 ====
The following example will play file1.wav from start offset of 1 second to end offset of 3 seconds, then twice file2.wav from second 5 to second 10.
"file1.wav:0:1000:3000,file2.wav:2:5000:10000"

==== Example 3 ====
The following example will play file1.wav once, ending at offset of 30 seconds.
"file1.wav:0:0:30000"

=== announcement_tone ===

params[:bridge][:announcement_tone] = "announcement.wav"

Audio file played on the incoming call before any outgoing call is placed. The outgoing call occurs when the file finished playing.

==== announcement_tone options ====
===== announcement_tone_answer =====
params[:bridge][:announcement_tone_answer] = "yes"

Forces an answer of the call before playing the announcement. Default if argument not provided is "no", in which case call is only alerted with in-band media.

===== announcement_code_detect =====
This option allows that the tone detection is enabled during the announcement play.

Collected digits can be inserted into the CDR logs (radius attribute "Telcob-CollectedDigits", or text CDR variable @{CollectedDigits}).

Collected digits can also be sent back to routing script, which is called again with the same call attributes, except that the called number is replaced by the collected digits.

Code detect has multiple options, as shown in the following code:
code_detect = {
:type => :DTMF, # :DTMF or :MFR1 tone detection.
# Default is MFR1.
:prefix => "", # Prefix (digits) that is removed from collected digits.
# Default is empty.
:suffix => "", # Suffix (digits) that is removed from collected digits
# and causes routing script to be immediately called.
# Default is empty.
:suffix_removal => false, # Controls the removal of the suffix from the collected digit string that's reported to routing script.
# Default is false
:timeout => 0, # Inter-digit timeout (ms) after which collected digits are passed to the routing script.
# Use 0 for "no timeout".
# Default is 1000ms
:barge_in_interruption => true, # When enabled, playing announcement is stopped as soon as first digit is collected.
# Default is true.
:proceed_on_play_done => false, # When true: Outgoing call is made after announcement finishes playing.
# Routing script is not called again.
# When false: Outgoing call is never made.
# Digits are collected until timeout or suffix match,
# then routing script is called again.
# Default is false.
:cas_on_hook => false, # Specific for CAS-R1 calls. Makes CAS bits switch to "on-hook" when announcement finished playing
# (but the call is not "terminated" from Toolpack point of view)
# Default is false.
:cas_on_hook_delay => 0, # Duration of cas bits "on-hook" state.
# Only effective if cas_on_hook is set to true.
# Value of 0 stands for "infinite delay".
# Default is 0.
:repeat_delay => 0, # Delay between repetition of the announcement. The announcement will repeat
# itself every "repeat_delay" until a code is detected (suffix match or timetout).
# Value of 0 stands for "infinite delay" (no repeating).
# Default is 0.
}
'''Example 1''': Collect DTMF digits, and call routing script again with collected digits upon timeout or suffix match.
code_detect = { :type => :DTMF, :suffix => "#", :timeout => 5000 }
params[:bridge][:announcement_code_detect] = code_detect

'''Example 2''': Collect digits during the announcement (for CDR logs), then proceed (make outgoing call) after announcement finishes playing
code_detect = { :type => :DTMF, :timeout => 0, :barge_in_interruption => false, :proceed_on_play_done => true }
params[:bridge][:announcement_code_detect] = code_detect

==== Controlling what happens after announcement ====
The routing script can control what happens with the call after the announcement finishes playing:
* An outgoing call is made
* Incoming call is hung-up
* Do nothing (wait for the incoming call to hang-up)
===== An outgoing call is made =====
This happens when the script has returned matching routes (and did not raise RoutingException)

===== Incoming call is hung-up =====
This happens when the script returns no routes (in which case base_routing will raise RoutingException with cause :no_route).

It also happens when the script explicitly raises RoutingException.

The incoming call will be terminated with the specified cause.
For example
raise RoutingException, :temporary_failure
(See "Reason values" section in this page for list of available causes)

===== Do nothing (wait for the incoming call to hang-up) =====
If a filter raises RoutingException with code :ok, then the incoming call will not be terminated at the end of the announcement play.
Announcement digit collection will remain active if appropriate.
For example:
raise RoutingException, :ok

=== ring_tone ===
params[:bridge][:ring_tone] = "ringing.wav"

Audio file played on the incoming call while waiting for the outgoing call to be answered.

Ring tone playback can also be configured in the Web Portal, from the incoming call's profile (under "Tones and Call Progress Options").

Routing script has precedence over profile (a routing script that fills params[:bridge][:ring_tone] will override the profile's ring tone behavior).

==== ring_tone options ====
===== ring_tone_state =====
params[:bridge][:ring_tone_state] = :alerted

Call state from which ring tone is being played. Available values are:
* '''immediately''': Ring tone starts playing immediately on the incoming leg
* '''accepted''': Ring tone starts playing as soon as outgoing call is accepted
* '''callprogress''': Ring tone starts playing as soon as "call progress" is received on the outgoing call
* '''alerted''' (default): Ring tone starts playing only once outgoing call is alerted (but won't play if alert indicates early media from outgoing call)

This option also apply when params[:bridge][:ring_tone] is not used, because it also apply to ring tone playback configured in the Web Portal, from the incoming call's profile.

=== busy_tone ===
Toolpack 2.8 and above:
params[:bridge][:busy_tone] = "no_route.wav"

Note: Obsolete name (toolpack 2.7.153 and earlier, but still supported in recent releases):
params[:bridge][:call_progress_tone] = "no_route.wav"

Audio file played on the incoming call when outgoing call fails (never answered).

Note that announcement_tone, if used, is played before the outgoing call attempt is made, and thus before the busy_tone.

Busy tone playback can also be configured in the Web Portal, from the incoming call's profile (under "Tones and Call Progress Options").

Routing script has precedence over profile (a routing script that fills params[:bridge][:busy_tone] will override the profile's busy tone behavior).

Special value '''"none"''' can be used by routing script to force playing nothing (as empty string would default to profile's behavior)

==== busy_tone options ====
===== busy_tone_answer =====
params[:bridge][:busy_tone_answer] = "yes"

Forces an answer of the call before playing the busy tone. Default if argument not provided is "no", in which case call is only alerted with in-band media.

=== disconnect_tone ===
params[:bridge][:disconnect_tone] = "max_duration.wav"

Audio file played on the incoming call when call duration (:max_call_duration) is reached. Then the leg will be terminated with specified reason (:call_duration_reason).

==== disconnect_tone options ====
===== max_call_duration =====
params[:bridge][:max_call_duration] = "60000"

Maximum call duration in millisecond. This timer is started when entering answer state.

===== call_duration_reason =====
params[:bridge][:call_duration_reason] = :resource_unavailable

Drop both legs with this reason when call duration (:max_call_duration) is reached.

=== Managing audio prompts through Web Portal ===
Audio prompts can be uploaded or deleted from the TMedia unit through the Web Portal:
[[Toolpack:Configuring_Audio_Prompts_A|Managing audio prompts]]

Prompts management must be done using the Web Portal of the primary server (in systems with redundant TMedia units or redundant host servers).
The file will automatically get replicated to the secondary server.

=== Managing audio prompts manually ===
Any file on the TMedia host file system can be played. This means it's possible to manage prompts through ssh/scp.

==== The default (replicated) prompts folder ====
By default, when playing a prompt, Toolpack will look in the default prompts folder:
/lib/tb/toolpack/pkg/prompts
The root of this "prompts" directory is automatically replicated to secondary unit of redundant setups (1+1, N+1, redundant hosts). Sub-folders won't be replicated.

Any prompt play request without explicit file path will map to this folder. For example:
params[:bridge][:busy_tone] = "no_route.wav"
This will correspond to file /lib/tb/toolpack/pkg/prompts/no_route.wav

==== Relative file paths ====
Any file path that begins with "file://" is considered relative to the tbstreamserver application's working directory:
/lib/tb/toolpack/setup/12358/2.8/apps/tbstreamserver/
(Where "2.8" may be replaced by the current major version of your system)

For example:
params[:bridge][:busy_tone] = "file://my_folder/no_route.wav"
This will correspond to file /lib/tb/toolpack/setup/12358/2.8/apps/tbstreamserver/my_folder/no_route.wav

==== Absolute file paths ====
Absolute paths can also be provided.
For example:
params[:bridge][:busy_tone] = "file:///root/my_folder/no_route.wav"
This will correspond to file /root/my_folder/no_route.wav

== Recording call legs ==
Introduced in release 2.6.44, it's now possible to use routing scripts to ask for recording incoming and/or outgoing call legs.

See example filter script "call_recording" (created by default in Web Portal routing scripts starting with 2.6.44) for an example.

=== Recording the incoming call leg ===
To record the incoming call leg, the routing script (in a "after filter" for example) has to set the following parameter:

bridge[ :record_incoming ] = ""

=== Recording the outgoing call leg ===
To record the outgoing call leg, the routing script (in a "after filter" for example) has to set the following parameter, per route (the decision to record or not, or the file name to record to, can be set per matching route):

# Need to clone the routes in order to have the right to modify them
routes = clone_routes params[:routes]
routes.each do |route|
route[ :record_outgoing ] = ""
end
# Store modified routes back to the parameters for this outgoing call
params[:routes] = routes

=== Record the outgoing call leg within incoming leg's recorded file (mixing) ===
[...]
route[ :record_outgoing ] = "@{MixWithIncoming}"
[...]

=== Choosing file path to record to ===
The value assigned to ":record_incoming" or ":record_outgoing" is the path to record the file to.

The paths can be absolute, or relative. When relative, they are relative to the "tbstreamserver" application working directory, for example:
/lib/tb/toolpack/setup/12358/2.7/apps/tbstreamserver/

* Empty file name will default to a name that contains various information about the call:
** ''LinkId'': Id common between all legs of this call bridge
** ''LegId'': Unique Id for this leg
** ''Nap'': Current NAP name this call leg is from
** ''Direction'': "IN" or "OUT" (depends if call leg is incoming or outgoing leg)
** ''Calling'': The calling number of this call leg
** ''Called'': The called number of this call leg
** ''Protocol'': The signaling protocol of this call leg (SS7, ISDN, CAS, SIP)
** ''Media info'': Codec + IP/Port for SIP calls, Trunk/Timeslot for TDM calls
* To record outgoing call leg in the same audio file as incoming call leg (mixing), use the following:
** @{MixWithIncoming}: Record outgoing legs in same file as incoming legs
* Variables can be used to insert in the recording path information that's not already available from routing scripts:
** @{CURRENT_PKG}: Version of current package
*** Example: 2.6.45
** @{DATE format}: Prints the date, where 'format' is expressed as described for the 'strftime' function
*** Example: @{DATE %Y-%m-%d} => 2013-01-28
** @{DefaultName}: Replaced by the default file name for recording, which contains:
*** LinkId: Id common between all legs of this call bridge
*** LegId: Unique Id for this leg
*** Nap: Current NAP name this call leg is from
*** Direction: "IN" or "OUT" (depends if call leg is incoming or outgoing leg)
*** Calling: Calling number
*** Called: Called number
*** Protocol: Protocol type of this call (SS7, ISDN, CASR2, SIP)
*** Media info: Codec + IP/Port for SIP calls, Trunk/Timeslot for TDM calls
*** Example: "73EBA698-F3D67B4B-NAP_SS7-IN-5550000-5550001-SS7-TRUNK_BELL_11-24.wav"
*** Example: "73EBA698-73EBA698-NAP_SIP-OUT-5550000-5550001-SIP-G723-10.3.10.101-1050.wav"
** @{DefaultPath}: Default recording folder and file name: "@{RECORD_PATH}/@{DATE %Y-%m-%d}/@{DefaultName}"
*** Example: "/lib/tb/toolpack/setup/12358/recorded_calls/73EBA698-F3D67B4B-NAP_SS7-IN-5550000-5550001-SS7-TRUNK_BELL_11-24.wav"
*** Example: "/lib/tb/toolpack/setup/12358/recorded_calls/73EBA698-73EBA698-NAP_SIP-OUT-5550000-5550001-SIP-G723-10.3.10.101-1050.wav"
** @{Direction}: Direction of current leg (IN our OUT)
*** Example: IN
** @{LegId}: Current LegId (Unique Id for this leg)
*** Example: F3D67B4B
** @{LinkId}: Current LinkId (Id common between all legs of this call bridge)
*** Example: 73EBA698
** @{PKG_HOME}: Path where packages are stored.
*** Note: It's not recomended to use that path on redundant systems, package file replication may cause confusion in recorded files.
*** Example: /lib/tb/toolpack/pkg
** @{PROMPT_PATH}: Default path where audio prompts are stored
*** Note: It's not recomended to use that path on redundant systems, package file replication may cause confusion in recorded files.
*** Example: /lib/tb/toolpack/pkg/prompts
** @{Protocol}: Protocol of current leg
*** Example: SS7
** @{RECORD_PATH}: Default recording folder: "@{TB_SETUP_HOME}/recorded_calls/"
** @{TBX_GW_PORT}: Current "System Id" (also called "Gateway Port")
*** Example: 12358
** And all variables listed here: [[Customer_application_framework:play_audio_files#Helpful_variables_to_build_play_or_record_file_paths|Building play or record file path]]

== Controlling UUI (user-to-user information) relay ==
UUI (user-to-user information) can be present in different messages received by either call leg during a call. For example, information can be carried during the initial invite, other information can be carried when the call is alerted, answered, or terminated.

Routing scripts can control if the UUI received from one leg through the call will be forwarded to the other call leg:
*uui_forward_enabled

Routing scripts can also read and modify the UUI received with the incoming call leg, before it gets forwarded upon creation of the outgoing call leg:
*uui

=== UUI (user-to-user indication) values ===

Byte array represented as ruby String. Use ''bridge=params[:bridge]'', then ''bridge[:uui]'' to access the data.

To access the bytes in Ruby, use ruby String operator []. For example: bridge[:uui][0] will return the binary value of the first UUI byte.

Function each_byte can also be useful to iterate through all bytes of the UUI.

=== uui_forward_enabled values ===

Controls forwarding or discarding of UUI to outgoing call leg.

Values for this parameter are "0", "1", "false" or "true.
* 0/false: UUI is not forwarded between call legs
* 1/true: UUI is forwarded between call legs

The value for this parameter at input of routing script depends on the "Forward UUI" parameter in the "Advanced" section of the Gateway configuration page of the Web Portal. The script may change this value to override the Gateway configuration.

== Authorization ==
Starting with release 2.7, it is possible to issue RADIUS authorization requests from routing scripts. To do so, the params[:authorization] object must be filled with the required RADIUS attributes and [[#Refuse|an exception must be raised]] with reason :authorization_required.

When the authorization is completed, the routing script is called again with the result. The params[:authorization] object will be filled with the RADIUS attributes from the response. The params[:authorization][:result] field will also contain a string indicating the result of the authorization:

* ''accept'': The authorization was successful.
* ''reject'': The authorization was refused.
* ''challenge'': The authorization was challenged.
* ''timeout'': The authorization was not answered.

== Call diversion options ==
It's possible to control the call flow when a call diversion information is received in the alerting state.

Two fields are available: bridge[ :diversion ] and bridge[ :diversion_reason ]

The internal release cause TOOLPACK_DIVERT_NOT_ALLOWED is used by gateway application to terminate both legs.

bridge[ :diversion ] = :allowed
The alert message will not be analyzed and the call will be progressed. Default behavior.
bridge[ :diversion ] = :not_allowed
If the alert message indicates that the call is diverted, the call will be released no matter the In-band information to allow
early media.
bridge[ :diversion ] = :not_allowed_w_early_media
The call will be released If the alert message indicates that the call is diverted with in-band information to allow early media.
bridge[ :diversion_reason ] = "*"
If the diversion is not allowed, the gateway will drop the call for any redirecting reason.
bridge[ :diversion_reason ] = "0,1,2"
or
bridge[ :diversion_reason ] = "unknown,busy,no_reply"
If the diversion is not allowed, the redirecting reason will be analyzed and the call will only be dropped for the configured cases.

See section [[Routing_script_tutorial:Mini_Development_Guide#Redirecting_number,_Original_Called_Number_and_Diversion_Reason|Redirecting number reason values]].

== Call transfer requests ==
Toolpack allows that [[Call transfer]] requests are relayed from one leg to the other, or to process them locally (making another outgoing call to replace the call that requested the call transfer).

If the chosen [[Call transfer]] mode is to process requests locally, upon reception of a call transfer request (SIP REFER or ISDN Facility), routing script will be called once again, to select the routes for the new outgoing call (call transfer target).

=== How to route call transfer request ===
Routing of a call transfer request is done exactly like routing of a normal incoming call.
The routing script generally does not need any modification to support that.

In some cases, the routing script may want to use information related to the transfer request to perform routing, or to insert information in the outgoing call leg.
Additional information is provided to the routing script, allowing routing decisions using information from the call transfer request (SIP REFER or ISDN Facility).
See below...

=== params[ :call ] content during transfer request ===
When processing a call transfer request, the params[ :call ] hash contains the information from the inbound call (same as was passed to the routing script upon arrival of the inbound call)
call = params[ :call ] -> Information from original inbound call, with exception of call[ :called ]

One exception (convenient because it allows a unmodified routing script to process call transfer request the same way as any other routing request):
call[ :called ] -> Replaced by the called number from the call transfer request (also called "redirection number")
Complementary information:
call[ :original_called_number ] -> Contains the called number that was initially received from the incoming call, prior to call transfer request
call[ :redirecting_number ] -> Number of the call from which the call transfer request was received (generally equals to original_called_number)

These fields will also be included in the outgoing call made after routing:
* original called number and redirecting number are existing fields on SS7 and ISDN calls
* SIP "diversion" header is used for SIP calls

=== params[ :transfer ] content ===
(this if valid only for release 2.7.102 and above) 
When processing a call transfer request, information from the call transfer request message (SIP REFER, ISDN Facility) is provided in params[ :transfer ]:
transfer = params[ :transfer ]
The following field is always present:
transfer[ :original_nap ] -> Contains the NAP of the first call from which a call transfer request was received
transfer[ :redirecting_nap ] -> Contains the NAP of the call from which the current call transfer request was received
(same as :original_nap for the first call transfer, different for subsequent transfers)
Examples of other fields that may be present, when appropriate:
transfer[ :uui ] -> The UUI (user-to-user information) found in the call transfer request
transfer[ :sip_header ] -> Contains custom SIP headers from the call transfer request
transfer[ :request_uri ] -> Contains the SIP Request URI

These fields are 'read-only'. They will not be included in the outgoing call, as they represent the contents of the call transfer request, and not the outgoing call to be made.

To insert/modify attributes of the outgoing call, the parameters from params[ :call ] must be edited instead.

== Redirection ==
In release 2.8 and above, redirection contacts are obtained from the routing engine in the following format:

contacts = params[ :contacts ]
contacts = {
:index=>"3",
:list=>[
{:called_number=>"6660", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"", :raw_data=>"", :expiration=>"3600"},
{:called_number=>"6661", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6661@192.168.215.127", :raw_data=>"<sip:6661@192.168.215.127>", :expiration=>"3600"}
{:called_number=>"6662", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6662@192.168.215.128", :raw_data=>"<sip:6662@192.168.215.128>", :expiration=>"3600"},
{:called_number=>"6663", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6663@192.168.215.129", :raw_data=>"<sip:6663@192.168.215.129>", :expiration=>"3600"},
{:called_number=>"6664", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6664@192.168.215.150", :raw_data=>"<sip:6664@192.168.215.150>", :expiration=>"3600"}
],
:source_indexes=>"nil,0,0,0,2"
}

* <code>params[:contacts][:list]</code> contains the contact log. Each contact within the list has the following fields:
** <code>:called_number</code> - the called number
** <code>:is_number_ported</code> - if the called number has been ported (for SIP: if the npdi parameter is present)
** <code>:ported_number</code> - the called number that was ported (for SIP: the rn parameter value, if available)
** <code>:sip_uri</code> - the SIP URI of the contact, without the contact-params section (without the expires and q contact parameters)
** <code>:raw_data</code> - the raw data representing the contact in the signaling protocol. For SIP, this is the full SIP URI (including the expires and q contact parameters).
** <code>:priority</code> - the priority of the contact [0-1000]
** <code>:expiration</code> - the expiration time in seconds of the contact
* <code>params[:contacts][:index]</code> contains the index of the contact that is currently being routed.
* <code>params[:contacts][:source_indexes]</code> contains a comma-separated list of indexes from <code>params[:contacts][:list]</code>. Each index represents the contact from which the contact in the list was obtained from.

To get more information, see:
*[[Routing_script_tutorial:SIP_Redirection_Contacts|SIP Redirection Contacts Parameters in a Call Flow]]

== Connected number ==
Insert a connected number in the answer message of the call flow.

Routing script example:
bridge = params[ :bridge ]
bridge [ :connected_number ] = "3335577"
bridge [ :connected_number_noa ] = :national_number
bridge [ :connected_number_npi ] = :private
bridge [ :connected_number_presentation ] = :allowed
bridge [ :connected_number_screening ] = :pass

== Terminating calls ==
In release 2.8, it is now possible to terminate a call through the routing scripts. The [[#Reason values|reason code]] must be specified in <code>params[:bridge][:reason]</code>. The <code>:terminate</code> hash must be created and copied into <code>params</code>:
terminate = {}
params[:terminate] = terminate
The following fields can then be set in <code>:terminate</code>:
* <code>:sip_header</code>
* <code>:contacts</code> # list of contacts as described in the [[#Redirection|redirection]] section
* <code>:isup_raw</code>
* <code>:isup_raw_variant</code>
* <code>:redirecting_number</code>
* <code>:redirecting_number_noa</code>
* <code>:redirecting_number_npi</code>
* <code>:redirecting_number_presentation</code>
* <code>:redirecting_number_reason</code>
* <code>:redirecting_number_counter</code>
* <code>:redirecting_number_indicator</code>
* <code>:original_called_number</code>
* <code>:original_called_number_noa</code>
* <code>:original_called_number_npi</code>
* <code>:original_called_number_presentation</code>
* <code>:original_called_number_reason</code>
* <code>:original_called_number_counter</code>

== Reason values ==

Check here for Termination Reason Cause codes: 

[[Termination_cause_codes|Termination Reason Cause codes]]
 

Example to refuse an incoming call leg.
raise RoutingException, :no_route

Reason cause strings available inside routing scripts:

List of Q.850 reason causes:
:unallocated_number
:no_route_to_network
:no_route_to_destination
:send_special_tone
:misdialled_trunk_prefix
:channel_unacceptable
:call_awarded_in_established_channel
:preemption
:reattempt
:qor_ported_number
:normal_call_clearing
:user_busy
:no_user_responding
:no_answer_from_user
:subscriber_absent
:call_rejected
:number_changed
:redirection
:exchange_routing_error
:non_selected_user_clearing
:destination_out_of_order
:address_incomplete
:facility_rejected
:response_to_status_enquiry
:normal_unspecified
:no_circuit_available
:network_out_of_order
:frame_mode_out_of_service
:frame_mode_connection_operational
:temporary_failure
:switching_equipment_congestion
:access_information_discarded
:requested_circuit_not_available
:precedence_call_blocked
:resource_unavailable
:quality_of_service_not_available
:requested_facility_not_subscribed
:outgoing_calls_barred
:outgoing_calls_barred_within_cug
:incoming_calls_barred
:incoming_calls_barred_within_cug
:bearer_cap_not_authorized
:bearer_cap_not_available
:inconsistency_access_info
:service_not_available
:bearer_cap_not_implemented
:channel_type_not_implemented
:requested_facility_not_implemented
:only_restricted_digital_info
:service_not_implemented
:invalid_call_reference
:channel_does_not_exist
:call_identity_does_not_exist
:call_identity_in_use
:no_call_suspended
:call_has_been_cleared
:user_not_member_of_cug
:incompatible_destination
:non_existant_cug
:invalid_transit_network
:invalid_message_unspecified
:mandatory_ie_missing
:message_type_non_existent
:message_not_compatible_with_call_state
:ie_non_existent
:invalid_ie_content
:msg_not_compatible_with_call_state
:recovery_on_timer_expiry
:parameter_non_existent_passed_on
:message_with_non_recognized_parameters_discarded
:protocol_error
:interworking_unspecified

List of toolpack reason causes:

:toolpack_normal or :normal
:toolpack_resource_error or :resource_error
:toolpack_timeout or :timeout
:toolpack_no_route or :no_route
:toolpack_call_collision or :call_collision
:toolpack_sync_drop or :sync_drop
:toolpack_signaling_error or :signaling_error
:toolpack_locally_rejected or :locally_rejected
:toolpack_interface_not_available or :interface_not_available
:toolpack_reset_in_progress or :reset_in_progress
:toolpack_adapter_reject or :adapter_reject
:toolpack_missing_or_invalid_ie or :missing_or_invalid_ie
:toolpack_incoming_only or :incoming_only
:toolpack_system_configuration_changed or :system_configuration_changed
:toolpack_resource_no_more_available or :resource_no_more_available
:toolpack_incompatible_media or :incompatible_media
:toolpack_resource_allocation_failed or :resource_allocation_failed
:toolpack_data_path_not_available or :data_path_not_available
:toolpack_local_congestion or :local_congestion
:toolpack_authorization_required or :authorization_required
:toolpack_call_divert_is_not_allowed or :call_divert_is_not_allowed

List of SIP reason causes: 
Reason causes starting with a digit must use the following syntax (can't use : as prefix).

'300_multiple_choices'
'301_moved_permanently'
'302_moved_temporarily'
'305_use_proxy'
'380_alternative_service'
'400_bad_request'
'401_unauthorized'
'402_payment_required'
'403_forbidden'
'404_not_found'
'405_method_not_allowed'
'406_not_acceptable'
'407_proxy_authentication_required'
'408_request_timeout'
'409_conflict'
'410_gone'
'413_request_entity_too_large'
'414_request_URI_too_long'
'415_unsupported_media'
'416_unsupported_URI_scheme'
'420_bad_extension'
'421_extension_required'
'422_session_timer_too_small'
'423_interval_too_brief'
'429_referrer_identity_error'
'480_temporary_unavailable'
'481_call_or_transaction_does_not_exist'
'482_loop_detected'
'483_too_many_hops'
'484_address_incomplete'
'485_ambiguous'
'486_busy_here'
'487_request_terminated'
'488_not_acceptable_here'
'489_bad_event'
'491_retry_after'
'500_server_internal_error'
'501_not_implemented'
'502_bad_gateway'
'503_service_unavailable'
'504_server_timeout'
'505_version_unsupported'
'513_message_too_large'
'600_busy_everywhere'
'603_decline'
'604_not_exist_anywhere'
'606_not_acceptable'

== Nap status ==

All the status fields of the NAPs are provided for use by the routing scripts. See the nap status provider for more details on which fields are available in the CEngineStatTransNap.hpp file.

'''Notice:''' These values may change between major release.

Routing script call attribute name Description
--------------------------------------------------------------------------------------------
"name" NAP name.
"signaling_type" Signaling type (SS7, ISDN, CASR2, SIP)
"profile" Profile name.
"sip_destination_ip" Destination IP address.
"sip_destination_port" Destination IP port.
"sip_transport_type" SIP transport type (:udp, :tcp, or :tls) (Toolpack 3.1 and more)
"inst_incoming_call_cnt" Instantaneous Count of incoming calls.
"inst_outgoing_call_cnt" Instantaneous Count of outgoing calls.
"available_cnt" Number of available circuits or channels.
"unavailable_cnt" Number of unavailable circuits or channels.
"availability_percent" Percentage of available circuits or channels.
"usage_percent" Percentage of used circuits or channels.
"unused_shared_percent" Percentage of used circuits or channels of this NAP available to make new calls with (taking into account shared with other NAPs)
"total_incoming_call_cnt" Total Count of incoming calls.
"global_asr_percent" Global calculated ASR percentage.
"total_outgoing_call_cnt" Total Count of outgoing calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_outgoing_call_cnt" Last 24 hours outgoing calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_outgoing_call_cnt" Current hour outgoing calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_outgoing_call_cnt" Last hour outgoing calls.
"poll_remote_proxy" Remote proxy polling enabled
"is_available" Remote proxy actually available or not
"time_since_polling" Time since the last availibility polling
"time_available_seconds" Number of seconds since the NAP is available
"time_unavailable_seconds" Number of seconds since the NAP is unavailable
"register_to_proxy" Register to proxy enabled
"registered" Actually registered or not
"time_since_refresh" Time since the last refresh
"time_registered_seconds" Number of seconds since the NAP is registered
"time_not_registered_seconds" Number of seconds since the NAP is not registered
"asr_stats_incoming_struct" Detailed Answer-Seizure Rate incoming statistics.
{
"global_asr_percent" Global calculated ASR percentage.
"total_call_cnt" Total count of calls.
"total_accepted_call_cnt" Total count of accepted calls (not dropped due to congestion or rate-limiting).
"total_answered_call_cnt" Total count of answered calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_call_cnt" Last 24 hours count of calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_call_cnt" Current hour count of calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_call_cnt" Last hour count of calls.
}
"asr_stats_outgoing_struct" Detailed Answer-Seizure Rate outgoing statistics.
{
"global_asr_percent" Global calculated ASR percentage.
"total_call_cnt" Total count of calls.
"total_accepted_call_cnt" Total count of accepted calls (not dropped due to congestion or rate-limiting).
"total_answered_call_cnt" Total count of answered calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_call_cnt" Last 24 hours count of calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_call_cnt" Current hour count of calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_call_cnt" Last hour count of calls.
}
"mos_struct" Detailed Mean Opinion Score statistics.
{
"last_24h_ingress" Last 24 hours calculated MOS for incoming RTP packets.
"last_24h_egress" Last 24 hours calculated MOS for outgoing RTP packets.
"current_hour_ingress" Current hour calculated MOS for incoming RTP packets.
"current_hour_egress" Current hour calculated MOS for outgoing RTP packets.
"last_hour_ingress" Last hour calculated MOS for incoming RTP packets.
"last_hour_egress" Last hour calculated MOS for outgoing RTP packets.
}
"network_quality_struct" Detailed network quality statistics.
{
"last_24h_ingress" Last 24 hours network quality percentage for incoming RTP packets.
"last_24h_egress" Last 24 hours network quality percentage for outgoing RTP packets.
"current_hour_ingress" Current hour network quality percentage for incoming RTP packets.
"current_hour_egress" Current hour network quality percentage for outgoing RTP packets.
"last_hour_ingress" Last hour network quality percentage for incoming RTP packets.
"last_hour_egress" Last hour network quality percentage for outgoing RTP packets.
}

 If the nap status is part of a substructure, the substructure will be a hash containing all subfield elements.

Example to access the signaling type and the number of incoming call count for the NAP of the current call:

incoming_nap = params[:naps][ params[:call][ :nap ].to_sym]
log_trace 4,"Incoming NAP parameters=" + incoming_nap.inspect
log_trace 4,"Incoming NAP signaling type=" + incoming_nap[:signaling_type].inspect
log_trace 4,"Incoming NAP call cnt=" + incoming_nap[:asr_stats_incoming_struct][:total_call_cnt].inspect

 It is also possible to add dynamic nap attributes in the web portal. These can be referenced by their name.

== Telephony Services ==
In release 2.10 and the above, telephony services (CNAM Request) can be manage from the routing engine in the following format:

params[:telephony_services].each do |service| -> Array of telephony services
service[:name] -> Customer telephony service name
service[:type] -> For now only "CNAM Request"
service[:enabled] -> Indicate if the service is enabled (true) or not (false)
(Only the telephony service define in the profile associated to the NAP is enabled)
(The others telephony services define in others profiles are disabled)
(If we are in the case where we return in the routing script with a response, it is important to set :enabled to false in order to avoid repeating the same query)
serviceParams = service[:params]
serviceParams[:return_to_script] -> Indicates to Gateway if we must return to the routing script after receiving the CNAM response
(It is important to set back to false this field to avoid an infinite loop)
serviceQuery = service[:query]
serviceQuery[:phone] -> 10 digits of calling number from the incoming call to send to the CNAM server
serviceQuery[:timeout] -> Timeout in millisecond to wait a CNAM response from CNAM server
(Default value from profile configuration)
serviceResponse = service[:response]
serviceResponse[:success] -> Indicates if we received a good CNAM response from the CNAM Server (Only present if :return_to_script is set to true)
serviceResponse[:caller_name] -> The caller name received in the CNAM response from the CNAM Server (Only present if :return_to_script is set to true)

== Custom user context ==
The routing script may '''save per-call information within the call context''', that will be available if routing is called again later during the call flow.

Cases where routing is called multiple time for the same call are:
- Call transfer requests
- SIP redirect requests
- Radius Authorization result
- Announcement server with digit collection

The routing script can save a recursive hash of attributes here:
params[:user_context]

For example
params[:user_context] = { "SomeKey" => "Some value I want to retrieve upon next routing for this call", "OtherVal" => { "subkey" => "subval" } }

Upon first call to routing script, params[:user_context] will be nil.
Upon subsequent calls to routing script, it will contain whatever the script had stored upon previous call (or nil if it was not set)

Note: This feature is available starting from release 2.9.85, 2.10.31 and 3.0.15 (in respective branches 2.9, 2.10 or 3.0)

== Routing Script Tests ==
The Web portal features a tool for Testing Scripts. The user must enter parameters to simulate the incoming call and after pressing the Test button, will output selected routes and numbers. You do not need to activate the new routes, or the new scripts to use this test tool: It can be used to test the routing scripts and routing table before activating it.
This is available in the Routing Scripts section of the Web portal.

=== Test parameters ===
==== @call_params ====

That variable should contain a hash of call parameters that will be passed to the routing script. This is equivalent to the incoming call parameters.

 

==== @nap_list ====

A list of the hash containing the nap statuses. This is equivalent to the nap statuses at the time the call is to be routed.

'''The nap list is hashed by the nap names in UPPERCASE.''' It is important to consider this when creating new dynamic route or nap attributes that may nap names that will be used to fetch a status.

 

==== @params ====

A hash of hashes containing parameters. This hash contains bridge parameters and other kind of parameter groups may be added in the future.

@params = {
:bridge => {:announcement_tone, "announcement.wav"},
:contacts => {
:index=>"1",
:list=>[
{:called_number=>"6660", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"",
:raw_data=>"", :expiration=>"3600"},
{:called_number=>"6661", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6661@192.168.215.127",
:raw_data=>"<sip:6661@192.168.215.127>", :expiration=>"3600"}
],
:source_indexes=>"nil,0"
}
}

 

----

 Back to [[Routing script tutorial|Routing Script Tutorial]].

Routing script tutorial:Mini Development Guide

2019-04-04T20:20:21Z

Abrassard: /* Script parameters protocol mapping */

== Call object ==

=== Get ===

This function is used to get the call parameters. The possible parameters are described in the section "Call parameters"

called_number = caf_call.get :called

=== List_params ===

This function is used to retrieve the list of supported call parameters. For example to extract all the possible call parameters from the the call object and put it in hash.

caf_call.list_params.each {|param| call[param] = caf_call.get param }

=== Accept ===

This function is used to accept a call. It actually creates one outgoing route that the gateway application will use to bridge the incoming call leg. If more than one outgoing route is "accepted", the gateway will try them one by one in the same order that they were accepted. If an outgoing call leg fails (according to 'route retry' parameters), the next route in line will be used.

This method takes 2 arguments, the call parameters (hash) and the route parameters (hash). Note that calling this method does NOT stop the flow of the script.

Apply route remapping rules

caf_call.accept out_call, route

=== Refuse ===

This function is used to set the reason code for the incoming call leg refusal. However, this function does NOT stop the flow of the script.

caf_call.refuse :reason => :temporary_failure

To immediately refuse the incoming call leg and stop processing the script, the script must raise an exception. Exiting the script by raising the exception overwrites any reason cause previously stored using refuse().

raise RoutingException, :no_route

The supported refusal cause values for both refuse() and raise() are described in the section "[[Routing_script_tutorial:Mini_Development_Guide#Reason_values|Reason values]]".

=== Script parameters protocol mapping ===

The following call parameters are available in the call object. For example:

called_number = call[:called]

For information on how to use and remap call parameters, see [[Toolpack:_How_to_Use_RegEx_in_Remapped_Called_and_Calling_Number_Mask | How to use regex in Remapped Called and Calling Number Mask]]

{| cellspacing="1" cellpadding="1" border="1" style="width: 921px; height: 805px;"
|-
! scope="col" | '''Script parameter name'''
! scope="col" | '''ISDN '''
! scope="col" | '''R2 CAS''' 
! scope="col" | '''SS7 '''
! scope="col" | '''SIP '''
! scope="col" | '''Comment '''
! scope="col" | '''Toolpack version '''
|-
| leg_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Leg ID 
| 
|-
| session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Session ID 
| 
|-
| original_session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Original Session ID (before call transfer or redirections) 
| 
|-
| calling 
| Q931: 'Calling party number' IE - Number digits 
| ANI (Group B) 
| Q763: 'Calling party number' IE - address signals (*) 
| SIP:From - user-info 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead. 
| 
|-
| calling_sip_host 
| N/A 
| N/A 
| N/A 
| SIP:From - host (domain or IP) 
| For example : The 'telcobridges.com' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| calling_sip_port 
| N/A 
| N/A 
| N/A 
| SIP:From - port 
| For example : The '6060' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| calling_noa 
| Q931: 'Calling party number' IE - Type of number 
| N/A 
| Q763: 'Calling party number' IE - nature of address indicator (*) 
| N/A 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead 
| 
|-
| calling_npi 
| Q931: 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: 'Calling party number' IE - numbering plan indicator (*) 
| N/A 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead 
| 
|-
| calling_display 
| Q931: 'Display' IE - Display information 
Q931: 'Facility CNAM' IE when presentation is allowed for DMS/NI2 variants 
| N/A 
| Q763
ITU97: 'Display information' IE - display information
ANSI95: 'Generic name' IE - display information
| SIP:From - display-name 
| 
| 
|-
| calling_display_type 
| Q931: 'Display' IE - Display information (present and/or first byte) 
| N/A 
| Q763: 'Display information' IE - present or not 
| N/A 
| 
| 
|-
| calling_presentation 
| Q931: 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: 'Calling party number' IE - address presentation restricted indicator 
|
SIP:From - display-name (displays 'anonymous' or not)

SIP:Remote-party-id - privacy 

| 
| 
|-
| calling_screening 
| Q931: 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: 'Calling party number' IE - screening 
| SIP:Remote-party-id - screen 
| 
| 
|-
| calling_category 
| N/A 
| Call party category (Group A) 
| Q763: 'Calling party's category' IE - calling party's category 
|
SIP:From - cpc

SIP:P-asserted-identity - cpc 

| 
| 
|-
| calling_subscriber
(Generic Number / NDS) 
| Q931: 2nd 'Calling party number' IE - Number digits 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - Number digits 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| Requires option 'support 2 calling number IE' in the profile. This variable has priority over 'private_address' in the outgoing direction. 
| 
|-
| calling_subscriber_noa 
| Q931: 2nd 'Calling party number' IE - Type of number 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - nature of address indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_npi 
| Q931: 2nd 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - numbering plan indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
 
| 
|-
| calling_subscriber_presentation 
| Q931: 2nd 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - presentation restricted indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_screening 
| Q931: 2nd 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - screening 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| private_display 
| Q931: 'Facility CNAM' IE when presentation is restricted for DMS/NI2 variants 
| N/A 
| N/A 
|
SIP:P-asserted-identity - display-name 

SIP:Remote-party-id - display-name 

| 
| 
|-
| private_display_type 
| N/A 
| N/A 
| N/A 
| N/A 
| Indicate presence or not of the private calling information 
| 
|-
| private_address 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 

| For example : The 'fluffy' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_sip_host 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - host (domain or IP)

SIP:Remote-party-id - host (domain or IP) 

| For example : The 'telcobridges.com' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_sip_port 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - port

SIP:Remote-party-id - port 

| For example : The '6060' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| called 
| Q931: 'Called party number' IE - Number digits 
| DNIS (Group A) 
| Q763: 'Called party number' IE - address signals 
| SIP:To - user-info and host 
| 
| 
|-
| called_sip_host 
| N/A 
| N/A 
| N/A 
| SIP:To - host 
| For example : The 'telcobridges.com' in To: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| called_sip_port 
| N/A 
| N/A 
| N/A 
| SIP:To - port number 
| For example : The '6060' in To: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| called_noa 
| Q931: 'Called party number' IE - Type of number 
| N/A 
| Q763: 'Called party number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| called_npi 
| Q931: 'Called party number' IE - Numbering plan identification 
| N/A 
| Q763: 'Called party number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| charge_number 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - address signals 
| N/A 
| 
| 
|-
| charge_number_noa 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| charge_number_npi 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| redirecting_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default redirecting number and original called number forwarding behavior from incoming to outgoing leg 
| 
|-
| redirecting_number 
| Q931: 'Redirecting number' 1st IE - Number digits 
| N/A 
| Q763: 'Redirecting number' IE - address signals 
| SIP:Diversion (2nd header) - display-name 
| 
| 
|-
| redirecting_number_noa 
| Q931: 'Redirecting number' 1st IE - Type of number 
| N/A 
| Q763: 'Redirecting number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| redirecting_number_npi 
| Q931: 'Redirecting number' 1st IE - Numbering plan identification 
| N/A 
| Q763: 'Redirecting number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| redirecting_number_presentation 
| Q931: 'Redirecting number' 1st IE - Presentation indicator 
| N/A 
| Q763: 'Redirecting number' IE - address presentation restricted indicator 
| SIP:Diversion (2nd header) - diversion-privacy 
| 
| 
|-
| redirecting_number_indicator 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirecting indicator 
| N/A 
| 
| 
|-
| redirecting_number_reason 
| Q931: 'Redirecting number' 1st IE - Reason for redirection 
| N/A 
| Q763: 'Redirection information' IE - redirecting reason 
| SIP:Diversion (2nd header) - diversion-reason 
| 
| 
|-
| redirecting_number_counter 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirection counter 
| SIP:Diversion (2nd header) - diversion-counter 
| 
| 
|-
| original_called_number
(OCN) 
| Q931: 'Redirecting number' 2nd IE - Number digits 
| N/A 
| Q763: 'Redirection number' IE - address signals 
| SIP:Diversion  (1st header) - display-name 
| 
| 
|-
| original_called_number_noa 
| Q931: 'Redirecting number' 2nd IE - Type of number 
| N/A 
| Q763: 'Redirection number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| original_called_number_npi 
| Q931: 'Redirecting number' 2nd IE - Numbering plan identification 
| N/A 
| Q763: 'Redirection number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| original_called_number_presentation 
| Q931: 'Redirecting number' 2nd IE - Presentation indicator 
| N/A 
| Q763: 'Redirection number' IE - address presentation restricted indicator 
| SIP:Diversion (1st header) - diversion-privacy 
| 
| 
|-
| original_called_number_reason 
| Q931: 'Redirecting number' 2nd IE - Reason for redirection 
| N/A 
| Q763: 'Redirection information' IE - original redirection reason 
| SIP:Diversion (1st header) - diversion-reason 
| 
| 
|-
| original_called_number_counter 
| N/A 
| N/A 
| N/A 
| SIP:Diversion (1st header) - diversion-counter 
| 
| 
|-
| ported_number_npdi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - with qualifier=Ported number is present 
| SIP:RequestURI - npdi=yes is present 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number 
| N/A 
| N/A 
| Q763: 'Generic number' IE - address signals with qualifier=Ported number 
| SIP:RequestURI - to user part when rn is present 
| rn is stored in the called number 
| 
|-
| ported_number_noa 
| N/A 
| N/A 
| Q763: 'Generic number' IE - nature of address indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number_npi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - numbering plan indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| oli
(Originating line information) 
| 5ESS Codeset 6 OLI - Value 
| N/A 
| ANSI: 'Originating line information' IE - OLI 
|
SIP:From - oli

SIP:P-asserted-identity - oli 

| 
| 
|-
| request_uri 
| N/A 
| N/A 
| N/A 
| Complete Request URI string 
| 
| 
|-
| request_uri_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default URI forwarding behavior from incoming to outgoing leg 
| 
|-
| sip_header 
| N/A 
| N/A 
| N/A 
| Any header 
| Requires option 'Forward custom headers' in Profiles->SIP 
| 2.7.63 
|-
| nap
(Network Access Point) 
| N/A 
| N/A 
| N/A 
| N/A 
| Incoming leg NAP name (read-only) 
| 
|-
| type_of_network_identification 
| Q931: 'Transit network selection' IE - Type of network identification 
| N/A 
| Q763: 'Transit network selection' IE - Type of network identification 
| N/A 
| 
| 2.7 
|-
| network_identification 
| Q931: 'Transit network selection' IE - Network identification 
| N/A 
| Q763: 'Transit network selection' IE - Network identification 
| SIP: Request-Line - cic 
| 
| 2.7 
|-
| network_identification_plan 
| Q931: 'Transit network selection' IE - Network identification plan 
| N/A 
| Q763: 'Transit network selection' IE - Network identification plan 
| N/A 
| 
| 2.7 
|-
| location_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default location number forwarding behavior from incoming to outgoing leg 
| 2.7 
|-
| location_number 
| N/A 
| N/A 
| Q763: 'Location number' IE - address signals 
| N/A 
| 
| 2.7 
|-
| location_number_noa 
| N/A 
| N/A 
| Q763: 'Location number' IE - nature of address indicator 
| N/A 
| 
| 2.7 
|-
| location_number_npi 
| N/A 
| N/A 
| Q763: 'Location number' IE - numbering plan indicator 
| N/A 
| 
| 2.7 
|-
| location_number_presentation 
| N/A 
| N/A 
| Q763: 'Location number' IE - presentation restricted indicator 
| N/A 
| 
| 2.7 
|-
| location_number_screening 
| N/A 
| N/A 
| Q763: 'Location number' IE - screening 
| N/A 
| 
| 2.7 
|-
| mlpp_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| A script needs to set this to true if it wants to overwrite MLPP information in the outgoing leg. Otherwise, profile relay 'outgoing mode' applies automatically. 
| 2.7 
|-
| mlpp_look_for_busy 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - look ahead for busy 
| N/A 
| 
| 2.7 
|-
| mlpp_precedence_level 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - precedence level 
| SIP:Resource-Priority - q735 
| 
| 2.7 
|-
| mlpp_network_identity 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - network identity 
| N/A 
| 
| 2.7 
|-
| mlpp_service_domain 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - MLPP service domain 
| N/A 
| 
| 2.7 
|-
| called_isub 
| Q931: 'Called party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub parameter 
| 
| 2.7 
|-
| called_isub_type 
| Q931: 'Called party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub-encoding parameter 
| 
| 2.7 
|-
| calling_isub 
| Q931: 'Calling party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub 
| 
| 2.7 
|-
| calling_isub_type 
| Q931: 'Callinf party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub-encoding 
| 
| 2.7 
|-
| ss7_fci_default 
| N/A 
| N/A 
| Default forward call indicator (FCI) value. 
| N/A 
| Toolpack will overwrite FCI bits A, D, F, I and M with appropriate values according to call conditions 
| 2.7 
|-
| ss7_fci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_fci_default that must be forced. 
| N/A 
| Bits from ss7_fci_default which corresponding bit in ss7_fci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| ss7_bci_default 
| N/A 
| N/A 
| Default backward call indicator (BCI) value. 
| N/A 
| Toolpack will overwrite BCI bits AB, I, K, M and N with appropriate values according to call conditions 
| 2.7 
|-
| ss7_bci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_bci_default that must be forced. 
| N/A 
| Bits from ss7_bci_default which corresponding bit in ss7_bci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| tdm_ls_name_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable line service and timeslot selection to create the outgoing leg 
| 3.0 
|-
| tdm_ls_name
(Line Service or T1/E1 trunk) 
| Incoming leg line service name 
| Incoming leg line service name 
| Incoming leg line service name 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this line service name to create outgoing leg 
| 2.7 
|-
| tdm_timeslot_nb 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this timeslot number to create outgoing leg 
| 2.7 
|-
| rtp_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP port 
| (read-only) 
| 2.7 
|-
| rtp_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP port 
| (read-only) 
| 2.7 
|-
| ss7_cot_enabled 
| N/A 
| N/A 
| Requests SS7 in-call continuity test for this outgoing SS7 call 
| N/A 
| Toolpack will request a continuity test on the timeslot before making the outgoing call. If COT fails, the call will be dropped (then another route may be attempted) 
| 2.8 
|-
| reverse_charging_indication 
| Incoming leg Reverse charging indication IE present 
| N/A 
| N/A 
| N/A 
| If set in routing script, will add Reverse charging indication IE in outgoing leg (also use reverse_charging_indication_forward_enabled) 
| 2.8.12 
|-
| reverse_charging_indication_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable forwarding of reverse charging indication from incoming to outgoing leg 
| 2.8.12 
|-
| sip_call_id 
| N/A 
| N/A 
| N/A 
| Incoming leg SIP Call-Id 
| (read-only) 
| 2.9.112 / 3.0.131 
|-
| sip_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP port 
| (read-only) 
| 2.8.13 
|-
| sip_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP port 
| (read-only) 
| 2.8.13 
|}

 

=== Noa values ===
The text below represents the value normally used by routing script. 
Incase it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 
Example numeric values for the SS7 protocol are shown in parenthesis. 
 
*<tt>unknown_number (0x2)</tt>
*<tt>international_number (0x4)</tt>
*<tt>national_number (0x3)</tt>
*<tt>subscriber_number (0x1)</tt>
*<tt>network_specific (0x5)</tt>
*<tt>network_routing_national_format (0x7)</tt>
*<tt>network_routing_international_format (0x8)</tt>
*<tt>abbreviated_number (0x6)</tt>
*<tt>subscriber_number_operator_requested (0x71)</tt>
*<tt>national_number_operator_requested (0x72)</tt>
*<tt>international_number_operator_requested (0x73)</tt>
*<tt>no_number_present_operator_requested (0x74)</tt>
*<tt>no_number_present_cut_through_call_to_carrier (0x75)</tt>
*<tt>test_line_test_code (0x77)</tt>
*<tt>non_unique_subscriber_number (0x71)</tt>
*<tt>non_unique_national_number (0x73)</tt>
*<tt>non_unique_international_number (0x74)</tt>
*<tt>call_950_numbe (0x76)</tt>
*<tt>special_number (0x73)</tt>
*<tt>national_number_with_transit_network_selection (0x74)</tt>
*<tt>international_number_with_transit_network_selection (0x75)</tt>

Those values will be remapped to the protocol specific NOA value. To provide protocol specific value:

*<tt>call_params[:called_noa] = 0x70</tt>

or

*<tt>call_params[:called_noa] = 112</tt>

=== Npi values ===

*<tt>unknown_number</tt>
*<tt>isdn</tt>
*<tt>telephony</tt>
*<tt>private</tt>
*<tt>data</tt>
*<tt>telex</tt>
*<tt>national</tt>

=== Calling Display Type values ===

*<tt>unspecified</tt> => Type is unspecified.
*<tt>calling_party_name</tt> => Type is 0xB1.

Those values will be remapped to the protocol specific Display Information Type value. To provide protocol specific value:

*<tt>call_params[:calling_display_type] = 0xB1</tt>

or

*<tt>call_params[:calling_display_type] = 177</tt>

=== Calling Display value ===

*<tt>call_params[:calling_display] = "Roger Fluffy"</tt>

=== Presentation values for Calling number, Calling Subscriber (Generic Number), Redirecting Number, Original Called Number (OCN) and Location Number ===
The text below represents the value normally used by routing script. 
Incase it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 
Example numeric values for the SS7 protocol are shown in parenthesis. 
 
*<tt>unspecified</tt>
*<tt>not_available (0x2)</tt>
*<tt>allowed (0x0)</tt>
*<tt>restricted (0x1)</tt>
*<tt>addr_restricted</tt>
*<tt>name_restricted</tt>

=== Calling Party Category ===
The text below represents the value normally used by routing script. 
In case it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 

Mapping from routing script to SS7/CAS R2/SIP
{| cellspacing="1" cellpadding="1" border="1"
|-
! scope="col" | '''Routing Script string '''
! scope="col" | '''SS7 raw value '''
! scope="col" | '''R2 CAS scripts''' 
! scope="col" | '''Default Rx CAS''' 
! scope="col" | '''default Tx CAS''' 
! scope="col" | '''SIP "cpc=" '''
|-
| subscriber 
| 0xa 
| CATEGORY_SUBSCRIBER 
| 1 and 7 
| 7 
| ordinary 
|-
| subscriber_with_priority 
| 0xb 
| CATEGORY_SUBSCRIBER_WITH_PRIORITY 
| 2 and 9 
| 2 
| priority 
|-
| operator_french 
| 0x1 
| CATEGORY_OPERATOR_FRENCH 
| 5 
| 5 
| operator 
|-
| operator_english 
| 0x2 
| CATEGORY_OPERATOR_ENGLISH (5) 
| 5 
| 5 
| operator 
|-
| operator_german 
| 0x3 
| CATEGORY_OPERATOR_GERMAN (5) 
| 5 
| 5 
| operator 
|-
| operator_russian 
| 0x4 
| CATEGORY_OPERATOR_RUSSIAN (5) 
| 5 
| 5 
| operator 
|-
| operator_spanish 
| 0x5 
| CATEGORY_OPERATOR_SPANISH (5) 
| 5 
| 5 
| operator 
|-
| data 
| 0xc 
| CATEGORY_DATA 
| 6 and 8 
| 6 
| datacall 
|-
| test 
| 0xd 
| CATEGORY_TEST 
| 3 
| 3 
| test 
|-
| payphone 
| 0xf 
| CATEGORY_PAYPHONE 
| none 
| 7 
| payphone 
|-
| unknown 
| 0x0 
| CATEGORY_UNKNOWN 
| 4, 11 to 15 
| 7 
| unknown 
|-
| unspecified 
| 0xa 
| invalid 
| none 
| none 
| invalid 
|}
[[CAS_R2_scripting#Category_meanings|Link to calling party categories used in CAS R2 scripts]]

=== Screening values for Calling number, Calling Subscriber (Generic Number), and Location Number ===
The text below represents the value normally used by routing script. 
Incase it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 
Example numeric values for the SS7 protocol are shown in parenthesis. 
 
*<tt>unspecified</tt>
*<tt>no (0x0)</tt>
*<tt>pass (0x1)</tt>
*<tt>fail (0x2)</tt>
*<tt>network_provided (0x3)</tt>

=== Redirecting indicator values ===

SS7:

*<tt>no_redirection</tt>
*<tt>call_rerouted</tt>
*<tt>call_rerouted_all_restricted</tt>
*<tt>call_diverted</tt>
*<tt>call_diverted_all_restricted</tt>
*<tt>call_rerouted_restricted</tt>
*<tt>call_diverted_restricted</tt>
*<tt>spare</tt>

=== Redirecting number, Original Called Number and Diversion Reason ===

ISDN:

*<tt>unknown</tt>
*<tt>busy</tt>
*<tt>no_reply</tt>
*<tt>deflection</tt>
*<tt>dte_out_of_order</tt>
*<tt>forwarding_by_called_dte</tt>
*<tt>unconditional</tt>

SS7:

*<tt>unknown</tt>
*<tt>busy (SIP: user-busy)</tt>
*<tt>no_reply (SIP: no-answer)</tt>
*<tt>unconditional</tt>
*<tt>deflection</tt>
*<tt>deflection_immediate</tt>
*<tt>mobile_not_reachable</tt>

=== OLI (originating line information) values ===

The OLI parameter is a string that represents an integer value from 0 to 255.

=== Information Transfer Capability values ===

information_transfer_capability:

*<tt>digital</tt>
*<tt>restricted_digital</tt>
*<tt>digital_with_tones</tt>
*<tt>speech</tt>
*<tt>3_1_khz_audio</tt>
*<tt>video</tt>

=== redirecting_number_forward_enabled values ===

Controls forwarding or discarding of redirecting number (SIP: diversion header) to the outgoing call leg.

Values for this parameter are "0", "1", "false" or "true.
*0/false: Redirecting number (and original called number) is not forwarded to outgoing call leg
*1/true: Redirecting number (and original called number) is forwarded to outgoing call leg

The value for this parameter at the input of the routing script depends on the "Forward redirecting number" parameter in the "Advanced" section of the Gateway configuration page of the Web Portal. The script may change this value to override the Gateway configuration.

Note: To "insert" a new redirecting number value on the outgoing leg, redirecting_number_forward_enabled must also be set to true.

=== request_uri ===

Enables access to the Request-Line URI. 

For example, if the Request-Line is:
<pre>Request-Line: INVITE sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0</pre>
Then the retrieved request_uri will be "sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0". 

In the routing scripts, to retrieve only the called number, this script can be used: 
<pre> if call_params[:request_uri] && call_params[:request_uri] =~ /sip:(.*)@.*/
call_params[:called] = $1
end
</pre>
==== request_uri_forward_enabled ====

This call parameter controls forwarding or discarding of request uri to outgoing call leg.The request uri is the information in the "Request-Line:" of the SIP INVITE message. 

Values for this parameter are "0", "1", "false" or "true. 

* 0/false: Request uri is not forwarded to outgoing call leg 

* 1/true: Request uri is forwarded to outgoing call leg 

The default value for this parameters is false. 

==== sip_scheme ====
(Available in Toolpack 3.1+)
This call parameters indicates the scheme (generally "sip" or "sips") of the incoming call.

This also allows to control the scheme used for the outgoing call (regardless if request_uri_forward_enabled is used or not)

Note: sips scheme must only be used on TLS NAPs (will cause call routing failure if NAP has only UDP or TCP transport types).

=== sip_header values ===
Contains custom sip headers from the inbound call leg. Any custom sip header can be added to an outgoing call leg: 

'''Note:'''

The SIP header is in string format.

'''string format:'''
<pre>call[ :sip_header ] = "P-my-custom-header:value1 \nP-my-custom-header2:value2 \nP-my-custom-header3:value3"
</pre>
(Note: \n above are actual newline characters, not '\' followed by 'n')

* PCAP sample: [[File:TB_Custom_SIP_Headers.pcap]]

List of sip headers that will not appear in call[:sip_header] since they are already processed by the SIP stack:
<pre>
Accept Error-Info Remote-Party-ID
Accept-Contact Event Replaces
Accept-Encoding Expires Reply-To
Accept-Language From Request-Disposition
Alert-Info In-Reply-To Subject
Allow Max-Forwards Subscription-State
Allow-Events MIME-version Supported
Also Min-Expires Timestamp
Anonymity Min-SE To
Authorization Organization Unsupported
Authentication-Info Path User-Agent
Call-ID Priority Via
Call-Info Privacy Warning
Contact Proxy-Authenticate WWW-Authenticate
Content-Disposition Proxy-Authorization Require
Content-Encoding Proxy-Require Response-Key
Content-Language P-Media-Authorization Retry-After
Content-Length P-Preferred-Identity RPID-Privacy
Content-Type P-Asserted-Identity Route
CSeq RAck RSeq
RAck Reason Security-Client
Reason Record-Route Security-Server
Date Refer-To Security-Verify
Diversion Referred-By Server
Encryption Reject-Contact Service-Route
Session-Expires
</pre>

=== sip header parameters ===
The routing script can read (and modify) some SIP header parameters (user parameters, URI parameters or header parameters) from some SIP headers (To, From, P-Asserted-Identity, Remote-Party-ID, Contact).

==== Available parameters ====
* '''call[ :calling_parameters ]''' (SIP "From" header)
* '''call[ :called_parameters ]''' (SIP "To" header)
* '''call[ :private_address_parameters ]''' (SIP "P-Asserted-Identity" or "Remote-Party-ID" header)
* '''call[ :contact_parameters ]''' (SIP "Contact" header)

These parameters (if present) contain a hash with 3 keys: user_param, uri_param and header_param.
Each of this key points to a string that contains all the parameters found in the corresponding SIP header.
* '''User parameters''' (parameters between the user name/number and the host). Example <sip:alice;'''param=value'''@somewhere.com>
* '''URI parameters''' (parameters at the end of the URI). Example <sip:alice@somewhere.com;'''param=value'''>
* '''Header parameters''' (outside the URI). Example <sip:alice@somewhere.com>;'''param=value'''
Example to print all parameters of SIP "To" header:
call[ :called_parameters ].inspect -> '{ :user_param => "name1=value1;name2=value2", :uri_param => "name=value", :header_param => "name=value;example_param_without_value" }'
Example to modify (replace) the URI parameters of SIP "To" header:
call[ :called_parameters ][ :uri_param ] = "user=phone"

==== Exceptions ====
'''Note:''' Some parameters are reported as their own call attribute (oli, isub, cpc, transport) so they have the same representation for all protocols (SS7, IDSN, SIP). They won't appear present in the generic SIP header parameters structures above.

==== Forwarding from inbound to outbound call ====
By default, the parameters are not forwarded in a SIP to SIP call flow. The parameters '''will be forwarded''' when:
* accessed (read) from either the inbound or outbound call parameters
* written in either the inbound or outbound call parameters

==== Example usage ====
Example to print the user parameters:
<pre>
if call[:calling_parameters]
puts "user parameters = #{call[:calling_parameters][:user_param].inspect}"
end
</pre>

Example SIP "From" header:
From:<sip:123456782;test1=val1;test2=val2@something.com;test3=val3;test4=val4>;test5=val5;test6=val6
And the resulting content in the routing script:
calling_param.inspect -> {:user_param=>"test1=val1;test2=val2", :uri_param=>"test3=val3;test4=val4", :header_param=>"test5=val5;test6=val6"}

'''Note''' that printing the inbound or outbound call parameters is considered as a "read" action and would result in forwarding the parameter on the outbound leg.

Example to overwrite inbound leg calling parameters with new parameters for the outbound leg:
<pre>
call [:calling_parameters] = {
:user_param => "user_param7=7;user_param8=8",
:uri_param => "uri_param9=value9",
:header_param => "header_paramA=A" }
</pre>

Example to add user=phone and keep all other uri parameters.
<pre>
call[:calling_parameters] ||= {} # Create a hash if not already present
call[:calling_parameters][:uri_param] ||= "" # Create a string if not already present
call[:calling_parameters][:uri_param] += ";" if call[:calling_parameters][:uri_param] != ""
call[:calling_parameters][:uri_param] += "user=phone"
</pre>

=== MLPP Precedence values ===

mlpp_look_for_busy:

*<tt>allowed</tt>
*<tt>path_reserved</tt>
*<tt>not_allowed</tt>

mlpp_precedence_level:

*<tt>flash_override</tt>
*<tt>flash</tt>
*<tt>immediate</tt>
*<tt>priority</tt>
*<tt>routine</tt>

mlpp_network_identity:

3 digits value from 0 to 999

mlpp_service_domain:

24 bits value from 0 to 16777215

=== ISUB subaddress information values ===

called_isub_type:
calling_isub_type:

*<tt>nsap</tt>
*<tt>nsap_ia5</tt>
*<tt>nsap_bcd</tt>
*<tt>user</tt>

called_isub:
calling_isub:

Digits for the subaddress information.

=== Network Identification Plan ===

network_identification_plan:

*<tt>Unknown</tt> (value 0)
*<tt>cic</tt> (3 digits carrier identification code plus circuit code, value 1, SS7 or ISDN)
*<tt>user</tt> (User, value 2, ISDN only)
*<tt>cic4</tt> (4 digits carrier identification code plus circuit code, value 2, SS7 only)
*<tt>dnic</tt> (public Data Network ID, value 3, SS7 only)
*<tt>mnic</tt> (public land mobile network, value 6, SS7 only)

=== Registered Users Information ===
Routing script can access information about registered users (when either the calling or called user is a known registered user).
When these fields are empty, it means that the calling/called (SIP from/to) does not correspond to a known registered user (routing script may still decide to route the call based on static routes).

Information for the called user:
params[:registered_user]
Information for the calling user:
params[:calling_registered_user]

These parameters are a hash of key/values that provide information about the contact.
{
:contact_list=>
[
{
:contact=>"<sip:user_name_or_number@hostname:7070;transport=UDP>", -> Full contact
:expires=>"60", -> Contact expiry time (seconds)
:host=>"hostname", -> host name from the contact header
:name=>"user_name_or_number", -> user name from the contact header
:nap_in=>"NAP_NAME", -> NAP that the contact has registered from
:port=>"7070", -> Port from the contact header
:transport=>"UDP" -> Transport type from the contact header
:q_value=>"0.00", -> Q-value for the contact (for contact ordering)
:src_host=>"10.0.0.10", -> Actual source IP address that the contact has registered from
:src_port=>"7070", -> Actual source port that the contact has registered from
:src_transport=>"UDP", -> Actual protocol that the contact has been registering with
}
]
}

== Route parameters ==

All route may have these parameters:

*calling
*called
*nap
*remapped_calling
*remapped_called
*remapped_nap
*remapped_destination_leg_profile (called remapped_profile prior to Toolpack 2.9)
*remapped_source_leg_profile (called remapped_incoming_profile prior to Toolpack 2.9)

Example:

route[:remapped_nap]

Additionally it is possible to add dynamic route attributes in the web portal. These can be referenced by their name.
For example:
*priority
*weight

== Routing calls toward registered users ==
Static routes normally chose an outbound NAP to forward the call to.

But it's also possible to create routes which outbound NAP is dynamically chosen by matching a registered user (when using [[Sip_registration_forwarding|SIP registration forwarding]]).

More information can be found [[Sip_registration_forwarding#SIP_Calls_routing|here]] about the way to control the [[Sip_registration_forwarding#SIP_Calls_routing|priority of "dynamic" vs "static" routes]].

More information can be found [[#Registered_Users_Information|here]] about using routing scripts to access registered users information during call routing.

== Playing prompts announcements or tones ==

New feature in release 2.6, all bridges may have these parameters. These can be used to play IVR prompts (audio files) in different states of the call flow.

*'''announcement_tone''' (played before outgoing call is routed)
*'''ring_tone''' (played after when waiting for outgoing call to answer)
*'''busy_tone''' (played if outgoing call failed)
*'''disconnect_tone''' (played after the call has reached it's maximum duration)

Example to play an announcement to incoming call (before routing outgoing call, regardless if a matching route is found or not):
bridge[:announcement_tone ] = "my_announcement.wav"

Example to play a ring-tone while the outgoing call is ringing:
bridge[:ring_tone] = "my_ring_tone.wav"

Example to play an audio file when outgoing call fails (no route, or outgoing call is refused):
bridge[:busy_tone] = "my_busy_tone.wav"

Example to play an audio file when call has reached the maximum allowed duration:
bridge[:disconnect_tone] = "your_account_balance_is_empty.wav"

=== Announcement file path format and options ===

All file plabyacks (:announcement_tone, :busy_tone, :ring_tone, :disconnect_tone) inside bridge parameters use this format.
<pre>"file1.wav:repeat:start_off:end_off,file2.wav:repeat:start_off:end_off,file3.wav:repeat:start_off:end_off"
</pre>
Optional parameters:
* repeat: number of times to play the file (0 and 1 have the same result)
* start_off: Start offset in milliseconds
* end_off: End offset in milliseconds

Http and other path formats are described here: [[Customer_application_framework:play_audio_files#Play_path_format|Path format]]

==== Example 1 ====
The following example will play file1.wav once, and then play file2.wav in loop:
"file1.wav,file2.wav:-1"

==== Example 2 ====
The following example will play file1.wav from start offset of 1 second to end offset of 3 seconds, then twice file2.wav from second 5 to second 10.
"file1.wav:0:1000:3000,file2.wav:2:5000:10000"

==== Example 3 ====
The following example will play file1.wav once, ending at offset of 30 seconds.
"file1.wav:0:0:30000"

=== announcement_tone ===

params[:bridge][:announcement_tone] = "announcement.wav"

Audio file played on the incoming call before any outgoing call is placed. The outgoing call occurs when the file finished playing.

==== announcement_tone options ====
===== announcement_tone_answer =====
params[:bridge][:announcement_tone_answer] = "yes"

Forces an answer of the call before playing the announcement. Default if argument not provided is "no", in which case call is only alerted with in-band media.

===== announcement_code_detect =====
This option allows that the tone detection is enabled during the announcement play.

Collected digits can be inserted into the CDR logs (radius attribute "Telcob-CollectedDigits", or text CDR variable @{CollectedDigits}).

Collected digits can also be sent back to routing script, which is called again with the same call attributes, except that the called number is replaced by the collected digits.

Code detect has multiple options, as shown in the following code:
code_detect = {
:type => :DTMF, # :DTMF or :MFR1 tone detection.
# Default is MFR1.
:prefix => "", # Prefix (digits) that is removed from collected digits.
# Default is empty.
:suffix => "", # Suffix (digits) that is removed from collected digits
# and causes routing script to be immediately called.
# Default is empty.
:suffix_removal => false, # Controls the removal of the suffix from the collected digit string that's reported to routing script.
# Default is false
:timeout => 0, # Inter-digit timeout (ms) after which collected digits are passed to the routing script.
# Use 0 for "no timeout".
# Default is 1000ms
:barge_in_interruption => true, # When enabled, playing announcement is stopped as soon as first digit is collected.
# Default is true.
:proceed_on_play_done => false, # When true: Outgoing call is made after announcement finishes playing.
# Routing script is not called again.
# When false: Outgoing call is never made.
# Digits are collected until timeout or suffix match,
# then routing script is called again.
# Default is false.
:cas_on_hook => false, # Specific for CAS-R1 calls. Makes CAS bits switch to "on-hook" when announcement finished playing
# (but the call is not "terminated" from Toolpack point of view)
# Default is false.
:cas_on_hook_delay => 0, # Duration of cas bits "on-hook" state.
# Only effective if cas_on_hook is set to true.
# Value of 0 stands for "infinite delay".
# Default is 0.
:repeat_delay => 0, # Delay between repetition of the announcement. The announcement will repeat
# itself every "repeat_delay" until a code is detected (suffix match or timetout).
# Value of 0 stands for "infinite delay" (no repeating).
# Default is 0.
}
'''Example 1''': Collect DTMF digits, and call routing script again with collected digits upon timeout or suffix match.
code_detect = { :type => :DTMF, :suffix => "#", :timeout => 5000 }
params[:bridge][:announcement_code_detect] = code_detect

'''Example 2''': Collect digits during the announcement (for CDR logs), then proceed (make outgoing call) after announcement finishes playing
code_detect = { :type => :DTMF, :timeout => 0, :barge_in_interruption => false, :proceed_on_play_done => true }
params[:bridge][:announcement_code_detect] = code_detect

==== Controlling what happens after announcement ====
The routing script can control what happens with the call after the announcement finishes playing:
* An outgoing call is made
* Incoming call is hung-up
* Do nothing (wait for the incoming call to hang-up)
===== An outgoing call is made =====
This happens when the script has returned matching routes (and did not raise RoutingException)

===== Incoming call is hung-up =====
This happens when the script returns no routes (in which case base_routing will raise RoutingException with cause :no_route).

It also happens when the script explicitly raises RoutingException.

The incoming call will be terminated with the specified cause.
For example
raise RoutingException, :temporary_failure
(See "Reason values" section in this page for list of available causes)

===== Do nothing (wait for the incoming call to hang-up) =====
If a filter raises RoutingException with code :ok, then the incoming call will not be terminated at the end of the announcement play.
Announcement digit collection will remain active if appropriate.
For example:
raise RoutingException, :ok

=== ring_tone ===
params[:bridge][:ring_tone] = "ringing.wav"

Audio file played on the incoming call while waiting for the outgoing call to be answered.

Ring tone playback can also be configured in the Web Portal, from the incoming call's profile (under "Tones and Call Progress Options").

Routing script has precedence over profile (a routing script that fills params[:bridge][:ring_tone] will override the profile's ring tone behavior).

==== ring_tone options ====
===== ring_tone_state =====
params[:bridge][:ring_tone_state] = :alerted

Call state from which ring tone is being played. Available values are:
* '''immediately''': Ring tone starts playing immediately on the incoming leg
* '''accepted''': Ring tone starts playing as soon as outgoing call is accepted
* '''callprogress''': Ring tone starts playing as soon as "call progress" is received on the outgoing call
* '''alerted''' (default): Ring tone starts playing only once outgoing call is alerted (but won't play if alert indicates early media from outgoing call)

This option also apply when params[:bridge][:ring_tone] is not used, because it also apply to ring tone playback configured in the Web Portal, from the incoming call's profile.

=== busy_tone ===
Toolpack 2.8 and above:
params[:bridge][:busy_tone] = "no_route.wav"

Note: Obsolete name (toolpack 2.7.153 and earlier, but still supported in recent releases):
params[:bridge][:call_progress_tone] = "no_route.wav"

Audio file played on the incoming call when outgoing call fails (never answered).

Note that announcement_tone, if used, is played before the outgoing call attempt is made, and thus before the busy_tone.

Busy tone playback can also be configured in the Web Portal, from the incoming call's profile (under "Tones and Call Progress Options").

Routing script has precedence over profile (a routing script that fills params[:bridge][:busy_tone] will override the profile's busy tone behavior).

Special value '''"none"''' can be used by routing script to force playing nothing (as empty string would default to profile's behavior)

==== busy_tone options ====
===== busy_tone_answer =====
params[:bridge][:busy_tone_answer] = "yes"

Forces an answer of the call before playing the busy tone. Default if argument not provided is "no", in which case call is only alerted with in-band media.

=== disconnect_tone ===
params[:bridge][:disconnect_tone] = "max_duration.wav"

Audio file played on the incoming call when call duration (:max_call_duration) is reached. Then the leg will be terminated with specified reason (:call_duration_reason).

==== disconnect_tone options ====
===== max_call_duration =====
params[:bridge][:max_call_duration] = "60000"

Maximum call duration in millisecond. This timer is started when entering answer state.

===== call_duration_reason =====
params[:bridge][:call_duration_reason] = :resource_unavailable

Drop both legs with this reason when call duration (:max_call_duration) is reached.

=== Managing audio prompts through Web Portal ===
Audio prompts can be uploaded or deleted from the TMedia unit through the Web Portal:
[[Toolpack:Configuring_Audio_Prompts_A|Managing audio prompts]]

Prompts management must be done using the Web Portal of the primary server (in systems with redundant TMedia units or redundant host servers).
The file will automatically get replicated to the secondary server.

=== Managing audio prompts manually ===
Any file on the TMedia host file system can be played. This means it's possible to manage prompts through ssh/scp.

==== The default (replicated) prompts folder ====
By default, when playing a prompt, Toolpack will look in the default prompts folder:
/lib/tb/toolpack/pkg/prompts
The root of this "prompts" directory is automatically replicated to secondary unit of redundant setups (1+1, N+1, redundant hosts). Sub-folders won't be replicated.

Any prompt play request without explicit file path will map to this folder. For example:
params[:bridge][:busy_tone] = "no_route.wav"
This will correspond to file /lib/tb/toolpack/pkg/prompts/no_route.wav

==== Relative file paths ====
Any file path that begins with "file://" is considered relative to the tbstreamserver application's working directory:
/lib/tb/toolpack/setup/12358/2.8/apps/tbstreamserver/
(Where "2.8" may be replaced by the current major version of your system)

For example:
params[:bridge][:busy_tone] = "file://my_folder/no_route.wav"
This will correspond to file /lib/tb/toolpack/setup/12358/2.8/apps/tbstreamserver/my_folder/no_route.wav

==== Absolute file paths ====
Absolute paths can also be provided.
For example:
params[:bridge][:busy_tone] = "file:///root/my_folder/no_route.wav"
This will correspond to file /root/my_folder/no_route.wav

== Recording call legs ==
Introduced in release 2.6.44, it's now possible to use routing scripts to ask for recording incoming and/or outgoing call legs.

See example filter script "call_recording" (created by default in Web Portal routing scripts starting with 2.6.44) for an example.

=== Recording the incoming call leg ===
To record the incoming call leg, the routing script (in a "after filter" for example) has to set the following parameter:

bridge[ :record_incoming ] = ""

=== Recording the outgoing call leg ===
To record the outgoing call leg, the routing script (in a "after filter" for example) has to set the following parameter, per route (the decision to record or not, or the file name to record to, can be set per matching route):

# Need to clone the routes in order to have the right to modify them
routes = clone_routes params[:routes]
routes.each do |route|
route[ :record_outgoing ] = ""
end
# Store modified routes back to the parameters for this outgoing call
params[:routes] = routes

=== Record the outgoing call leg within incoming leg's recorded file (mixing) ===
[...]
route[ :record_outgoing ] = "@{MixWithIncoming}"
[...]

=== Choosing file path to record to ===
The value assigned to ":record_incoming" or ":record_outgoing" is the path to record the file to.

The paths can be absolute, or relative. When relative, they are relative to the "tbstreamserver" application working directory, for example:
/lib/tb/toolpack/setup/12358/2.7/apps/tbstreamserver/

* Empty file name will default to a name that contains various information about the call:
** ''LinkId'': Id common between all legs of this call bridge
** ''LegId'': Unique Id for this leg
** ''Nap'': Current NAP name this call leg is from
** ''Direction'': "IN" or "OUT" (depends if call leg is incoming or outgoing leg)
** ''Calling'': The calling number of this call leg
** ''Called'': The called number of this call leg
** ''Protocol'': The signaling protocol of this call leg (SS7, ISDN, CAS, SIP)
** ''Media info'': Codec + IP/Port for SIP calls, Trunk/Timeslot for TDM calls
* To record outgoing call leg in the same audio file as incoming call leg (mixing), use the following:
** @{MixWithIncoming}: Record outgoing legs in same file as incoming legs
* Variables can be used to insert in the recording path information that's not already available from routing scripts:
** @{CURRENT_PKG}: Version of current package
*** Example: 2.6.45
** @{DATE format}: Prints the date, where 'format' is expressed as described for the 'strftime' function
*** Example: @{DATE %Y-%m-%d} => 2013-01-28
** @{DefaultName}: Replaced by the default file name for recording, which contains:
*** LinkId: Id common between all legs of this call bridge
*** LegId: Unique Id for this leg
*** Nap: Current NAP name this call leg is from
*** Direction: "IN" or "OUT" (depends if call leg is incoming or outgoing leg)
*** Calling: Calling number
*** Called: Called number
*** Protocol: Protocol type of this call (SS7, ISDN, CASR2, SIP)
*** Media info: Codec + IP/Port for SIP calls, Trunk/Timeslot for TDM calls
*** Example: "73EBA698-F3D67B4B-NAP_SS7-IN-5550000-5550001-SS7-TRUNK_BELL_11-24.wav"
*** Example: "73EBA698-73EBA698-NAP_SIP-OUT-5550000-5550001-SIP-G723-10.3.10.101-1050.wav"
** @{DefaultPath}: Default recording folder and file name: "@{RECORD_PATH}/@{DATE %Y-%m-%d}/@{DefaultName}"
*** Example: "/lib/tb/toolpack/setup/12358/recorded_calls/73EBA698-F3D67B4B-NAP_SS7-IN-5550000-5550001-SS7-TRUNK_BELL_11-24.wav"
*** Example: "/lib/tb/toolpack/setup/12358/recorded_calls/73EBA698-73EBA698-NAP_SIP-OUT-5550000-5550001-SIP-G723-10.3.10.101-1050.wav"
** @{Direction}: Direction of current leg (IN our OUT)
*** Example: IN
** @{LegId}: Current LegId (Unique Id for this leg)
*** Example: F3D67B4B
** @{LinkId}: Current LinkId (Id common between all legs of this call bridge)
*** Example: 73EBA698
** @{PKG_HOME}: Path where packages are stored.
*** Note: It's not recomended to use that path on redundant systems, package file replication may cause confusion in recorded files.
*** Example: /lib/tb/toolpack/pkg
** @{PROMPT_PATH}: Default path where audio prompts are stored
*** Note: It's not recomended to use that path on redundant systems, package file replication may cause confusion in recorded files.
*** Example: /lib/tb/toolpack/pkg/prompts
** @{Protocol}: Protocol of current leg
*** Example: SS7
** @{RECORD_PATH}: Default recording folder: "@{TB_SETUP_HOME}/recorded_calls/"
** @{TBX_GW_PORT}: Current "System Id" (also called "Gateway Port")
*** Example: 12358
** And all variables listed here: [[Customer_application_framework:play_audio_files#Helpful_variables_to_build_play_or_record_file_paths|Building play or record file path]]

== Controlling UUI (user-to-user information) relay ==
UUI (user-to-user information) can be present in different messages received by either call leg during a call. For example, information can be carried during the initial invite, other information can be carried when the call is alerted, answered, or terminated.

Routing scripts can control if the UUI received from one leg through the call will be forwarded to the other call leg:
*uui_forward_enabled

Routing scripts can also read and modify the UUI received with the incoming call leg, before it gets forwarded upon creation of the outgoing call leg:
*uui

=== UUI (user-to-user indication) values ===

Byte array represented as ruby String. Use ''bridge=params[:bridge]'', then ''bridge[:uui]'' to access the data.

To access the bytes in Ruby, use ruby String operator []. For example: bridge[:uui][0] will return the binary value of the first UUI byte.

Function each_byte can also be useful to iterate through all bytes of the UUI.

=== uui_forward_enabled values ===

Controls forwarding or discarding of UUI to outgoing call leg.

Values for this parameter are "0", "1", "false" or "true.
* 0/false: UUI is not forwarded between call legs
* 1/true: UUI is forwarded between call legs

The value for this parameter at input of routing script depends on the "Forward UUI" parameter in the "Advanced" section of the Gateway configuration page of the Web Portal. The script may change this value to override the Gateway configuration.

== Authorization ==
Starting with release 2.7, it is possible to issue RADIUS authorization requests from routing scripts. To do so, the params[:authorization] object must be filled with the required RADIUS attributes and [[#Refuse|an exception must be raised]] with reason :authorization_required.

When the authorization is completed, the routing script is called again with the result. The params[:authorization] object will be filled with the RADIUS attributes from the response. The params[:authorization][:result] field will also contain a string indicating the result of the authorization:

* ''accept'': The authorization was successful.
* ''reject'': The authorization was refused.
* ''challenge'': The authorization was challenged.
* ''timeout'': The authorization was not answered.

== Call diversion options ==
It's possible to control the call flow when a call diversion information is received in the alerting state.

Two fields are available: bridge[ :diversion ] and bridge[ :diversion_reason ]

The internal release cause TOOLPACK_DIVERT_NOT_ALLOWED is used by gateway application to terminate both legs.

bridge[ :diversion ] = :allowed
The alert message will not be analyzed and the call will be progressed. Default behavior.
bridge[ :diversion ] = :not_allowed
If the alert message indicates that the call is diverted, the call will be released no matter the In-band information to allow
early media.
bridge[ :diversion ] = :not_allowed_w_early_media
The call will be released If the alert message indicates that the call is diverted with in-band information to allow early media.
bridge[ :diversion_reason ] = "*"
If the diversion is not allowed, the gateway will drop the call for any redirecting reason.
bridge[ :diversion_reason ] = "0,1,2"
or
bridge[ :diversion_reason ] = "unknown,busy,no_reply"
If the diversion is not allowed, the redirecting reason will be analyzed and the call will only be dropped for the configured cases.

See section [[Routing_script_tutorial:Mini_Development_Guide#Redirecting_number,_Original_Called_Number_and_Diversion_Reason|Redirecting number reason values]].

== Call transfer requests ==
Toolpack allows that [[Call transfer]] requests are relayed from one leg to the other, or to process them locally (making another outgoing call to replace the call that requested the call transfer).

If the chosen [[Call transfer]] mode is to process requests locally, upon reception of a call transfer request (SIP REFER or ISDN Facility), routing script will be called once again, to select the routes for the new outgoing call (call transfer target).

=== How to route call transfer request ===
Routing of a call transfer request is done exactly like routing of a normal incoming call.
The routing script generally does not need any modification to support that.

In some cases, the routing script may want to use information related to the transfer request to perform routing, or to insert information in the outgoing call leg.
Additional information is provided to the routing script, allowing routing decisions using information from the call transfer request (SIP REFER or ISDN Facility).
See below...

=== params[ :call ] content during transfer request ===
When processing a call transfer request, the params[ :call ] hash contains the information from the inbound call (same as was passed to the routing script upon arrival of the inbound call)
call = params[ :call ] -> Information from original inbound call, with exception of call[ :called ]

One exception (convenient because it allows a unmodified routing script to process call transfer request the same way as any other routing request):
call[ :called ] -> Replaced by the called number from the call transfer request (also called "redirection number")
Complementary information:
call[ :original_called_number ] -> Contains the called number that was initially received from the incoming call, prior to call transfer request
call[ :redirecting_number ] -> Number of the call from which the call transfer request was received (generally equals to original_called_number)

These fields will also be included in the outgoing call made after routing:
* original called number and redirecting number are existing fields on SS7 and ISDN calls
* SIP "diversion" header is used for SIP calls

=== params[ :transfer ] content ===
(this if valid only for release 2.7.102 and above) 
When processing a call transfer request, information from the call transfer request message (SIP REFER, ISDN Facility) is provided in params[ :transfer ]:
transfer = params[ :transfer ]
The following field is always present:
transfer[ :original_nap ] -> Contains the NAP of the first call from which a call transfer request was received
transfer[ :redirecting_nap ] -> Contains the NAP of the call from which the current call transfer request was received
(same as :original_nap for the first call transfer, different for subsequent transfers)
Examples of other fields that may be present, when appropriate:
transfer[ :uui ] -> The UUI (user-to-user information) found in the call transfer request
transfer[ :sip_header ] -> Contains custom SIP headers from the call transfer request
transfer[ :request_uri ] -> Contains the SIP Request URI

These fields are 'read-only'. They will not be included in the outgoing call, as they represent the contents of the call transfer request, and not the outgoing call to be made.

To insert/modify attributes of the outgoing call, the parameters from params[ :call ] must be edited instead.

== Redirection ==
In release 2.8 and above, redirection contacts are obtained from the routing engine in the following format:

contacts = params[ :contacts ]
contacts = {
:index=>"3",
:list=>[
{:called_number=>"6660", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"", :raw_data=>"", :expiration=>"3600"},
{:called_number=>"6661", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6661@192.168.215.127", :raw_data=>"<sip:6661@192.168.215.127>", :expiration=>"3600"}
{:called_number=>"6662", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6662@192.168.215.128", :raw_data=>"<sip:6662@192.168.215.128>", :expiration=>"3600"},
{:called_number=>"6663", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6663@192.168.215.129", :raw_data=>"<sip:6663@192.168.215.129>", :expiration=>"3600"},
{:called_number=>"6664", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6664@192.168.215.150", :raw_data=>"<sip:6664@192.168.215.150>", :expiration=>"3600"}
],
:source_indexes=>"nil,0,0,0,2"
}

* <code>params[:contacts][:list]</code> contains the contact log. Each contact within the list has the following fields:
** <code>:called_number</code> - the called number
** <code>:is_number_ported</code> - if the called number has been ported (for SIP: if the npdi parameter is present)
** <code>:ported_number</code> - the called number that was ported (for SIP: the rn parameter value, if available)
** <code>:sip_uri</code> - the SIP URI of the contact, without the contact-params section (without the expires and q contact parameters)
** <code>:raw_data</code> - the raw data representing the contact in the signaling protocol. For SIP, this is the full SIP URI (including the expires and q contact parameters).
** <code>:priority</code> - the priority of the contact [0-1000]
** <code>:expiration</code> - the expiration time in seconds of the contact
* <code>params[:contacts][:index]</code> contains the index of the contact that is currently being routed.
* <code>params[:contacts][:source_indexes]</code> contains a comma-separated list of indexes from <code>params[:contacts][:list]</code>. Each index represents the contact from which the contact in the list was obtained from.

To get more information, see:
*[[Routing_script_tutorial:SIP_Redirection_Contacts|SIP Redirection Contacts Parameters in a Call Flow]]

== Connected number ==
Insert a connected number in the answer message of the call flow.

Routing script example:
bridge = params[ :bridge ]
bridge [ :connected_number ] = "3335577"
bridge [ :connected_number_noa ] = :national_number
bridge [ :connected_number_npi ] = :private
bridge [ :connected_number_presentation ] = :allowed
bridge [ :connected_number_screening ] = :pass

== Terminating calls ==
In release 2.8, it is now possible to terminate a call through the routing scripts. The [[#Reason values|reason code]] must be specified in <code>params[:bridge][:reason]</code>. The <code>:terminate</code> hash must be created and copied into <code>params</code>:
terminate = {}
params[:terminate] = terminate
The following fields can then be set in <code>:terminate</code>:
* <code>:sip_header</code>
* <code>:contacts</code> # list of contacts as described in the [[#Redirection|redirection]] section
* <code>:isup_raw</code>
* <code>:isup_raw_variant</code>
* <code>:redirecting_number</code>
* <code>:redirecting_number_noa</code>
* <code>:redirecting_number_npi</code>
* <code>:redirecting_number_presentation</code>
* <code>:redirecting_number_reason</code>
* <code>:redirecting_number_counter</code>
* <code>:redirecting_number_indicator</code>
* <code>:original_called_number</code>
* <code>:original_called_number_noa</code>
* <code>:original_called_number_npi</code>
* <code>:original_called_number_presentation</code>
* <code>:original_called_number_reason</code>
* <code>:original_called_number_counter</code>

== Reason values ==

Check here for Termination Reason Cause codes: 

[[Termination_cause_codes|Termination Reason Cause codes]]
 

Example to refuse an incoming call leg.
raise RoutingException, :no_route

Reason cause strings available inside routing scripts:

List of Q.850 reason causes:
:unallocated_number
:no_route_to_network
:no_route_to_destination
:send_special_tone
:misdialled_trunk_prefix
:channel_unacceptable
:call_awarded_in_established_channel
:preemption
:reattempt
:qor_ported_number
:normal_call_clearing
:user_busy
:no_user_responding
:no_answer_from_user
:subscriber_absent
:call_rejected
:number_changed
:redirection
:exchange_routing_error
:non_selected_user_clearing
:destination_out_of_order
:address_incomplete
:facility_rejected
:response_to_status_enquiry
:normal_unspecified
:no_circuit_available
:network_out_of_order
:frame_mode_out_of_service
:frame_mode_connection_operational
:temporary_failure
:switching_equipment_congestion
:access_information_discarded
:requested_circuit_not_available
:precedence_call_blocked
:resource_unavailable
:quality_of_service_not_available
:requested_facility_not_subscribed
:outgoing_calls_barred
:outgoing_calls_barred_within_cug
:incoming_calls_barred
:incoming_calls_barred_within_cug
:bearer_cap_not_authorized
:bearer_cap_not_available
:inconsistency_access_info
:service_not_available
:bearer_cap_not_implemented
:channel_type_not_implemented
:requested_facility_not_implemented
:only_restricted_digital_info
:service_not_implemented
:invalid_call_reference
:channel_does_not_exist
:call_identity_does_not_exist
:call_identity_in_use
:no_call_suspended
:call_has_been_cleared
:user_not_member_of_cug
:incompatible_destination
:non_existant_cug
:invalid_transit_network
:invalid_message_unspecified
:mandatory_ie_missing
:message_type_non_existent
:message_not_compatible_with_call_state
:ie_non_existent
:invalid_ie_content
:msg_not_compatible_with_call_state
:recovery_on_timer_expiry
:parameter_non_existent_passed_on
:message_with_non_recognized_parameters_discarded
:protocol_error
:interworking_unspecified

List of toolpack reason causes:

:toolpack_normal or :normal
:toolpack_resource_error or :resource_error
:toolpack_timeout or :timeout
:toolpack_no_route or :no_route
:toolpack_call_collision or :call_collision
:toolpack_sync_drop or :sync_drop
:toolpack_signaling_error or :signaling_error
:toolpack_locally_rejected or :locally_rejected
:toolpack_interface_not_available or :interface_not_available
:toolpack_reset_in_progress or :reset_in_progress
:toolpack_adapter_reject or :adapter_reject
:toolpack_missing_or_invalid_ie or :missing_or_invalid_ie
:toolpack_incoming_only or :incoming_only
:toolpack_system_configuration_changed or :system_configuration_changed
:toolpack_resource_no_more_available or :resource_no_more_available
:toolpack_incompatible_media or :incompatible_media
:toolpack_resource_allocation_failed or :resource_allocation_failed
:toolpack_data_path_not_available or :data_path_not_available
:toolpack_local_congestion or :local_congestion
:toolpack_authorization_required or :authorization_required
:toolpack_call_divert_is_not_allowed or :call_divert_is_not_allowed

List of SIP reason causes: 
Reason causes starting with a digit must use the following syntax (can't use : as prefix).

'300_multiple_choices'
'301_moved_permanently'
'302_moved_temporarily'
'305_use_proxy'
'380_alternative_service'
'400_bad_request'
'401_unauthorized'
'402_payment_required'
'403_forbidden'
'404_not_found'
'405_method_not_allowed'
'406_not_acceptable'
'407_proxy_authentication_required'
'408_request_timeout'
'409_conflict'
'410_gone'
'413_request_entity_too_large'
'414_request_URI_too_long'
'415_unsupported_media'
'416_unsupported_URI_scheme'
'420_bad_extension'
'421_extension_required'
'422_session_timer_too_small'
'423_interval_too_brief'
'429_referrer_identity_error'
'480_temporary_unavailable'
'481_call_or_transaction_does_not_exist'
'482_loop_detected'
'483_too_many_hops'
'484_address_incomplete'
'485_ambiguous'
'486_busy_here'
'487_request_terminated'
'488_not_acceptable_here'
'489_bad_event'
'491_retry_after'
'500_server_internal_error'
'501_not_implemented'
'502_bad_gateway'
'503_service_unavailable'
'504_server_timeout'
'505_version_unsupported'
'513_message_too_large'
'600_busy_everywhere'
'603_decline'
'604_not_exist_anywhere'
'606_not_acceptable'

== Nap status ==

All the status fields of the NAPs are provided for use by the routing scripts. See the nap status provider for more details on which fields are available in the CEngineStatTransNap.hpp file.

'''Notice:''' These values may change between major release.

Routing script call attribute name Description
--------------------------------------------------------------------------------------------
"name" NAP name.
"signaling_type" Signaling type (SS7, ISDN, CASR2, SIP)
"profile" Profile name.
"sip_destination_ip" Destination IP address.
"sip_destination_port" Destination IP port.
"sip_transport_type" SIP transport type (:udp, :tcp, or :tls) (Toolpack 3.1 and more)
"inst_incoming_call_cnt" Instantaneous Count of incoming calls.
"inst_outgoing_call_cnt" Instantaneous Count of outgoing calls.
"available_cnt" Number of available circuits or channels.
"unavailable_cnt" Number of unavailable circuits or channels.
"availability_percent" Percentage of available circuits or channels.
"usage_percent" Percentage of used circuits or channels.
"unused_shared_percent" Percentage of used circuits or channels of this NAP available to make new calls with (taking into account shared with other NAPs)
"total_incoming_call_cnt" Total Count of incoming calls.
"global_asr_percent" Global calculated ASR percentage.
"total_outgoing_call_cnt" Total Count of outgoing calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_outgoing_call_cnt" Last 24 hours outgoing calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_outgoing_call_cnt" Current hour outgoing calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_outgoing_call_cnt" Last hour outgoing calls.
"poll_remote_proxy" Remote proxy polling enabled
"is_available" Remote proxy actually available or not
"time_since_polling" Time since the last availibility polling
"time_available_seconds" Number of seconds since the NAP is available
"time_unavailable_seconds" Number of seconds since the NAP is unavailable
"register_to_proxy" Register to proxy enabled
"registered" Actually registered or not
"time_since_refresh" Time since the last refresh
"time_registered_seconds" Number of seconds since the NAP is registered
"time_not_registered_seconds" Number of seconds since the NAP is not registered
"asr_stats_incoming_struct" Detailed Answer-Seizure Rate incoming statistics.
{
"global_asr_percent" Global calculated ASR percentage.
"total_call_cnt" Total count of calls.
"total_accepted_call_cnt" Total count of accepted calls (not dropped due to congestion or rate-limiting).
"total_answered_call_cnt" Total count of answered calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_call_cnt" Last 24 hours count of calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_call_cnt" Current hour count of calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_call_cnt" Last hour count of calls.
}
"asr_stats_outgoing_struct" Detailed Answer-Seizure Rate outgoing statistics.
{
"global_asr_percent" Global calculated ASR percentage.
"total_call_cnt" Total count of calls.
"total_accepted_call_cnt" Total count of accepted calls (not dropped due to congestion or rate-limiting).
"total_answered_call_cnt" Total count of answered calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_call_cnt" Last 24 hours count of calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_call_cnt" Current hour count of calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_call_cnt" Last hour count of calls.
}
"mos_struct" Detailed Mean Opinion Score statistics.
{
"last_24h_ingress" Last 24 hours calculated MOS for incoming RTP packets.
"last_24h_egress" Last 24 hours calculated MOS for outgoing RTP packets.
"current_hour_ingress" Current hour calculated MOS for incoming RTP packets.
"current_hour_egress" Current hour calculated MOS for outgoing RTP packets.
"last_hour_ingress" Last hour calculated MOS for incoming RTP packets.
"last_hour_egress" Last hour calculated MOS for outgoing RTP packets.
}
"network_quality_struct" Detailed network quality statistics.
{
"last_24h_ingress" Last 24 hours network quality percentage for incoming RTP packets.
"last_24h_egress" Last 24 hours network quality percentage for outgoing RTP packets.
"current_hour_ingress" Current hour network quality percentage for incoming RTP packets.
"current_hour_egress" Current hour network quality percentage for outgoing RTP packets.
"last_hour_ingress" Last hour network quality percentage for incoming RTP packets.
"last_hour_egress" Last hour network quality percentage for outgoing RTP packets.
}

 If the nap status is part of a substructure, the substructure will be a hash containing all subfield elements.

Example to access the signaling type and the number of incoming call count for the NAP of the current call:

incoming_nap = params[:naps][ params[:call][ :nap ].to_sym]
log_trace 4,"Incoming NAP parameters=" + incoming_nap.inspect
log_trace 4,"Incoming NAP signaling type=" + incoming_nap[:signaling_type].inspect
log_trace 4,"Incoming NAP call cnt=" + incoming_nap[:asr_stats_incoming_struct][:total_call_cnt].inspect

 It is also possible to add dynamic nap attributes in the web portal. These can be referenced by their name.

== Telephony Services ==
In release 2.10 and the above, telephony services (CNAM Request) can be manage from the routing engine in the following format:

params[:telephony_services].each do |service| -> Array of telephony services
service[:name] -> Customer telephony service name
service[:type] -> For now only "CNAM Request"
service[:enabled] -> Indicate if the service is enabled (true) or not (false)
(Only the telephony service define in the profile associated to the NAP is enabled)
(The others telephony services define in others profiles are disabled)
(If we are in the case where we return in the routing script with a response, it is important to set :enabled to false in order to avoid repeating the same query)
serviceParams = service[:params]
serviceParams[:return_to_script] -> Indicates to Gateway if we must return to the routing script after receiving the CNAM response
(It is important to set back to false this field to avoid an infinite loop)
serviceQuery = service[:query]
serviceQuery[:phone] -> 10 digits of calling number from the incoming call to send to the CNAM server
serviceQuery[:timeout] -> Timeout in millisecond to wait a CNAM response from CNAM server
(Default value from profile configuration)
serviceResponse = service[:response]
serviceResponse[:success] -> Indicates if we received a good CNAM response from the CNAM Server (Only present if :return_to_script is set to true)
serviceResponse[:caller_name] -> The caller name received in the CNAM response from the CNAM Server (Only present if :return_to_script is set to true)

== Custom user context ==
The routing script may '''save per-call information within the call context''', that will be available if routing is called again later during the call flow.

Cases where routing is called multiple time for the same call are:
- Call transfer requests
- SIP redirect requests
- Radius Authorization result
- Announcement server with digit collection

The routing script can save a recursive hash of attributes here:
params[:user_context]

For example
params[:user_context] = { "SomeKey" => "Some value I want to retrieve upon next routing for this call", "OtherVal" => { "subkey" => "subval" } }

Upon first call to routing script, params[:user_context] will be nil.
Upon subsequent calls to routing script, it will contain whatever the script had stored upon previous call (or nil if it was not set)

Note: This feature is available starting from release 2.9.85, 2.10.31 and 3.0.15 (in respective branches 2.9, 2.10 or 3.0)

== Routing Script Tests ==
The Web portal features a tool for Testing Scripts. The user must enter parameters to simulate the incoming call and after pressing the Test button, will output selected routes and numbers. You do not need to activate the new routes, or the new scripts to use this test tool: It can be used to test the routing scripts and routing table before activating it.
This is available in the Routing Scripts section of the Web portal.

=== Test parameters ===
==== @call_params ====

That variable should contain a hash of call parameters that will be passed to the routing script. This is equivalent to the incoming call parameters.

 

==== @nap_list ====

A list of the hash containing the nap statuses. This is equivalent to the nap statuses at the time the call is to be routed.

'''The nap list is hashed by the nap names in UPPERCASE.''' It is important to consider this when creating new dynamic route or nap attributes that may nap names that will be used to fetch a status.

 

==== @params ====

A hash of hashes containing parameters. This hash contains bridge parameters and other kind of parameter groups may be added in the future.

@params = {
:bridge => {:announcement_tone, "announcement.wav"},
:contacts => {
:index=>"1",
:list=>[
{:called_number=>"6660", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"",
:raw_data=>"", :expiration=>"3600"},
{:called_number=>"6661", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6661@192.168.215.127",
:raw_data=>"<sip:6661@192.168.215.127>", :expiration=>"3600"}
],
:source_indexes=>"nil,0"
}
}

 

----

 Back to [[Routing script tutorial|Routing Script Tutorial]].

Routing script tutorial:Mini Development Guide

2019-04-04T20:10:29Z

Abrassard:

== Call object ==

=== Get ===

This function is used to get the call parameters. The possible parameters are described in the section "Call parameters"

called_number = caf_call.get :called

=== List_params ===

This function is used to retrieve the list of supported call parameters. For example to extract all the possible call parameters from the the call object and put it in hash.

caf_call.list_params.each {|param| call[param] = caf_call.get param }

=== Accept ===

This function is used to accept a call. It actually creates one outgoing route that the gateway application will use to bridge the incoming call leg. If more than one outgoing route is "accepted", the gateway will try them one by one in the same order that they were accepted. If an outgoing call leg fails (according to 'route retry' parameters), the next route in line will be used.

This method takes 2 arguments, the call parameters (hash) and the route parameters (hash). Note that calling this method does NOT stop the flow of the script.

Apply route remapping rules

caf_call.accept out_call, route

=== Refuse ===

This function is used to set the reason code for the incoming call leg refusal. However, this function does NOT stop the flow of the script.

caf_call.refuse :reason => :temporary_failure

To immediately refuse the incoming call leg and stop processing the script, the script must raise an exception. Exiting the script by raising the exception overwrites any reason cause previously stored using refuse().

raise RoutingException, :no_route

The supported refusal cause values for both refuse() and raise() are described in the section "[[Routing_script_tutorial:Mini_Development_Guide#Reason_values|Reason values]]".

=== Script parameters protocol mapping ===

The following call parameters are available in the call object. For example:

called_number = call[:called]

For information on how to use and remap call parameters, see [[Toolpack:_How_to_Use_RegEx_in_Remapped_Called_and_Calling_Number_Mask | How to use regex in Remapped Called and Calling Number Mask]]

{| cellspacing="1" cellpadding="1" border="1" style="width: 921px; height: 805px;"
|-
! scope="col" | '''Script parameter name'''
! scope="col" | '''ISDN '''
! scope="col" | '''R2 CAS''' 
! scope="col" | '''SS7 '''
! scope="col" | '''SIP '''
! scope="col" | '''Comment '''
! scope="col" | '''Toolpack version '''
|-
| leg_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Leg ID 
| 
|-
| session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Session ID 
| 
|-
| original_session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Original Session ID (before call transfer or redirections) 
| 
|-
| calling 
| Q931: 'Calling party number' IE - Number digits 
| ANI (Group B) 
| Q763: 'Calling party number' IE - address signals (*) 
| SIP:From - user-info 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead. 
| 
|-
| calling_sip_host 
| N/A 
| N/A 
| N/A 
| SIP:From - host (domain or IP) 
| For example : The 'telcobridges.com' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| calling_sip_port 
| N/A 
| N/A 
| N/A 
| SIP:From - port 
| For example : The '6060' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| calling_noa 
| Q931: 'Calling party number' IE - Type of number 
| N/A 
| Q763: 'Calling party number' IE - nature of address indicator (*) 
| N/A 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead 
| 
|-
| calling_npi 
| Q931: 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: 'Calling party number' IE - numbering plan indicator (*) 
| N/A 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead 
| 
|-
| calling_display 
| Q931: 'Display' IE - Display information 
Q931: 'Facility CNAM' IE when presentation is allowed for DMS/NI2 variants 
| N/A 
| Q763
ITU97: 'Display information' IE - display information
ANSI95: 'Generic name' IE - display information
| SIP:From - display-name 
| 
| 
|-
| calling_display_type 
| Q931: 'Display' IE - Display information (present and/or first byte) 
| N/A 
| Q763: 'Display information' IE - present or not 
| N/A 
| 
| 
|-
| calling_presentation 
| Q931: 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: 'Calling party number' IE - address presentation restricted indicator 
|
SIP:From - display-name (displays 'anonymous' or not)

SIP:Remote-party-id - privacy 

| 
| 
|-
| calling_screening 
| Q931: 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: 'Calling party number' IE - screening 
| SIP:Remote-party-id - screen 
| 
| 
|-
| calling_category 
| N/A 
| Call party category (Group A) 
| Q763: 'Calling party's category' IE - calling party's category 
|
SIP:From - cpc

SIP:P-asserted-identity - cpc 

| 
| 
|-
| calling_subscriber
(Generic Number / NDS) 
| Q931: 2nd 'Calling party number' IE - Number digits 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - Number digits 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| Requires option 'support 2 calling number IE' in the profile. This variable has priority over 'private_address' in the outgoing direction. 
| 
|-
| calling_subscriber_noa 
| Q931: 2nd 'Calling party number' IE - Type of number 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - nature of address indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_npi 
| Q931: 2nd 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - numbering plan indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
 
| 
|-
| calling_subscriber_presentation 
| Q931: 2nd 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - presentation restricted indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_screening 
| Q931: 2nd 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - screening 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| private_display 
| Q931: 'Facility CNAM' IE when presentation is restricted for DMS/NI2 variants 
| N/A 
| N/A 
|
SIP:P-asserted-identity - display-name 

SIP:Remote-party-id - display-name 

| 
| 
|-
| private_display_type 
| N/A 
| N/A 
| N/A 
| N/A 
| Indicate presence or not of the private calling information 
| 
|-
| private_address 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 

| For example : The 'fluffy' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_sip_host 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - host (domain or IP)

SIP:Remote-party-id - host (domain or IP) 

| For example : The 'telcobridges.com' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_sip_port 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - port

SIP:Remote-party-id - port 

| For example : The '6060' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| called 
| Q931: 'Called party number' IE - Number digits 
| DNIS (Group A) 
| Q763: 'Called party number' IE - address signals 
| SIP:To - user-info and host 
| 
| 
|-
| called_sip_host 
| N/A 
| N/A 
| N/A 
| SIP:To - host 
| For example : The 'telcobridges.com' in To: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| called_sip_port 
| N/A 
| N/A 
| N/A 
| SIP:To - port number 
| For example : The '6060' in To: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| called_noa 
| Q931: 'Called party number' IE - Type of number 
| N/A 
| Q763: 'Called party number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| called_npi 
| Q931: 'Called party number' IE - Numbering plan identification 
| N/A 
| Q763: 'Called party number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| charge_number 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - address signals 
| N/A 
| 
| 
|-
| charge_number_noa 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| charge_number_npi 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| redirecting_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default redirecting number and original called number forwarding behavior from incoming to outgoing leg 
| 
|-
| redirecting_number 
| Q931: 'Redirecting number' 1st IE - Number digits 
| N/A 
| Q763: 'Redirecting number' IE - address signals 
| SIP:Diversion (2nd header) - display-name 
| 
| 
|-
| redirecting_number_noa 
| Q931: 'Redirecting number' 1st IE - Type of number 
| N/A 
| Q763: 'Redirecting number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| redirecting_number_npi 
| Q931: 'Redirecting number' 1st IE - Numbering plan identification 
| N/A 
| Q763: 'Redirecting number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| redirecting_number_presentation 
| Q931: 'Redirecting number' 1st IE - Presentation indicator 
| N/A 
| Q763: 'Redirecting number' IE - address presentation restricted indicator 
| SIP:Diversion (2nd header) - diversion-privacy 
| 
| 
|-
| redirecting_number_indicator 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirecting indicator 
| N/A 
| 
| 
|-
| redirecting_number_reason 
| Q931: 'Redirecting number' 1st IE - Reason for redirection 
| N/A 
| Q763: 'Redirection information' IE - redirecting reason 
| SIP:Diversion (2nd header) - diversion-reason 
| 
| 
|-
| redirecting_number_counter 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirection counter 
| SIP:Diversion (2nd header) - diversion-counter 
| 
| 
|-
| original_called_number
(OCN) 
| Q931: 'Redirecting number' 2nd IE - Number digits 
| N/A 
| Q763: 'Redirection number' IE - address signals 
| SIP:Diversion  (1st header) - display-name 
| 
| 
|-
| original_called_number_noa 
| Q931: 'Redirecting number' 2nd IE - Type of number 
| N/A 
| Q763: 'Redirection number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| original_called_number_npi 
| Q931: 'Redirecting number' 2nd IE - Numbering plan identification 
| N/A 
| Q763: 'Redirection number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| original_called_number_presentation 
| Q931: 'Redirecting number' 2nd IE - Presentation indicator 
| N/A 
| Q763: 'Redirection number' IE - address presentation restricted indicator 
| SIP:Diversion (1st header) - diversion-privacy 
| 
| 
|-
| original_called_number_reason 
| Q931: 'Redirecting number' 2nd IE - Reason for redirection 
| N/A 
| Q763: 'Redirection information' IE - original redirection reason 
| SIP:Diversion (1st header) - diversion-reason 
| 
| 
|-
| original_called_number_counter 
| N/A 
| N/A 
| N/A 
| SIP:Diversion (1st header) - diversion-counter 
| 
| 
|-
| ported_number_npdi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - with qualifier=Ported number is present 
| SIP:RequestURI - npdi=yes is present 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number 
| N/A 
| N/A 
| Q763: 'Generic number' IE - address signals with qualifier=Ported number 
| SIP:RequestURI - to user part when rn is present 
| rn is stored in the called number 
| 
|-
| ported_number_noa 
| N/A 
| N/A 
| Q763: 'Generic number' IE - nature of address indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number_npi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - numbering plan indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| oli
(Originating line information) 
| 5ESS Codeset 6 OLI - Value 
| N/A 
| ANSI: 'Originating line information' IE - OLI 
|
SIP:From - oli

SIP:P-asserted-identity - oli 

| 
| 
|-
| request_uri 
| N/A 
| N/A 
| N/A 
| Complete Request URI string 
| 
| 
|-
| request_uri_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default URI forwarding behavior from incoming to outgoing leg 
| 
|-
| sip_header 
| N/A 
| N/A 
| N/A 
| Any header 
| Requires option 'Forward custom headers' in Profiles->SIP 
| 2.7.63 
|-
| nap
(Network Access Point) 
| N/A 
| N/A 
| N/A 
| N/A 
| Incoming leg NAP name (read-only) 
| 
|-
| type_of_network_identification 
| Q931: 'Transit network selection' IE - Type of network identification 
| N/A 
| Q763: 'Transit network selection' IE - Type of network identification 
| N/A 
| 
| 2.7 
|-
| network_identification 
| Q931: 'Transit network selection' IE - Network identification 
| N/A 
| Q763: 'Transit network selection' IE - Network identification 
| SIP: Request-Line - cic 
| 
| 2.7 
|-
| network_identification_plan 
| Q931: 'Transit network selection' IE - Network identification plan 
| N/A 
| Q763: 'Transit network selection' IE - Network identification plan 
| N/A 
| 
| 2.7 
|-
| location_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default location number forwarding behavior from incoming to outgoing leg 
| 2.7 
|-
| location_number 
| N/A 
| N/A 
| Q763: 'Location number' IE - address signals 
| N/A 
| 
| 2.7 
|-
| location_number_noa 
| N/A 
| N/A 
| Q763: 'Location number' IE - nature of address indicator 
| N/A 
| 
| 2.7 
|-
| location_number_npi 
| N/A 
| N/A 
| Q763: 'Location number' IE - numbering plan indicator 
| N/A 
| 
| 2.7 
|-
| location_number_presentation 
| N/A 
| N/A 
| Q763: 'Location number' IE - presentation restricted indicator 
| N/A 
| 
| 2.7 
|-
| location_number_screening 
| N/A 
| N/A 
| Q763: 'Location number' IE - screening 
| N/A 
| 
| 2.7 
|-
| mlpp_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| A script needs to set this to true if it wants to overwrite MLPP information in the outgoing leg. Otherwise, profile relay 'outgoing mode' applies automatically. 
| 2.7 
|-
| mlpp_look_for_busy 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - look ahead for busy 
| N/A 
| 
| 2.7 
|-
| mlpp_precedence_level 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - precedence level 
| SIP:Resource-Priority - q735 
| 
| 2.7 
|-
| mlpp_network_identity 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - network identity 
| N/A 
| 
| 2.7 
|-
| mlpp_service_domain 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - MLPP service domain 
| N/A 
| 
| 2.7 
|-
| called_isub 
| Q931: 'Called party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub parameter 
| 
| 2.7 
|-
| called_isub_type 
| Q931: 'Called party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub-encoding parameter 
| 
| 2.7 
|-
| calling_isub 
| Q931: 'Calling party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub 
| 
| 2.7 
|-
| calling_isub_type 
| Q931: 'Callinf party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub-encoding 
| 
| 2.7 
|-
| ss7_fci_default 
| N/A 
| N/A 
| Default forward call indicator (FCI) value. 
| N/A 
| Toolpack will overwrite FCI bits A, D, F, I and M with appropriate values according to call conditions 
| 2.7 
|-
| ss7_fci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_fci_default that must be forced. 
| N/A 
| Bits from ss7_fci_default which corresponding bit in ss7_fci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| ss7_bci_default 
| N/A 
| N/A 
| Default backward call indicator (BCI) value. 
| N/A 
| Toolpack will overwrite BCI bits AB, I, K, M and N with appropriate values according to call conditions 
| 2.7 
|-
| ss7_bci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_bci_default that must be forced. 
| N/A 
| Bits from ss7_bci_default which corresponding bit in ss7_bci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| tdm_ls_name_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable line service and timeslot selection to create the outgoing leg 
| 3.0 
|-
| tdm_ls_name
(Line Service or T1/E1 trunk) 
| Incoming leg line service name 
| Incoming leg line service name 
| Incoming leg line service name 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this line service name to create outgoing leg 
| 2.7 
|-
| tdm_timeslot_nb 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this timeslot number to create outgoing leg 
| 2.7 
|-
| rtp_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP port 
| (read-only) 
| 2.7 
|-
| rtp_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP port 
| (read-only) 
| 2.7 
|-
| ss7_cot_enabled 
| N/A 
| N/A 
| Requests SS7 in-call continuity test for this outgoing SS7 call 
| N/A 
| Toolpack will request a continuity test on the timeslot before making the outgoing call. If COT fails, the call will be dropped (then another route may be attempted) 
| 2.8 
|-
| reverse_charging_indication 
| Incoming leg Reverse charging indication IE present 
| N/A 
| N/A 
| N/A 
| If set in routing script, will add Reverse charging indication IE in outgoing leg (also use reverse_charging_indication_forward_enabled) 
| 2.8.12 
|-
| reverse_charging_indication_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable forwarding of reverse charging indication from incoming to outgoing leg 
| 2.8.12 
|-
| sip_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP port 
| (read-only) 
| 2.8.13 
|-
| sip_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP port 
| (read-only) 
| 2.8.13 
|}

 

=== Noa values ===
The text below represents the value normally used by routing script. 
Incase it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 
Example numeric values for the SS7 protocol are shown in parenthesis. 
 
*<tt>unknown_number (0x2)</tt>
*<tt>international_number (0x4)</tt>
*<tt>national_number (0x3)</tt>
*<tt>subscriber_number (0x1)</tt>
*<tt>network_specific (0x5)</tt>
*<tt>network_routing_national_format (0x7)</tt>
*<tt>network_routing_international_format (0x8)</tt>
*<tt>abbreviated_number (0x6)</tt>
*<tt>subscriber_number_operator_requested (0x71)</tt>
*<tt>national_number_operator_requested (0x72)</tt>
*<tt>international_number_operator_requested (0x73)</tt>
*<tt>no_number_present_operator_requested (0x74)</tt>
*<tt>no_number_present_cut_through_call_to_carrier (0x75)</tt>
*<tt>test_line_test_code (0x77)</tt>
*<tt>non_unique_subscriber_number (0x71)</tt>
*<tt>non_unique_national_number (0x73)</tt>
*<tt>non_unique_international_number (0x74)</tt>
*<tt>call_950_numbe (0x76)</tt>
*<tt>special_number (0x73)</tt>
*<tt>national_number_with_transit_network_selection (0x74)</tt>
*<tt>international_number_with_transit_network_selection (0x75)</tt>

Those values will be remapped to the protocol specific NOA value. To provide protocol specific value:

*<tt>call_params[:called_noa] = 0x70</tt>

or

*<tt>call_params[:called_noa] = 112</tt>

=== Npi values ===

*<tt>unknown_number</tt>
*<tt>isdn</tt>
*<tt>telephony</tt>
*<tt>private</tt>
*<tt>data</tt>
*<tt>telex</tt>
*<tt>national</tt>

=== Calling Display Type values ===

*<tt>unspecified</tt> => Type is unspecified.
*<tt>calling_party_name</tt> => Type is 0xB1.

Those values will be remapped to the protocol specific Display Information Type value. To provide protocol specific value:

*<tt>call_params[:calling_display_type] = 0xB1</tt>

or

*<tt>call_params[:calling_display_type] = 177</tt>

=== Calling Display value ===

*<tt>call_params[:calling_display] = "Roger Fluffy"</tt>

=== Presentation values for Calling number, Calling Subscriber (Generic Number), Redirecting Number, Original Called Number (OCN) and Location Number ===
The text below represents the value normally used by routing script. 
Incase it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 
Example numeric values for the SS7 protocol are shown in parenthesis. 
 
*<tt>unspecified</tt>
*<tt>not_available (0x2)</tt>
*<tt>allowed (0x0)</tt>
*<tt>restricted (0x1)</tt>
*<tt>addr_restricted</tt>
*<tt>name_restricted</tt>

=== Calling Party Category ===
The text below represents the value normally used by routing script. 
In case it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 

Mapping from routing script to SS7/CAS R2/SIP
{| cellspacing="1" cellpadding="1" border="1"
|-
! scope="col" | '''Routing Script string '''
! scope="col" | '''SS7 raw value '''
! scope="col" | '''R2 CAS scripts''' 
! scope="col" | '''Default Rx CAS''' 
! scope="col" | '''default Tx CAS''' 
! scope="col" | '''SIP "cpc=" '''
|-
| subscriber 
| 0xa 
| CATEGORY_SUBSCRIBER 
| 1 and 7 
| 7 
| ordinary 
|-
| subscriber_with_priority 
| 0xb 
| CATEGORY_SUBSCRIBER_WITH_PRIORITY 
| 2 and 9 
| 2 
| priority 
|-
| operator_french 
| 0x1 
| CATEGORY_OPERATOR_FRENCH 
| 5 
| 5 
| operator 
|-
| operator_english 
| 0x2 
| CATEGORY_OPERATOR_ENGLISH (5) 
| 5 
| 5 
| operator 
|-
| operator_german 
| 0x3 
| CATEGORY_OPERATOR_GERMAN (5) 
| 5 
| 5 
| operator 
|-
| operator_russian 
| 0x4 
| CATEGORY_OPERATOR_RUSSIAN (5) 
| 5 
| 5 
| operator 
|-
| operator_spanish 
| 0x5 
| CATEGORY_OPERATOR_SPANISH (5) 
| 5 
| 5 
| operator 
|-
| data 
| 0xc 
| CATEGORY_DATA 
| 6 and 8 
| 6 
| datacall 
|-
| test 
| 0xd 
| CATEGORY_TEST 
| 3 
| 3 
| test 
|-
| payphone 
| 0xf 
| CATEGORY_PAYPHONE 
| none 
| 7 
| payphone 
|-
| unknown 
| 0x0 
| CATEGORY_UNKNOWN 
| 4, 11 to 15 
| 7 
| unknown 
|-
| unspecified 
| 0xa 
| invalid 
| none 
| none 
| invalid 
|}
[[CAS_R2_scripting#Category_meanings|Link to calling party categories used in CAS R2 scripts]]

=== Screening values for Calling number, Calling Subscriber (Generic Number), and Location Number ===
The text below represents the value normally used by routing script. 
Incase it's required to use a value that's not defined in the text values below, a integer can be provided and will be used "as-is" in the signaling message. 
Example numeric values for the SS7 protocol are shown in parenthesis. 
 
*<tt>unspecified</tt>
*<tt>no (0x0)</tt>
*<tt>pass (0x1)</tt>
*<tt>fail (0x2)</tt>
*<tt>network_provided (0x3)</tt>

=== Redirecting indicator values ===

SS7:

*<tt>no_redirection</tt>
*<tt>call_rerouted</tt>
*<tt>call_rerouted_all_restricted</tt>
*<tt>call_diverted</tt>
*<tt>call_diverted_all_restricted</tt>
*<tt>call_rerouted_restricted</tt>
*<tt>call_diverted_restricted</tt>
*<tt>spare</tt>

=== Redirecting number, Original Called Number and Diversion Reason ===

ISDN:

*<tt>unknown</tt>
*<tt>busy</tt>
*<tt>no_reply</tt>
*<tt>deflection</tt>
*<tt>dte_out_of_order</tt>
*<tt>forwarding_by_called_dte</tt>
*<tt>unconditional</tt>

SS7:

*<tt>unknown</tt>
*<tt>busy (SIP: user-busy)</tt>
*<tt>no_reply (SIP: no-answer)</tt>
*<tt>unconditional</tt>
*<tt>deflection</tt>
*<tt>deflection_immediate</tt>
*<tt>mobile_not_reachable</tt>

=== OLI (originating line information) values ===

The OLI parameter is a string that represents an integer value from 0 to 255.

=== Information Transfer Capability values ===

information_transfer_capability:

*<tt>digital</tt>
*<tt>restricted_digital</tt>
*<tt>digital_with_tones</tt>
*<tt>speech</tt>
*<tt>3_1_khz_audio</tt>
*<tt>video</tt>

=== redirecting_number_forward_enabled values ===

Controls forwarding or discarding of redirecting number (SIP: diversion header) to the outgoing call leg.

Values for this parameter are "0", "1", "false" or "true.
*0/false: Redirecting number (and original called number) is not forwarded to outgoing call leg
*1/true: Redirecting number (and original called number) is forwarded to outgoing call leg

The value for this parameter at the input of the routing script depends on the "Forward redirecting number" parameter in the "Advanced" section of the Gateway configuration page of the Web Portal. The script may change this value to override the Gateway configuration.

Note: To "insert" a new redirecting number value on the outgoing leg, redirecting_number_forward_enabled must also be set to true.

=== request_uri ===

Enables access to the Request-Line URI. 

For example, if the Request-Line is:
<pre>Request-Line: INVITE sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0</pre>
Then the retrieved request_uri will be "sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0". 

In the routing scripts, to retrieve only the called number, this script can be used: 
<pre> if call_params[:request_uri] && call_params[:request_uri] =~ /sip:(.*)@.*/
call_params[:called] = $1
end
</pre>
==== request_uri_forward_enabled ====

This call parameter controls forwarding or discarding of request uri to outgoing call leg.The request uri is the information in the "Request-Line:" of the SIP INVITE message. 

Values for this parameter are "0", "1", "false" or "true. 

* 0/false: Request uri is not forwarded to outgoing call leg 

* 1/true: Request uri is forwarded to outgoing call leg 

The default value for this parameters is false. 

==== sip_scheme ====
(Available in Toolpack 3.1+)
This call parameters indicates the scheme (generally "sip" or "sips") of the incoming call.

This also allows to control the scheme used for the outgoing call (regardless if request_uri_forward_enabled is used or not)

Note: sips scheme must only be used on TLS NAPs (will cause call routing failure if NAP has only UDP or TCP transport types).

=== sip_header values ===
Contains custom sip headers from the inbound call leg. Any custom sip header can be added to an outgoing call leg: 

'''Note:'''

The SIP header is in string format.

'''string format:'''
<pre>call[ :sip_header ] = "P-my-custom-header:value1 \nP-my-custom-header2:value2 \nP-my-custom-header3:value3"
</pre>
(Note: \n above are actual newline characters, not '\' followed by 'n')

* PCAP sample: [[File:TB_Custom_SIP_Headers.pcap]]

List of sip headers that will not appear in call[:sip_header] since they are already processed by the SIP stack:
<pre>
Accept Error-Info Remote-Party-ID
Accept-Contact Event Replaces
Accept-Encoding Expires Reply-To
Accept-Language From Request-Disposition
Alert-Info In-Reply-To Subject
Allow Max-Forwards Subscription-State
Allow-Events MIME-version Supported
Also Min-Expires Timestamp
Anonymity Min-SE To
Authorization Organization Unsupported
Authentication-Info Path User-Agent
Call-ID Priority Via
Call-Info Privacy Warning
Contact Proxy-Authenticate WWW-Authenticate
Content-Disposition Proxy-Authorization Require
Content-Encoding Proxy-Require Response-Key
Content-Language P-Media-Authorization Retry-After
Content-Length P-Preferred-Identity RPID-Privacy
Content-Type P-Asserted-Identity Route
CSeq RAck RSeq
RAck Reason Security-Client
Reason Record-Route Security-Server
Date Refer-To Security-Verify
Diversion Referred-By Server
Encryption Reject-Contact Service-Route
Session-Expires
</pre>

=== sip header parameters ===
The routing script can read (and modify) some SIP header parameters (user parameters, URI parameters or header parameters) from some SIP headers (To, From, P-Asserted-Identity, Remote-Party-ID, Contact).

==== Available parameters ====
* '''call[ :calling_parameters ]''' (SIP "From" header)
* '''call[ :called_parameters ]''' (SIP "To" header)
* '''call[ :private_address_parameters ]''' (SIP "P-Asserted-Identity" or "Remote-Party-ID" header)
* '''call[ :contact_parameters ]''' (SIP "Contact" header)

These parameters (if present) contain a hash with 3 keys: user_param, uri_param and header_param.
Each of this key points to a string that contains all the parameters found in the corresponding SIP header.
* '''User parameters''' (parameters between the user name/number and the host). Example <sip:alice;'''param=value'''@somewhere.com>
* '''URI parameters''' (parameters at the end of the URI). Example <sip:alice@somewhere.com;'''param=value'''>
* '''Header parameters''' (outside the URI). Example <sip:alice@somewhere.com>;'''param=value'''
Example to print all parameters of SIP "To" header:
call[ :called_parameters ].inspect -> '{ :user_param => "name1=value1;name2=value2", :uri_param => "name=value", :header_param => "name=value;example_param_without_value" }'
Example to modify (replace) the URI parameters of SIP "To" header:
call[ :called_parameters ][ :uri_param ] = "user=phone"

==== Exceptions ====
'''Note:''' Some parameters are reported as their own call attribute (oli, isub, cpc, transport) so they have the same representation for all protocols (SS7, IDSN, SIP). They won't appear present in the generic SIP header parameters structures above.

==== Forwarding from inbound to outbound call ====
By default, the parameters are not forwarded in a SIP to SIP call flow. The parameters '''will be forwarded''' when:
* accessed (read) from either the inbound or outbound call parameters
* written in either the inbound or outbound call parameters

==== Example usage ====
Example to print the user parameters:
<pre>
if call[:calling_parameters]
puts "user parameters = #{call[:calling_parameters][:user_param].inspect}"
end
</pre>

Example SIP "From" header:
From:<sip:123456782;test1=val1;test2=val2@something.com;test3=val3;test4=val4>;test5=val5;test6=val6
And the resulting content in the routing script:
calling_param.inspect -> {:user_param=>"test1=val1;test2=val2", :uri_param=>"test3=val3;test4=val4", :header_param=>"test5=val5;test6=val6"}

'''Note''' that printing the inbound or outbound call parameters is considered as a "read" action and would result in forwarding the parameter on the outbound leg.

Example to overwrite inbound leg calling parameters with new parameters for the outbound leg:
<pre>
call [:calling_parameters] = {
:user_param => "user_param7=7;user_param8=8",
:uri_param => "uri_param9=value9",
:header_param => "header_paramA=A" }
</pre>

Example to add user=phone and keep all other uri parameters.
<pre>
call[:calling_parameters] ||= {} # Create a hash if not already present
call[:calling_parameters][:uri_param] ||= "" # Create a string if not already present
call[:calling_parameters][:uri_param] += ";" if call[:calling_parameters][:uri_param] != ""
call[:calling_parameters][:uri_param] += "user=phone"
</pre>

=== MLPP Precedence values ===

mlpp_look_for_busy:

*<tt>allowed</tt>
*<tt>path_reserved</tt>
*<tt>not_allowed</tt>

mlpp_precedence_level:

*<tt>flash_override</tt>
*<tt>flash</tt>
*<tt>immediate</tt>
*<tt>priority</tt>
*<tt>routine</tt>

mlpp_network_identity:

3 digits value from 0 to 999

mlpp_service_domain:

24 bits value from 0 to 16777215

=== ISUB subaddress information values ===

called_isub_type:
calling_isub_type:

*<tt>nsap</tt>
*<tt>nsap_ia5</tt>
*<tt>nsap_bcd</tt>
*<tt>user</tt>

called_isub:
calling_isub:

Digits for the subaddress information.

=== Network Identification Plan ===

network_identification_plan:

*<tt>Unknown</tt> (value 0)
*<tt>cic</tt> (3 digits carrier identification code plus circuit code, value 1, SS7 or ISDN)
*<tt>user</tt> (User, value 2, ISDN only)
*<tt>cic4</tt> (4 digits carrier identification code plus circuit code, value 2, SS7 only)
*<tt>dnic</tt> (public Data Network ID, value 3, SS7 only)
*<tt>mnic</tt> (public land mobile network, value 6, SS7 only)

=== Registered Users Information ===
Routing script can access information about registered users (when either the calling or called user is a known registered user).
When these fields are empty, it means that the calling/called (SIP from/to) does not correspond to a known registered user (routing script may still decide to route the call based on static routes).

Information for the called user:
params[:registered_user]
Information for the calling user:
params[:calling_registered_user]

These parameters are a hash of key/values that provide information about the contact.
{
:contact_list=>
[
{
:contact=>"<sip:user_name_or_number@hostname:7070;transport=UDP>", -> Full contact
:expires=>"60", -> Contact expiry time (seconds)
:host=>"hostname", -> host name from the contact header
:name=>"user_name_or_number", -> user name from the contact header
:nap_in=>"NAP_NAME", -> NAP that the contact has registered from
:port=>"7070", -> Port from the contact header
:transport=>"UDP" -> Transport type from the contact header
:q_value=>"0.00", -> Q-value for the contact (for contact ordering)
:src_host=>"10.0.0.10", -> Actual source IP address that the contact has registered from
:src_port=>"7070", -> Actual source port that the contact has registered from
:src_transport=>"UDP", -> Actual protocol that the contact has been registering with
}
]
}

== Route parameters ==

All route may have these parameters:

*calling
*called
*nap
*remapped_calling
*remapped_called
*remapped_nap
*remapped_destination_leg_profile (called remapped_profile prior to Toolpack 2.9)
*remapped_source_leg_profile (called remapped_incoming_profile prior to Toolpack 2.9)

Example:

route[:remapped_nap]

Additionally it is possible to add dynamic route attributes in the web portal. These can be referenced by their name.
For example:
*priority
*weight

== Routing calls toward registered users ==
Static routes normally chose an outbound NAP to forward the call to.

But it's also possible to create routes which outbound NAP is dynamically chosen by matching a registered user (when using [[Sip_registration_forwarding|SIP registration forwarding]]).

More information can be found [[Sip_registration_forwarding#SIP_Calls_routing|here]] about the way to control the [[Sip_registration_forwarding#SIP_Calls_routing|priority of "dynamic" vs "static" routes]].

More information can be found [[#Registered_Users_Information|here]] about using routing scripts to access registered users information during call routing.

== Playing prompts announcements or tones ==

New feature in release 2.6, all bridges may have these parameters. These can be used to play IVR prompts (audio files) in different states of the call flow.

*'''announcement_tone''' (played before outgoing call is routed)
*'''ring_tone''' (played after when waiting for outgoing call to answer)
*'''busy_tone''' (played if outgoing call failed)
*'''disconnect_tone''' (played after the call has reached it's maximum duration)

Example to play an announcement to incoming call (before routing outgoing call, regardless if a matching route is found or not):
bridge[:announcement_tone ] = "my_announcement.wav"

Example to play a ring-tone while the outgoing call is ringing:
bridge[:ring_tone] = "my_ring_tone.wav"

Example to play an audio file when outgoing call fails (no route, or outgoing call is refused):
bridge[:busy_tone] = "my_busy_tone.wav"

Example to play an audio file when call has reached the maximum allowed duration:
bridge[:disconnect_tone] = "your_account_balance_is_empty.wav"

=== Announcement file path format and options ===

All file plabyacks (:announcement_tone, :busy_tone, :ring_tone, :disconnect_tone) inside bridge parameters use this format.
<pre>"file1.wav:repeat:start_off:end_off,file2.wav:repeat:start_off:end_off,file3.wav:repeat:start_off:end_off"
</pre>
Optional parameters:
* repeat: number of times to play the file (0 and 1 have the same result)
* start_off: Start offset in milliseconds
* end_off: End offset in milliseconds

Http and other path formats are described here: [[Customer_application_framework:play_audio_files#Play_path_format|Path format]]

==== Example 1 ====
The following example will play file1.wav once, and then play file2.wav in loop:
"file1.wav,file2.wav:-1"

==== Example 2 ====
The following example will play file1.wav from start offset of 1 second to end offset of 3 seconds, then twice file2.wav from second 5 to second 10.
"file1.wav:0:1000:3000,file2.wav:2:5000:10000"

==== Example 3 ====
The following example will play file1.wav once, ending at offset of 30 seconds.
"file1.wav:0:0:30000"

=== announcement_tone ===

params[:bridge][:announcement_tone] = "announcement.wav"

Audio file played on the incoming call before any outgoing call is placed. The outgoing call occurs when the file finished playing.

==== announcement_tone options ====
===== announcement_tone_answer =====
params[:bridge][:announcement_tone_answer] = "yes"

Forces an answer of the call before playing the announcement. Default if argument not provided is "no", in which case call is only alerted with in-band media.

===== announcement_code_detect =====
This option allows that the tone detection is enabled during the announcement play.

Collected digits can be inserted into the CDR logs (radius attribute "Telcob-CollectedDigits", or text CDR variable @{CollectedDigits}).

Collected digits can also be sent back to routing script, which is called again with the same call attributes, except that the called number is replaced by the collected digits.

Code detect has multiple options, as shown in the following code:
code_detect = {
:type => :DTMF, # :DTMF or :MFR1 tone detection.
# Default is MFR1.
:prefix => "", # Prefix (digits) that is removed from collected digits.
# Default is empty.
:suffix => "", # Suffix (digits) that is removed from collected digits
# and causes routing script to be immediately called.
# Default is empty.
:suffix_removal => false, # Controls the removal of the suffix from the collected digit string that's reported to routing script.
# Default is false
:timeout => 0, # Inter-digit timeout (ms) after which collected digits are passed to the routing script.
# Use 0 for "no timeout".
# Default is 1000ms
:barge_in_interruption => true, # When enabled, playing announcement is stopped as soon as first digit is collected.
# Default is true.
:proceed_on_play_done => false, # When true: Outgoing call is made after announcement finishes playing.
# Routing script is not called again.
# When false: Outgoing call is never made.
# Digits are collected until timeout or suffix match,
# then routing script is called again.
# Default is false.
:cas_on_hook => false, # Specific for CAS-R1 calls. Makes CAS bits switch to "on-hook" when announcement finished playing
# (but the call is not "terminated" from Toolpack point of view)
# Default is false.
:cas_on_hook_delay => 0, # Duration of cas bits "on-hook" state.
# Only effective if cas_on_hook is set to true.
# Value of 0 stands for "infinite delay".
# Default is 0.
:repeat_delay => 0, # Delay between repetition of the announcement. The announcement will repeat
# itself every "repeat_delay" until a code is detected (suffix match or timetout).
# Value of 0 stands for "infinite delay" (no repeating).
# Default is 0.
}
'''Example 1''': Collect DTMF digits, and call routing script again with collected digits upon timeout or suffix match.
code_detect = { :type => :DTMF, :suffix => "#", :timeout => 5000 }
params[:bridge][:announcement_code_detect] = code_detect

'''Example 2''': Collect digits during the announcement (for CDR logs), then proceed (make outgoing call) after announcement finishes playing
code_detect = { :type => :DTMF, :timeout => 0, :barge_in_interruption => false, :proceed_on_play_done => true }
params[:bridge][:announcement_code_detect] = code_detect

==== Controlling what happens after announcement ====
The routing script can control what happens with the call after the announcement finishes playing:
* An outgoing call is made
* Incoming call is hung-up
* Do nothing (wait for the incoming call to hang-up)
===== An outgoing call is made =====
This happens when the script has returned matching routes (and did not raise RoutingException)

===== Incoming call is hung-up =====
This happens when the script returns no routes (in which case base_routing will raise RoutingException with cause :no_route).

It also happens when the script explicitly raises RoutingException.

The incoming call will be terminated with the specified cause.
For example
raise RoutingException, :temporary_failure
(See "Reason values" section in this page for list of available causes)

===== Do nothing (wait for the incoming call to hang-up) =====
If a filter raises RoutingException with code :ok, then the incoming call will not be terminated at the end of the announcement play.
Announcement digit collection will remain active if appropriate.
For example:
raise RoutingException, :ok

=== ring_tone ===
params[:bridge][:ring_tone] = "ringing.wav"

Audio file played on the incoming call while waiting for the outgoing call to be answered.

Ring tone playback can also be configured in the Web Portal, from the incoming call's profile (under "Tones and Call Progress Options").

Routing script has precedence over profile (a routing script that fills params[:bridge][:ring_tone] will override the profile's ring tone behavior).

==== ring_tone options ====
===== ring_tone_state =====
params[:bridge][:ring_tone_state] = :alerted

Call state from which ring tone is being played. Available values are:
* '''immediately''': Ring tone starts playing immediately on the incoming leg
* '''accepted''': Ring tone starts playing as soon as outgoing call is accepted
* '''callprogress''': Ring tone starts playing as soon as "call progress" is received on the outgoing call
* '''alerted''' (default): Ring tone starts playing only once outgoing call is alerted (but won't play if alert indicates early media from outgoing call)

This option also apply when params[:bridge][:ring_tone] is not used, because it also apply to ring tone playback configured in the Web Portal, from the incoming call's profile.

=== busy_tone ===
Toolpack 2.8 and above:
params[:bridge][:busy_tone] = "no_route.wav"

Note: Obsolete name (toolpack 2.7.153 and earlier, but still supported in recent releases):
params[:bridge][:call_progress_tone] = "no_route.wav"

Audio file played on the incoming call when outgoing call fails (never answered).

Note that announcement_tone, if used, is played before the outgoing call attempt is made, and thus before the busy_tone.

Busy tone playback can also be configured in the Web Portal, from the incoming call's profile (under "Tones and Call Progress Options").

Routing script has precedence over profile (a routing script that fills params[:bridge][:busy_tone] will override the profile's busy tone behavior).

Special value '''"none"''' can be used by routing script to force playing nothing (as empty string would default to profile's behavior)

==== busy_tone options ====
===== busy_tone_answer =====
params[:bridge][:busy_tone_answer] = "yes"

Forces an answer of the call before playing the busy tone. Default if argument not provided is "no", in which case call is only alerted with in-band media.

=== disconnect_tone ===
params[:bridge][:disconnect_tone] = "max_duration.wav"

Audio file played on the incoming call when call duration (:max_call_duration) is reached. Then the leg will be terminated with specified reason (:call_duration_reason).

==== disconnect_tone options ====
===== max_call_duration =====
params[:bridge][:max_call_duration] = "60000"

Maximum call duration in millisecond. This timer is started when entering answer state.

===== call_duration_reason =====
params[:bridge][:call_duration_reason] = :resource_unavailable

Drop both legs with this reason when call duration (:max_call_duration) is reached.

=== Managing audio prompts through Web Portal ===
Audio prompts can be uploaded or deleted from the TMedia unit through the Web Portal:
[[Toolpack:Configuring_Audio_Prompts_A|Managing audio prompts]]

Prompts management must be done using the Web Portal of the primary server (in systems with redundant TMedia units or redundant host servers).
The file will automatically get replicated to the secondary server.

=== Managing audio prompts manually ===
Any file on the TMedia host file system can be played. This means it's possible to manage prompts through ssh/scp.

==== The default (replicated) prompts folder ====
By default, when playing a prompt, Toolpack will look in the default prompts folder:
/lib/tb/toolpack/pkg/prompts
The root of this "prompts" directory is automatically replicated to secondary unit of redundant setups (1+1, N+1, redundant hosts). Sub-folders won't be replicated.

Any prompt play request without explicit file path will map to this folder. For example:
params[:bridge][:busy_tone] = "no_route.wav"
This will correspond to file /lib/tb/toolpack/pkg/prompts/no_route.wav

==== Relative file paths ====
Any file path that begins with "file://" is considered relative to the tbstreamserver application's working directory:
/lib/tb/toolpack/setup/12358/2.8/apps/tbstreamserver/
(Where "2.8" may be replaced by the current major version of your system)

For example:
params[:bridge][:busy_tone] = "file://my_folder/no_route.wav"
This will correspond to file /lib/tb/toolpack/setup/12358/2.8/apps/tbstreamserver/my_folder/no_route.wav

==== Absolute file paths ====
Absolute paths can also be provided.
For example:
params[:bridge][:busy_tone] = "file:///root/my_folder/no_route.wav"
This will correspond to file /root/my_folder/no_route.wav

== Recording call legs ==
Introduced in release 2.6.44, it's now possible to use routing scripts to ask for recording incoming and/or outgoing call legs.

See example filter script "call_recording" (created by default in Web Portal routing scripts starting with 2.6.44) for an example.

=== Recording the incoming call leg ===
To record the incoming call leg, the routing script (in a "after filter" for example) has to set the following parameter:

bridge[ :record_incoming ] = ""

=== Recording the outgoing call leg ===
To record the outgoing call leg, the routing script (in a "after filter" for example) has to set the following parameter, per route (the decision to record or not, or the file name to record to, can be set per matching route):

# Need to clone the routes in order to have the right to modify them
routes = clone_routes params[:routes]
routes.each do |route|
route[ :record_outgoing ] = ""
end
# Store modified routes back to the parameters for this outgoing call
params[:routes] = routes

=== Record the outgoing call leg within incoming leg's recorded file (mixing) ===
[...]
route[ :record_outgoing ] = "@{MixWithIncoming}"
[...]

=== Choosing file path to record to ===
The value assigned to ":record_incoming" or ":record_outgoing" is the path to record the file to.

The paths can be absolute, or relative. When relative, they are relative to the "tbstreamserver" application working directory, for example:
/lib/tb/toolpack/setup/12358/2.7/apps/tbstreamserver/

* Empty file name will default to a name that contains various information about the call:
** ''LinkId'': Id common between all legs of this call bridge
** ''LegId'': Unique Id for this leg
** ''Nap'': Current NAP name this call leg is from
** ''Direction'': "IN" or "OUT" (depends if call leg is incoming or outgoing leg)
** ''Calling'': The calling number of this call leg
** ''Called'': The called number of this call leg
** ''Protocol'': The signaling protocol of this call leg (SS7, ISDN, CAS, SIP)
** ''Media info'': Codec + IP/Port for SIP calls, Trunk/Timeslot for TDM calls
* To record outgoing call leg in the same audio file as incoming call leg (mixing), use the following:
** @{MixWithIncoming}: Record outgoing legs in same file as incoming legs
* Variables can be used to insert in the recording path information that's not already available from routing scripts:
** @{CURRENT_PKG}: Version of current package
*** Example: 2.6.45
** @{DATE format}: Prints the date, where 'format' is expressed as described for the 'strftime' function
*** Example: @{DATE %Y-%m-%d} => 2013-01-28
** @{DefaultName}: Replaced by the default file name for recording, which contains:
*** LinkId: Id common between all legs of this call bridge
*** LegId: Unique Id for this leg
*** Nap: Current NAP name this call leg is from
*** Direction: "IN" or "OUT" (depends if call leg is incoming or outgoing leg)
*** Calling: Calling number
*** Called: Called number
*** Protocol: Protocol type of this call (SS7, ISDN, CASR2, SIP)
*** Media info: Codec + IP/Port for SIP calls, Trunk/Timeslot for TDM calls
*** Example: "73EBA698-F3D67B4B-NAP_SS7-IN-5550000-5550001-SS7-TRUNK_BELL_11-24.wav"
*** Example: "73EBA698-73EBA698-NAP_SIP-OUT-5550000-5550001-SIP-G723-10.3.10.101-1050.wav"
** @{DefaultPath}: Default recording folder and file name: "@{RECORD_PATH}/@{DATE %Y-%m-%d}/@{DefaultName}"
*** Example: "/lib/tb/toolpack/setup/12358/recorded_calls/73EBA698-F3D67B4B-NAP_SS7-IN-5550000-5550001-SS7-TRUNK_BELL_11-24.wav"
*** Example: "/lib/tb/toolpack/setup/12358/recorded_calls/73EBA698-73EBA698-NAP_SIP-OUT-5550000-5550001-SIP-G723-10.3.10.101-1050.wav"
** @{Direction}: Direction of current leg (IN our OUT)
*** Example: IN
** @{LegId}: Current LegId (Unique Id for this leg)
*** Example: F3D67B4B
** @{LinkId}: Current LinkId (Id common between all legs of this call bridge)
*** Example: 73EBA698
** @{PKG_HOME}: Path where packages are stored.
*** Note: It's not recomended to use that path on redundant systems, package file replication may cause confusion in recorded files.
*** Example: /lib/tb/toolpack/pkg
** @{PROMPT_PATH}: Default path where audio prompts are stored
*** Note: It's not recomended to use that path on redundant systems, package file replication may cause confusion in recorded files.
*** Example: /lib/tb/toolpack/pkg/prompts
** @{Protocol}: Protocol of current leg
*** Example: SS7
** @{RECORD_PATH}: Default recording folder: "@{TB_SETUP_HOME}/recorded_calls/"
** @{TBX_GW_PORT}: Current "System Id" (also called "Gateway Port")
*** Example: 12358
** And all variables listed here: [[Customer_application_framework:play_audio_files#Helpful_variables_to_build_play_or_record_file_paths|Building play or record file path]]

== Controlling UUI (user-to-user information) relay ==
UUI (user-to-user information) can be present in different messages received by either call leg during a call. For example, information can be carried during the initial invite, other information can be carried when the call is alerted, answered, or terminated.

Routing scripts can control if the UUI received from one leg through the call will be forwarded to the other call leg:
*uui_forward_enabled

Routing scripts can also read and modify the UUI received with the incoming call leg, before it gets forwarded upon creation of the outgoing call leg:
*uui

=== UUI (user-to-user indication) values ===

Byte array represented as ruby String. Use ''bridge=params[:bridge]'', then ''bridge[:uui]'' to access the data.

To access the bytes in Ruby, use ruby String operator []. For example: bridge[:uui][0] will return the binary value of the first UUI byte.

Function each_byte can also be useful to iterate through all bytes of the UUI.

=== uui_forward_enabled values ===

Controls forwarding or discarding of UUI to outgoing call leg.

Values for this parameter are "0", "1", "false" or "true.
* 0/false: UUI is not forwarded between call legs
* 1/true: UUI is forwarded between call legs

The value for this parameter at input of routing script depends on the "Forward UUI" parameter in the "Advanced" section of the Gateway configuration page of the Web Portal. The script may change this value to override the Gateway configuration.

== Authorization ==
Starting with release 2.7, it is possible to issue RADIUS authorization requests from routing scripts. To do so, the params[:authorization] object must be filled with the required RADIUS attributes and [[#Refuse|an exception must be raised]] with reason :authorization_required.

When the authorization is completed, the routing script is called again with the result. The params[:authorization] object will be filled with the RADIUS attributes from the response. The params[:authorization][:result] field will also contain a string indicating the result of the authorization:

* ''accept'': The authorization was successful.
* ''reject'': The authorization was refused.
* ''challenge'': The authorization was challenged.
* ''timeout'': The authorization was not answered.

== Call diversion options ==
It's possible to control the call flow when a call diversion information is received in the alerting state.

Two fields are available: bridge[ :diversion ] and bridge[ :diversion_reason ]

The internal release cause TOOLPACK_DIVERT_NOT_ALLOWED is used by gateway application to terminate both legs.

bridge[ :diversion ] = :allowed
The alert message will not be analyzed and the call will be progressed. Default behavior.
bridge[ :diversion ] = :not_allowed
If the alert message indicates that the call is diverted, the call will be released no matter the In-band information to allow
early media.
bridge[ :diversion ] = :not_allowed_w_early_media
The call will be released If the alert message indicates that the call is diverted with in-band information to allow early media.
bridge[ :diversion_reason ] = "*"
If the diversion is not allowed, the gateway will drop the call for any redirecting reason.
bridge[ :diversion_reason ] = "0,1,2"
or
bridge[ :diversion_reason ] = "unknown,busy,no_reply"
If the diversion is not allowed, the redirecting reason will be analyzed and the call will only be dropped for the configured cases.

See section [[Routing_script_tutorial:Mini_Development_Guide#Redirecting_number,_Original_Called_Number_and_Diversion_Reason|Redirecting number reason values]].

== Call transfer requests ==
Toolpack allows that [[Call transfer]] requests are relayed from one leg to the other, or to process them locally (making another outgoing call to replace the call that requested the call transfer).

If the chosen [[Call transfer]] mode is to process requests locally, upon reception of a call transfer request (SIP REFER or ISDN Facility), routing script will be called once again, to select the routes for the new outgoing call (call transfer target).

=== How to route call transfer request ===
Routing of a call transfer request is done exactly like routing of a normal incoming call.
The routing script generally does not need any modification to support that.

In some cases, the routing script may want to use information related to the transfer request to perform routing, or to insert information in the outgoing call leg.
Additional information is provided to the routing script, allowing routing decisions using information from the call transfer request (SIP REFER or ISDN Facility).
See below...

=== params[ :call ] content during transfer request ===
When processing a call transfer request, the params[ :call ] hash contains the information from the inbound call (same as was passed to the routing script upon arrival of the inbound call)
call = params[ :call ] -> Information from original inbound call, with exception of call[ :called ]

One exception (convenient because it allows a unmodified routing script to process call transfer request the same way as any other routing request):
call[ :called ] -> Replaced by the called number from the call transfer request (also called "redirection number")
Complementary information:
call[ :original_called_number ] -> Contains the called number that was initially received from the incoming call, prior to call transfer request
call[ :redirecting_number ] -> Number of the call from which the call transfer request was received (generally equals to original_called_number)

These fields will also be included in the outgoing call made after routing:
* original called number and redirecting number are existing fields on SS7 and ISDN calls
* SIP "diversion" header is used for SIP calls

=== params[ :transfer ] content ===
(this if valid only for release 2.7.102 and above) 
When processing a call transfer request, information from the call transfer request message (SIP REFER, ISDN Facility) is provided in params[ :transfer ]:
transfer = params[ :transfer ]
The following field is always present:
transfer[ :original_nap ] -> Contains the NAP of the first call from which a call transfer request was received
transfer[ :redirecting_nap ] -> Contains the NAP of the call from which the current call transfer request was received
(same as :original_nap for the first call transfer, different for subsequent transfers)
Examples of other fields that may be present, when appropriate:
transfer[ :uui ] -> The UUI (user-to-user information) found in the call transfer request
transfer[ :sip_header ] -> Contains custom SIP headers from the call transfer request
transfer[ :request_uri ] -> Contains the SIP Request URI

These fields are 'read-only'. They will not be included in the outgoing call, as they represent the contents of the call transfer request, and not the outgoing call to be made.

To insert/modify attributes of the outgoing call, the parameters from params[ :call ] must be edited instead.

== Redirection ==
In release 2.8 and above, redirection contacts are obtained from the routing engine in the following format:

contacts = params[ :contacts ]
contacts = {
:index=>"3",
:list=>[
{:called_number=>"6660", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"", :raw_data=>"", :expiration=>"3600"},
{:called_number=>"6661", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6661@192.168.215.127", :raw_data=>"<sip:6661@192.168.215.127>", :expiration=>"3600"}
{:called_number=>"6662", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6662@192.168.215.128", :raw_data=>"<sip:6662@192.168.215.128>", :expiration=>"3600"},
{:called_number=>"6663", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6663@192.168.215.129", :raw_data=>"<sip:6663@192.168.215.129>", :expiration=>"3600"},
{:called_number=>"6664", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6664@192.168.215.150", :raw_data=>"<sip:6664@192.168.215.150>", :expiration=>"3600"}
],
:source_indexes=>"nil,0,0,0,2"
}

* <code>params[:contacts][:list]</code> contains the contact log. Each contact within the list has the following fields:
** <code>:called_number</code> - the called number
** <code>:is_number_ported</code> - if the called number has been ported (for SIP: if the npdi parameter is present)
** <code>:ported_number</code> - the called number that was ported (for SIP: the rn parameter value, if available)
** <code>:sip_uri</code> - the SIP URI of the contact, without the contact-params section (without the expires and q contact parameters)
** <code>:raw_data</code> - the raw data representing the contact in the signaling protocol. For SIP, this is the full SIP URI (including the expires and q contact parameters).
** <code>:priority</code> - the priority of the contact [0-1000]
** <code>:expiration</code> - the expiration time in seconds of the contact
* <code>params[:contacts][:index]</code> contains the index of the contact that is currently being routed.
* <code>params[:contacts][:source_indexes]</code> contains a comma-separated list of indexes from <code>params[:contacts][:list]</code>. Each index represents the contact from which the contact in the list was obtained from.

To get more information, see:
*[[Routing_script_tutorial:SIP_Redirection_Contacts|SIP Redirection Contacts Parameters in a Call Flow]]

== Connected number ==
Insert a connected number in the answer message of the call flow.

Routing script example:
bridge = params[ :bridge ]
bridge [ :connected_number ] = "3335577"
bridge [ :connected_number_noa ] = :national_number
bridge [ :connected_number_npi ] = :private
bridge [ :connected_number_presentation ] = :allowed
bridge [ :connected_number_screening ] = :pass

== Terminating calls ==
In release 2.8, it is now possible to terminate a call through the routing scripts. The [[#Reason values|reason code]] must be specified in <code>params[:bridge][:reason]</code>. The <code>:terminate</code> hash must be created and copied into <code>params</code>:
terminate = {}
params[:terminate] = terminate
The following fields can then be set in <code>:terminate</code>:
* <code>:sip_header</code>
* <code>:contacts</code> # list of contacts as described in the [[#Redirection|redirection]] section
* <code>:isup_raw</code>
* <code>:isup_raw_variant</code>
* <code>:redirecting_number</code>
* <code>:redirecting_number_noa</code>
* <code>:redirecting_number_npi</code>
* <code>:redirecting_number_presentation</code>
* <code>:redirecting_number_reason</code>
* <code>:redirecting_number_counter</code>
* <code>:redirecting_number_indicator</code>
* <code>:original_called_number</code>
* <code>:original_called_number_noa</code>
* <code>:original_called_number_npi</code>
* <code>:original_called_number_presentation</code>
* <code>:original_called_number_reason</code>
* <code>:original_called_number_counter</code>

== Reason values ==

Check here for Termination Reason Cause codes: 

[[Termination_cause_codes|Termination Reason Cause codes]]
 

Example to refuse an incoming call leg.
raise RoutingException, :no_route

Reason cause strings available inside routing scripts:

List of Q.850 reason causes:
:unallocated_number
:no_route_to_network
:no_route_to_destination
:send_special_tone
:misdialled_trunk_prefix
:channel_unacceptable
:call_awarded_in_established_channel
:preemption
:reattempt
:qor_ported_number
:normal_call_clearing
:user_busy
:no_user_responding
:no_answer_from_user
:subscriber_absent
:call_rejected
:number_changed
:redirection
:exchange_routing_error
:non_selected_user_clearing
:destination_out_of_order
:address_incomplete
:facility_rejected
:response_to_status_enquiry
:normal_unspecified
:no_circuit_available
:network_out_of_order
:frame_mode_out_of_service
:frame_mode_connection_operational
:temporary_failure
:switching_equipment_congestion
:access_information_discarded
:requested_circuit_not_available
:precedence_call_blocked
:resource_unavailable
:quality_of_service_not_available
:requested_facility_not_subscribed
:outgoing_calls_barred
:outgoing_calls_barred_within_cug
:incoming_calls_barred
:incoming_calls_barred_within_cug
:bearer_cap_not_authorized
:bearer_cap_not_available
:inconsistency_access_info
:service_not_available
:bearer_cap_not_implemented
:channel_type_not_implemented
:requested_facility_not_implemented
:only_restricted_digital_info
:service_not_implemented
:invalid_call_reference
:channel_does_not_exist
:call_identity_does_not_exist
:call_identity_in_use
:no_call_suspended
:call_has_been_cleared
:user_not_member_of_cug
:incompatible_destination
:non_existant_cug
:invalid_transit_network
:invalid_message_unspecified
:mandatory_ie_missing
:message_type_non_existent
:message_not_compatible_with_call_state
:ie_non_existent
:invalid_ie_content
:msg_not_compatible_with_call_state
:recovery_on_timer_expiry
:parameter_non_existent_passed_on
:message_with_non_recognized_parameters_discarded
:protocol_error
:interworking_unspecified

List of toolpack reason causes:

:toolpack_normal or :normal
:toolpack_resource_error or :resource_error
:toolpack_timeout or :timeout
:toolpack_no_route or :no_route
:toolpack_call_collision or :call_collision
:toolpack_sync_drop or :sync_drop
:toolpack_signaling_error or :signaling_error
:toolpack_locally_rejected or :locally_rejected
:toolpack_interface_not_available or :interface_not_available
:toolpack_reset_in_progress or :reset_in_progress
:toolpack_adapter_reject or :adapter_reject
:toolpack_missing_or_invalid_ie or :missing_or_invalid_ie
:toolpack_incoming_only or :incoming_only
:toolpack_system_configuration_changed or :system_configuration_changed
:toolpack_resource_no_more_available or :resource_no_more_available
:toolpack_incompatible_media or :incompatible_media
:toolpack_resource_allocation_failed or :resource_allocation_failed
:toolpack_data_path_not_available or :data_path_not_available
:toolpack_local_congestion or :local_congestion
:toolpack_authorization_required or :authorization_required
:toolpack_call_divert_is_not_allowed or :call_divert_is_not_allowed

List of SIP reason causes: 
Reason causes starting with a digit must use the following syntax (can't use : as prefix).

'300_multiple_choices'
'301_moved_permanently'
'302_moved_temporarily'
'305_use_proxy'
'380_alternative_service'
'400_bad_request'
'401_unauthorized'
'402_payment_required'
'403_forbidden'
'404_not_found'
'405_method_not_allowed'
'406_not_acceptable'
'407_proxy_authentication_required'
'408_request_timeout'
'409_conflict'
'410_gone'
'413_request_entity_too_large'
'414_request_URI_too_long'
'415_unsupported_media'
'416_unsupported_URI_scheme'
'420_bad_extension'
'421_extension_required'
'422_session_timer_too_small'
'423_interval_too_brief'
'429_referrer_identity_error'
'480_temporary_unavailable'
'481_call_or_transaction_does_not_exist'
'482_loop_detected'
'483_too_many_hops'
'484_address_incomplete'
'485_ambiguous'
'486_busy_here'
'487_request_terminated'
'488_not_acceptable_here'
'489_bad_event'
'491_retry_after'
'500_server_internal_error'
'501_not_implemented'
'502_bad_gateway'
'503_service_unavailable'
'504_server_timeout'
'505_version_unsupported'
'513_message_too_large'
'600_busy_everywhere'
'603_decline'
'604_not_exist_anywhere'
'606_not_acceptable'

== Nap status ==

All the status fields of the NAPs are provided for use by the routing scripts. See the nap status provider for more details on which fields are available in the CEngineStatTransNap.hpp file.

'''Notice:''' These values may change between major release.

Routing script call attribute name Description
--------------------------------------------------------------------------------------------
"name" NAP name.
"signaling_type" Signaling type (SS7, ISDN, CASR2, SIP)
"profile" Profile name.
"sip_destination_ip" Destination IP address.
"sip_destination_port" Destination IP port.
"sip_transport_type" SIP transport type (:udp, :tcp, or :tls) (Toolpack 3.1 and more)
"inst_incoming_call_cnt" Instantaneous Count of incoming calls.
"inst_outgoing_call_cnt" Instantaneous Count of outgoing calls.
"available_cnt" Number of available circuits or channels.
"unavailable_cnt" Number of unavailable circuits or channels.
"availability_percent" Percentage of available circuits or channels.
"usage_percent" Percentage of used circuits or channels.
"unused_shared_percent" Percentage of used circuits or channels of this NAP available to make new calls with (taking into account shared with other NAPs)
"total_incoming_call_cnt" Total Count of incoming calls.
"global_asr_percent" Global calculated ASR percentage.
"total_outgoing_call_cnt" Total Count of outgoing calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_outgoing_call_cnt" Last 24 hours outgoing calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_outgoing_call_cnt" Current hour outgoing calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_outgoing_call_cnt" Last hour outgoing calls.
"poll_remote_proxy" Remote proxy polling enabled
"is_available" Remote proxy actually available or not
"time_since_polling" Time since the last availibility polling
"time_available_seconds" Number of seconds since the NAP is available
"time_unavailable_seconds" Number of seconds since the NAP is unavailable
"register_to_proxy" Register to proxy enabled
"registered" Actually registered or not
"time_since_refresh" Time since the last refresh
"time_registered_seconds" Number of seconds since the NAP is registered
"time_not_registered_seconds" Number of seconds since the NAP is not registered
"asr_stats_incoming_struct" Detailed Answer-Seizure Rate incoming statistics.
{
"global_asr_percent" Global calculated ASR percentage.
"total_call_cnt" Total count of calls.
"total_accepted_call_cnt" Total count of accepted calls (not dropped due to congestion or rate-limiting).
"total_answered_call_cnt" Total count of answered calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_call_cnt" Last 24 hours count of calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_call_cnt" Current hour count of calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_call_cnt" Last hour count of calls.
}
"asr_stats_outgoing_struct" Detailed Answer-Seizure Rate outgoing statistics.
{
"global_asr_percent" Global calculated ASR percentage.
"total_call_cnt" Total count of calls.
"total_accepted_call_cnt" Total count of accepted calls (not dropped due to congestion or rate-limiting).
"total_answered_call_cnt" Total count of answered calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_call_cnt" Last 24 hours count of calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_call_cnt" Current hour count of calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_call_cnt" Last hour count of calls.
}
"mos_struct" Detailed Mean Opinion Score statistics.
{
"last_24h_ingress" Last 24 hours calculated MOS for incoming RTP packets.
"last_24h_egress" Last 24 hours calculated MOS for outgoing RTP packets.
"current_hour_ingress" Current hour calculated MOS for incoming RTP packets.
"current_hour_egress" Current hour calculated MOS for outgoing RTP packets.
"last_hour_ingress" Last hour calculated MOS for incoming RTP packets.
"last_hour_egress" Last hour calculated MOS for outgoing RTP packets.
}
"network_quality_struct" Detailed network quality statistics.
{
"last_24h_ingress" Last 24 hours network quality percentage for incoming RTP packets.
"last_24h_egress" Last 24 hours network quality percentage for outgoing RTP packets.
"current_hour_ingress" Current hour network quality percentage for incoming RTP packets.
"current_hour_egress" Current hour network quality percentage for outgoing RTP packets.
"last_hour_ingress" Last hour network quality percentage for incoming RTP packets.
"last_hour_egress" Last hour network quality percentage for outgoing RTP packets.
}

 If the nap status is part of a substructure, the substructure will be a hash containing all subfield elements.

Example to access the signaling type and the number of incoming call count for the NAP of the current call:

incoming_nap = params[:naps][ params[:call][ :nap ].to_sym]
log_trace 4,"Incoming NAP parameters=" + incoming_nap.inspect
log_trace 4,"Incoming NAP signaling type=" + incoming_nap[:signaling_type].inspect
log_trace 4,"Incoming NAP call cnt=" + incoming_nap[:asr_stats_incoming_struct][:total_call_cnt].inspect

 It is also possible to add dynamic nap attributes in the web portal. These can be referenced by their name.

== Telephony Services ==
In release 2.10 and the above, telephony services (CNAM Request) can be manage from the routing engine in the following format:

params[:telephony_services].each do |service| -> Array of telephony services
service[:name] -> Customer telephony service name
service[:type] -> For now only "CNAM Request"
service[:enabled] -> Indicate if the service is enabled (true) or not (false)
(Only the telephony service define in the profile associated to the NAP is enabled)
(The others telephony services define in others profiles are disabled)
(If we are in the case where we return in the routing script with a response, it is important to set :enabled to false in order to avoid repeating the same query)
serviceParams = service[:params]
serviceParams[:return_to_script] -> Indicates to Gateway if we must return to the routing script after receiving the CNAM response
(It is important to set back to false this field to avoid an infinite loop)
serviceQuery = service[:query]
serviceQuery[:phone] -> 10 digits of calling number from the incoming call to send to the CNAM server
serviceQuery[:timeout] -> Timeout in millisecond to wait a CNAM response from CNAM server
(Default value from profile configuration)
serviceResponse = service[:response]
serviceResponse[:success] -> Indicates if we received a good CNAM response from the CNAM Server (Only present if :return_to_script is set to true)
serviceResponse[:caller_name] -> The caller name received in the CNAM response from the CNAM Server (Only present if :return_to_script is set to true)

== Custom user context ==
The routing script may '''save per-call information within the call context''', that will be available if routing is called again later during the call flow.

Cases where routing is called multiple time for the same call are:
- Call transfer requests
- SIP redirect requests
- Radius Authorization result
- Announcement server with digit collection

The routing script can save a recursive hash of attributes here:
params[:user_context]

For example
params[:user_context] = { "SomeKey" => "Some value I want to retrieve upon next routing for this call", "OtherVal" => { "subkey" => "subval" } }

Upon first call to routing script, params[:user_context] will be nil.
Upon subsequent calls to routing script, it will contain whatever the script had stored upon previous call (or nil if it was not set)

Note: This feature is available starting from release 2.9.85, 2.10.31 and 3.0.15 (in respective branches 2.9, 2.10 or 3.0)

== Routing Script Tests ==
The Web portal features a tool for Testing Scripts. The user must enter parameters to simulate the incoming call and after pressing the Test button, will output selected routes and numbers. You do not need to activate the new routes, or the new scripts to use this test tool: It can be used to test the routing scripts and routing table before activating it.
This is available in the Routing Scripts section of the Web portal.

=== Test parameters ===
==== @call_params ====

That variable should contain a hash of call parameters that will be passed to the routing script. This is equivalent to the incoming call parameters.

 

==== @nap_list ====

A list of the hash containing the nap statuses. This is equivalent to the nap statuses at the time the call is to be routed.

'''The nap list is hashed by the nap names in UPPERCASE.''' It is important to consider this when creating new dynamic route or nap attributes that may nap names that will be used to fetch a status.

 

==== @params ====

A hash of hashes containing parameters. This hash contains bridge parameters and other kind of parameter groups may be added in the future.

@params = {
:bridge => {:announcement_tone, "announcement.wav"},
:contacts => {
:index=>"1",
:list=>[
{:called_number=>"6660", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"",
:raw_data=>"", :expiration=>"3600"},
{:called_number=>"6661", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6661@192.168.215.127",
:raw_data=>"<sip:6661@192.168.215.127>", :expiration=>"3600"}
],
:source_indexes=>"nil,0"
}
}

 

----

 Back to [[Routing script tutorial|Routing Script Tutorial]].

Tmedia Routing

2019-03-28T18:49:03Z

Abrassard: /* Filter Scripts examples: */

== Static routing table ==
<pre>Gateway -> Routes
</pre>
 
[[File:Gateway_Static_Routes.png|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: [[Toolpack: How to Use RegEx in Remapped Called and Calling Number Mask|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|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 [[Tmedia_Routing#Label_routing|Label Routing]] or contact [[Support:Contacting_TelcoBridges_technical_support|TelcoBridges Support]] 

=== Exporting / importing routes ===
You can import or export the static routing table using the web portal. Go to:
<pre>Gateway -> Routes -> Route table actions -> Export Static Routes </pre>
or
<pre>Gateway -> Routes -> Route table actions -> Import Static Routes </pre>
 This is the default configuration of the Media Gateway

== Standard Scripts ==
<pre>Gateway -> Routing scripts </pre>
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|How to Setup Standard Scripts]] 

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

== Filters ==
<pre>Gateway -> Routing scripts </pre>
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
# 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.

==== 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 init_my_custom_after_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[ :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

=== Filter Scripts examples: ===

*'''priority_and_weight_load_balancer.rb:''' After filter that will reorder routes by priority and weight (load sharing per weight for routes with the same priority)
*'''forward_sip_domain.rb:''' Route remap filter that will, per route, control forwarding of sip domain of various SIP headers (forward domains, else replace by local IP / proxy IP)
*'''sip_header_params.rb:''' After remap filter that will add specified parameters to specified SIP headers
*'''Black and White listing (black_white_listing.rb):''' With this script, any called or calling number prefix can be blacklisted or whitelisted. This script can be assigned globally, or per NAP. It reads a .csv file which has the called and calling number list. See [[Adding White or Black listing to Routing Script]]
*'''lawful_intercept.rb:''' Script that will identify some calls to perform lawful interception on (by calling/called number matching from a .csv file)

Learn how to add a Filter to normal scripts: [[How to Setup Filters|How to setup Filters]] 

== Label routing ==
<pre>Gateway -> Routing scripts
Gateway -> FileDb
Gateway -> Routesets </pre>
 

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: [[Routeset Routing|Label routing]] and [[Adding_Label_Routing_to_any_Routing_Script|Adding Label Routing to any Routing Script]] 

== Custom Routing Scripts ==
<pre>Gateway -> 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. 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:Mini Development Guide|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|Scriptable Routing Engine]] 

=== Playing prompts ===
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]].

=== Recording calls ===
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]].

== 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: 
<pre>Profiles -> default [Edit] -> Edit Reason Cause mapping </pre>
 

Route retry is enabled by default. Timers and conditions on route retry can be adjusted from the configuration: 
<pre>Gateway -> Configurations -> Advanced </pre>
NOTE: The route-retry feature is available for other types of routing as well.

 

For more details, see the [[Route retry|Route Retry]] page 

 

[[category:Tmedia_Features]]

== Related actions ==
'''Refer to the appropriate Toolpack release:'''

*[[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]]
*[[Toolpack:Call_Routes_Settings_A|Call Routes Settings v2.8]]
<div class="mw-collapsible mw-collapsed" data-collapsetext="other versions" data-expandtext="Click here for other versions" style="width: 400px;">
*[[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>

Tmedia Routing

2019-03-28T18:42:59Z

Abrassard: /* Filters */

== Static routing table ==
<pre>Gateway -> Routes
</pre>
 
[[File:Gateway_Static_Routes.png|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: [[Toolpack: How to Use RegEx in Remapped Called and Calling Number Mask|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|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 [[Tmedia_Routing#Label_routing|Label Routing]] or contact [[Support:Contacting_TelcoBridges_technical_support|TelcoBridges Support]] 

=== Exporting / importing routes ===
You can import or export the static routing table using the web portal. Go to:
<pre>Gateway -> Routes -> Route table actions -> Export Static Routes </pre>
or
<pre>Gateway -> Routes -> Route table actions -> Import Static Routes </pre>
 This is the default configuration of the Media Gateway

== Standard Scripts ==
<pre>Gateway -> Routing scripts </pre>
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|How to Setup Standard Scripts]] 

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

== Filters ==
<pre>Gateway -> Routing scripts </pre>
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
# 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.

==== 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 init_my_custom_after_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[ :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

=== Filter Scripts examples: ===

*'''Request-URI routing (ruri.rb):''' Will route the call on SIP RURI instead of the to: field
*'''Modify the Nature of Address (noa_npi_remap.rb):''' We can use this to change the NOA to national or international
*'''Remove Loop (FilterRemoveLoop.rb): '''Will prevent calls from being routed back to the sender
*'''Load sharing on NAP groups or on route groups (nap_group_weight_retry_with_overload.rb):''' This is a powerful script that allows for a regrouping of NAPs of the same kind, distributes loads among them, and prioritizes one group versus another.  Alternatively, you can do the same on routes. You need to add two columns to the NAPs (or the routes), one called "group" and one called "weight". Groups of lower value will have a higher priority (group=0 has more priority than group=10). The calls will be distributed according to the weight value. To have an equal number of calls on each destination, use the same weight value (weight=10). See [[Adding Load Sharing to Routing Script|Adding Load Sharing to Routing Script]] 
*'''Black and White listing (black_white_listing.rb):''' With this script, any called or calling number prefix can be blacklisted or whitelisted. This script can be assigned globally, or per NAP. It reads a .csv file which has the called and calling number list. See [[Adding White or Black listing to Routing Script]]
 

Learn how to add a Filter to normal scripts: [[How to Setup Filters|How to setup Filters]] 

== Label routing ==
<pre>Gateway -> Routing scripts
Gateway -> FileDb
Gateway -> Routesets </pre>
 

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: [[Routeset Routing|Label routing]] and [[Adding_Label_Routing_to_any_Routing_Script|Adding Label Routing to any Routing Script]] 

== Custom Routing Scripts ==
<pre>Gateway -> 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. 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:Mini Development Guide|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|Scriptable Routing Engine]] 

=== Playing prompts ===
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]].

=== Recording calls ===
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]].

== 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: 
<pre>Profiles -> default [Edit] -> Edit Reason Cause mapping </pre>
 

Route retry is enabled by default. Timers and conditions on route retry can be adjusted from the configuration: 
<pre>Gateway -> Configurations -> Advanced </pre>
NOTE: The route-retry feature is available for other types of routing as well.

 

For more details, see the [[Route retry|Route Retry]] page 

 

[[category:Tmedia_Features]]

== Related actions ==
'''Refer to the appropriate Toolpack release:'''

*[[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]]
*[[Toolpack:Call_Routes_Settings_A|Call Routes Settings v2.8]]
<div class="mw-collapsible mw-collapsed" data-collapsetext="other versions" data-expandtext="Click here for other versions" style="width: 400px;">
*[[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>

Tmedia Routing

2019-03-28T18:37:21Z

Abrassard: /* Route remap (route_remap) */

== Static routing table ==
<pre>Gateway -> Routes
</pre>
 
[[File:Gateway_Static_Routes.png|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: [[Toolpack: How to Use RegEx in Remapped Called and Calling Number Mask|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|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 [[Tmedia_Routing#Label_routing|Label Routing]] or contact [[Support:Contacting_TelcoBridges_technical_support|TelcoBridges Support]] 

=== Exporting / importing routes ===
You can import or export the static routing table using the web portal. Go to:
<pre>Gateway -> Routes -> Route table actions -> Export Static Routes </pre>
or
<pre>Gateway -> Routes -> Route table actions -> Import Static Routes </pre>
 This is the default configuration of the Media Gateway

== Standard Scripts ==
<pre>Gateway -> Routing scripts </pre>
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|How to Setup Standard Scripts]] 

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

== Filters ==
<pre>Gateway -> Routing scripts </pre>
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
# 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.

==== 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 init_my_custom_after_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[ :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

=== Filter Scripts examples: ===

*'''Request-URI routing (ruri.rb):''' Will route the call on SIP RURI instead of the to: field
*'''Modify the Nature of Address (noa_npi_remap.rb):''' We can use this to change the NOA to national or international
*'''Remove Loop (FilterRemoveLoop.rb): '''Will prevent calls from being routed back to the sender
*'''Load sharing on NAP groups or on route groups (nap_group_weight_retry_with_overload.rb):''' This is a powerful script that allows for a regrouping of NAPs of the same kind, distributes loads among them, and prioritizes one group versus another.  Alternatively, you can do the same on routes. You need to add two columns to the NAPs (or the routes), one called "group" and one called "weight". Groups of lower value will have a higher priority (group=0 has more priority than group=10). The calls will be distributed according to the weight value. To have an equal number of calls on each destination, use the same weight value (weight=10). See [[Adding Load Sharing to Routing Script|Adding Load Sharing to Routing Script]] 
*'''Black and White listing (black_white_listing.rb):''' With this script, any called or calling number prefix can be blacklisted or whitelisted. This script can be assigned globally, or per NAP. It reads a .csv file which has the called and calling number list. See [[Adding White or Black listing to Routing Script]]
 

Learn how to add a Filter to normal scripts: [[How to Setup Filters|How to setup Filters]] 

== Label routing ==
<pre>Gateway -> Routing scripts
Gateway -> FileDb
Gateway -> Routesets </pre>
 

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: [[Routeset Routing|Label routing]] and [[Adding_Label_Routing_to_any_Routing_Script|Adding Label Routing to any Routing Script]] 

== Custom Routing Scripts ==
<pre>Gateway -> 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. 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:Mini Development Guide|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|Scriptable Routing Engine]] 

=== Playing prompts ===
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]].

=== Recording calls ===
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]].

== 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: 
<pre>Profiles -> default [Edit] -> Edit Reason Cause mapping </pre>
 

Route retry is enabled by default. Timers and conditions on route retry can be adjusted from the configuration: 
<pre>Gateway -> Configurations -> Advanced </pre>
NOTE: The route-retry feature is available for other types of routing as well.

 

For more details, see the [[Route retry|Route Retry]] page 

 

[[category:Tmedia_Features]]

== Related actions ==
'''Refer to the appropriate Toolpack release:'''

*[[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]]
*[[Toolpack:Call_Routes_Settings_A|Call Routes Settings v2.8]]
<div class="mw-collapsible mw-collapsed" data-collapsetext="other versions" data-expandtext="Click here for other versions" style="width: 400px;">
*[[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>

Tmedia Routing

2019-03-28T18:35:16Z

Abrassard: /* After remap (after_remap) */

== Static routing table ==
<pre>Gateway -> Routes
</pre>
 
[[File:Gateway_Static_Routes.png|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: [[Toolpack: How to Use RegEx in Remapped Called and Calling Number Mask|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|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 [[Tmedia_Routing#Label_routing|Label Routing]] or contact [[Support:Contacting_TelcoBridges_technical_support|TelcoBridges Support]] 

=== Exporting / importing routes ===
You can import or export the static routing table using the web portal. Go to:
<pre>Gateway -> Routes -> Route table actions -> Export Static Routes </pre>
or
<pre>Gateway -> Routes -> Route table actions -> Import Static Routes </pre>
 This is the default configuration of the Media Gateway

== Standard Scripts ==
<pre>Gateway -> Routing scripts </pre>
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|How to Setup Standard Scripts]] 

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

== Filters ==
<pre>Gateway -> Routing scripts </pre>
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
# 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.

==== 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 init_my_custom_after_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.

==== 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[ :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

=== Filter Scripts examples: ===

*'''Request-URI routing (ruri.rb):''' Will route the call on SIP RURI instead of the to: field
*'''Modify the Nature of Address (noa_npi_remap.rb):''' We can use this to change the NOA to national or international
*'''Remove Loop (FilterRemoveLoop.rb): '''Will prevent calls from being routed back to the sender
*'''Load sharing on NAP groups or on route groups (nap_group_weight_retry_with_overload.rb):''' This is a powerful script that allows for a regrouping of NAPs of the same kind, distributes loads among them, and prioritizes one group versus another.  Alternatively, you can do the same on routes. You need to add two columns to the NAPs (or the routes), one called "group" and one called "weight". Groups of lower value will have a higher priority (group=0 has more priority than group=10). The calls will be distributed according to the weight value. To have an equal number of calls on each destination, use the same weight value (weight=10). See [[Adding Load Sharing to Routing Script|Adding Load Sharing to Routing Script]] 
*'''Black and White listing (black_white_listing.rb):''' With this script, any called or calling number prefix can be blacklisted or whitelisted. This script can be assigned globally, or per NAP. It reads a .csv file which has the called and calling number list. See [[Adding White or Black listing to Routing Script]]
 

Learn how to add a Filter to normal scripts: [[How to Setup Filters|How to setup Filters]] 

== Label routing ==
<pre>Gateway -> Routing scripts
Gateway -> FileDb
Gateway -> Routesets </pre>
 

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: [[Routeset Routing|Label routing]] and [[Adding_Label_Routing_to_any_Routing_Script|Adding Label Routing to any Routing Script]] 

== Custom Routing Scripts ==
<pre>Gateway -> 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. 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:Mini Development Guide|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|Scriptable Routing Engine]] 

=== Playing prompts ===
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]].

=== Recording calls ===
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]].

== 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: 
<pre>Profiles -> default [Edit] -> Edit Reason Cause mapping </pre>
 

Route retry is enabled by default. Timers and conditions on route retry can be adjusted from the configuration: 
<pre>Gateway -> Configurations -> Advanced </pre>
NOTE: The route-retry feature is available for other types of routing as well.

 

For more details, see the [[Route retry|Route Retry]] page 

 

[[category:Tmedia_Features]]

== Related actions ==
'''Refer to the appropriate Toolpack release:'''

*[[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]]
*[[Toolpack:Call_Routes_Settings_A|Call Routes Settings v2.8]]
<div class="mw-collapsible mw-collapsed" data-collapsetext="other versions" data-expandtext="Click here for other versions" style="width: 400px;">
*[[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>

Tmedia Routing

2019-03-28T18:34:59Z

Abrassard: /* After filter (after_filter) */

== Static routing table ==
<pre>Gateway -> Routes
</pre>
 
[[File:Gateway_Static_Routes.png|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: [[Toolpack: How to Use RegEx in Remapped Called and Calling Number Mask|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|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 [[Tmedia_Routing#Label_routing|Label Routing]] or contact [[Support:Contacting_TelcoBridges_technical_support|TelcoBridges Support]] 

=== Exporting / importing routes ===
You can import or export the static routing table using the web portal. Go to:
<pre>Gateway -> Routes -> Route table actions -> Export Static Routes </pre>
or
<pre>Gateway -> Routes -> Route table actions -> Import Static Routes </pre>
 This is the default configuration of the Media Gateway

== Standard Scripts ==
<pre>Gateway -> Routing scripts </pre>
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|How to Setup Standard Scripts]] 

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

== Filters ==
<pre>Gateway -> Routing scripts </pre>
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
# 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.

==== 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 init_my_custom_after_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.

==== 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[ :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.
end

=== Filter Scripts examples: ===

*'''Request-URI routing (ruri.rb):''' Will route the call on SIP RURI instead of the to: field
*'''Modify the Nature of Address (noa_npi_remap.rb):''' We can use this to change the NOA to national or international
*'''Remove Loop (FilterRemoveLoop.rb): '''Will prevent calls from being routed back to the sender
*'''Load sharing on NAP groups or on route groups (nap_group_weight_retry_with_overload.rb):''' This is a powerful script that allows for a regrouping of NAPs of the same kind, distributes loads among them, and prioritizes one group versus another.  Alternatively, you can do the same on routes. You need to add two columns to the NAPs (or the routes), one called "group" and one called "weight". Groups of lower value will have a higher priority (group=0 has more priority than group=10). The calls will be distributed according to the weight value. To have an equal number of calls on each destination, use the same weight value (weight=10). See [[Adding Load Sharing to Routing Script|Adding Load Sharing to Routing Script]] 
*'''Black and White listing (black_white_listing.rb):''' With this script, any called or calling number prefix can be blacklisted or whitelisted. This script can be assigned globally, or per NAP. It reads a .csv file which has the called and calling number list. See [[Adding White or Black listing to Routing Script]]
 

Learn how to add a Filter to normal scripts: [[How to Setup Filters|How to setup Filters]] 

== Label routing ==
<pre>Gateway -> Routing scripts
Gateway -> FileDb
Gateway -> Routesets </pre>
 

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: [[Routeset Routing|Label routing]] and [[Adding_Label_Routing_to_any_Routing_Script|Adding Label Routing to any Routing Script]] 

== Custom Routing Scripts ==
<pre>Gateway -> 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. 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:Mini Development Guide|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|Scriptable Routing Engine]] 

=== Playing prompts ===
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]].

=== Recording calls ===
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]].

== 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: 
<pre>Profiles -> default [Edit] -> Edit Reason Cause mapping </pre>
 

Route retry is enabled by default. Timers and conditions on route retry can be adjusted from the configuration: 
<pre>Gateway -> Configurations -> Advanced </pre>
NOTE: The route-retry feature is available for other types of routing as well.

 

For more details, see the [[Route retry|Route Retry]] page 

 

[[category:Tmedia_Features]]

== Related actions ==
'''Refer to the appropriate Toolpack release:'''

*[[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]]
*[[Toolpack:Call_Routes_Settings_A|Call Routes Settings v2.8]]
<div class="mw-collapsible mw-collapsed" data-collapsetext="other versions" data-expandtext="Click here for other versions" style="width: 400px;">
*[[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>

Tmedia Routing

2019-03-28T18:34:44Z

Abrassard: /* Before filter (before_filter) */

== Static routing table ==
<pre>Gateway -> Routes
</pre>
 
[[File:Gateway_Static_Routes.png|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: [[Toolpack: How to Use RegEx in Remapped Called and Calling Number Mask|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|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 [[Tmedia_Routing#Label_routing|Label Routing]] or contact [[Support:Contacting_TelcoBridges_technical_support|TelcoBridges Support]] 

=== Exporting / importing routes ===
You can import or export the static routing table using the web portal. Go to:
<pre>Gateway -> Routes -> Route table actions -> Export Static Routes </pre>
or
<pre>Gateway -> Routes -> Route table actions -> Import Static Routes </pre>
 This is the default configuration of the Media Gateway

== Standard Scripts ==
<pre>Gateway -> Routing scripts </pre>
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|How to Setup Standard Scripts]] 

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

== Filters ==
<pre>Gateway -> Routing scripts </pre>
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
# 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.

==== 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 init_my_custom_after_filter above for details about params
end

==== Route remap (route_remap) ====
Called once per matching route. Perform per-route remapping of some call attributes, based on per-route attributes.

==== 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[ :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.
end

=== Filter Scripts examples: ===

*'''Request-URI routing (ruri.rb):''' Will route the call on SIP RURI instead of the to: field
*'''Modify the Nature of Address (noa_npi_remap.rb):''' We can use this to change the NOA to national or international
*'''Remove Loop (FilterRemoveLoop.rb): '''Will prevent calls from being routed back to the sender
*'''Load sharing on NAP groups or on route groups (nap_group_weight_retry_with_overload.rb):''' This is a powerful script that allows for a regrouping of NAPs of the same kind, distributes loads among them, and prioritizes one group versus another.  Alternatively, you can do the same on routes. You need to add two columns to the NAPs (or the routes), one called "group" and one called "weight". Groups of lower value will have a higher priority (group=0 has more priority than group=10). The calls will be distributed according to the weight value. To have an equal number of calls on each destination, use the same weight value (weight=10). See [[Adding Load Sharing to Routing Script|Adding Load Sharing to Routing Script]] 
*'''Black and White listing (black_white_listing.rb):''' With this script, any called or calling number prefix can be blacklisted or whitelisted. This script can be assigned globally, or per NAP. It reads a .csv file which has the called and calling number list. See [[Adding White or Black listing to Routing Script]]
 

Learn how to add a Filter to normal scripts: [[How to Setup Filters|How to setup Filters]] 

== Label routing ==
<pre>Gateway -> Routing scripts
Gateway -> FileDb
Gateway -> Routesets </pre>
 

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: [[Routeset Routing|Label routing]] and [[Adding_Label_Routing_to_any_Routing_Script|Adding Label Routing to any Routing Script]] 

== Custom Routing Scripts ==
<pre>Gateway -> 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. 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:Mini Development Guide|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|Scriptable Routing Engine]] 

=== Playing prompts ===
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]].

=== Recording calls ===
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]].

== 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: 
<pre>Profiles -> default [Edit] -> Edit Reason Cause mapping </pre>
 

Route retry is enabled by default. Timers and conditions on route retry can be adjusted from the configuration: 
<pre>Gateway -> Configurations -> Advanced </pre>
NOTE: The route-retry feature is available for other types of routing as well.

 

For more details, see the [[Route retry|Route Retry]] page 

 

[[category:Tmedia_Features]]

== Related actions ==
'''Refer to the appropriate Toolpack release:'''

*[[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]]
*[[Toolpack:Call_Routes_Settings_A|Call Routes Settings v2.8]]
<div class="mw-collapsible mw-collapsed" data-collapsetext="other versions" data-expandtext="Click here for other versions" style="width: 400px;">
*[[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>

Tmedia Routing

2019-03-28T18:32:05Z

Abrassard: /* After remap (after_remap) */

== Static routing table ==
<pre>Gateway -> Routes
</pre>
 
[[File:Gateway_Static_Routes.png|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: [[Toolpack: How to Use RegEx in Remapped Called and Calling Number Mask|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|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 [[Tmedia_Routing#Label_routing|Label Routing]] or contact [[Support:Contacting_TelcoBridges_technical_support|TelcoBridges Support]] 

=== Exporting / importing routes ===
You can import or export the static routing table using the web portal. Go to:
<pre>Gateway -> Routes -> Route table actions -> Export Static Routes </pre>
or
<pre>Gateway -> Routes -> Route table actions -> Import Static Routes </pre>
 This is the default configuration of the Media Gateway

== Standard Scripts ==
<pre>Gateway -> Routing scripts </pre>
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|How to Setup Standard Scripts]] 

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

== Filters ==
<pre>Gateway -> Routing scripts </pre>
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
# 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.

==== 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.
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 init_my_custom_after_filter above for details about params
end

==== Route remap (route_remap) ====
Called once per matching route. Perform per-route remapping of some call attributes, based on per-route attributes.

==== 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[ :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.
end

=== Filter Scripts examples: ===

*'''Request-URI routing (ruri.rb):''' Will route the call on SIP RURI instead of the to: field
*'''Modify the Nature of Address (noa_npi_remap.rb):''' We can use this to change the NOA to national or international
*'''Remove Loop (FilterRemoveLoop.rb): '''Will prevent calls from being routed back to the sender
*'''Load sharing on NAP groups or on route groups (nap_group_weight_retry_with_overload.rb):''' This is a powerful script that allows for a regrouping of NAPs of the same kind, distributes loads among them, and prioritizes one group versus another.  Alternatively, you can do the same on routes. You need to add two columns to the NAPs (or the routes), one called "group" and one called "weight". Groups of lower value will have a higher priority (group=0 has more priority than group=10). The calls will be distributed according to the weight value. To have an equal number of calls on each destination, use the same weight value (weight=10). See [[Adding Load Sharing to Routing Script|Adding Load Sharing to Routing Script]] 
*'''Black and White listing (black_white_listing.rb):''' With this script, any called or calling number prefix can be blacklisted or whitelisted. This script can be assigned globally, or per NAP. It reads a .csv file which has the called and calling number list. See [[Adding White or Black listing to Routing Script]]
 

Learn how to add a Filter to normal scripts: [[How to Setup Filters|How to setup Filters]] 

== Label routing ==
<pre>Gateway -> Routing scripts
Gateway -> FileDb
Gateway -> Routesets </pre>
 

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: [[Routeset Routing|Label routing]] and [[Adding_Label_Routing_to_any_Routing_Script|Adding Label Routing to any Routing Script]] 

== Custom Routing Scripts ==
<pre>Gateway -> 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. 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:Mini Development Guide|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|Scriptable Routing Engine]] 

=== Playing prompts ===
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]].

=== Recording calls ===
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]].

== 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: 
<pre>Profiles -> default [Edit] -> Edit Reason Cause mapping </pre>
 

Route retry is enabled by default. Timers and conditions on route retry can be adjusted from the configuration: 
<pre>Gateway -> Configurations -> Advanced </pre>
NOTE: The route-retry feature is available for other types of routing as well.

 

For more details, see the [[Route retry|Route Retry]] page 

 

[[category:Tmedia_Features]]

== Related actions ==
'''Refer to the appropriate Toolpack release:'''

*[[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]]
*[[Toolpack:Call_Routes_Settings_A|Call Routes Settings v2.8]]
<div class="mw-collapsible mw-collapsed" data-collapsetext="other versions" data-expandtext="Click here for other versions" style="width: 400px;">
*[[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>

Tmedia Routing

2019-03-28T18:31:09Z

Abrassard: /* Before filter (before_filter) */

== Static routing table ==
<pre>Gateway -> Routes
</pre>
 
[[File:Gateway_Static_Routes.png|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: [[Toolpack: How to Use RegEx in Remapped Called and Calling Number Mask|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|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 [[Tmedia_Routing#Label_routing|Label Routing]] or contact [[Support:Contacting_TelcoBridges_technical_support|TelcoBridges Support]] 

=== Exporting / importing routes ===
You can import or export the static routing table using the web portal. Go to:
<pre>Gateway -> Routes -> Route table actions -> Export Static Routes </pre>
or
<pre>Gateway -> Routes -> Route table actions -> Import Static Routes </pre>
 This is the default configuration of the Media Gateway

== Standard Scripts ==
<pre>Gateway -> Routing scripts </pre>
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|How to Setup Standard Scripts]] 

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

== Filters ==
<pre>Gateway -> Routing scripts </pre>
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
# 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.

==== 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.
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 init_my_custom_after_filter above for details about params
end

==== Route remap (route_remap) ====
Called once per matching route. Perform per-route remapping of some call attributes, based on per-route attributes.

==== 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.

=== Filter Scripts examples: ===

*'''Request-URI routing (ruri.rb):''' Will route the call on SIP RURI instead of the to: field
*'''Modify the Nature of Address (noa_npi_remap.rb):''' We can use this to change the NOA to national or international
*'''Remove Loop (FilterRemoveLoop.rb): '''Will prevent calls from being routed back to the sender
*'''Load sharing on NAP groups or on route groups (nap_group_weight_retry_with_overload.rb):''' This is a powerful script that allows for a regrouping of NAPs of the same kind, distributes loads among them, and prioritizes one group versus another.  Alternatively, you can do the same on routes. You need to add two columns to the NAPs (or the routes), one called "group" and one called "weight". Groups of lower value will have a higher priority (group=0 has more priority than group=10). The calls will be distributed according to the weight value. To have an equal number of calls on each destination, use the same weight value (weight=10). See [[Adding Load Sharing to Routing Script|Adding Load Sharing to Routing Script]] 
*'''Black and White listing (black_white_listing.rb):''' With this script, any called or calling number prefix can be blacklisted or whitelisted. This script can be assigned globally, or per NAP. It reads a .csv file which has the called and calling number list. See [[Adding White or Black listing to Routing Script]]
 

Learn how to add a Filter to normal scripts: [[How to Setup Filters|How to setup Filters]] 

== Label routing ==
<pre>Gateway -> Routing scripts
Gateway -> FileDb
Gateway -> Routesets </pre>
 

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: [[Routeset Routing|Label routing]] and [[Adding_Label_Routing_to_any_Routing_Script|Adding Label Routing to any Routing Script]] 

== Custom Routing Scripts ==
<pre>Gateway -> 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. 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:Mini Development Guide|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|Scriptable Routing Engine]] 

=== Playing prompts ===
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]].

=== Recording calls ===
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]].

== 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: 
<pre>Profiles -> default [Edit] -> Edit Reason Cause mapping </pre>
 

Route retry is enabled by default. Timers and conditions on route retry can be adjusted from the configuration: 
<pre>Gateway -> Configurations -> Advanced </pre>
NOTE: The route-retry feature is available for other types of routing as well.

 

For more details, see the [[Route retry|Route Retry]] page 

 

[[category:Tmedia_Features]]

== Related actions ==
'''Refer to the appropriate Toolpack release:'''

*[[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]]
*[[Toolpack:Call_Routes_Settings_A|Call Routes Settings v2.8]]
<div class="mw-collapsible mw-collapsed" data-collapsetext="other versions" data-expandtext="Click here for other versions" style="width: 400px;">
*[[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>

Tmedia Routing

2019-03-28T18:28:24Z

Abrassard: /* After filter (after_filter) */

== Static routing table ==
<pre>Gateway -> Routes
</pre>
 
[[File:Gateway_Static_Routes.png|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: [[Toolpack: How to Use RegEx in Remapped Called and Calling Number Mask|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|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 [[Tmedia_Routing#Label_routing|Label Routing]] or contact [[Support:Contacting_TelcoBridges_technical_support|TelcoBridges Support]] 

=== Exporting / importing routes ===
You can import or export the static routing table using the web portal. Go to:
<pre>Gateway -> Routes -> Route table actions -> Export Static Routes </pre>
or
<pre>Gateway -> Routes -> Route table actions -> Import Static Routes </pre>
 This is the default configuration of the Media Gateway

== Standard Scripts ==
<pre>Gateway -> Routing scripts </pre>
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|How to Setup Standard Scripts]] 

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

== Filters ==
<pre>Gateway -> Routing scripts </pre>
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
# 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.

==== 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] All attributes of the incoming call to route.
# Can be modified. Will affect subsequent filters, and routing output.
# - params[ :routes ] All routes in your configuration with all their attributes.
# Cannot be modified.
# - params[ :naps ] All NAPs in the configuration and their attributes
# Cannot be modified.
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 init_my_custom_after_filter above for details about params
end

==== Route remap (route_remap) ====
Called once per matching route. Perform per-route remapping of some call attributes, based on per-route attributes.

==== 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.

=== Filter Scripts examples: ===

*'''Request-URI routing (ruri.rb):''' Will route the call on SIP RURI instead of the to: field
*'''Modify the Nature of Address (noa_npi_remap.rb):''' We can use this to change the NOA to national or international
*'''Remove Loop (FilterRemoveLoop.rb): '''Will prevent calls from being routed back to the sender
*'''Load sharing on NAP groups or on route groups (nap_group_weight_retry_with_overload.rb):''' This is a powerful script that allows for a regrouping of NAPs of the same kind, distributes loads among them, and prioritizes one group versus another.  Alternatively, you can do the same on routes. You need to add two columns to the NAPs (or the routes), one called "group" and one called "weight". Groups of lower value will have a higher priority (group=0 has more priority than group=10). The calls will be distributed according to the weight value. To have an equal number of calls on each destination, use the same weight value (weight=10). See [[Adding Load Sharing to Routing Script|Adding Load Sharing to Routing Script]] 
*'''Black and White listing (black_white_listing.rb):''' With this script, any called or calling number prefix can be blacklisted or whitelisted. This script can be assigned globally, or per NAP. It reads a .csv file which has the called and calling number list. See [[Adding White or Black listing to Routing Script]]
 

Learn how to add a Filter to normal scripts: [[How to Setup Filters|How to setup Filters]] 

== Label routing ==
<pre>Gateway -> Routing scripts
Gateway -> FileDb
Gateway -> Routesets </pre>
 

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: [[Routeset Routing|Label routing]] and [[Adding_Label_Routing_to_any_Routing_Script|Adding Label Routing to any Routing Script]] 

== Custom Routing Scripts ==
<pre>Gateway -> 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. 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:Mini Development Guide|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|Scriptable Routing Engine]] 

=== Playing prompts ===
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]].

=== Recording calls ===
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]].

== 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: 
<pre>Profiles -> default [Edit] -> Edit Reason Cause mapping </pre>
 

Route retry is enabled by default. Timers and conditions on route retry can be adjusted from the configuration: 
<pre>Gateway -> Configurations -> Advanced </pre>
NOTE: The route-retry feature is available for other types of routing as well.

 

For more details, see the [[Route retry|Route Retry]] page 

 

[[category:Tmedia_Features]]

== Related actions ==
'''Refer to the appropriate Toolpack release:'''

*[[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]]
*[[Toolpack:Call_Routes_Settings_A|Call Routes Settings v2.8]]
<div class="mw-collapsible mw-collapsed" data-collapsetext="other versions" data-expandtext="Click here for other versions" style="width: 400px;">
*[[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>

Tmedia Routing

2019-03-28T18:18:27Z

Abrassard: /* Order route (order_route) */

== Static routing table ==
<pre>Gateway -> Routes
</pre>
 
[[File:Gateway_Static_Routes.png|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: [[Toolpack: How to Use RegEx in Remapped Called and Calling Number Mask|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|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 [[Tmedia_Routing#Label_routing|Label Routing]] or contact [[Support:Contacting_TelcoBridges_technical_support|TelcoBridges Support]] 

=== Exporting / importing routes ===
You can import or export the static routing table using the web portal. Go to:
<pre>Gateway -> Routes -> Route table actions -> Export Static Routes </pre>
or
<pre>Gateway -> Routes -> Route table actions -> Import Static Routes </pre>
 This is the default configuration of the Media Gateway

== Standard Scripts ==
<pre>Gateway -> Routing scripts </pre>
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|How to Setup Standard Scripts]] 

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

== Filters ==
<pre>Gateway -> Routing scripts </pre>
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
# 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.

==== 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] All attributes of the incoming call to route.
# Can be modified. Will affect subsequent filters, and routing output.
# - params[ :routes ] All routes in your configuration with all their attributes.
# Cannot be modified.
# - params[ :naps ] All NAPs in the configuration and their attributes
# Cannot be modified.
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) ====
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 (route_remap) ====
Called once per matching route. Perform per-route remapping of some call attributes, based on per-route attributes.

==== 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.

=== Filter Scripts examples: ===

*'''Request-URI routing (ruri.rb):''' Will route the call on SIP RURI instead of the to: field
*'''Modify the Nature of Address (noa_npi_remap.rb):''' We can use this to change the NOA to national or international
*'''Remove Loop (FilterRemoveLoop.rb): '''Will prevent calls from being routed back to the sender
*'''Load sharing on NAP groups or on route groups (nap_group_weight_retry_with_overload.rb):''' This is a powerful script that allows for a regrouping of NAPs of the same kind, distributes loads among them, and prioritizes one group versus another.  Alternatively, you can do the same on routes. You need to add two columns to the NAPs (or the routes), one called "group" and one called "weight". Groups of lower value will have a higher priority (group=0 has more priority than group=10). The calls will be distributed according to the weight value. To have an equal number of calls on each destination, use the same weight value (weight=10). See [[Adding Load Sharing to Routing Script|Adding Load Sharing to Routing Script]] 
*'''Black and White listing (black_white_listing.rb):''' With this script, any called or calling number prefix can be blacklisted or whitelisted. This script can be assigned globally, or per NAP. It reads a .csv file which has the called and calling number list. See [[Adding White or Black listing to Routing Script]]
 

Learn how to add a Filter to normal scripts: [[How to Setup Filters|How to setup Filters]] 

== Label routing ==
<pre>Gateway -> Routing scripts
Gateway -> FileDb
Gateway -> Routesets </pre>
 

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: [[Routeset Routing|Label routing]] and [[Adding_Label_Routing_to_any_Routing_Script|Adding Label Routing to any Routing Script]] 

== Custom Routing Scripts ==
<pre>Gateway -> 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. 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:Mini Development Guide|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|Scriptable Routing Engine]] 

=== Playing prompts ===
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]].

=== Recording calls ===
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]].

== 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: 
<pre>Profiles -> default [Edit] -> Edit Reason Cause mapping </pre>
 

Route retry is enabled by default. Timers and conditions on route retry can be adjusted from the configuration: 
<pre>Gateway -> Configurations -> Advanced </pre>
NOTE: The route-retry feature is available for other types of routing as well.

 

For more details, see the [[Route retry|Route Retry]] page 

 

[[category:Tmedia_Features]]

== Related actions ==
'''Refer to the appropriate Toolpack release:'''

*[[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]]
*[[Toolpack:Call_Routes_Settings_A|Call Routes Settings v2.8]]
<div class="mw-collapsible mw-collapsed" data-collapsetext="other versions" data-expandtext="Click here for other versions" style="width: 400px;">
*[[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>

Tmedia Routing

2019-03-28T18:15:44Z

Abrassard: /* Types of filters */

== Static routing table ==
<pre>Gateway -> Routes
</pre>
 
[[File:Gateway_Static_Routes.png|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: [[Toolpack: How to Use RegEx in Remapped Called and Calling Number Mask|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|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 [[Tmedia_Routing#Label_routing|Label Routing]] or contact [[Support:Contacting_TelcoBridges_technical_support|TelcoBridges Support]] 

=== Exporting / importing routes ===
You can import or export the static routing table using the web portal. Go to:
<pre>Gateway -> Routes -> Route table actions -> Export Static Routes </pre>
or
<pre>Gateway -> Routes -> Route table actions -> Import Static Routes </pre>
 This is the default configuration of the Media Gateway

== Standard Scripts ==
<pre>Gateway -> Routing scripts </pre>
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|How to Setup Standard Scripts]] 

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

== Filters ==
<pre>Gateway -> Routing scripts </pre>
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
# 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.

==== 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] All attributes of the incoming call to route.
# Can be modified. Will affect subsequent filters, and routing output.
# - params[ :routes ] All routes in your configuration with all their attributes.
# Cannot be modified.
# - params[ :naps ] All NAPs in the configuration and their attributes
# Cannot be modified.
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.

==== After filter (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 (route_remap) ====
Called once per matching route. Perform per-route remapping of some call attributes, based on per-route attributes.

==== 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.

=== Filter Scripts examples: ===

*'''Request-URI routing (ruri.rb):''' Will route the call on SIP RURI instead of the to: field
*'''Modify the Nature of Address (noa_npi_remap.rb):''' We can use this to change the NOA to national or international
*'''Remove Loop (FilterRemoveLoop.rb): '''Will prevent calls from being routed back to the sender
*'''Load sharing on NAP groups or on route groups (nap_group_weight_retry_with_overload.rb):''' This is a powerful script that allows for a regrouping of NAPs of the same kind, distributes loads among them, and prioritizes one group versus another.  Alternatively, you can do the same on routes. You need to add two columns to the NAPs (or the routes), one called "group" and one called "weight". Groups of lower value will have a higher priority (group=0 has more priority than group=10). The calls will be distributed according to the weight value. To have an equal number of calls on each destination, use the same weight value (weight=10). See [[Adding Load Sharing to Routing Script|Adding Load Sharing to Routing Script]] 
*'''Black and White listing (black_white_listing.rb):''' With this script, any called or calling number prefix can be blacklisted or whitelisted. This script can be assigned globally, or per NAP. It reads a .csv file which has the called and calling number list. See [[Adding White or Black listing to Routing Script]]
 

Learn how to add a Filter to normal scripts: [[How to Setup Filters|How to setup Filters]] 

== Label routing ==
<pre>Gateway -> Routing scripts
Gateway -> FileDb
Gateway -> Routesets </pre>
 

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: [[Routeset Routing|Label routing]] and [[Adding_Label_Routing_to_any_Routing_Script|Adding Label Routing to any Routing Script]] 

== Custom Routing Scripts ==
<pre>Gateway -> 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. 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:Mini Development Guide|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|Scriptable Routing Engine]] 

=== Playing prompts ===
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]].

=== Recording calls ===
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]].

== 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: 
<pre>Profiles -> default [Edit] -> Edit Reason Cause mapping </pre>
 

Route retry is enabled by default. Timers and conditions on route retry can be adjusted from the configuration: 
<pre>Gateway -> Configurations -> Advanced </pre>
NOTE: The route-retry feature is available for other types of routing as well.

 

For more details, see the [[Route retry|Route Retry]] page 

 

[[category:Tmedia_Features]]

== Related actions ==
'''Refer to the appropriate Toolpack release:'''

*[[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]]
*[[Toolpack:Call_Routes_Settings_A|Call Routes Settings v2.8]]
<div class="mw-collapsible mw-collapsed" data-collapsetext="other versions" data-expandtext="Click here for other versions" style="width: 400px;">
*[[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>

Tmedia Routing

2019-03-28T18:05:35Z

Abrassard: /* Types of filters */

== Static routing table ==
<pre>Gateway -> Routes
</pre>
 
[[File:Gateway_Static_Routes.png|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: [[Toolpack: How to Use RegEx in Remapped Called and Calling Number Mask|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|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 [[Tmedia_Routing#Label_routing|Label Routing]] or contact [[Support:Contacting_TelcoBridges_technical_support|TelcoBridges Support]] 

=== Exporting / importing routes ===
You can import or export the static routing table using the web portal. Go to:
<pre>Gateway -> Routes -> Route table actions -> Export Static Routes </pre>
or
<pre>Gateway -> Routes -> Route table actions -> Import Static Routes </pre>
 This is the default configuration of the Media Gateway

== Standard Scripts ==
<pre>Gateway -> Routing scripts </pre>
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|How to Setup Standard Scripts]] 

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

== Filters ==
<pre>Gateway -> Routing scripts </pre>
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
# 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.

==== 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_method, :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_method( params )
# params contains:
# - The parameters you passed when attached this filter in your main script
# - params[ :routes ] 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 ] 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 init_my_custom_method( params )
# params contains:
# - The parameters you passed when attached this filter in your main script
# - params[ :call] All attributes of the incoming call to route.
# Can be modified. Will affect subsequent filters, and routing output.
# - params[ :routes ] All routes in your configuration with all their attributes.
# Cannot be modified.
# - params[ :naps ] All NAPs in the configuration and their attributes
# Cannot be modified.
end

==== Route match (route_match) ====
Eliminates routes based on some matching criteria.

==== Order route (order_route) ====
Change the order of matching routes.

==== After filter (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 (route_remap) ====
Called once per matching route. Perform per-route remapping of some call attributes, based on per-route attributes.

==== 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.

=== Filter Scripts examples: ===

*'''Request-URI routing (ruri.rb):''' Will route the call on SIP RURI instead of the to: field
*'''Modify the Nature of Address (noa_npi_remap.rb):''' We can use this to change the NOA to national or international
*'''Remove Loop (FilterRemoveLoop.rb): '''Will prevent calls from being routed back to the sender
*'''Load sharing on NAP groups or on route groups (nap_group_weight_retry_with_overload.rb):''' This is a powerful script that allows for a regrouping of NAPs of the same kind, distributes loads among them, and prioritizes one group versus another.  Alternatively, you can do the same on routes. You need to add two columns to the NAPs (or the routes), one called "group" and one called "weight". Groups of lower value will have a higher priority (group=0 has more priority than group=10). The calls will be distributed according to the weight value. To have an equal number of calls on each destination, use the same weight value (weight=10). See [[Adding Load Sharing to Routing Script|Adding Load Sharing to Routing Script]] 
*'''Black and White listing (black_white_listing.rb):''' With this script, any called or calling number prefix can be blacklisted or whitelisted. This script can be assigned globally, or per NAP. It reads a .csv file which has the called and calling number list. See [[Adding White or Black listing to Routing Script]]
 

Learn how to add a Filter to normal scripts: [[How to Setup Filters|How to setup Filters]] 

== Label routing ==
<pre>Gateway -> Routing scripts
Gateway -> FileDb
Gateway -> Routesets </pre>
 

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: [[Routeset Routing|Label routing]] and [[Adding_Label_Routing_to_any_Routing_Script|Adding Label Routing to any Routing Script]] 

== Custom Routing Scripts ==
<pre>Gateway -> 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. 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:Mini Development Guide|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|Scriptable Routing Engine]] 

=== Playing prompts ===
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]].

=== Recording calls ===
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]].

== 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: 
<pre>Profiles -> default [Edit] -> Edit Reason Cause mapping </pre>
 

Route retry is enabled by default. Timers and conditions on route retry can be adjusted from the configuration: 
<pre>Gateway -> Configurations -> Advanced </pre>
NOTE: The route-retry feature is available for other types of routing as well.

 

For more details, see the [[Route retry|Route Retry]] page 

 

[[category:Tmedia_Features]]

== Related actions ==
'''Refer to the appropriate Toolpack release:'''

*[[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]]
*[[Toolpack:Call_Routes_Settings_A|Call Routes Settings v2.8]]
<div class="mw-collapsible mw-collapsed" data-collapsetext="other versions" data-expandtext="Click here for other versions" style="width: 400px;">
*[[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>

Tmedia Routing

2019-03-28T18:04:03Z

Abrassard: Added summary of types of filters

== Static routing table ==
<pre>Gateway -> Routes
</pre>
 
[[File:Gateway_Static_Routes.png|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: [[Toolpack: How to Use RegEx in Remapped Called and Calling Number Mask|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|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 [[Tmedia_Routing#Label_routing|Label Routing]] or contact [[Support:Contacting_TelcoBridges_technical_support|TelcoBridges Support]] 

=== Exporting / importing routes ===
You can import or export the static routing table using the web portal. Go to:
<pre>Gateway -> Routes -> Route table actions -> Export Static Routes </pre>
or
<pre>Gateway -> Routes -> Route table actions -> Import Static Routes </pre>
 This is the default configuration of the Media Gateway

== Standard Scripts ==
<pre>Gateway -> Routing scripts </pre>
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|How to Setup Standard Scripts]] 

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

== Filters ==
<pre>Gateway -> Routing scripts </pre>
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
# 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.

==== 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_method, :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_method( params )
# params contains:
# - The parameters you passed when attached this filter in your main script
# - params[ :routes ] 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 ] 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 init_my_custom_method( params )
# params contains:
# - The parameters you passed when attached this filter in your main script
# - params[ :call] All attributes of the incoming call to route.
# Can be modified. Will affect subsequent filters, and routing output.
# - params[ :routes ] All routes in your configuration with all their attributes.
# Cannot be modified.
# - params[ :naps ] All NAPs in the configuration and their attributes
# Cannot be modified.
end

==== After filter (after_filter) ====
*'''After filter: '''Adds post-processing on outgoing parameters

=== Filter Scripts examples: ===

*'''Request-URI routing (ruri.rb):''' Will route the call on SIP RURI instead of the to: field
*'''Modify the Nature of Address (noa_npi_remap.rb):''' We can use this to change the NOA to national or international
*'''Remove Loop (FilterRemoveLoop.rb): '''Will prevent calls from being routed back to the sender
*'''Load sharing on NAP groups or on route groups (nap_group_weight_retry_with_overload.rb):''' This is a powerful script that allows for a regrouping of NAPs of the same kind, distributes loads among them, and prioritizes one group versus another.  Alternatively, you can do the same on routes. You need to add two columns to the NAPs (or the routes), one called "group" and one called "weight". Groups of lower value will have a higher priority (group=0 has more priority than group=10). The calls will be distributed according to the weight value. To have an equal number of calls on each destination, use the same weight value (weight=10). See [[Adding Load Sharing to Routing Script|Adding Load Sharing to Routing Script]] 
*'''Black and White listing (black_white_listing.rb):''' With this script, any called or calling number prefix can be blacklisted or whitelisted. This script can be assigned globally, or per NAP. It reads a .csv file which has the called and calling number list. See [[Adding White or Black listing to Routing Script]]
 

Learn how to add a Filter to normal scripts: [[How to Setup Filters|How to setup Filters]] 

== Label routing ==
<pre>Gateway -> Routing scripts
Gateway -> FileDb
Gateway -> Routesets </pre>
 

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: [[Routeset Routing|Label routing]] and [[Adding_Label_Routing_to_any_Routing_Script|Adding Label Routing to any Routing Script]] 

== Custom Routing Scripts ==
<pre>Gateway -> 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. 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:Mini Development Guide|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|Scriptable Routing Engine]] 

=== Playing prompts ===
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]].

=== Recording calls ===
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]].

== 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: 
<pre>Profiles -> default [Edit] -> Edit Reason Cause mapping </pre>
 

Route retry is enabled by default. Timers and conditions on route retry can be adjusted from the configuration: 
<pre>Gateway -> Configurations -> Advanced </pre>
NOTE: The route-retry feature is available for other types of routing as well.

 

For more details, see the [[Route retry|Route Retry]] page 

 

[[category:Tmedia_Features]]

== Related actions ==
'''Refer to the appropriate Toolpack release:'''

*[[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]]
*[[Toolpack:Call_Routes_Settings_A|Call Routes Settings v2.8]]
<div class="mw-collapsible mw-collapsed" data-collapsetext="other versions" data-expandtext="Click here for other versions" style="width: 400px;">
*[[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>

Tmedia Routing

2019-03-28T17:58:58Z

Abrassard: Started to improve documentation about routing scripts

== Static routing table ==
<pre>Gateway -> Routes
</pre>
 
[[File:Gateway_Static_Routes.png|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: [[Toolpack: How to Use RegEx in Remapped Called and Calling Number Mask|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|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 [[Tmedia_Routing#Label_routing|Label Routing]] or contact [[Support:Contacting_TelcoBridges_technical_support|TelcoBridges Support]] 

=== Exporting / importing routes ===
You can import or export the static routing table using the web portal. Go to:
<pre>Gateway -> Routes -> Route table actions -> Export Static Routes </pre>
or
<pre>Gateway -> Routes -> Route table actions -> Import Static Routes </pre>
 This is the default configuration of the Media Gateway

== Standard Scripts ==
<pre>Gateway -> Routing scripts </pre>
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|How to Setup Standard Scripts]] 

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

== Filters ==
<pre>Gateway -> Routing scripts </pre>
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 ===

==== 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_method, :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_method( params )
# params contains:
# - The parameters you passed when attached this filter in your main script
# - params[ :routes ] 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 ] 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 init_my_custom_method( params )
# params contains:
# - The parameters you passed when attached this filter in your main script
# - params[ :call] All attributes of the incoming call to route.
# Can be modified. Will affect subsequent filters, and routing output.
# - params[ :routes ] All routes in your configuration with all their attributes.
# Cannot be modified.
# - params[ :naps ] All NAPs in the configuration and their attributes
# Cannot be modified.
end

*'''After filter: '''Adds post-processing on outgoing parameters

=== Filter Scripts examples: ===

*'''Request-URI routing (ruri.rb):''' Will route the call on SIP RURI instead of the to: field
*'''Modify the Nature of Address (noa_npi_remap.rb):''' We can use this to change the NOA to national or international
*'''Remove Loop (FilterRemoveLoop.rb): '''Will prevent calls from being routed back to the sender
*'''Load sharing on NAP groups or on route groups (nap_group_weight_retry_with_overload.rb):''' This is a powerful script that allows for a regrouping of NAPs of the same kind, distributes loads among them, and prioritizes one group versus another.  Alternatively, you can do the same on routes. You need to add two columns to the NAPs (or the routes), one called "group" and one called "weight". Groups of lower value will have a higher priority (group=0 has more priority than group=10). The calls will be distributed according to the weight value. To have an equal number of calls on each destination, use the same weight value (weight=10). See [[Adding Load Sharing to Routing Script|Adding Load Sharing to Routing Script]] 
*'''Black and White listing (black_white_listing.rb):''' With this script, any called or calling number prefix can be blacklisted or whitelisted. This script can be assigned globally, or per NAP. It reads a .csv file which has the called and calling number list. See [[Adding White or Black listing to Routing Script]]
 

Learn how to add a Filter to normal scripts: [[How to Setup Filters|How to setup Filters]] 

== Label routing ==
<pre>Gateway -> Routing scripts
Gateway -> FileDb
Gateway -> Routesets </pre>
 

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: [[Routeset Routing|Label routing]] and [[Adding_Label_Routing_to_any_Routing_Script|Adding Label Routing to any Routing Script]] 

== Custom Routing Scripts ==
<pre>Gateway -> 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. 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:Mini Development Guide|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|Scriptable Routing Engine]] 

=== Playing prompts ===
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]].

=== Recording calls ===
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]].

== 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: 
<pre>Profiles -> default [Edit] -> Edit Reason Cause mapping </pre>
 

Route retry is enabled by default. Timers and conditions on route retry can be adjusted from the configuration: 
<pre>Gateway -> Configurations -> Advanced </pre>
NOTE: The route-retry feature is available for other types of routing as well.

 

For more details, see the [[Route retry|Route Retry]] page 

 

[[category:Tmedia_Features]]

== Related actions ==
'''Refer to the appropriate Toolpack release:'''

*[[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]]
*[[Toolpack:Call_Routes_Settings_A|Call Routes Settings v2.8]]
<div class="mw-collapsible mw-collapsed" data-collapsetext="other versions" data-expandtext="Click here for other versions" style="width: 400px;">
*[[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>

Toolpack:Certificates

2019-03-14T15:05:12Z

Abrassard:

This page provides useful shell commands and instructions to create and manipulate certificates with FreeSBC.

== Installing a custom private key and local certificate on FreeSBC ==

[[Create_A_SIP_Certificate_A#Upload_local_certificates_.28optional.29|See documentation here]]

== Use FreeSBC (or Linux) shell to manipulate certificates ==
You can use FreeSBC's shell (or most Linux hosts' shell as long as OpenSSL is installed) to create and view private keys, certificates and CSRs (certificate signing requests).

=== Create new private key ===
openssl genrsa -des3 -out MY_PRIVATE_KEY.pem 2048

You will be prompted to enter a passphrase:
Generating RSA private key, 2048 bit long modulus
.....................+++
..............................+++
e is 65537 (0x10001)
Enter pass phrase for MY_PRIVATE_KEY.pem:
Verifying - Enter pass phrase for MY_PRIVATE_KEY.pem:

Resulting file:
-rw-r--r-- 1 root root 1704 Mar 14 09:15 MY_PRIVATE_KEY.key

=== Create a self-signed certificate from a private key ===
openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout MY_PRIVATE_KEY.key -out MY_CERTIFICATE.crt

You will be prompted for some questions for certificate contents:
Generating a 2048 bit RSA private key
.........................................................+++
........................................................................................................................................................................................+++
writing new private key to 'MY_PRIVATE_KEY.key'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [XX]:CA
State or Province Name (full name) []:Quebec
Locality Name (eg, city) [Default City]:Boucherville
Organization Name (eg, company) [Default Company Ltd]:TelcoBridges
Organizational Unit Name (eg, section) []:
Common Name (eg, your name or your server's hostname) []:MyFreeSBC
Email Address []:support@telcobridges.com

Resulting files:
-rw-r--r-- 1 root root 1415 Mar 14 09:15 MY_CERTIFICATE.crt
-rw-r--r-- 1 root root 1751 Mar 14 09:14 MY_PRIVATE_KEY.pem

=== Create a CSR (certificate signing request) from a private key ===
openssl req -key MY_PRIVATE_KEY.key -new -out MY_CSR.csr
You will be prompted for some questions for certificate contents:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [XX]:CA
State or Province Name (full name) []:Quebec
Locality Name (eg, city) [Default City]:Boucherville
Organization Name (eg, company) [Default Company Ltd]:TelcoBridges
Organizational Unit Name (eg, section) []:
Common Name (eg, your name or your server's hostname) []:MyFreeSBC
Email Address []:support@telcobridges.com

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:my_password
An optional company name []:TelcoBridges

Resulting files:
-rw-r--r-- 1 root root 1127 Mar 14 09:20 MY_CSR.csr

=== View a certificate contents ===
openssl x509 -noout -text -in MY_CERTIFICATE.crt

Resulting output:
Certificate:
Data:
Version: 3 (0x2)
Serial Number:
f3:fc:c5:72:ea:a9:50:a6
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=CA, ST=Quebec, L=Boucherville, O=TelcoBridges, CN=MyFreeSBC/emailAddress=support@telcobridges.com
Validity
Not Before: Mar 14 13:15:53 2019 GMT
Not After : Mar 13 13:15:53 2020 GMT
Subject: C=CA, ST=Quebec, L=Boucherville, O=TelcoBridges, CN=MyFreeSBC/emailAddress=support@telcobridges.com
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
Public-Key: (2048 bit)
Modulus:
00:dc:38:85:9f:75:ce:cf:7c:3b:60:20:11:d1:47:
00:39:6e:10:5c:3b:72:6e:26:09:70:7a:df:14:b3:
f4:60:fb:0d:73:69:a9:4c:4f:a0:34:12:83:1a:9b:
ce:f0:61:59:bd:f1:fb:a3:cb:84:be:a5:3b:86:e5:
e0:66:82:53:fd:69:c3:f1:cf:85:73:2d:30:a9:a5:
82:4e:e2:0f:20:de:88:9d:7a:42:d3:19:7b:09:08:
68:75:c4:36:46:23:f2:c6:05:49:e6:79:06:ce:f8:
9f:66:11:ad:e3:41:6c:f5:cb:df:3a:a4:77:a3:b3:
9b:55:f4:fc:5a:5a:c1:ae:c5:5d:0b:de:b1:1a:bc:
3d:02:b9:0c:5d:d8:57:33:66:b2:a8:c0:c2:74:16:
20:32:63:0f:8b:8f:aa:f4:aa:bc:8a:12:1b:54:e1:
87:c7:10:79:ea:1d:f3:e2:4b:b3:b5:70:d5:ec:27:
24:d3:f2:37:20:7e:f7:2c:69:21:63:50:4a:fe:a2:
98:4f:bc:c8:4b:3c:74:68:95:8e:0a:0b:42:39:d3:
cb:88:1d:55:c1:e1:61:f3:b0:64:42:6f:ec:c5:6f:
8f:f8:1c:a8:d9:5b:fc:d7:54:91:3b:0a:c4:1a:82:
d1:96:11:ca:16:b8:44:f0:48:3a:1e:e4:78:d0:14:
f5:1d
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Subject Key Identifier:
9C:DA:43:3C:BC:E6:B1:8B:E7:B4:1C:AB:39:14:66:72:F5:C2:D6:25
X509v3 Authority Key Identifier:
keyid:9C:DA:43:3C:BC:E6:B1:8B:E7:B4:1C:AB:39:14:66:72:F5:C2:D6:25

X509v3 Basic Constraints:
CA:TRUE
Signature Algorithm: sha256WithRSAEncryption
4c:96:41:e8:ff:d8:79:e0:db:22:ec:a2:10:1b:c0:88:f3:83:
60:b1:2d:91:06:15:a4:96:4a:9a:fb:3c:39:a4:48:04:a9:55:
1b:b5:c2:c8:08:e0:70:d7:03:c5:e1:1d:f7:0c:3d:38:49:aa:
9b:85:1f:d2:6b:61:f5:10:9a:c7:0a:ff:34:a4:e9:d5:0b:cd:
2a:90:84:07:ac:74:7f:d9:e1:dd:33:dd:ae:8c:5a:61:ec:20:
d3:6e:7c:e5:be:46:94:b4:bc:da:54:80:12:28:5b:12:80:a1:
ad:86:6a:f9:dc:1f:f8:a5:cb:ab:2a:30:5d:f8:19:9f:e8:82:
9b:32:b7:cc:d5:f9:7d:3b:35:51:8b:a5:39:e3:71:84:37:09:
20:e0:d9:6c:6f:37:76:49:3a:01:ea:ce:8b:71:74:fe:29:2c:
84:3d:3b:9e:6c:50:64:53:36:90:6e:49:ce:40:fd:80:c7:25:
31:d5:49:42:0f:c7:37:9a:9e:99:6b:37:3e:9a:71:a7:a2:87:
19:1d:a3:44:48:b8:c3:65:c1:55:b2:0c:57:e8:0f:a6:f2:a5:
b4:d3:50:04:fe:fd:86:2c:c2:0a:c2:20:aa:81:26:48:34:3a:
3d:a6:2e:1b:eb:d7:b9:f1:a2:ad:7a:42:37:81:63:02:ac:3b:
e6:01:6b:10

=== View a certificate signing request (CSR) ===
openssl req -text -noout -verify -in MY_CSR.csr

Resulting output:
verify OK
Certificate Request:
Data:
Version: 0 (0x0)
Subject: C=CA, ST=Quebec, L=Boucherville, O=TelcoBridges, CN=MyFreeSBC/emailAddress=support@telcobridges.com
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
Public-Key: (2048 bit)
Modulus:
00:dc:38:85:9f:75:ce:cf:7c:3b:60:20:11:d1:47:
00:39:6e:10:5c:3b:72:6e:26:09:70:7a:df:14:b3:
f4:60:fb:0d:73:69:a9:4c:4f:a0:34:12:83:1a:9b:
ce:f0:61:59:bd:f1:fb:a3:cb:84:be:a5:3b:86:e5:
e0:66:82:53:fd:69:c3:f1:cf:85:73:2d:30:a9:a5:
82:4e:e2:0f:20:de:88:9d:7a:42:d3:19:7b:09:08:
68:75:c4:36:46:23:f2:c6:05:49:e6:79:06:ce:f8:
9f:66:11:ad:e3:41:6c:f5:cb:df:3a:a4:77:a3:b3:
9b:55:f4:fc:5a:5a:c1:ae:c5:5d:0b:de:b1:1a:bc:
3d:02:b9:0c:5d:d8:57:33:66:b2:a8:c0:c2:74:16:
20:32:63:0f:8b:8f:aa:f4:aa:bc:8a:12:1b:54:e1:
87:c7:10:79:ea:1d:f3:e2:4b:b3:b5:70:d5:ec:27:
24:d3:f2:37:20:7e:f7:2c:69:21:63:50:4a:fe:a2:
98:4f:bc:c8:4b:3c:74:68:95:8e:0a:0b:42:39:d3:
cb:88:1d:55:c1:e1:61:f3:b0:64:42:6f:ec:c5:6f:
8f:f8:1c:a8:d9:5b:fc:d7:54:91:3b:0a:c4:1a:82:
d1:96:11:ca:16:b8:44:f0:48:3a:1e:e4:78:d0:14:
f5:1d
Exponent: 65537 (0x10001)
Attributes:
challengePassword :my_password
unstructuredName :TelcoBridges
Signature Algorithm: sha256WithRSAEncryption
85:98:17:25:45:42:f6:44:f0:51:ca:42:32:92:e6:0e:a6:9d:
59:73:1c:82:c6:9b:c1:b7:17:00:77:f3:42:52:86:d6:08:a8:
30:99:02:41:c6:c2:22:b2:98:b9:f7:83:b9:b0:ab:5b:59:95:
9c:32:3b:9b:15:1c:4c:90:d1:bb:cf:fb:85:c4:5d:df:df:9e:
18:1b:f8:5b:b5:68:60:0f:d8:c6:5d:29:0c:54:b3:63:88:0c:
05:59:34:ad:c0:11:5b:e9:fb:e8:8c:c1:b5:5f:83:60:78:05:
b7:7e:66:d7:1a:59:5a:2e:b3:9c:c2:38:68:29:bf:44:51:da:
c9:2b:c3:f1:47:3c:d4:ce:4a:b2:8f:7d:6a:72:46:13:a8:97:
18:7e:bf:b0:33:14:ee:61:ed:94:c6:c0:19:92:14:2d:a0:8c:
b1:a2:c1:61:40:62:90:7c:64:09:52:ec:b6:fd:cb:fe:56:3f:
6e:de:e3:38:93:ee:e4:26:33:59:6c:3f:4f:36:87:de:96:4d:
c4:bd:ce:35:b2:79:16:38:f5:84:c8:ce:4a:27:11:6b:4b:0d:
9b:9f:dd:63:87:ca:23:12:8c:64:3b:c7:f0:46:e8:bd:e0:e7:
35:9d:b9:fb:aa:60:e2:48:8f:9b:6b:fb:69:2f:a5:7c:94:5a:
70:4d:a6:d1

=== Check that a certificate and a CSR match the private key ===
openssl x509 -noout -modulus -in MY_CERTIFICATE.crt | openssl md5
openssl rsa -noout -modulus -in MY_PRIVATE_KEY.key | openssl md5
openssl req -noout -modulus -in MY_CSR.csr | openssl md5

All 3 commands should display the same MD5 hash:
(stdin)= 41c46eddc15580673fe4adb8f5255634

Toolpack:Certificates

2019-03-14T15:04:07Z

Abrassard: Created page with "This page provides useful shell commands and instructions to create and manipulate certificates with FreeSBC. == Installing a custom private key and local certificate on Free..."

This page provides useful shell commands and instructions to create and manipulate certificates with FreeSBC.

== Installing a custom private key and local certificate on FreeSBC ==

[[Toolpack:Tsbc_TLS_Profiles#Upload_local_certificates_.28optional.29|See documentation here]]

== Use FreeSBC (or Linux) shell to manipulate certificates ==
You can use FreeSBC's shell (or most Linux hosts' shell as long as OpenSSL is installed) to create and view private keys, certificates and CSRs (certificate signing requests).

=== Create new private key ===
openssl genrsa -des3 -out MY_PRIVATE_KEY.pem 2048

You will be prompted to enter a passphrase:
Generating RSA private key, 2048 bit long modulus
.....................+++
..............................+++
e is 65537 (0x10001)
Enter pass phrase for MY_PRIVATE_KEY.pem:
Verifying - Enter pass phrase for MY_PRIVATE_KEY.pem:

Resulting file:
-rw-r--r-- 1 root root 1704 Mar 14 09:15 MY_PRIVATE_KEY.key

=== Create a self-signed certificate from a private key ===
openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout MY_PRIVATE_KEY.key -out MY_CERTIFICATE.crt

You will be prompted for some questions for certificate contents:
Generating a 2048 bit RSA private key
.........................................................+++
........................................................................................................................................................................................+++
writing new private key to 'MY_PRIVATE_KEY.key'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [XX]:CA
State or Province Name (full name) []:Quebec
Locality Name (eg, city) [Default City]:Boucherville
Organization Name (eg, company) [Default Company Ltd]:TelcoBridges
Organizational Unit Name (eg, section) []:
Common Name (eg, your name or your server's hostname) []:MyFreeSBC
Email Address []:support@telcobridges.com

Resulting files:
-rw-r--r-- 1 root root 1415 Mar 14 09:15 MY_CERTIFICATE.crt
-rw-r--r-- 1 root root 1751 Mar 14 09:14 MY_PRIVATE_KEY.pem

=== Create a CSR (certificate signing request) from a private key ===
openssl req -key MY_PRIVATE_KEY.key -new -out MY_CSR.csr
You will be prompted for some questions for certificate contents:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [XX]:CA
State or Province Name (full name) []:Quebec
Locality Name (eg, city) [Default City]:Boucherville
Organization Name (eg, company) [Default Company Ltd]:TelcoBridges
Organizational Unit Name (eg, section) []:
Common Name (eg, your name or your server's hostname) []:MyFreeSBC
Email Address []:support@telcobridges.com

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:my_password
An optional company name []:TelcoBridges

Resulting files:
-rw-r--r-- 1 root root 1127 Mar 14 09:20 MY_CSR.csr

=== View a certificate contents ===
openssl x509 -noout -text -in MY_CERTIFICATE.crt

Resulting output:
Certificate:
Data:
Version: 3 (0x2)
Serial Number:
f3:fc:c5:72:ea:a9:50:a6
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=CA, ST=Quebec, L=Boucherville, O=TelcoBridges, CN=MyFreeSBC/emailAddress=support@telcobridges.com
Validity
Not Before: Mar 14 13:15:53 2019 GMT
Not After : Mar 13 13:15:53 2020 GMT
Subject: C=CA, ST=Quebec, L=Boucherville, O=TelcoBridges, CN=MyFreeSBC/emailAddress=support@telcobridges.com
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
Public-Key: (2048 bit)
Modulus:
00:dc:38:85:9f:75:ce:cf:7c:3b:60:20:11:d1:47:
00:39:6e:10:5c:3b:72:6e:26:09:70:7a:df:14:b3:
f4:60:fb:0d:73:69:a9:4c:4f:a0:34:12:83:1a:9b:
ce:f0:61:59:bd:f1:fb:a3:cb:84:be:a5:3b:86:e5:
e0:66:82:53:fd:69:c3:f1:cf:85:73:2d:30:a9:a5:
82:4e:e2:0f:20:de:88:9d:7a:42:d3:19:7b:09:08:
68:75:c4:36:46:23:f2:c6:05:49:e6:79:06:ce:f8:
9f:66:11:ad:e3:41:6c:f5:cb:df:3a:a4:77:a3:b3:
9b:55:f4:fc:5a:5a:c1:ae:c5:5d:0b:de:b1:1a:bc:
3d:02:b9:0c:5d:d8:57:33:66:b2:a8:c0:c2:74:16:
20:32:63:0f:8b:8f:aa:f4:aa:bc:8a:12:1b:54:e1:
87:c7:10:79:ea:1d:f3:e2:4b:b3:b5:70:d5:ec:27:
24:d3:f2:37:20:7e:f7:2c:69:21:63:50:4a:fe:a2:
98:4f:bc:c8:4b:3c:74:68:95:8e:0a:0b:42:39:d3:
cb:88:1d:55:c1:e1:61:f3:b0:64:42:6f:ec:c5:6f:
8f:f8:1c:a8:d9:5b:fc:d7:54:91:3b:0a:c4:1a:82:
d1:96:11:ca:16:b8:44:f0:48:3a:1e:e4:78:d0:14:
f5:1d
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Subject Key Identifier:
9C:DA:43:3C:BC:E6:B1:8B:E7:B4:1C:AB:39:14:66:72:F5:C2:D6:25
X509v3 Authority Key Identifier:
keyid:9C:DA:43:3C:BC:E6:B1:8B:E7:B4:1C:AB:39:14:66:72:F5:C2:D6:25

X509v3 Basic Constraints:
CA:TRUE
Signature Algorithm: sha256WithRSAEncryption
4c:96:41:e8:ff:d8:79:e0:db:22:ec:a2:10:1b:c0:88:f3:83:
60:b1:2d:91:06:15:a4:96:4a:9a:fb:3c:39:a4:48:04:a9:55:
1b:b5:c2:c8:08:e0:70:d7:03:c5:e1:1d:f7:0c:3d:38:49:aa:
9b:85:1f:d2:6b:61:f5:10:9a:c7:0a:ff:34:a4:e9:d5:0b:cd:
2a:90:84:07:ac:74:7f:d9:e1:dd:33:dd:ae:8c:5a:61:ec:20:
d3:6e:7c:e5:be:46:94:b4:bc:da:54:80:12:28:5b:12:80:a1:
ad:86:6a:f9:dc:1f:f8:a5:cb:ab:2a:30:5d:f8:19:9f:e8:82:
9b:32:b7:cc:d5:f9:7d:3b:35:51:8b:a5:39:e3:71:84:37:09:
20:e0:d9:6c:6f:37:76:49:3a:01:ea:ce:8b:71:74:fe:29:2c:
84:3d:3b:9e:6c:50:64:53:36:90:6e:49:ce:40:fd:80:c7:25:
31:d5:49:42:0f:c7:37:9a:9e:99:6b:37:3e:9a:71:a7:a2:87:
19:1d:a3:44:48:b8:c3:65:c1:55:b2:0c:57:e8:0f:a6:f2:a5:
b4:d3:50:04:fe:fd:86:2c:c2:0a:c2:20:aa:81:26:48:34:3a:
3d:a6:2e:1b:eb:d7:b9:f1:a2:ad:7a:42:37:81:63:02:ac:3b:
e6:01:6b:10

=== View a certificate signing request (CSR) ===
openssl req -text -noout -verify -in MY_CSR.csr

Resulting output:
verify OK
Certificate Request:
Data:
Version: 0 (0x0)
Subject: C=CA, ST=Quebec, L=Boucherville, O=TelcoBridges, CN=MyFreeSBC/emailAddress=support@telcobridges.com
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
Public-Key: (2048 bit)
Modulus:
00:dc:38:85:9f:75:ce:cf:7c:3b:60:20:11:d1:47:
00:39:6e:10:5c:3b:72:6e:26:09:70:7a:df:14:b3:
f4:60:fb:0d:73:69:a9:4c:4f:a0:34:12:83:1a:9b:
ce:f0:61:59:bd:f1:fb:a3:cb:84:be:a5:3b:86:e5:
e0:66:82:53:fd:69:c3:f1:cf:85:73:2d:30:a9:a5:
82:4e:e2:0f:20:de:88:9d:7a:42:d3:19:7b:09:08:
68:75:c4:36:46:23:f2:c6:05:49:e6:79:06:ce:f8:
9f:66:11:ad:e3:41:6c:f5:cb:df:3a:a4:77:a3:b3:
9b:55:f4:fc:5a:5a:c1:ae:c5:5d:0b:de:b1:1a:bc:
3d:02:b9:0c:5d:d8:57:33:66:b2:a8:c0:c2:74:16:
20:32:63:0f:8b:8f:aa:f4:aa:bc:8a:12:1b:54:e1:
87:c7:10:79:ea:1d:f3:e2:4b:b3:b5:70:d5:ec:27:
24:d3:f2:37:20:7e:f7:2c:69:21:63:50:4a:fe:a2:
98:4f:bc:c8:4b:3c:74:68:95:8e:0a:0b:42:39:d3:
cb:88:1d:55:c1:e1:61:f3:b0:64:42:6f:ec:c5:6f:
8f:f8:1c:a8:d9:5b:fc:d7:54:91:3b:0a:c4:1a:82:
d1:96:11:ca:16:b8:44:f0:48:3a:1e:e4:78:d0:14:
f5:1d
Exponent: 65537 (0x10001)
Attributes:
challengePassword :my_password
unstructuredName :TelcoBridges
Signature Algorithm: sha256WithRSAEncryption
85:98:17:25:45:42:f6:44:f0:51:ca:42:32:92:e6:0e:a6:9d:
59:73:1c:82:c6:9b:c1:b7:17:00:77:f3:42:52:86:d6:08:a8:
30:99:02:41:c6:c2:22:b2:98:b9:f7:83:b9:b0:ab:5b:59:95:
9c:32:3b:9b:15:1c:4c:90:d1:bb:cf:fb:85:c4:5d:df:df:9e:
18:1b:f8:5b:b5:68:60:0f:d8:c6:5d:29:0c:54:b3:63:88:0c:
05:59:34:ad:c0:11:5b:e9:fb:e8:8c:c1:b5:5f:83:60:78:05:
b7:7e:66:d7:1a:59:5a:2e:b3:9c:c2:38:68:29:bf:44:51:da:
c9:2b:c3:f1:47:3c:d4:ce:4a:b2:8f:7d:6a:72:46:13:a8:97:
18:7e:bf:b0:33:14:ee:61:ed:94:c6:c0:19:92:14:2d:a0:8c:
b1:a2:c1:61:40:62:90:7c:64:09:52:ec:b6:fd:cb:fe:56:3f:
6e:de:e3:38:93:ee:e4:26:33:59:6c:3f:4f:36:87:de:96:4d:
c4:bd:ce:35:b2:79:16:38:f5:84:c8:ce:4a:27:11:6b:4b:0d:
9b:9f:dd:63:87:ca:23:12:8c:64:3b:c7:f0:46:e8:bd:e0:e7:
35:9d:b9:fb:aa:60:e2:48:8f:9b:6b:fb:69:2f:a5:7c:94:5a:
70:4d:a6:d1

=== Check that a certificate and a CSR match the private key ===
openssl x509 -noout -modulus -in MY_CERTIFICATE.crt | openssl md5
openssl rsa -noout -modulus -in MY_PRIVATE_KEY.key | openssl md5
openssl req -noout -modulus -in MY_CSR.csr | openssl md5

All 3 commands should display the same MD5 hash:
(stdin)= 41c46eddc15580673fe4adb8f5255634

Toolpack:Tsbc TLS Profiles

2019-03-11T18:41:33Z

Abrassard: Minor edits

Certificates are used to provide secure connections, like HTTPs (secure connection to the web portal) or [[FreeSBC]] secure SIP calls (SIP over TLS).

This pages describes how to import certificates and group them into TLS profiles, which is the first step to configure secure SIP on [[FreeSBC]].

These TLS profiles can later be used to create SIP Transport servers using TLS.

== Configuring Certificates and TLS Profiles ==
{{DISPLAYTITLE:Configuring Certificates and TLS Profiles}}

'''''Applies to version(s): v3.1 and above'''''

Multiple TLS profiles can be created in [[Toolpack]]. A TLS profile is a collection of certificates and other settings that define the behavior of TLS connections. Multiple TLS profiles can be used to expose different certificates and options to different TLS connections in [[Toolpack]], though one TLS profile is generally enough.

== Upload trusted certificates ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureCertificates_0.png|150px]]

=== Click ''' Create New Certificate ''' ===

[[Image:ConfigureCertificates_1.png|250px]]

=== Configure certificate parameters ===

* Give a name that is meaningful to you
* Select "Trusted" certificate to import a remote party's certificate to trust
* Drag-and-drop (or copy-paste) the certificate's text content into the appropriate text box
* Click "Create"

[[Image:ConfigureCertificates_2.png|500px]]

== Upload local certificates (optional) ==
Toolpack already contains, by default, a unique self-signed certificate (unique per Toolpack system, shared for 1+1 hosts). This certificate is used for HTTPs, and can also be used for TLS.

In case you want to use a custom local certificate (like an officially signed certificate for your domain name), proceed as follows:
* Repeat the same procedure as above (but using "Local" certificate type) to import the local certificate
* Use ssh (command-line or using tool like Filezilla) to upload the private key to the unit to following path. Use the '''same file''' name as the local certificate name previously used to import in the web portal (except file extension):
/lib/tb/toolpack/pkg/ssl_certificate/

Example:

[[Image:ConfigureCertificates_3.png|500px]]

Then:
scp my_local_cert.key root@MyFreeSbcHostName:/lib/tb/toolpack/pkg/ssl_certificate/

== Create TLS profile ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureTlsProfile_0.png|150px]]

=== Click ''' Create New TLS Profile''' ===

[[Image:ConfigureTlsProfile_1.png|300px]]

=== Configure TLS Profile parameters ===

* Give a name that is meaningful to you
* Decide if client authentication is required (meaning that incoming connections require remote side to present a trusted certificate)
* Select a local certificate (either one imported earlier, or the "Default" certificate which is automatically generated by Toolpack and is also used for HTTPS)
* Click "Create"
* Select one or multiple "trusted" certificates, which correspond to remote equipment's certificates (or root certificates from which remote certificates are signed)

[[Image:ConfigureTlsProfile_2.png|500px]]

[[Image:ConfigureTlsProfile_3.png|500px]]

Toolpack:Tsbc TLS Profiles

2019-03-11T18:26:52Z

Abrassard:

Certificates are used to provide secure connections, like HTTPs (secure connection to thw web portal) or secure SIP calls (SIP over TLS).
This pages describes how to import certificates and group them into TLS profiles.

These TLS profiles can later be used to create SIP Transport servers using TLS.

== Configuring Certificates and TLS Profiles ==
{{DISPLAYTITLE:Configuring Certificates and TLS Profiles}}

'''''Applies to version(s): v3.1 and above'''''

Multiple TLS profiles can be created in [[Toolpack]]. A TLS profile is a collection of certificates and other settings that define the behavior of TLS connections. Multiple TLS profiles can be used to expose different certificates and options to different TLS connections in [[Toolpack]], though one TLS profile is generally enough.

== Upload trusted certificates ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureCertificates_0.png|150px]]

=== Click ''' Create New Certificate ''' ===

[[Image:ConfigureCertificates_1.png|250px]]

=== Configure certificate parameters ===

* Give a name that is meaningful to you
* Select "Trusted" certificate to import a remote party's certificate to trust
* Drag-and-drop (or copy-paste) the certificate's text content into the appropriate text box
* Click "Create"

[[Image:ConfigureCertificates_2.png|500px]]

== Upload local certificates (optional) ==
Toolpack already contains, by default, a unique self-signed certificate (unique per Toolpack system, shared for 1+1 hosts). This certificate is used for HTTPs, and can also be used for TLS.

In case you want to use a custom local certificate (like an officially signed certificate for your domain name), proceed as follows:
* Repeat the same procedure as above (but using "Local" certificate type) to import the local certificate
* Use ssh (command-line or using tool like Filezilla) to upload the private key to the unit to following path. Use the '''same file''' name as the local certificate name previously used to import in the web portal (except file extension):
/lib/tb/toolpack/pkg/ssl_certificate/

Example:

[[Image:ConfigureCertificates_3.png|500px]]

Then:
scp my_local_cert.key root@MyFreeSbcHostName:/lib/tb/toolpack/pkg/ssl_certificate/

== Create TLS profile ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureTlsProfile_0.png|150px]]

=== Click ''' Create New TLS Profile''' ===

[[Image:ConfigureTlsProfile_1.png|300px]]

=== Configure TLS Profile parameters ===

* Give a name that is meaningful to you
* Decide if client authentication is required (meaning that incoming connections require remote side to present a trusted certificate)
* Select a local certificate (either one imported earlier, or the "Default" certificate which is automatically generated by Toolpack and is also used for HTTPS)
* Click "Create"
* Select one or multiple "trusted" certificates, which correspond to remote equipment's certificates (or root certificates from which remote certificates are signed)

[[Image:ConfigureTlsProfile_2.png|500px]]

[[Image:ConfigureTlsProfile_3.png|500px]]

Toolpack:Tsbc TLS Profiles

2019-03-11T18:23:20Z

Abrassard: /* Upload local certificates (optional) */

Certificates are used to provide secure connections, like HTTPs (secure connection to thw web portal) or secure SIP calls (SIP over TLS).
This pages describes how to import certificates and group them into TLS profiles.

These TLS profiles can later be used to create SIP Transport servers using TLS.

== Configuring Certificates and TLS Profiles ==
{{DISPLAYTITLE:Configuring Certificates and TLS Profiles}}

'''''Applies to version(s): v3.1 and above'''''

Multiple TLS profiles can be created in [[Toolpack]]. A TLS profile is a collection of certificates and other settings that define the behavior of TLS connections. Multiple TLS profiles can be used to expose different certificates and options to different TLS connections in [[Toolpack]], though one TLS profile is generally enough.

== Upload trusted certificates ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureCertificates_0.png|150px]]

=== Click ''' Create New Certificate ''' ===

[[Image:ConfigureCertificates_1.png|250px]]

=== Configure certificate parameters ===

* Give a name that is meaningful to you
* Select "Trusted" certificate to import a remote party's certificate to trust
* Drag-and-drop (or copy-paste) the certificate's text content into the appropriate text box
* Click "Create"

[[Image:ConfigureCertificates_2.png|500px]]

== Upload local certificates (optional) ==
Toolpack already contains a unique default certificate (unique per Toolpack system, shared for 1+1 hosts). This certificate is used for HTTPs, and can also be used for TLS.

In case you want to use a custom local certificate, proceed as follows:
* Repeat the same procedure as above (but using "Local" certificate type) to import the local certificate
* Use ssh (command-line or using tool like Filezilla) to upload the private key to the unit to following path. Use the '''same file''' name as the local certificate name previously used to import in the web portal (except file extension):
/lib/tb/toolpack/pkg/ssl_certificate/

Example:

[[Image:ConfigureCertificates_3.png|500px]]

Then:
scp my_local_cert.key root@MyFreeSbcHostName:/lib/tb/toolpack/pkg/ssl_certificate/

== Create TLS profile ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureTlsProfile_0.png|150px]]

=== Click ''' Create New TLS Profile''' ===

[[Image:ConfigureTlsProfile_1.png|300px]]

=== Configure TLS Profile parameters ===

* Give a name that is meaningful to you
* Decide if client authentication is required (meaning that incoming connections require remote side to present a trusted certificate)
* Select a local certificate (either one imported earlier, or the "Default" certificate which is automatically generated by Toolpack and is also used for HTTPS)
* Click "Create"
* Select one or multiple "trusted" certificates, which correspond to remote equipment's certificates (or root certificates from which remote certificates are signed)

[[Image:ConfigureTlsProfile_2.png|500px]]

[[Image:ConfigureTlsProfile_3.png|500px]]

Toolpack:Tsbc TLS Profiles

2019-03-11T17:52:53Z

Abrassard:

Certificates are used to provide secure connections, like HTTPs (secure connection to thw web portal) or secure SIP calls (SIP over TLS).
This pages describes how to import certificates and group them into TLS profiles.

These TLS profiles can later be used to create SIP Transport servers using TLS.

== Configuring Certificates and TLS Profiles ==
{{DISPLAYTITLE:Configuring Certificates and TLS Profiles}}

'''''Applies to version(s): v3.1 and above'''''

Multiple TLS profiles can be created in [[Toolpack]]. A TLS profile is a collection of certificates and other settings that define the behavior of TLS connections. Multiple TLS profiles can be used to expose different certificates and options to different TLS connections in [[Toolpack]], though one TLS profile is generally enough.

== Upload trusted certificates ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureCertificates_0.png|150px]]

=== Click ''' Create New Certificate ''' ===

[[Image:ConfigureCertificates_1.png|250px]]

=== Configure certificate parameters ===

* Give a name that is meaningful to you
* Select "Trusted" certificate to import a remote party's certificate to trust
* Drag-and-drop (or copy-paste) the certificate's text content into the appropriate text box
* Click "Create"

[[Image:ConfigureCertificates_2.png|500px]]

== Upload local certificates (optional) ==
Toolpack already contains a unique default certificate (unique per Toolpack system, shared for 1+1 hosts). This certificate is used for HTTPs, and can also be used for TLS.

In case you want to use a custom local certificate, proceed as follows:
* Repeat the same procedure as above (but using "Local" certificate type) to import the local certificate
* Use ssh (command-line or using tool like Filezilla) to upload the private key to the unit to following path. Use the '''same file''' name as the local certificate name previously used to import in the web portal (except file extension):
/lib/tb/toolpack/pkg/ssl_certificate/

Example:
[[Image:ConfigureCertificates_3.png|500px]]
Then:
scp my_local_cert.key root@MyFreeSbcHostName:/lib/tb/toolpack/pkg/ssl_certificate/

== Create TLS profile ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureTlsProfile_0.png|150px]]

=== Click ''' Create New TLS Profile''' ===

[[Image:ConfigureTlsProfile_1.png|300px]]

=== Configure TLS Profile parameters ===

* Give a name that is meaningful to you
* Decide if client authentication is required (meaning that incoming connections require remote side to present a trusted certificate)
* Select a local certificate (either one imported earlier, or the "Default" certificate which is automatically generated by Toolpack and is also used for HTTPS)
* Click "Create"
* Select one or multiple "trusted" certificates, which correspond to remote equipment's certificates (or root certificates from which remote certificates are signed)

[[Image:ConfigureTlsProfile_2.png|500px]]

[[Image:ConfigureTlsProfile_3.png|500px]]

Toolpack:Tsbc TLS Profiles

2019-03-11T17:51:38Z

Abrassard: Adjusted images width

== Configuring Certificates and TLS Profiles ==
{{DISPLAYTITLE:Configuring Certificates and TLS Profiles}}

'''''Applies to version(s): v3.1 and above'''''

Multiple TLS profiles can be created in [[Toolpack]]. A TLS profile is a collection of certificates and other settings that define the behavior of TLS connections. Multiple TLS profiles can be used to expose different certificates and options to different TLS connections in [[Toolpack]], though one TLS profile is generally enough.

== Upload trusted certificates ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureCertificates_0.png|150px]]

=== Click ''' Create New Certificate ''' ===

[[Image:ConfigureCertificates_1.png|250px]]

=== Configure certificate parameters ===

* Give a name that is meaningful to you
* Select "Trusted" certificate to import a remote party's certificate to trust
* Drag-and-drop (or copy-paste) the certificate's text content into the appropriate text box
* Click "Create"

[[Image:ConfigureCertificates_2.png|500px]]

== Upload local certificates (optional) ==
Toolpack already contains a unique default certificate (unique per Toolpack system, shared for 1+1 hosts). This certificate is used for HTTPs, and can also be used for TLS.

In case you want to use a custom local certificate, proceed as follows:
* Repeat the same procedure as above (but using "Local" certificate type) to import the local certificate
* Use ssh (command-line or using tool like Filezilla) to upload the private key to the unit to following path. Use the '''same file''' name as the local certificate name previously used to import in the web portal (except file extension):
/lib/tb/toolpack/pkg/ssl_certificate/

Example:
[[Image:ConfigureCertificates_3.png|500px]]
Then:
scp my_local_cert.key root@MyFreeSbcHostName:/lib/tb/toolpack/pkg/ssl_certificate/

== Create TLS profile ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureTlsProfile_0.png|150px]]

=== Click ''' Create New TLS Profile''' ===

[[Image:ConfigureTlsProfile_1.png|300px]]

=== Configure TLS Profile parameters ===

* Give a name that is meaningful to you
* Decide if client authentication is required (meaning that incoming connections require remote side to present a trusted certificate)
* Select a local certificate (either one imported earlier, or the "Default" certificate which is automatically generated by Toolpack and is also used for HTTPS)
* Click "Create"
* Select one or multiple "trusted" certificates, which correspond to remote equipment's certificates (or root certificates from which remote certificates are signed)

[[Image:ConfigureTlsProfile_2.png|500px]]

[[Image:ConfigureTlsProfile_3.png|500px]]

File:ConfigureTlsProfile 3.png

2019-03-11T17:47:33Z

Abrassard:

File:ConfigureTlsProfile 2.png

2019-03-11T17:47:25Z

Abrassard:

File:ConfigureCertificates 3.png

2019-03-11T17:43:26Z

Abrassard:

Toolpack:Tsbc TLS Profiles

2019-03-11T17:43:16Z

Abrassard:

== Configuring Certificates and TLS Profiles ==
{{DISPLAYTITLE:Configuring Certificates and TLS Profiles}}

'''''Applies to version(s): v3.1 and above'''''

Multiple TLS profiles can be created in [[Toolpack]]. A TLS profile is a collection of certificates and other settings that define the behavior of TLS connections. Multiple TLS profiles can be used to expose different certificates and options to different TLS connections in [[Toolpack]], though one TLS profile is generally enough.

== Upload trusted certificates ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureCertificates_0.png|150px]]

=== Click ''' Create New Certificate ''' ===

[[Image:ConfigureCertificates_1.png]]

=== Configure certificate parameters ===

* Give a name that is meaningful to you
* Select "Trusted" certificate to import a remote party's certificate to trust
* Drag-and-drop (or copy-paste) the certificate's text content into the appropriate text box
* Click "Create"

[[Image:ConfigureCertificates_2.png]]

== Upload local certificates (optional) ==
Toolpack already contains a unique default certificate (unique per Toolpack system, shared for 1+1 hosts). This certificate is used for HTTPs, and can also be used for TLS.

In case you want to use a custom local certificate, proceed as follows:
* Repeat the same procedure as above (but using "Local" certificate type) to import the local certificate
* Use ssh (command-line or using tool like Filezilla) to upload the private key to the unit to following path. Use the '''same file''' name as the local certificate name previously used to import in the web portal (except file extension):
/lib/tb/toolpack/pkg/ssl_certificate/

Example:
[[Image:ConfigureCertificates_3.png]]
Then:
scp my_local_cert.key root@MyFreeSbcHostName:/lib/tb/toolpack/pkg/ssl_certificate/

== Create TLS profile ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureTlsProfile_0.png]]

=== Click ''' Create New TLS Profile''' ===

[[Image:ConfigureTlsProfile_1.png]]

=== Configure TLS Profile parameters ===

* Give a name that is meaningful to you
* Decide if client authentication is required (meaning that incoming connections require remote side to present a trusted certificate)
* Select a local certificate (either one imported earlier, or the "Default" certificate which is automatically generated by Toolpack and is also used for HTTPS)
* Click "Create"
* Select one or multiple "trusted" certificates, which correspond to remote equipment's certificates (or root certificates from which remote certificates are signed)

[[Image:ConfigureTlsProfile_2.png]]

[[Image:ConfigureTlsProfile_3.png]]

File:ConfigureTlsProfile 1.png

2019-03-11T17:40:33Z

Abrassard:

File:ConfigureTlsProfile 0.png

2019-03-11T17:40:25Z

Abrassard:

Toolpack:Tsbc TLS Profiles

2019-03-11T17:40:17Z

Abrassard:

== Configuring Certificates and TLS Profiles ==
{{DISPLAYTITLE:Configuring Certificates and TLS Profiles}}

'''''Applies to version(s): v3.1 and above'''''

Multiple TLS profiles can be created in [[Toolpack]]. A TLS profile is a collection of certificates and other settings that define the behavior of TLS connections. Multiple TLS profiles can be used to expose different certificates and options to different TLS connections in [[Toolpack]], though one TLS profile is generally enough.

== Upload trusted certificates ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureCertificates_0.png|150px]]

=== Click ''' Create New Certificate ''' ===

[[Image:ConfigureCertificates_1.png]]

=== Configure certificate parameters ===

* Give a name that is meaningful to you
* Select "Trusted" certificate to import a remote party's certificate to trust
* Drag-and-drop (or copy-paste) the certificate's text content into the appropriate text box
* Click "Create"

[[Image:ConfigureCertificates_2.png]]

== Upload local certificates (optional) ==
Toolpack already contains a unique default certificate (unique per Toolpack system, shared for 1+1 hosts). This certificate is used for HTTPs, and can also be used for TLS.

In case you want to use a custom local certificate, proceed as follows:
* Repeat the same procedure as above (but using "Local" certificate type) to import the local certificate
* Use ssh (command-line or using tool like Filezilla) to upload the private key to the unit to following path. Use the '''same file''' name as the local certificate name previously used to import in the web portal (except file extension):
/lib/tb/toolpack/pkg/ssl_certificate/

Example:
scp my_local_cert.key root@MyFreeSbcHostName:/lib/tb/toolpack/pkg/ssl_certificate/

== Create TLS profile ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureTlsProfile_0.png]]

=== Click ''' Create New TLS Profile''' ===

[[Image:ConfigureTlsProfile_1.png]]

=== Configure TLS Profile parameters ===

* Give a name that is meaningful to you
* Decide if client authentication is required (meaning that incoming connections require remote side to present a trusted certificate)
* Select a local certificate (either one imported earlier, or the "Default" certificate which is automatically generated by Toolpack and is also used for HTTPS)
* Click "Create"
* Select one or multiple "trusted" certificates, which correspond to remote equipment's certificates (or root certificates from which remote certificates are signed)

[[Image:ConfigureTlsProfile_2.png]]

[[Image:ConfigureTlsProfile_3.png]]

File:ConfigureCertificates 2.png

2019-03-11T17:38:40Z

Abrassard:

File:ConfigureCertificates 1.png

2019-03-11T17:36:44Z

Abrassard:

Toolpack:Tsbc TLS Profiles

2019-03-11T17:36:38Z

Abrassard:

== Configuring Certificates and TLS Profiles ==
{{DISPLAYTITLE:Configuring Certificates and TLS Profiles}}

'''''Applies to version(s): v3.1 and above'''''

Multiple TLS profiles can be created in [[Toolpack]]. A TLS profile is a collection of certificates and other settings that define the behavior of TLS connections. Multiple TLS profiles can be used to expose different certificates and options to different TLS connections in [[Toolpack]], though one TLS profile is generally enough.

== Upload trusted certificates ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureCertificates_0.png|150px]]

=== Click ''' Create New Certificate ''' ===

[[Image:ConfigureCertificates_1.png]]

=== Configure certificate parameters ===

* Give a name that is meaningful to you
* Select "Trusted" certificate to import a remote party's certificate to trust
* Drag-and-drop (or copy-paste) the certificate's text content into the appropriate text box
* Click "Create"

[[Image:ConfigureCertificates_2.png]]

== Upload local certificates (optional) ==
Toolpack already contains a unique default certificate that is unique. This certificate is used for HTTPs, and can also be used for TLS.

[[Image:ConfigureCertificates_3.png]]

In case you want to use a custom local certificate, proceed as follows:
* Repeat the same procedure as above (but using "Local" certificate type) to import the local certificate
* Use ssh (command-line or using tool like Filezilla) to upload the private key to the unit to following path. Use the '''same file''' name as the local certificate name previously used to import in the web portal (except file extension):
/lib/tb/toolpack/pkg/ssl_certificate/

Example:
scp my_local_cert.key root@MyFreeSbcHostName:/lib/tb/toolpack/pkg/ssl_certificate/

== Create TLS profile ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureTlsProfile_0.png]]

=== Click ''' Create New TLS Profile''' ===

[[Image:ConfigureTlsProfile_1.png]]

=== Configure TLS Profile parameters ===

* Give a name that is meaningful to you
* Decide if client authentication is required (meaning that incoming connections require remote side to present a trusted certificate)
* Select a local certificate (either one imported earlier, or the "Default" certificate which is automatically generated by Toolpack and is also used for HTTPS)
* Click "Create"
* Select one or multiple "trusted" certificates, which correspond to remote equipment's certificates (or root certificates from which remote certificates are signed)

[[Image:ConfigureTlsProfile_2.png]]

[[Image:ConfigureTlsProfile_3.png]]

File:ConfigureCertificates 0.png

2019-03-11T17:32:14Z

Abrassard:

Toolpack:Tsbc TLS Profiles

2019-03-11T17:31:56Z

Abrassard:

== Configuring Certificates and TLS Profiles ==
{{DISPLAYTITLE:Configuring Certificates and TLS Profiles}}

'''''Applies to version(s): v3.1 and above'''''

Multiple TLS profiles can be created in [[Toolpack]]. A TLS profile is a collection of certificates and other settings that define the behavior of TLS connections. Multiple TLS profiles can be used to expose different certificates and options to different TLS connections in [[Toolpack]], though one TLS profile is generally enough.

== Upload trusted certificates ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureCertificates_0.png]]

=== Click ''' Create New Certificate ''' ===

[[Image:ConfigureCertificates_1.png]]

=== Configure certificate parameters ===

* Give a name that is meaningful to you
* Select "Trusted" certificate to import a remote party's certificate to trust
* Drag-and-drop (or copy-paste) the certificate's text content into the appropriate text box
* Click "Create"

[[Image:ConfigureCertificates_2.png]]

== Upload local certificates (optional) ==
Toolpack already contains a unique default certificate that is unique. This certificate is used for HTTPs, and can also be used for TLS.

[[Image:ConfigureCertificates_3.png]]

In case you want to use a custom local certificate, proceed as follows:
* Repeat the same procedure as above (but using "Local" certificate type) to import the local certificate
* Use ssh (command-line or using tool like Filezilla) to upload the private key to the unit to following path. Use the '''same file''' name as the local certificate name previously used to import in the web portal (except file extension):
/lib/tb/toolpack/pkg/ssl_certificate/

Example:
scp my_local_cert.key root@MyFreeSbcHostName:/lib/tb/toolpack/pkg/ssl_certificate/

== Create TLS profile ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureTlsProfile_0.png]]

=== Click ''' Create New TLS Profile''' ===

[[Image:ConfigureTlsProfile_1.png]]

=== Configure TLS Profile parameters ===

* Give a name that is meaningful to you
* Decide if client authentication is required (meaning that incoming connections require remote side to present a trusted certificate)
* Select a local certificate (either one imported earlier, or the "Default" certificate which is automatically generated by Toolpack and is also used for HTTPS)
* Click "Create"
* Select one or multiple "trusted" certificates, which correspond to remote equipment's certificates (or root certificates from which remote certificates are signed)

[[Image:ConfigureTlsProfile_2.png]]

[[Image:ConfigureTlsProfile_3.png]]

Toolpack:Tsbc TLS Profiles

2019-03-11T17:31:27Z

Abrassard: Draft

== Configuring Certificates and TLS Profiles ==
{{DISPLAYTITLE:Configuring Certificates and TLS Profiles}}

'''''Applies to version(s): v3.1 and above'''''

Multiple TLS profiles can be created in [[Toolpack]]. A TLS profile is a collection of certificates and other settings that define the behavior of TLS connections. Multiple TLS profiles can be used to expose different certificates and options to different TLS connections in [[Toolpack]], though one TLS profile is generally enough.

== Upload trusted certificates ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureCertificates_0.png]]

=== Click ''' Create New Certificate ''' ===

[[Image:ConfigureCertificates_1.png]]

=== Configure certificate parameters ===

* Give a name that is meaningful to you
* Select "Trusted" certificate to import a remote party's certificate to trust
* Drag-and-drop (or copy-paste) the certificate's text content into the appropriate text box
* Click "Create"

[[Image:ConfigureCertificates_2.png]]

== Upload local certificates (optional) ==
Toolpack already contains a unique default certificate that is unique. This certificate is used for HTTPs, and can also be used for TLS.

[[Image:ConfigureCertificates_3.png]]

In case you want to use a custom local certificate, proceed as follows:
* Repeat the same procedure as above (but using "Local" certificate type) to import the local certificate
* Use ssh (command-line or using tool like Filezilla) to upload the private key to the unit to following path. Use the '''same file''' name as the local certificate name previously used to import in the web portal (except file extension):
/lib/tb/toolpack/pkg/ssl_certificate/

Example:
scp my_local_cert.key root@MyFreeSbcHostName:/lib/tb/toolpack/pkg/ssl_certificate/

== Create TLS profile ==

=== Select '''Certificates''' from the navigation panel ===

[[Image:ConfigureTlsProfile_0.png]]

=== Click ''' Create New TLS Profile''' ===

[[Image:ConfigureTlsProfile_1.png]]

=== Configure TLS Profile parameters ===

* Give a name that is meaningful to you
* Decide if client authentication is required (meaning that incoming connections require remote side to present a trusted certificate)
* Select a local certificate (either one imported earlier, or the "Default" certificate which is automatically generated by Toolpack and is also used for HTTPS)
* Click "Create"
* Select one or multiple "trusted" certificates, which correspond to remote equipment's certificates (or root certificates from which remote certificates are signed)

Toolpack:Tsbc Protocol Stack Settings 3.0

2019-03-11T14:53:50Z

Abrassard: Added link to TLS profiles

{{DISPLAYTITLE:FreeSBC Web Portal 3.0: Protocol Stacks}}

'''Applies to FreeSBC and Tmedia products'''

==Security==
Prior to configuring SIP using TLS transport (secure SIP), certificates must be created, and a TLS profile must be created using these certificates.

Please refer to the following documentation before proceeding with steps lower on this page:
* [[Tsbc_TLS_Profiles|Configure certificates and TLS profiles]]

=Protocol Stacks=

==SIP==

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 1) Configure IP port range
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 2) Configure SIP Signaling
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 3) Modify NAP profile
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 4a) Configure Network Access Points (NAPs)
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 4b) Configure Network Access Points (NAPs)
|-
| valign="top" |
*[[Toolpack:Creating_an_IP_Port_Range_SBC A|Create an IP port range]]

| valign="top" |
*[[Toolpack:Creating_a_SIP_Stack_SBC A|Create a SIP stack]]
*[[Toolpack:Creating_a_SIP_Transport_Server_SBC A|Create a SIP transport server]]

| valign="top" |
*[[Toolpack:Modify_Profile_Sbc_A|Modify profile]]

| valign="top" |
*[[Toolpack:Allocating_a_SIP_Network_Access_Point_(NAP)_SBC A|Allocate a SIP NAP]]

| valign="top" |
*[[Toolpack:Allocating_a_SIP_Open_Network_Access_Point_(NAP)_SBC A|Allocate an open SIP NAP]]

|}

===SIP Register===

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 1)
 Configure SIP Domain
! 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;" | (Step 2)
Configure SIP Register Filtering Rule (Optional)
|-
| valign="top" |
*[[Toolpack:Creating_a_SIP_Domain_SBC A|Create a SIP domain]]
*[[Toolpack:Creating_a_SIP_Registrar_SBC A|Create a SIP registrar]]

| valign="top" |
*[[Toolpack:Creating_a_SIP_Register_Filtering_Rule_A|Create a filtering rule]]
*[[Toolpack:Creating_a_SIP_Register_Filtering_Rule_Condition_A|Add a filtering rule condition]]
*[[Toolpack:Creating_a_SIP_Register_Filtering_Rule_Action_A|Add a filtering rule action]]
|}

===SIP Advanced Features===
<div class="mw-collapsible mw-collapsed" data-collapsetext="SIP-I SIP-T" data-expandtext="SIP-I SIP-T" style="width: 400px;">
{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | SIP-I SIP-T
|-
| valign="top" |
*[[Enabling_SIP_I_SIP_T D|Enable SIP-I SIP-T]]
|}
</div>
<div class="mw-collapsible mw-collapsed" data-collapsetext="SIP Spiral" data-expandtext="SIP Spiral" style="width: 400px;">
{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | SIP Spiral
|-
| valign="top" |
*[[Enabling_SIP_Spiral D|Enable SIP Spiral]]
|}

</div>

<div class="mw-collapsible mw-collapsed" data-collapsetext="NAT traversal" data-expandtext="NAT traversal" style="width: 400px;">
{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | Remote NAT Traversal
|-
| valign="top" |
*[[Enabling_Remote_NAT_Traversal_C|Enable Remote NAT Traversal]]
|}
</div>

<div class="mw-collapsible mw-collapsed" data-collapsetext="DNS" data-expandtext="DNS" style="width: 400px;">
{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | DNS
|-
| valign="top" |
*[[Toolpack:Configuring_DNS_Parameters_C|Enable DNS]]
|}
</div>

===SIP Service Affecting Parameters===

<div class="mw-collapsible mw-collapsed" data-collapsetext="SIP Service Affecting Parameters" data-expandtext="SIP Service Affecting Parameters" style="width: 400px;">
When modifying the following parameters, the SIP stack will be deallocated and reallocated, resulting in a loss of active calls. Be careful when changing these parameters: 

'''Quirks'''
* All Parameters
'''Header Parameters'''
*Domain Name
*Add rPort
'''DNS Parameters'''
*Enabled
*Use Cache
*Cache Expire Time
*Address and Port
</div>

Sbc Tutorial Guide v3.1

2019-03-11T14:53:03Z

Abrassard: /* Web Portal Categories */

{{DISPLAYTITLE:FreeSBC 3.1 Web Portal Tutorial Guide}}

__NOTOC__
=Introduction=
The Web Portal Tutorial provides you with a scenario-based approach to configuring and monitoring the status of [[FreeSBC|FreeSbc]] systems, using the Web Portal configuration tool. Complete general installation configuration steps, before you begin configuring your specific application.

==Prerequisites==
[[FreeSBC|FreeSbc]] devices must be installed as described in their respective [[Product_Installation|installation guides]].

==Web Portal Categories==
Web Portal configuration and status topics are grouped into the following major categories. It is recommended that you follow this order.

*System [[Toolpack:Tsbc System Settings 3.1|(Configuration)]] [[Toolpack:Tsbc System Status 3.1|(Status)]]
**Host Role
**SBC
**Access and User Management
**Database Backup
**SNMP
**Configuration
**Minor Package Upgrade
**Software Licenses
**Statistics
**Audit Logs

*IP Network [[Toolpack:Tsbc IP Network Settings 3.1|(Configuration)]] [[Toolpack:Tsbc_IP_Network_Status_3.1|(Status)]]
**IP Network
**NAT
**Transcoding Units

*Protocol Stack [[Toolpack:Tsbc_Protocol_Stack_Settings_3.1|(Configuration)]] [[Toolpack:Tsbc_Protocol_Stack_Status_3.1|(Status)]]
**Certificates and TLS Profiles [[Toolpack:Tsbc_TLS_Profiles|(Configuration)]]
**SIP
**Calls
**NAP

*CDR [[Toolpack:Tsbc_CDR_Settings_3.1|(Configuration)]]
**Text CDR
**RADIUS [[Toolpack:Tsbc_CDR_Status_3.1|(Status)]]

*Fax [[Toolpack:Tsbc_Fax_Settings_3.1|(Configuration)]]
**FAX passthrough (silence suppression)
**FAX T.38
**FAX passthrough (NSE)
**FAX passthrough (VBD)

*Call Route [[Toolpack:Tsbc_Call Routes_Settings_3.1|(Configuration)]]
**Static Route
**Routing Script
**Label Routing
**RADIUS Authorization and Authentication [[Toolpack:Tsbc_CDR_Status_3.1|(Status)]]

*Lawful Intercept [[Toolpack:Tsbc Lawful Interception 3.1|(Configuration)]] [[(Status)]]

*Troubleshooting [[Toolpack:Tsbc Troubleshooting 3.1|(Configuration)]]
**CallTrace
**Test Call
**Target Recording
**Ethernet Capture

*Use Cases [[Toolpack:Tsbc Use_Cases A|(Configuration)]]
**IP Network
**Redirect
**Transcoding Unit

[[category:Toolpack]]

Sbc Tutorial Guide v3.1

2019-03-11T14:52:49Z

Abrassard: Added link to TLS profiles

{{DISPLAYTITLE:FreeSBC 3.1 Web Portal Tutorial Guide}}

__NOTOC__
=Introduction=
The Web Portal Tutorial provides you with a scenario-based approach to configuring and monitoring the status of [[FreeSBC|FreeSbc]] systems, using the Web Portal configuration tool. Complete general installation configuration steps, before you begin configuring your specific application.

==Prerequisites==
[[FreeSBC|FreeSbc]] devices must be installed as described in their respective [[Product_Installation|installation guides]].

==Web Portal Categories==
Web Portal configuration and status topics are grouped into the following major categories. It is recommended that you follow this order.

*System [[Toolpack:Tsbc System Settings 3.1|(Configuration)]] [[Toolpack:Tsbc System Status 3.1|(Status)]]
**Host Role
**SBC
**Access and User Management
**Database Backup
**SNMP
**Configuration
**Minor Package Upgrade
**Software Licenses
**Statistics
**Audit Logs

*IP Network [[Toolpack:Tsbc IP Network Settings 3.1|(Configuration)]] [[Toolpack:Tsbc_IP_Network_Status_3.1|(Status)]]
**IP Network
**NAT
**Transcoding Units

*Protocol Stack [[Toolpack:Tsbc_Protocol_Stack_Settings_3.1|(Configuration)]] [[Toolpack:Tsbc_Protocol_Stack_Status_3.1|(Status)]]
***Certificates and TLS Profiles [[Toolpack:Tsbc_TLS_Profiles|(Configuration)]]
**SIP
**Calls
**NAP

*CDR [[Toolpack:Tsbc_CDR_Settings_3.1|(Configuration)]]
**Text CDR
**RADIUS [[Toolpack:Tsbc_CDR_Status_3.1|(Status)]]

*Fax [[Toolpack:Tsbc_Fax_Settings_3.1|(Configuration)]]
**FAX passthrough (silence suppression)
**FAX T.38
**FAX passthrough (NSE)
**FAX passthrough (VBD)

*Call Route [[Toolpack:Tsbc_Call Routes_Settings_3.1|(Configuration)]]
**Static Route
**Routing Script
**Label Routing
**RADIUS Authorization and Authentication [[Toolpack:Tsbc_CDR_Status_3.1|(Status)]]

*Lawful Intercept [[Toolpack:Tsbc Lawful Interception 3.1|(Configuration)]] [[(Status)]]

*Troubleshooting [[Toolpack:Tsbc Troubleshooting 3.1|(Configuration)]]
**CallTrace
**Test Call
**Target Recording
**Ethernet Capture

*Use Cases [[Toolpack:Tsbc Use_Cases A|(Configuration)]]
**IP Network
**Redirect
**Transcoding Unit

[[category:Toolpack]]

SIP

2019-03-11T14:28:03Z

Abrassard: Added TLS RFCs

Session Initiation Protocol, more commonly known as SIP, is a signaling protocol for packet-based networks and is commonly used, along with H.323 to provide signaling for voice over IP (VoIP) communications.

== TelcoBridges and SIP ==

[[Toolpack]] provides support for signaling using the Session Initiation Protocol, more commonly known as SIP, for voice over IP (VoIP) communications. SIP may be used in conjunction with various [[Voice_codecs|voice codecs]] for the media component of a call. TelcoBridges [[Tmedia]] media gateways and [[Tdev]] development platforms support SIP signaling concurrently with [[SS7]], [[ISDN]] and other [[Signaling_protocols|signaling protocols]].

SIP signaling stacks are configured for IP applications and for each [[Tmedia]] or [[Tdev]] unit requiring SIP signaling.

Based upon your system requirements, you can configure a SIP stack to carry signaling traffic over multiple transport servers, which are IP endpoints comprised of: protocol type (UDP, TCP or TLS), port number and IP interface.

A conceptual illustration is provided below:

[[Image:SIP stack conceptual illustration.png|600px| ]] 

While TelcoBridges media gateways can perform multiple simultaneous functions such as switching and transcoding as well as deliver value-added services such as [[IVR]] or conferencing, they can also be configured to perform a single function. In this case, it is possible to configure TelcoBridges media gateway to act as a [[SIP gateway]], or a [[FreeSBC|SBC]].

=== TelcoBridges' SIP Implementation ===
TelcoBridges' SIP implementation works on top of a couple of layers, including SIP and [[TUCL]]. In the following figure, grey boxes represent entities that need allocation on the TelcoBridges equipment. The TUCL layer is a transport layer used by SIP on our architecture. TUCL presents some advantages over a simple TCP/IP stack. For instance, it adds tracing facilities to any virtual interface.

[[Image:TB-SIP-Architecture.jpg|400px| ]]

=== Supported SIP RFCs ===

TelcoBridges supports the following RFCs for SIP:

{| border="1"
|-
! Specification
! TMedia SIP stack support
! Toolpack API Support
! Media Gateway Application Support
|-
| RFC 2327 Session Description Protocol
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 2833 RTP Payload for DTMF Digits, Telephony Tones and Telephony Signals
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 2976 SIP INFO Method
| align="center" | Yes
| align="center" | Complete
| align="center" | Partial: For DTMF Tones exchange only
|-
| RFC 3204 MIME media types for ISUP and QSIG Objects
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3261 Session Initiate Protocol
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3262 Reliability of Provisional Responses in the Session Initiation Protocol (SIP)
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3263 Session Initiation Protocol (SIP): Locating SIP Servers
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3264 An Offer/Answer Model with the Session Description Protocol (SDP)
| align="center" | Yes
| align="center" | Complete
| align="center" | Partial ('Indicating capabilities' not supported)
|-
| RFC 3265 Session Initiation Protocol (SIP)-Specific Event Notification
| align="center" | Yes
| align="center" | No
| align="center" | No
|-
| RFC 3311 The Session Initiation Protocol (SIP) UPDATE Method
| align="center" | Yes
| align="center" | Partial (Only For Session Timer Refresh)
| align="center" | Partial: For Session Timer Refresh and SDP reception following a SIP INVITE that had no body
|-
| RFC 3323 A Privacy Mechanism for the Session Initiation Protocol (SIP)
| align="center" | Yes
| align="center" | Partial'''1'''
| align="center" | Partial'''1'''
|-
| RFC 3325 Private Extensions to the Session Initiation Protocol (SIP) for Asserted Identity within Trusted Networks
| align="center" | Yes
| align="center" | Partial (No P-Preferred-Identity)
| align="center" | Partial (No P-Preferred-Identity)
|-
| RFC 3326 The Reason Header Field for the Session Initiation Protocol (SIP)
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3372 Session Initiation Protocol for Telephones (SIP-T)
| align="center" | Yes
| align="center" | Partial (no ISUP MIME bodies Encryption support)
| align="center" | Partial (no ISUP MIME bodies Encryption support)
|-
| RFC 3389 Real-time Transport Protocol (RTP) Payload for Comfort Noise (CN)
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3398 ISUP-SIP Mapping
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3515 Refer Method
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3551 RTP Profile for Audio and Video Conferences with Minimal Control
| align="center" | Yes
| align="center" | Partial (For supported audio codecs, single channel)
| align="center" | Partial (For supported audio codecs, single channel)
|-
| RFC 3555 MIME Type Registration of RTP Payload Formats
| align="center" | Yes
| align="center" | Partial (For supported audio codecs)
| align="center" | Partial (For supported audio codecs)
|-
| RFC 3578 Overlap
| align="center" | Yes
| align="center" | Partial (Conversion of ISUP Overlap Signalling into SIP en-bloc Signalling)
| align="center" | Partial (Conversion of ISUP Overlap Signalling into SIP en-bloc Signalling)
|-
| RFC 3581 An Extension to the Session Initiation Protocol (SIP) for Symmetric Response Routing
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3665 Session Initiation Protocol (SIP) Basic Call Flow Examples
| align="center" | Yes
| align="center" | Partial*
| align="center" | Partial*
|-
| RFC 3666 Public Switched Telephone Network (PSTN) Call Flows
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3764 enumservice registration for Session Initiation Protocol (SIP) Addresses-of-Record
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3891 "Replaces" Header
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3892 Referred-By Mechanism
| align="center" | Yes
| align="center" | No
| align="center" | No
|-
| RFC 4028 Session Timers in the Session Initiation Protocol (SIP)
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 4694 Number Portability Parameters for the "tel" URI
| align="center" | Yes
| align="center" | Yes
| align="center" | Partial (relay of rn and npdi SIP<->SS7)
|-
| RFC 4733 RTP Payload for DTMF Digits, Telephony Tones and Telephony Signals
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 5246 - The Transport Layer Security (TLS) Protocol Version 1.2
| align="center" | Yes
| align="center" | Yes
| align="center" | Yes
|-
| RFC 5630 - The Use of the SIPS URI Scheme in the Session Initiation Protocol
| align="center" | Yes
| align="center" | Yes
| align="center" | Yes
|-
| RFC 5806 Diversion Indication in SIP
| align="center" | Yes
| align="center" | Yes
| align="center" | Unconditional forward scenario
|}

 

['''1'''] For more information please contact [[Support:Contacting TelcoBridges technical support|customer support]].

== Maximum Capacity ==
{| cellpadding="5" border="1" class="wikitable" style="text-align: center"
|-
! !!Release !! SIP SAP !! SIP Transport Server !! SIP NAP
|-
| rowspan="2" | TMG800
| 2.2-2.5 || 4 || 10 || 256
|-
| 2.6+ || 16 || 16 || 512
|-
| rowspan="2" | TMG3200
| 2.2-2.5 || 4 || 10 || 256
|-
| 2.6+ || 16 || 16 || 512
|-
| rowspan="2" | TMG7800
| 2.2-2.5 || 64 (4/Tmedia) || 160 (10/Tmedia) || 256
|-
| 2.6+ || 256 (16/Tmedia) || 256 (16/Tmedia) || 512
|}

== Configuration ==

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | FreeSBC
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | Tmedia/Tsig/Tdev
|-
| valign="top" |
*[[Toolpack:Tsbc_Protocol_Stack_Settings_3.0|v3.0: SIP Signaling]]
| valign="top" |
*[[Toolpack:Protocol_Stack_Settings_D#SIP|v3.0: SIP Signaling]]
*[[Toolpack:Protocol_Stack_Settings_C#SIP|v2.10: SIP Signaling]]
*[[Toolpack:Protocol_Stack_Settings_B#SIP|v2.9: SIP Signaling]]
*[[Toolpack:Protocol_Stack_Settings_A#SIP|v2.8: SIP Signaling]]
|}

== References ==
*[http://en.wikipedia.org/wiki/Session_Initiation_Protocol Wikipedia article]
*[http://www.sipforum.org/ SIP Forum]
*[[media:Tb640 sip user's guide.pdf|TelcoBridges SIP User’s Guide]]

[[Category:Glossary]]
[[Category:Revise on Major]]

SIP

2019-03-11T13:32:00Z

Abrassard: /* TelcoBridges and SIP */

Session Initiation Protocol, more commonly known as SIP, is a signaling protocol for packet-based networks and is commonly used, along with H.323 to provide signaling for voice over IP (VoIP) communications.

== TelcoBridges and SIP ==

[[Toolpack]] provides support for signaling using the Session Initiation Protocol, more commonly known as SIP, for voice over IP (VoIP) communications. SIP may be used in conjunction with various [[Voice_codecs|voice codecs]] for the media component of a call. TelcoBridges [[Tmedia]] media gateways and [[Tdev]] development platforms support SIP signaling concurrently with [[SS7]], [[ISDN]] and other [[Signaling_protocols|signaling protocols]].

SIP signaling stacks are configured for IP applications and for each [[Tmedia]] or [[Tdev]] unit requiring SIP signaling.

Based upon your system requirements, you can configure a SIP stack to carry signaling traffic over multiple transport servers, which are IP endpoints comprised of: protocol type (UDP, TCP or TLS), port number and IP interface.

A conceptual illustration is provided below:

[[Image:SIP stack conceptual illustration.png|600px| ]] 

While TelcoBridges media gateways can perform multiple simultaneous functions such as switching and transcoding as well as deliver value-added services such as [[IVR]] or conferencing, they can also be configured to perform a single function. In this case, it is possible to configure TelcoBridges media gateway to act as a [[SIP gateway]], or a [[FreeSBC|SBC]].

=== TelcoBridges' SIP Implementation ===
TelcoBridges' SIP implementation works on top of a couple of layers, including SIP and [[TUCL]]. In the following figure, grey boxes represent entities that need allocation on the TelcoBridges equipment. The TUCL layer is a transport layer used by SIP on our architecture. TUCL presents some advantages over a simple TCP/IP stack. For instance, it adds tracing facilities to any virtual interface.

[[Image:TB-SIP-Architecture.jpg|400px| ]]

=== Supported SIP RFCs ===

TelcoBridges supports the following RFCs for SIP:

{| border="1"
|-
! Specification
! TMedia SIP stack support
! Toolpack API Support
! Media Gateway Application Support
|-
| RFC 2327 Session Description Protocol
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 2833 RTP Payload for DTMF Digits, Telephony Tones and Telephony Signals
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 2976 SIP INFO Method
| align="center" | Yes
| align="center" | Complete
| align="center" | Partial: For DTMF Tones exchange only
|-
| RFC 3204 MIME media types for ISUP and QSIG Objects
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3261 Session Initiate Protocol
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3262 Reliability of Provisional Responses in the Session Initiation Protocol (SIP)
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3263 Session Initiation Protocol (SIP): Locating SIP Servers
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3264 An Offer/Answer Model with the Session Description Protocol (SDP)
| align="center" | Yes
| align="center" | Complete
| align="center" | Partial ('Indicating capabilities' not supported)
|-
| RFC 3265 Session Initiation Protocol (SIP)-Specific Event Notification
| align="center" | Yes
| align="center" | No
| align="center" | No
|-
| RFC 3311 The Session Initiation Protocol (SIP) UPDATE Method
| align="center" | Yes
| align="center" | Partial (Only For Session Timer Refresh)
| align="center" | Partial: For Session Timer Refresh and SDP reception following a SIP INVITE that had no body
|-
| RFC 3323 A Privacy Mechanism for the Session Initiation Protocol (SIP)
| align="center" | Yes
| align="center" | Partial'''1'''
| align="center" | Partial'''1'''
|-
| RFC 3325 Private Extensions to the Session Initiation Protocol (SIP) for Asserted Identity within Trusted Networks
| align="center" | Yes
| align="center" | Partial (No P-Preferred-Identity)
| align="center" | Partial (No P-Preferred-Identity)
|-
| RFC 3326 The Reason Header Field for the Session Initiation Protocol (SIP)
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3372 Session Initiation Protocol for Telephones (SIP-T)
| align="center" | Yes
| align="center" | Partial (no ISUP MIME bodies Encryption support)
| align="center" | Partial (no ISUP MIME bodies Encryption support)
|-
| RFC 3389 Real-time Transport Protocol (RTP) Payload for Comfort Noise (CN)
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3398 ISUP-SIP Mapping
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3515 Refer Method
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3551 RTP Profile for Audio and Video Conferences with Minimal Control
| align="center" | Yes
| align="center" | Partial (For supported audio codecs, single channel)
| align="center" | Partial (For supported audio codecs, single channel)
|-
| RFC 3555 MIME Type Registration of RTP Payload Formats
| align="center" | Yes
| align="center" | Partial (For supported audio codecs)
| align="center" | Partial (For supported audio codecs)
|-
| RFC 3578 Overlap
| align="center" | Yes
| align="center" | Partial (Conversion of ISUP Overlap Signalling into SIP en-bloc Signalling)
| align="center" | Partial (Conversion of ISUP Overlap Signalling into SIP en-bloc Signalling)
|-
| RFC 3581 An Extension to the Session Initiation Protocol (SIP) for Symmetric Response Routing
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3665 Session Initiation Protocol (SIP) Basic Call Flow Examples
| align="center" | Yes
| align="center" | Partial*
| align="center" | Partial*
|-
| RFC 3666 Public Switched Telephone Network (PSTN) Call Flows
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3764 enumservice registration for Session Initiation Protocol (SIP) Addresses-of-Record
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3891 "Replaces" Header
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3892 Referred-By Mechanism
| align="center" | Yes
| align="center" | No
| align="center" | No
|-
| RFC 4028 Session Timers in the Session Initiation Protocol (SIP)
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 4694 Number Portability Parameters for the "tel" URI
| align="center" | Yes
| align="center" | Yes
| align="center" | Partial (relay of rn and npdi SIP<->SS7)
|-
| RFC 4733 RTP Payload for DTMF Digits, Telephony Tones and Telephony Signals
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 5806 Diversion Indication in SIP
| align="center" | Yes
| align="center" | Yes
| align="center" | Unconditional forward scenario
|}

 

['''1'''] For more information please contact [[Support:Contacting TelcoBridges technical support|customer support]].

== Maximum Capacity ==
{| cellpadding="5" border="1" class="wikitable" style="text-align: center"
|-
! !!Release !! SIP SAP !! SIP Transport Server !! SIP NAP
|-
| rowspan="2" | TMG800
| 2.2-2.5 || 4 || 10 || 256
|-
| 2.6+ || 16 || 16 || 512
|-
| rowspan="2" | TMG3200
| 2.2-2.5 || 4 || 10 || 256
|-
| 2.6+ || 16 || 16 || 512
|-
| rowspan="2" | TMG7800
| 2.2-2.5 || 64 (4/Tmedia) || 160 (10/Tmedia) || 256
|-
| 2.6+ || 256 (16/Tmedia) || 256 (16/Tmedia) || 512
|}

== Configuration ==

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | FreeSBC
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | Tmedia/Tsig/Tdev
|-
| valign="top" |
*[[Toolpack:Tsbc_Protocol_Stack_Settings_3.0|v3.0: SIP Signaling]]
| valign="top" |
*[[Toolpack:Protocol_Stack_Settings_D#SIP|v3.0: SIP Signaling]]
*[[Toolpack:Protocol_Stack_Settings_C#SIP|v2.10: SIP Signaling]]
*[[Toolpack:Protocol_Stack_Settings_B#SIP|v2.9: SIP Signaling]]
*[[Toolpack:Protocol_Stack_Settings_A#SIP|v2.8: SIP Signaling]]
|}

== References ==
*[http://en.wikipedia.org/wiki/Session_Initiation_Protocol Wikipedia article]
*[http://www.sipforum.org/ SIP Forum]
*[[media:Tb640 sip user's guide.pdf|TelcoBridges SIP User’s Guide]]

[[Category:Glossary]]
[[Category:Revise on Major]]

File:SIP stack conceptual illustration.png

2019-03-11T13:28:42Z

Abrassard:

SIP

2019-03-11T13:28:28Z

Abrassard: /* TelcoBridges and SIP */

Session Initiation Protocol, more commonly known as SIP, is a signaling protocol for packet-based networks and is commonly used, along with H.323 to provide signaling for voice over IP (VoIP) communications.

== TelcoBridges and SIP ==

[[Toolpack]] provides support for signaling using the Session Initiation Protocol, more commonly known as SIP, for voice over IP (VoIP) communications. SIP may be used in conjunction with various [[Voice_codecs|voice codecs]] for the media component of a call. TelcoBridges [[Tmedia]] media gateways and [[Tdev]] development platforms support SIP signaling concurrently with [[SS7]], [[ISDN]] and other [[Signaling_protocols|signaling protocols]].

SIP signaling stacks are configured for IP applications and for each [[Tmedia]] or [[Tdev]] unit requiring SIP signaling.

Based upon your system requirements, you can configure a SIP stack to carry signaling traffic over multiple transport servers, which are IP endpoints comprised of: protocol type (UDP, TCP or TLS), port number and IP interface.

A conceptual illustration is provided below:

[[Image:SIP stack conceptual illustration.png| ]] 

While TelcoBridges media gateways can perform multiple simultaneous functions such as switching and transcoding as well as deliver value-added services such as [[IVR]] or conferencing, they can also be configured to perform a single function. In this case, it is possible to configure TelcoBridges media gateway to act as a [[SIP gateway]], or a [[FreeSBC|SBC]].

=== TelcoBridges' SIP Implementation ===
TelcoBridges' SIP implementation works on top of a couple of layers, including SIP and [[TUCL]]. In the following figure, grey boxes represent entities that need allocation on the TelcoBridges equipment. The TUCL layer is a transport layer used by SIP on our architecture. TUCL presents some advantages over a simple TCP/IP stack. For instance, it adds tracing facilities to any virtual interface.

[[Image:TB-SIP-Architecture.jpg|400px| ]]

=== Supported SIP RFCs ===

TelcoBridges supports the following RFCs for SIP:

{| border="1"
|-
! Specification
! TMedia SIP stack support
! Toolpack API Support
! Media Gateway Application Support
|-
| RFC 2327 Session Description Protocol
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 2833 RTP Payload for DTMF Digits, Telephony Tones and Telephony Signals
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 2976 SIP INFO Method
| align="center" | Yes
| align="center" | Complete
| align="center" | Partial: For DTMF Tones exchange only
|-
| RFC 3204 MIME media types for ISUP and QSIG Objects
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3261 Session Initiate Protocol
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3262 Reliability of Provisional Responses in the Session Initiation Protocol (SIP)
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3263 Session Initiation Protocol (SIP): Locating SIP Servers
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3264 An Offer/Answer Model with the Session Description Protocol (SDP)
| align="center" | Yes
| align="center" | Complete
| align="center" | Partial ('Indicating capabilities' not supported)
|-
| RFC 3265 Session Initiation Protocol (SIP)-Specific Event Notification
| align="center" | Yes
| align="center" | No
| align="center" | No
|-
| RFC 3311 The Session Initiation Protocol (SIP) UPDATE Method
| align="center" | Yes
| align="center" | Partial (Only For Session Timer Refresh)
| align="center" | Partial: For Session Timer Refresh and SDP reception following a SIP INVITE that had no body
|-
| RFC 3323 A Privacy Mechanism for the Session Initiation Protocol (SIP)
| align="center" | Yes
| align="center" | Partial'''1'''
| align="center" | Partial'''1'''
|-
| RFC 3325 Private Extensions to the Session Initiation Protocol (SIP) for Asserted Identity within Trusted Networks
| align="center" | Yes
| align="center" | Partial (No P-Preferred-Identity)
| align="center" | Partial (No P-Preferred-Identity)
|-
| RFC 3326 The Reason Header Field for the Session Initiation Protocol (SIP)
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3372 Session Initiation Protocol for Telephones (SIP-T)
| align="center" | Yes
| align="center" | Partial (no ISUP MIME bodies Encryption support)
| align="center" | Partial (no ISUP MIME bodies Encryption support)
|-
| RFC 3389 Real-time Transport Protocol (RTP) Payload for Comfort Noise (CN)
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3398 ISUP-SIP Mapping
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3515 Refer Method
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3551 RTP Profile for Audio and Video Conferences with Minimal Control
| align="center" | Yes
| align="center" | Partial (For supported audio codecs, single channel)
| align="center" | Partial (For supported audio codecs, single channel)
|-
| RFC 3555 MIME Type Registration of RTP Payload Formats
| align="center" | Yes
| align="center" | Partial (For supported audio codecs)
| align="center" | Partial (For supported audio codecs)
|-
| RFC 3578 Overlap
| align="center" | Yes
| align="center" | Partial (Conversion of ISUP Overlap Signalling into SIP en-bloc Signalling)
| align="center" | Partial (Conversion of ISUP Overlap Signalling into SIP en-bloc Signalling)
|-
| RFC 3581 An Extension to the Session Initiation Protocol (SIP) for Symmetric Response Routing
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3665 Session Initiation Protocol (SIP) Basic Call Flow Examples
| align="center" | Yes
| align="center" | Partial*
| align="center" | Partial*
|-
| RFC 3666 Public Switched Telephone Network (PSTN) Call Flows
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3764 enumservice registration for Session Initiation Protocol (SIP) Addresses-of-Record
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3891 "Replaces" Header
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3892 Referred-By Mechanism
| align="center" | Yes
| align="center" | No
| align="center" | No
|-
| RFC 4028 Session Timers in the Session Initiation Protocol (SIP)
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 4694 Number Portability Parameters for the "tel" URI
| align="center" | Yes
| align="center" | Yes
| align="center" | Partial (relay of rn and npdi SIP<->SS7)
|-
| RFC 4733 RTP Payload for DTMF Digits, Telephony Tones and Telephony Signals
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 5806 Diversion Indication in SIP
| align="center" | Yes
| align="center" | Yes
| align="center" | Unconditional forward scenario
|}

 

['''1'''] For more information please contact [[Support:Contacting TelcoBridges technical support|customer support]].

== Maximum Capacity ==
{| cellpadding="5" border="1" class="wikitable" style="text-align: center"
|-
! !!Release !! SIP SAP !! SIP Transport Server !! SIP NAP
|-
| rowspan="2" | TMG800
| 2.2-2.5 || 4 || 10 || 256
|-
| 2.6+ || 16 || 16 || 512
|-
| rowspan="2" | TMG3200
| 2.2-2.5 || 4 || 10 || 256
|-
| 2.6+ || 16 || 16 || 512
|-
| rowspan="2" | TMG7800
| 2.2-2.5 || 64 (4/Tmedia) || 160 (10/Tmedia) || 256
|-
| 2.6+ || 256 (16/Tmedia) || 256 (16/Tmedia) || 512
|}

== Configuration ==

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | FreeSBC
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | Tmedia/Tsig/Tdev
|-
| valign="top" |
*[[Toolpack:Tsbc_Protocol_Stack_Settings_3.0|v3.0: SIP Signaling]]
| valign="top" |
*[[Toolpack:Protocol_Stack_Settings_D#SIP|v3.0: SIP Signaling]]
*[[Toolpack:Protocol_Stack_Settings_C#SIP|v2.10: SIP Signaling]]
*[[Toolpack:Protocol_Stack_Settings_B#SIP|v2.9: SIP Signaling]]
*[[Toolpack:Protocol_Stack_Settings_A#SIP|v2.8: SIP Signaling]]
|}

== References ==
*[http://en.wikipedia.org/wiki/Session_Initiation_Protocol Wikipedia article]
*[http://www.sipforum.org/ SIP Forum]
*[[media:Tb640 sip user's guide.pdf|TelcoBridges SIP User’s Guide]]

[[Category:Glossary]]
[[Category:Revise on Major]]

SIP

2019-03-11T13:27:45Z

Abrassard: Added concepts of TLS

Session Initiation Protocol, more commonly known as SIP, is a signaling protocol for packet-based networks and is commonly used, along with H.323 to provide signaling for voice over IP (VoIP) communications.

== TelcoBridges and SIP ==

[[Toolpack]] provides support for signaling using the Session Initiation Protocol, more commonly known as SIP, for voice over IP (VoIP) communications. SIP may be used in conjunction with various [[Voice_codecs|voice codecs]] for the media component of a call. TelcoBridges [[Tmedia]] media gateways and [[Tdev]] development platforms support SIP signaling concurrently with [[SS7]], [[ISDN]] and other [[Signaling_protocols|signaling protocols]].

SIP signaling stacks are configured for IP applications and for each [[Tmedia]] or [[Tdev]] unit requiring SIP signaling.

Based upon your system requirements, you can configure a SIP stack to carry signaling traffic over multiple transport servers, which are IP endpoints comprised of: protocol type (UDP, TCP or TLS), port number and IP interface.

A conceptual illustration is provided below:

[[Image:SIP stack conceptual illustration.jpg| ]] 

While TelcoBridges media gateways can perform multiple simultaneous functions such as switching and transcoding as well as deliver value-added services such as [[IVR]] or conferencing, they can also be configured to perform a single function. In this case, it is possible to configure TelcoBridges media gateway to act as a [[SIP gateway]], or a [[FreeSBC|SBC]].

=== TelcoBridges' SIP Implementation ===
TelcoBridges' SIP implementation works on top of a couple of layers, including SIP and [[TUCL]]. In the following figure, grey boxes represent entities that need allocation on the TelcoBridges equipment. The TUCL layer is a transport layer used by SIP on our architecture. TUCL presents some advantages over a simple TCP/IP stack. For instance, it adds tracing facilities to any virtual interface.

[[Image:TB-SIP-Architecture.jpg|400px| ]]

=== Supported SIP RFCs ===

TelcoBridges supports the following RFCs for SIP:

{| border="1"
|-
! Specification
! TMedia SIP stack support
! Toolpack API Support
! Media Gateway Application Support
|-
| RFC 2327 Session Description Protocol
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 2833 RTP Payload for DTMF Digits, Telephony Tones and Telephony Signals
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 2976 SIP INFO Method
| align="center" | Yes
| align="center" | Complete
| align="center" | Partial: For DTMF Tones exchange only
|-
| RFC 3204 MIME media types for ISUP and QSIG Objects
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3261 Session Initiate Protocol
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3262 Reliability of Provisional Responses in the Session Initiation Protocol (SIP)
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3263 Session Initiation Protocol (SIP): Locating SIP Servers
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3264 An Offer/Answer Model with the Session Description Protocol (SDP)
| align="center" | Yes
| align="center" | Complete
| align="center" | Partial ('Indicating capabilities' not supported)
|-
| RFC 3265 Session Initiation Protocol (SIP)-Specific Event Notification
| align="center" | Yes
| align="center" | No
| align="center" | No
|-
| RFC 3311 The Session Initiation Protocol (SIP) UPDATE Method
| align="center" | Yes
| align="center" | Partial (Only For Session Timer Refresh)
| align="center" | Partial: For Session Timer Refresh and SDP reception following a SIP INVITE that had no body
|-
| RFC 3323 A Privacy Mechanism for the Session Initiation Protocol (SIP)
| align="center" | Yes
| align="center" | Partial'''1'''
| align="center" | Partial'''1'''
|-
| RFC 3325 Private Extensions to the Session Initiation Protocol (SIP) for Asserted Identity within Trusted Networks
| align="center" | Yes
| align="center" | Partial (No P-Preferred-Identity)
| align="center" | Partial (No P-Preferred-Identity)
|-
| RFC 3326 The Reason Header Field for the Session Initiation Protocol (SIP)
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3372 Session Initiation Protocol for Telephones (SIP-T)
| align="center" | Yes
| align="center" | Partial (no ISUP MIME bodies Encryption support)
| align="center" | Partial (no ISUP MIME bodies Encryption support)
|-
| RFC 3389 Real-time Transport Protocol (RTP) Payload for Comfort Noise (CN)
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3398 ISUP-SIP Mapping
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3515 Refer Method
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3551 RTP Profile for Audio and Video Conferences with Minimal Control
| align="center" | Yes
| align="center" | Partial (For supported audio codecs, single channel)
| align="center" | Partial (For supported audio codecs, single channel)
|-
| RFC 3555 MIME Type Registration of RTP Payload Formats
| align="center" | Yes
| align="center" | Partial (For supported audio codecs)
| align="center" | Partial (For supported audio codecs)
|-
| RFC 3578 Overlap
| align="center" | Yes
| align="center" | Partial (Conversion of ISUP Overlap Signalling into SIP en-bloc Signalling)
| align="center" | Partial (Conversion of ISUP Overlap Signalling into SIP en-bloc Signalling)
|-
| RFC 3581 An Extension to the Session Initiation Protocol (SIP) for Symmetric Response Routing
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3665 Session Initiation Protocol (SIP) Basic Call Flow Examples
| align="center" | Yes
| align="center" | Partial*
| align="center" | Partial*
|-
| RFC 3666 Public Switched Telephone Network (PSTN) Call Flows
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3764 enumservice registration for Session Initiation Protocol (SIP) Addresses-of-Record
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3891 "Replaces" Header
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 3892 Referred-By Mechanism
| align="center" | Yes
| align="center" | No
| align="center" | No
|-
| RFC 4028 Session Timers in the Session Initiation Protocol (SIP)
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 4694 Number Portability Parameters for the "tel" URI
| align="center" | Yes
| align="center" | Yes
| align="center" | Partial (relay of rn and npdi SIP<->SS7)
|-
| RFC 4733 RTP Payload for DTMF Digits, Telephony Tones and Telephony Signals
| align="center" | Yes
| align="center" | Complete
| align="center" | Complete
|-
| RFC 5806 Diversion Indication in SIP
| align="center" | Yes
| align="center" | Yes
| align="center" | Unconditional forward scenario
|}

 

['''1'''] For more information please contact [[Support:Contacting TelcoBridges technical support|customer support]].

== Maximum Capacity ==
{| cellpadding="5" border="1" class="wikitable" style="text-align: center"
|-
! !!Release !! SIP SAP !! SIP Transport Server !! SIP NAP
|-
| rowspan="2" | TMG800
| 2.2-2.5 || 4 || 10 || 256
|-
| 2.6+ || 16 || 16 || 512
|-
| rowspan="2" | TMG3200
| 2.2-2.5 || 4 || 10 || 256
|-
| 2.6+ || 16 || 16 || 512
|-
| rowspan="2" | TMG7800
| 2.2-2.5 || 64 (4/Tmedia) || 160 (10/Tmedia) || 256
|-
| 2.6+ || 256 (16/Tmedia) || 256 (16/Tmedia) || 512
|}

== Configuration ==

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | FreeSBC
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | Tmedia/Tsig/Tdev
|-
| valign="top" |
*[[Toolpack:Tsbc_Protocol_Stack_Settings_3.0|v3.0: SIP Signaling]]
| valign="top" |
*[[Toolpack:Protocol_Stack_Settings_D#SIP|v3.0: SIP Signaling]]
*[[Toolpack:Protocol_Stack_Settings_C#SIP|v2.10: SIP Signaling]]
*[[Toolpack:Protocol_Stack_Settings_B#SIP|v2.9: SIP Signaling]]
*[[Toolpack:Protocol_Stack_Settings_A#SIP|v2.8: SIP Signaling]]
|}

== References ==
*[http://en.wikipedia.org/wiki/Session_Initiation_Protocol Wikipedia article]
*[http://www.sipforum.org/ SIP Forum]
*[[media:Tb640 sip user's guide.pdf|TelcoBridges SIP User’s Guide]]

[[Category:Glossary]]
[[Category:Revise on Major]]