Routing script tutorial:Mini Development Guide

From TBwiki
Revision as of 06:35, 3 August 2012 by Abrassard (Talk | contribs)
Jump to: navigation, search

Contents

Call object

Get

Those function are 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 params 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 gateway application will use to bridge the incoming call leg. If more than one outgoing route is "accepted", gateway will try them one by one in the same order 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:

Script parameter name ISDN
 		R2 CAS
 SS7
 		SIP
 		Comment
calling
 Q931: 'Calling party number' IE - Number digits
ANI (Group B)
 Q763: 'Calling party number' IE - address signals (*)
 SIP:From - user-info
 * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead.
calling_noa
 Q931: 'Calling party number' IE - Type of number
 N/A
 Q763: 'Calling party number' IE - nature of address indicator (*)
 N/A
 * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead
calling_npi
Q931: 'Calling party number' IE - Numbering plan identification
 N/A
 Q763: 'Calling party number' IE - numbering plan indicator (*)
 N/A
 * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead
calling_display
Q931: 'Display' IE - Display information
 N/A
 Q763: 'Display information' IE - display information
 SIP:From - display-name
calling_display_type
 Q931: 'Display' IE - Display information (present and/or first byte)
 N/A
 Q763: 'Display information' IE - present or not
 N/A
calling_presentation
Q931: 'Calling party number' IE - Presentation indicator
 N/A
 Q763: 'Calling party number' IE - address presentation restricted indicator

SIP:From - display-name (displays 'anonymous' or not)

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

SIP:From - cpc

SIP:P-asserted-identity - cpc
private_display
 N/A
 N/A
 N/A

SIP:P-asserted-identity - display-name

SIP:Remote-party-id - display-name
private_display_type
N/A
 N/A
 N/A
 N/A
 Indicate presence or not of the private calling information
private_address
 N/A
 N/A
 N/A

SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info
called
Q931: 'Called party number' IE - Number digits
DNIS (Group A)
 Q763: 'Called party number' IE - address signals
 SIP:To - user-info and host
called_noa
Q931: 'Called party number' IE - Type of number
 N/A
 Q763: 'Called party number' IE - nature of address indicator
 N/A
called_npi
Q931: 'Called party number' IE - Numbering plan identification
 N/A
 Q763: 'Called party number' IE - numbering plan indicator
 N/A
charge_number
 N/A
 N/A
 ANSI: 'Charge number' IE - address signals
 N/A
charge_number_noa
N/A
 N/A
 ANSI: 'Charge number' IE - nature of address indicator
 N/A
charge_number_npi
 N/A
 N/A
 ANSI: 'Charge number' IE - numbering plan indicator
 N/A
redirecting_number_forward_enabled
N/A
 N/A
 N/A
 N/A
 Overwrite default redirecting number forwarding behavior from incoming to outgoing leg
redirecting_number
Q931: 'Redirecting number' 1st IE - Number digits
N/A
 Q763: 'Redirecting number' IE - address signals
 SIP:Diversion (2nd header) - display-name
redirecting_number_noa
Q931: 'Redirecting number' 1st IE - Type of number
 N/A
 Q763: 'Redirecting number' IE - nature of address indicator
 N/A
redirecting_number_npi
Q931: 'Redirecting number' 1st IE - Numbering plan identification
 N/A
 Q763: 'Redirecting number' IE - numbering plan indicator
 N/A
redirecting_number_presentation
Q931: 'Redirecting number' 1st IE - Presentation indicator
N/A
 Q763: 'Redirecting number' IE - address presentation restricted indicator
 SIP:Diversion (2nd header) - diversion-privacy
redirecting_number_screening
Q931: 'Redirecting number' 1st IE - Screening indicator
 N/A
 Q763: 'Redirecting number' IE - screening (national)
 SIP:Diversion (2nd header) - diversion-screen
redirecting_number_reason
Q931: 'Redirecting number' 1st IE - Reason for redirection
 N/A
 Q763: 'Redirection information' IE - redirecting reason
 SIP:Diversion (2nd header) - diversion-reason
