Routing Script tutorial: A Mini Development Guide
Introduction
This Routing Script Tutorial provides you with essential information in managing the routing of your calls. Consult the sections below to learn more.
Accessing Routing Script Parameters
Learn how to access routing script parameters.
Routing Script Parameter Mapping Table
Learn how each Routing Script Parameter maps to varying protocols.
Script Parameters Definition
Learn about the definition of each script parameter.
Script Parameters Definition for SIP
Learn about the definition of each script parameter for SIP.
Registered Users Information
Learn how routing scripts access information about registered users.
Route Parameters and Call Routing
Learn about the standard parameters used in a call and how they route to registered users.
Playing prompts announcements or tones
Learn how to play all sorts of media files for call prompts, announcements, and tones.
Recording
Learn how to use routing scripts to record incoming and/or outgoing call legs.
User-to-User Information
Learn how to use User-to-User Information (UUI) in routing scripts.
Radius Autorization
Learn how to send RADIUS authorization requests in routing scripts.
ENUM Query
Learn how to send ENUM Query requests to DNS servers in routing scripts.
DNS Query
Learn how to send DNS Query requests to DNS servers in routing scripts.
Call Diversion Options
Learn how control a call flow with diversion options.
Call Transfer Requests
Learn how to route call transfer requests.
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 fromparams[:contacts][:list]. Each index represents the contact from which the contact in the list was obtained from.
To get more information, see:
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.