Routing script tutorial:Mini Development Guide

Latest revision as of 14:16, 10 March 2021

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 "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 How to use regex in Remapped Called and Calling Number Mask

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.

• unknown_number (2 or 0x2)
• international_number (4 or 0x4)
• national_number (3 or 0x3)
• subscriber_number (1 or 0x1)
• network_specific (5 or 0x5)
• network_routing_national_format (7 or 0x7)
• network_routing_international_format (8 or 0x8)
• abbreviated_number (6 or 0x6)
• subscriber_number_operator_requested (113 or 0x71)
• national_number_operator_requested (114 or 0x72)
• international_number_operator_requested (115 or 0x73)
• no_number_present_operator_requested (116 or 0x74)
• no_number_present_cut_through_call_to_carrier (117 or 0x75)
• test_line_test_code (119 or 0x77)
• non_unique_subscriber_number (113 or 0x71)
• non_unique_national_number (115 or 0x73)
• non_unique_international_number (116 or 0x74)
• call_950_number (118 or 0x76)
• special_number (115 or 0x73)
• national_number_with_transit_network_selection (116 or 0x74)
• international_number_with_transit_network_selection (117 or 0x75)

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

• call_params[:called_noa] = 0x70

or

• call_params[:called_noa] = 112

Npi values

• unknown_number
• isdn
• telephony
• private
• data
• telex
• national

Calling Display Type values

• unspecified => Type is unspecified.
• calling_party_name => Type is 0xB1.

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

• call_params[:calling_display_type] = 0xB1

or

• call_params[:calling_display_type] = 177

Calling Display value

• call_params[:calling_display] = "Roger Fluffy"

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.

• unspecified
• not_available (0x2)
• allowed (0x0)
• restricted (0x1)
• addr_restricted
• name_restricted

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

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.
In case it is required to use a value that is not defined in the text values below, an 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.

• unspecified
• no (0x0)
• pass (0x1)
• fail (0x2)
• network_provided (0x3)

Redirecting indicator values

SS7:

• no_redirection
• call_rerouted
• call_rerouted_all_restricted
• call_diverted
• call_diverted_all_restricted
• call_rerouted_restricted
• call_diverted_restricted
• spare

Redirecting number, Original Called Number and Diversion Reason

ISDN:

• unknown
• busy
• no_reply
• deflection
• dte_out_of_order
• forwarding_by_called_dte
• unconditional

SS7:

• unknown
• busy (SIP: user-busy)
• no_reply (SIP: no-answer)
• unconditional
• deflection
• deflection_immediate
• mobile_not_reachable

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:

• digital
• restricted_digital
• digital_with_tones
• speech
• 3_1_khz_audio
• video

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:

Request-Line: INVITE sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0

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:

    if call_params[:request_uri] && call_params[:request_uri] =~ /sip:(.*)@.*/
       call_params[:called] = $1
    end

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 parameter indicates the scheme (generally "sip" or "sips") of the incoming call.

This also allows the control of 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:

call[ :sip_header ] = "P-my-custom-header:value1 \nP-my-custom-header2:value2 \nP-my-custom-header3:value3"