redirecting_number_counter
N/A
 N/A
 Q763: 'Redirection information' IE - redirection counter
 SIP:Diversion (2nd header) - diversion-counter
original_called_number
Q931: 'Redirecting number' 2nd IE - Number digits
N/A
 Q763: 'Redirection number' IE - address signals
 SIP:Diversion  (1st header) - display-name
original_called_number_noa
Q931: 'Redirecting number' 2nd IE - Type of number
 N/A
 Q763: 'Redirection number' IE - nature of address indicator
 N/A
original_called_number_npi
Q931: 'Redirecting number' 2nd IE - Numbering plan identification
 N/A
 Q763: 'Redirection number' IE - numbering plan indicator
 N/A
original_called_number_presentation
Q931: 'Redirecting number' 2nd IE - Presentation indicator
N/A
 Q763: 'Redirection number' IE - address presentation restricted indicator
 SIP:Diversion (1st header) - diversion-privacy
original_called_number_screening
Q931: 'Redirecting number' 2nd IE - Screening indicator
 N/A
 Q763: 'Redirection number' IE - screening (national)
 SIP:Diversion (1st header) - diversion-screen
original_called_number_reason
Q931: 'Redirecting number' 2nd IE - Reason for redirection
 N/A
 Q763: 'Redirection information' IE - original redirection reason
 SIP:Diversion (1st header) - diversion-reason
original_called_number_counter
N/A
 N/A
 N/A
 SIP:Diversion (1st header) - diversion-counter
ported_number
N/A
 N/A
 Q763: 'Called party number' IE - address signals
 SIP:RequestURI - rn
 Only valid if SIP/SS7 supports LNP
ported_number_noa
N/A
 N/A
 Q763: 'Called party number' IE - nature of address indicator
 N/A
 Only valid if SIP/SS7 supports LNP
ported_number_npi
N/A
 N/A
 Q763: 'Called party number' IE - numbering plan indicator
 N/A
 Only valid if SIP/SS7 supports LNP
oli
5ESS Codeset 6 OLI - Value
 N/A
 ANSI: 'Originating line information' IE - OLI

SIP:From - oli

SIP:P-asserted-identity - oli
request_uri
N/A
 N/A
 N/A
 Complete Request URI string
request_uri_forward_enabled
N/A
 N/A
 N/A
 N/A
 Overwrite default URI forwarding behavior from incoming to outgoing leg
sip_header
 N/A
 N/A
 N/A
 Any header
 Outgoing leg (write) only
nap
 N/A
 N/A
 N/A
 N/A
 Incoming leg NAP name (read-only)


Notice: All values are documented in the noa_npi_remap.rb script and may change between major release.

Noa values

  • unknown_number
  • international_number
  • national_number
  • subscriber_number
  • network_specific
  • network_routing_national_format
  • network_routing_international_format
  • abbreviated_number
  • subscriber_number_operator_requested
  • national_number_operator_requested
  • international_number_operator_requested
  • no_number_present_operator_requested
  • no_number_present_cut_through_call_to_carrier
  • test_line_test_code
  • non_unique_subscriber_number
  • non_unique_national_number
  • non_unique_international_number
  • call_950_number

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

  • unspecified
  • not_available
  • allowed
  • restricted
  • addr_restricted
  • name_restricted

Screening values

  • unspecified
  • no
  • pass
  • fail
  • network_provided

Redirecting number reason values

ISDN:

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

SS7:

  • unknown
  • busy
  • no_reply
  • 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.


redirecting_number_forward_enabled values

Controls forwarding or discarding of redirecting number (SIP: diversion header) to 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 input of 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.


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 values

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 value for this parameter at input of routing script is always false.

Route parameters

All route may have these parameters:

  • calling
  • called
  • nap
  • remapped_calling
  • remapped_called
  • remapped_nap
  • remapped_profile

Additionally it is possible to add dynamic route attributes in the web portal. These can be referenced by their name.

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 or wav files in different states of the call flow, like playing an announcement when the caller dials in. You can also manage the User to User information element.

  • announcement_tone
  • call_progress_tone
  • ring_tone
  • max_call_duration
  • call_duration_reason
  • disconnect_tone
  • uui
  • uui_forward_enabled

