Routing script tutorial:Mini Development Guide

From TBwiki

(Difference between revisions)

Revision as of 20:59, 23 January 2012

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 takes 2 arguments, the call parameters (hash) and the route parameters (hash).

Apply route remapping rules

 caf_call.accept out_call, route

Refuse

This function is used to refuse a call with a reason code argument parameters :

 caf_call.refuse :reason => :temporary_failure

The supported values are described in the section "Reason values".

The following call parameters are available in the call object:

Script parameter name	ISDN	R2 CAS	SS7	SIP	Comment
calling		ANI (Group B)		SIP:From user-info
calling_noa		N/A		N/A
calling_npi		N/A		N/A
calling_display		N/A		SIP:From name-addr
calling_display_type		N/A		N/A
calling_presentation		N/A		SIP:From name-addr (displays 'anonymous' or not)
calling_screening		N/A		N/A
calling_category		Call party category (Group A)		SIP:From cpc
private_display		N/A		SIP:p-asserted-identity user-info
private_display_type		N/A		N/A
private_address		N/A		SIP:p-asserted-identity name-addr
called		DNIS (Group A)		SIP:To name-addr
called_noa		N/A		N/A
called_npi		N/A		N/A
charge_number		N/A		N/A
charge_number_noa		N/A		N/A
charge_number_npi		N/A		N/A
redirecting_number_forward_enabled	N/A	N/A	N/A	N/A	Overwrite default redirecting number forwarding from incoming to outgoing leg
redirecting_number		N/A		SIP:Diversion (2nd header) name-addr
redirecting_number_noa		N/A		N/A
redirecting_number_npi		N/A		N/A
redirecting_number_presentation		N/A		SIP:Diversion (2nd header) diversion-privacy
redirecting_number_screening		N/A		SIP:Diversion (2nd header) diversion-screen
redirecting_number_reason		N/A		SIP:Diversion (2nd header) diversion-reason
redirecting_number_counter		N/A		SIP:Diversion (2nd header) diversion-counter
original_called_number		N/A		SIP:Diversion (1st header) name-addr
original_called_number_noa		N/A		N/A
original_called_number_npi		N/A		N/A
original_called_number_presentation		N/A		SIP:Diversion (1st header) diversion-privacy
original_called_number_screening		N/A		SIP:Diversion (1st header) diversion-screen
original_called_number_reason		N/A		SIP:Diversion (1st header) diversion-reason
original_called_number_counter		N/A		SIP:Diversion (1st header) diversion-counter
ported_number		N/A		SIP:To rn
ported_number_noa		N/A		N/A
ported_number_npi		N/A		N/A
oli		N/A		SIP:From 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 from incoming to outgoing leg
any 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.

Bridge parameters

New feature in release 2.6, all bridges may have these parameters:

announcement_tone
call_progress_tone
ring_tone
max_call_duration
call_duration_reason
disconnect_tone
uui
uui_forward_enabled

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

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.

@@ Line 44: / Line 44: @@
 | calling<br>
 | <br>
-| <br>
+| ANI (Group B)<br>
 | <br>
 | SIP:From&nbsp; user-info<br>
@@ Line 51: / Line 51: @@
 | calling_noa<br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | N/A<br>
@@ Line 58: / Line 58: @@
 | calling_npi <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | N/A<br>
@@ Line 65: / Line 65: @@
 | calling_display <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | SIP:From&nbsp; name-addr<br>
@@ Line 72: / Line 72: @@
 | calling_display_type<br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | N/A<br>
@@ Line 79: / Line 79: @@
 | calling_presentation <br>
 | <br>
+| N/A<br>
 | <br>
-| <br>
+| SIP:From name-addr (displays 'anonymous' or not)<br>
-| N/A<br>
 | <br>
 |-
 | calling_screening<br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | N/A<br>
@@ Line 93: / Line 93: @@
 | calling_category<br>
 | <br>
-| <br>
+| Call party category (Group A)<br>
 | <br>
 | SIP:From cpc<br>
