|
|
| (12 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| {{DISPLAYTITLE:Routing Script tutorial: A Mini Development Guide}} | | {{DISPLAYTITLE:Routing Script Tutorial: Development Guide}} |
| | |
| | |
|
| |
|
| ==Introduction== | | ==Introduction== |
| This Routing Script Tutorial provides you with essential information in managing the routing of your calls. Consult the sections below to learn more. | | This Routing Script Tutorial provides you with essential information in managing the routing of your calls. Consult the sections below to learn more. |
| | |
| | {| class="wikitable" |
| | |
| | |[[File:NoteIcon.png|100px]]|| An alternate version of this guide for routing scripts is available. [[Routing script tutorial|Consult it to enhance your learning.]] |
| | |} |
|
| |
|
| ==Accessing Routing Script Parameters == | | ==Accessing Routing Script Parameters == |
| Line 54: |
Line 61: |
| == Terminating Calls == | | == Terminating Calls == |
| [[Routing Script Tutorial: Terminating Calls|Learn how to terminate calls with routing scripts.]] | | [[Routing Script Tutorial: Terminating Calls|Learn how to terminate calls with routing scripts.]] |
|
| |
|
| |
|
| == NAP status and other NAP information == | | == NAP status and other NAP information == |
| | [[Routing Script Tutorial: NAP Status and other NAP Information|Learn how to use NAP status field in routing scripts.]] |
|
| |
|
| All the status fields of the NAPs are provided for use by the routing scripts.
| | == Telephony Services (CNAM Request over SS7)== |
| ''<br> For developpers: see the nap status provider for more details on which fields are available in the CEngineStatTransNap.hpp file.''
| | [[Routing Script Tutorial: CNAM Request|Learn how to manage CNAM requests over SS7.]] |
| | |
| '''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.
| |
| }
| |
|
| |
| <br> 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 ===
| |
| <br> 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
| |
| | |
| <br> To get the configured NAP list, you can do this:
| |
| nap_lists = params[:naps]
| |
| log_trace 1, "nap_lists = " + nap_lists.inspect
| |
| | |
| <br> 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
| |
| <br> Or which network the call is coming from:
| |
| log_trace 1,"Incoming NAP signaling type=" + nap_lists[incoming_nap][:signaling_type].inspect
| |
| | |
| <br> 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
| |
| | |
| <br> 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)
| | == Custom User Context == |
| | [[Routing Script Tutorial: Custom User Context|Custom User Context]] |
|
| |
|
| == Routing Script Tests == | | == 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.
| | [[Routing Script Tutorial: Routing Script Tests|Learn how to use the Web Portal to test your routing scripts.]] |
| 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.
| |
| | |
| <br>
| |
| | |
| ==== @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.
| |
| | |
| <br>
| |
| | |
| ==== @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"
| |
| }
| |
| }
| |
| | |
| <br>
| |
| | |
| ----
| |
| | |
| <br> Back to [[Routing script tutorial|Routing Script Tutorial]].
| |
| | |
| [[category:FAQ]]
| |