(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:

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

Note: Since version 3.0.57, Referred-By is now a SIP custom parameter

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[ :supp_private_address_parameters ] (SIP supplementary/second "P-Asserted-Identity" header)
• call[ :preferred_id_parameters ] (SIP "P-Preferred-Identity" 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 will not appear 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:

  if call[:calling_parameters]
    puts "user parameters = #{call[:calling_parameters][:user_param].inspect}"
  end

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:

call [:calling_parameters] = { 
  :user_param => "user_param7=7;user_param8=8",
  :uri_param => "uri_param9=value9",
  :header_param => "header_paramA=A" }

Example to add user=phone and keep all other uri parameters.

  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"

MLPP Precedence values

mlpp_look_for_busy:

• allowed
• path_reserved
• not_allowed

mlpp_precedence_level:

• flash_override
• flash
• immediate
• priority
• routine

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:

• nsap
• nsap_ia5
• nsap_bcd
• user

called_isub: calling_isub:

Digits for the subaddress information.

Network Identification Plan

network_identification_plan:

• Unknown (value 0)
• cic (3 digits carrier identification code plus circuit code, value 1, SS7 or ISDN)
• user (User, value 2, ISDN only)
• cic4 (4 digits carrier identification code plus circuit code, value 2, SS7 only)
• dnic (public Data Network ID, value 3, SS7 only)
• mnic (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 choose an outbound NAP to forward the call to. It is also possible to create routes from which the outbound NAP is dynamically chosen by matching a registered user (when using SIP registration forwarding).

More information can be found here about the way to control the priority of "dynamic" vs "static" routes.

More information can be found 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.

"file1.wav:repeat:start_off:end_off,file2.wav:repeat:start_off:end_off,file3.wav:repeat:start_off:end_off"

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: Path format

Example 1

The following example will play file1.wav once, and then play file2.wav in a loop:

 "file1.wav,file2.wav:-1"

Example 2

The following example will play file1.wav from a start offset of 1 second to an end offset of 3 seconds, followed by file2.wav being played two times 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 an 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 applies when params[:bridge][:ring_tone] are not used, because it also applies 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: 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: 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 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.

ENUM Query

Starting with release 3.1, it is possible to issue ENUM Query requests to DNS servers from routing scripts. To do so, the params[:enum_query] object must be filled with the required ENUM Query attributes params[:enum_query][:fqdn] and an exception must be raised with reason :enum_query_required.

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

• ok: The ENUM Query was successful.
• timeout: The ENUM Query was not answered.

The params[:enum_query][:responses_list] field will contain a list of hash responses for each NAPTR records.

NAPTR records contain:

• :uri
• :order
• :preference

Example:

 params[:enum_query][:responses_list]
   [{:order=>"200", :preference=>"10", :uri=>"!^03111.*$!sip:123456782@example-2.com!"}, 
    {:order=>"100", :preference=>"1", :uri=>"!^03222.*$!sip:123456782@example-3.com!"}, 
    {:order=>"200", :preference=>"1", :uri=>"!^03111.*$!sip:123456782@example-1.com!"}]

Using enum_called_remap.rb before filter script allows handling of ENUM query requests/responses. The match and replace regular expression from ENUM query responses are applied to params[:call][:called] to get "new called". This script allows update of the call parameters according to "new called" value. Refer to enum_called_remap.rb before filter script to get instructions on how to integrate this script into the main routing script (i.e. simple_routing_sbc.rb):

 ...
 require 'enum_called_remap' unless defined?(EnumCalledRemap)
 ...
 include EnumCalledRemap
 ...
 before_filter :method => :enum_called_remap
 ...

Resolve ENUM Query down to type A records

The ENUM query could also resolve uri from responses and get matching outgoing NAP, NAP proxy IP and port through a sequence of DNS queries (i.e. NAPTR, SRV down to type A records). This behavior could be requested using "dns_query" parameter:

 params[:enum_query][:dns_query] = true

When ENUM and DNS Queries complete, the routing script is called again with the results. The params[:enum_query] and params[:dns_query] objects will be filled with the ENUM Query and the DNS Query attributes from the responses. The DNS query responses are available through params[:dns_query][:responses_list] call parameters:

 params[:dns_query][:responses_list]
   [{:nap=>"NAP_UDP", :nap_proxy_ip=>"10.3.14.191", :nap_proxy_port=>"8080", :transport=>"UDP", :order=>"100",
     :preference=>"1", :priority=>"0", :weight=>"5"},
    {:nap=>"NAP_TCP", :nap_proxy_ip=>"10.3.14.192", :nap_proxy_port=>"8081", :transport=>"TCP", :order=>"100",
     :preference=>"2", :priority=>"1", :weight=>"10"}]

Add dynamic routes

The ENUM query could also add dynamic routes base on DNS query responses. This could be requested using the "add_dynamic_routes" call parameter:

 params[:enum_query][:dns_query] = true
 params[:enum_query][:add_dynamic_routes] = true

Note that it is mandatary to send DNS query to add dynamic routes.

The "base_routing.rb" script version should be greater then 1.37 in order to allow dynamic routes creation base on DNS query responses.

When requesting to add_dynamic_routes, the dns_query responses are used to create routes. Make sure that your configuration includes a route with remapped_nap = "Registered or DNS users". A route will be created for each DNS query responses. The routes "remapped_nap" takes NAP value from DNS query responses.

It is required to modify main routing script (i.e. simple_routing_sbc.rb) to forward IP/port values from params[:routes] to params[:call] like we are doing for NAP. See following example:

 ...
 # This will select the outgoing NAP for this call according to the "remapped_nap" route parameter
 route_remap :call_field_name => :nap, :route_field_name => :remapped_nap
 
 # This will select the outgoing NAP proxy ip address for this call according to the "remapped_nap_proxy_ip" route parameter
 route_remap :call_field_name => :nap_proxy_ip, :route_field_name => :remapped_nap_proxy_ip
 
 # This will select the outgoing NAP proxy port for this call according to the "remapped_nap_proxy_port" route parameter
 route_remap :call_field_name => :nap_proxy_port, :route_field_name => :remapped_nap_proxy_port
 ...

DNS Query

Similarly to ENUM query, starting with release 3.1, it is possible to issue DNS Query requests to DNS servers from routing scripts. This could be used to skip the ENUM Query part when the called uri is already known but still need to get the matching outgoing NAP, NAP proxy IP and port. To do so, the params[:dns_query] object must be filled with the required DNS Query attributes params[:dns_query][:fqdn] and an exception must be raised with reason :dns_query_required.

When DNS Query completes, the routing script is called again with the result. The params[:dns_query] object will be filled with the DNS Query attributes from the responses. The DNS query responses are available through params[:dns_query][:responses_list] call parameters:

 params[:dns_query][:responses_list]
   [{:nap=>"NAP_UDP", :nap_proxy_ip=>"10.3.14.191", :nap_proxy_port=>"8080", :transport=>"UDP", :order=>"100",
     :preference=>"1", :priority=>"0", :weight=>"5"},
    {:nap=>"NAP_TCP", :nap_proxy_ip=>"10.3.14.192", :nap_proxy_port=>"8081", :transport=>"TCP", :order=>"100",
     :preference=>"2", :priority=>"1", :weight=>"10"}]

Add dynamic routes

Similarly to ENUM Query, the DNS query could also create dynamic routes base on DNS query responses. This could be requested using the "add_dynamic_routes" call parameter:

 params[:dns_query][:add_dynamic_routes] = true

The "base_routing.rb" script version should be greater then 1.37 in order to allow dynamic routes creation base on DNS query responses.

When requesting to add_dynamic_routes, the dns_query responses are used to create routes. Make sure that your configuration include a route with remapped_nap = "Registered or DNS users". A route will be created for each DNS query responses. The routes "remapped_nap" takes NAP value from DNS query responses.

It is required to modify main routing script (i.e. simple_routing_sbc.rb) to forward IP/port values from params[:routes] to params[:call] like we are doing for NAP. See following example:

 ...
 # This will select the outgoing NAP for this call according to the "remapped_nap" route parameter
 route_remap :call_field_name => :nap, :route_field_name => :remapped_nap
 
 # This will select the outgoing NAP proxy ip address for this call according to the "remapped_nap_proxy_ip" route parameter
 route_remap :call_field_name => :nap_proxy_ip, :route_field_name => :remapped_nap_proxy_ip
 
 # This will select the outgoing NAP proxy port for this call according to the "remapped_nap_proxy_port" route parameter
 route_remap :call_field_name => :nap_proxy_port, :route_field_name => :remapped_nap_proxy_port
 ...

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 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"
 }

• params[:contacts][:list] contains the contact log. Each contact within the list has the following fields:
  • :called_number - the called number
  • :is_number_ported - if the called number has been ported (for SIP: if the npdi parameter is present)
  • :ported_number - the called number that was ported (for SIP: the rn parameter value, if available)
  • :sip_uri - the SIP URI of the contact, without the contact-params section (without the expires and q contact parameters)
  • :raw_data - 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).
  • :priority - the priority of the contact [0-1000]
  • :expiration - the expiration time in seconds of the contact
• params[:contacts][:index] contains the index of the contact that is currently being routed.
• params[:contacts][:source_indexes] contains a comma-separated list of indexes from params[:contacts][:list]. Each index represents the contact from which the contact in the list was obtained from.

To get more information, see:

• 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 code must be specified in params[:bridge][:reason]. The :terminate hash must be created and copied into params:

 terminate = {}
 params[:terminate] = terminate

The following fields can then be set in :terminate:

• :sip_header
• :contacts # list of contacts as described in the redirection section
• :isup_raw
• :isup_raw_variant
• :redirecting_number
• :redirecting_number_noa
• :redirecting_number_npi
• :redirecting_number_presentation
• :redirecting_number_reason
• :redirecting_number_counter
• :redirecting_number_indicator
• :original_called_number
• :original_called_number_noa
• :original_called_number_npi
• :original_called_number_presentation
• :original_called_number_reason
• :original_called_number_counter

Reason values

Check here for Termination Reason 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 and other NAP information

All the status fields of the NAPs are provided for use by the routing scripts.
For developpers: 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.
 }
 