@@ Line 100: / Line 100: @@
 | private_display<br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | SIP:p-asserted-identity&nbsp; user-info<br>
@@ Line 107: / Line 107: @@
 | private_display_type <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | N/A<br>
@@ Line 114: / Line 114: @@
 | private_address<br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | SIP:p-asserted-identity name-addr <br>
@@ Line 121: / Line 121: @@
 | called <br>
 | <br>
-| <br>
+| DNIS (Group A)<br>
 | <br>
 | SIP:To&nbsp; name-addr<br>
@@ Line 128: / Line 128: @@
 | called_noa <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | N/A<br>
@@ Line 135: / Line 135: @@
 | called_npi <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | N/A<br>
@@ Line 142: / Line 142: @@
 | charge_number<br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | N/A<br>
@@ Line 149: / Line 149: @@
 | charge_number_noa <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | N/A<br>
@@ Line 156: / Line 156: @@
 | charge_number_npi<br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | N/A<br>
@@ Line 162: / Line 162: @@
 |-
 | redirecting_number_forward_enabled <br>
-| <br>
+| N/A<br>
-| <br>
+| N/A<br>
-| <br>
+| N/A<br>
 | N/A<br>
 | Overwrite default redirecting number forwarding from incoming to outgoing leg <br>
@@ Line 170: / Line 170: @@
 | redirecting_number <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | SIP:Diversion (2nd header)&nbsp; name-addr<br>
@@ Line 177: / Line 177: @@
 | redirecting_number_noa <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | N/A<br>
@@ Line 184: / Line 184: @@
 | redirecting_number_npi <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | N/A<br>
@@ Line 191: / Line 191: @@
 | redirecting_number_presentation <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | SIP:Diversion&nbsp;(2nd header) diversion-privacy<br>
@@ Line 198: / Line 198: @@
 | redirecting_number_screening <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | SIP:Diversion (2nd header)&nbsp; diversion-screen<br>
@@ Line 205: / Line 205: @@
 | redirecting_number_reason <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | SIP:Diversion (2nd header)&nbsp; diversion-reason<br>
@@ Line 212: / Line 212: @@
 | redirecting_number_counter <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | SIP:Diversion (2nd header) diversion-counter<br>
@@ Line 219: / Line 219: @@
 | original_called_number <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | SIP:Diversion&nbsp; (1st header)&nbsp; name-addr<br>
@@ Line 226: / Line 226: @@
 | original_called_number_noa <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | N/A<br>
@@ Line 233: / Line 233: @@
 | original_called_number_npi <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | N/A<br>
@@ Line 240: / Line 240: @@
 | original_called_number_presentation <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | SIP:Diversion (1st header) diversion-privacy<br>
@@ Line 247: / Line 247: @@
 | original_called_number_screening <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | SIP:Diversion (1st header) diversion-screen<br>
@@ Line 254: / Line 254: @@
 | original_called_number_reason <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | SIP:Diversion (1st header) diversion-reason<br>
@@ Line 261: / Line 261: @@
 | original_called_number_counter <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | SIP:Diversion (1st header) diversion-counter<br>
@@ Line 268: / Line 268: @@
 | ported_number <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
-| <br>
+| SIP:To&nbsp; rn<br>
 | <br>
 |-
 | ported_number_noa <br>
 | <br>
+| N/A<br>
 | <br>
-| <br>
+| N/A<br>
-| <br>
 | <br>
 |-
 | ported_number_npi <br>
 | <br>
+| N/A<br>
 | <br>
-| <br>
+| N/A<br>
-| <br>
-| <br>
-|-
-| nap <br>
-| <br>
-| <br>
-| <br>
-| <br>
 | <br>
 |-
 | oli <br>
 | <br>
-| <br>
+| N/A<br>
 | <br>
 | SIP:From oli<br>
@@ Line 321: / Line 314: @@
 | Any header<br>
 | Outgoing leg (write) only<br>
+|-
+| nap<br>
+| N/A<br>
+| N/A<br>
+| N/A<br>
+| N/A<br>
+| Incoming leg NAP name (read-only)<br>
 |}