The following sections show how to access those different parameters from inside a filter. The 'params' hash is the sole argument passed to a filter function and contains call, nap, route and bridge parameters. This hash is created by the base_routing.rb scripts to regroup all relevant information just before calling the filter functions.

Tone string format

All tone strings (:announcement_tone, :call_progress_tone, :ring_tone, :disconnect_tone) inside bridge parameters are using this format. 

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

optional repeat parameter: number of times to play the file (0 and 1 have the same result)
optional start_off parameter : Start offset in milliseconds
optional end_off parameter: End offset in milliseconds

Example: "file1.wav,file2.wav:-1" will play file1.wav one time and then play file2.wav in loop.
Example: "file1.wav:0:1000:3000,file2.wav:2:5000:10000" will play file1.wav from second 1 to second 3 then file2.wav from second 5 to second 10 two times.
Example: "file1.wav:0:0:30000" will play file1.wav one time for a max duration of 30 seconds.

announcement_tone

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

Prompt played on the incoming leg with the stream_server before any outgoing call is placed. The outgoing call occurs when the wav file is completed or when the "profile:Busy Tone max duration" is reached.

call_progress_tone

params[:bridge][:call_progress_tone] = "no_route.wav"

Prompt played after "announcement_tone" when reason is not "ok" or when outgoing call disconnect before answer state.
"none" value is used to bypass "profile:Generate Busy (Congestion) Tone" and to play no audio prompt.

ring_tone

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

Prompt played between alerting state and answer state. Bypass any other ring back tone (RBT) configured in profile.

max_call_duration

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

Maximum call duration in millisecond for the current bridge. 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.

disconnect_tone

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

Prompt played (on the incoming leg only) when call duration (:max_call_duration) is reached before terminating the leg with call duration reason (:call_duration_reason).

UUI (user-to-user indication) values