The nap status is part of a substructure and will be a hash containing all subfield elements.

Example to access NAP information and NAP status of the current call

To find the incoming nap in a routing script, we can do this in before_filter or after_filter and use these lines to create a symbol:

   incoming_nap = params[:call][:nap].to_sym
   log_trace 1, "incoming_nap = " + incoming_nap.inspect

To get the configured NAP list, you can do this:

   nap_lists = params[:naps]
   log_trace 1, "nap_lists = " + nap_lists.inspect

From the list above, you can find how many calls you have on this NAP:

   log_trace 1,"Incoming NAP call count=" + nap_lists[incoming_nap][:asr_stats_incoming_struct][:total_call_cnt].inspect 

Or which network the call is coming from:

   log_trace 1,"Incoming NAP signaling type=" + nap_lists[incoming_nap][:signaling_type].inspect 

If you are using a "NAP Columns" custom parameter (Create New NAP Column), you can get the information (since incoming_nap is a symbol):

   network_type = nap_lists[incoming_nap][:network_type]
   log_trace 1, "For incoming_nap = " + incoming_nap.inspect + " network_type is: " + network_type.inspect

If you want to modify something according to nap information, you may need to do a loop like this:

   nap_lists.each do |nap_list,nap_info|
     log_trace 1, "NAP: " + nap_info[:name].inspect + " network_type: " + nap_info[:network_type].inspect
   end

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 times 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.