Byte array represented as ruby String. Use bridge=params[:bridge], bridge.get(:uui).each_byte to access the data in case the UUI contains non printable character.

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 to outgoing call leg 1/true: UUI is forwarded to outgoing call leg 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.

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:

  • 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:
    • @{DefaultName}: Same file name (without parent folder path) as the one used when empty string is provided
      • 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}: Same path as the one used when empty string is provided
      • Example: "recorded_calls/73EBA698-F3D67B4B-NAP_SS7-IN-5550000-5550001-SS7-TRUNK_BELL_11-24.wav"
      • Example: "recorded_calls/73EBA698-73EBA698-NAP_SIP-OUT-5550000-5550001-SIP-G723-10.3.10.101-1050.wav"
    • @{LinkId}: Current LinkId (Id common between all legs of this call bridge)
      • Example: "73EBA698"
    • @{LegId}: Current LegId (Unique Id for this leg)
      • Example: "F3D67B4B"
    • @{Protocol}: Protocol type of current leg
      • Example: "SS7"
    • @{Direction}: Direction of current leg (IN our OUT)
      • Example: "IN"
    • @{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"
    • @{CURRENT_PKG}: Version of current package
      • Example: "2.6.45"
    • @{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"
    • @{TBX_GW_PORT}: Current "System Id" (also called "Gateway Port")
      • Example: "12358"

Reason values

Check here for Termination Reason Cause codes:

Termination Reason Cause codes

Nap status

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

Notice: These values may change between major release. 

 #define NAP_STATS_FIELDS \
   /* Field,                                 szName,                            szDescription,                                        szOptions */ \
   ( SIGNALING_TYPE,                         "signaling_type",                  "Signaling type.",                                    "" ) \
   ( INCOMING_CALL_CNT,                      "inst_incoming_call_cnt",          "Instantaneous Count of incoming calls.",             "" ) \
   ( OUTGOING_CALL_CNT,                      "inst_outgoing_call_cnt",          "Instantaneous Count of outgoing calls.",             "" ) \
   ( AVAILABLE_CNT,                          "available_cnt",                   "Number of available circuits or channels.",          "" ) \
   ( UNAVAILABLE_CNT,                        "unavailable_cnt",                 "Number of unavailable circuits or channels.",        "" ) \
   ( AVAILABILITY_PCT,                       "availability_percent",            "Percentage of available circuits or channels.",      "" ) \
   ( USAGE_PCT,                              "usage_percent",                   "Percentage of used circuits or channels.",           "" ) \
   ( TOTAL_INCOMING_CALL_CNT,                "total_incoming_call_cnt",         "Total Count of incoming calls.",                     "" ) \
   ( ASR_STRUCT,                             "asr_statistics_struct",           "Detailed Answer-Seizure Rate Statistics.",           "" ) \
     ( GLOBAL_ASR_PCT,                       "global_asr_percent",              "Global calculated ASR percentage.",                  "" ) \
     ( TOTAL_OUTGOING_CALL_CNT,              "total_outgoing_call_cnt",         "Total Count of outgoing calls.",                     "" ) \
     ( LAST_24H_ASR_PCT,                     "last_24h_asr_percent",            "Last 24 hours calculated ASR percentage.",           "" ) \
     ( LAST_24H_OUTGOING_CALL_CNT,           "last_24h_outgoing_call_cnt",      "Last 24 hours outgoing calls.",                      "" ) \
     ( HOUR_ASR_PCT,                         "current_hour_asr_percent",        "Current hour calculated ASR percentage.",            "" ) \
     ( HOUR_OUTGOING_CALL_CNT,               "current_hour_outgoing_call_cnt",  "Current hour outgoing calls.",                       "" ) \
     ( LAST_HOUR_ASR_PCT,                    "last_hour_asr_percent",           "Last hour calculated ASR percentage.",               "" ) \
      ( LAST_HOUR_OUTGOING_CALL_CNT,         "last_hour_outgoing_call_cnt",     "Last hour outgoing calls.",                          "" ) \
   ( AVAILABILITY_DETECTION_STRUCT,          "availability_detection_struct",   "Detailed availibility detection Statistics",         "" ) \
     ( POLL_REMOTE_PROXY,                    "poll_remote_proxy",               "Remote proxy polling enabled",                       "" ) \
     ( IS_AVAILABLE,                         "is_available",                    "Remote proxy actually available or not",             "" ) \
     ( TIME_SINCE_POLLING,                   "time_since_polling",              "Time since the last availibility polling",           "" ) \
     ( TIME_AVAILABLE_SECONDS,               "time_available_seconds",          "Number of seconds since the NAP is available",       "x" ) \
     ( TIME_UNAVAILABLE_SECONDS,             "time_unavailable_seconds",        "Number of seconds since the NAP is unavailable",     "x" ) \
   ( REGISTRATION_STRUCT,                    "registration_struct",             "Detailed registration Statistics",                   "" ) \
     ( REGISTER_TO_PROXY,                    "register_to_proxy",               "Register to proxy enabled",                          "" ) \
     ( IS_REGISTERED,                        "registered",                      "Actually registered or not",                         "" ) \
     ( TIME_SINCE_REFRESH,                   "time_since_refresh",              "Time since the last refresh",                        "" ) \
     ( TIME_REGISTERED_SECONDS,              "time_registered_seconds",         "Number of seconds since the NAP is registered",      "x" ) \
     ( TIME_NOT_REGISTERED_SECONDS,          "time_not_registered_seconds",     "Number of seconds since the NAP is not registered",  "x" ) \
   /*!< Nap Status Fields */


If the nap status is part of a substructure, it's name in the routing scripts must be composed of the structure name appended by an underscore and the field name.

For example the name to use for the global ASR percentage is: 

 asr_statistics_struct_global_asr_percent


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

Test parameters

@call_params

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


@nap_list

A list of 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.

Example: @params = {:bridge => {:announcement_tone, "announcement.wav"}}



Back to Routing Script Tutorial.

Retrieved from "https://docs.telcobridges.com/mediawiki/index.php?title=Routing_script_tutorial:Mini_Development_Guide&oldid=11843"
Personal tools