TBwiki - User contributions [en]

Toolpack: How to Use RegEx in Remapped Called and Calling Number Mask

2018-07-05T21:06:08Z

Lucas Joyal: Add a SIP specific matching section to discuss new matching and remapping feature.

== Regular Expressions ==
A regular expression is a sequence of characters that forms a search and replace pattern. This is useful to modify the called or calling number digit strings. The version used in the TelcoBridges units is based on PERL regular expression.

== The Rule ==
The remapped called number mask or remapped calling number mask must have 2 regular expressions, and it must be in the form of '/regexWithCapturingGroup/replaceString/'. In the first regular expression, you specify capturing groups using parentheses (...) while in the second regular expression, you specify how to remap the number by referencing the capturing group using \1, \2, etc.

Please refer to [[Toolpack: Commonly Used Regular Expression Pattern|Commonly Used Regular Expression Pattern]] for the patterns usually used.

=== Example 1 ===
If you need to match a called number starts with the digits 450 and then 7 other digits, please put this in the called number mask:

/^450[0-9]{7}$/

^ means the matching is done from the beginning of the number. 
$ means the matching is done to the end of then number. 
450 is the exact prefix to match. 
[0-9]{7} means there should be 7 occurrences of the digits 0 to 9. [1-9]{7} would mean 7 digits, excluding 0.

=== Example 2 ===
In this example, we have to match a called number starts with optional 1, then digits 450 and then 7 other digits.

/^1?450[0-9]{7}$/

? means the preceding pattern, i.e. the digit '1', is optional.

=== Example 3 ===
In this example, we have to match a called number with 4 possible prefixes followed by 7 other digits.

/^(800|888|877|866)[0-9]{7}/

In this example, we have 2 independent regular expression. The first one match prefix '800' with 7 digits, second match prefix '88' with 8 digits.

/^800[0-9]{7}$|^88[0-9]{8}$/

The | (pipe character) means "or"

=== Example 4 ===
In this example, we have to match a called number with a prefix followed by 6 to 11 digits.

/^880([0-9]{6,11})$/

=== Example 5 ===
In this example, we want to match any digit string that doesn't start with 080.

/^(?!080)([0-9]*)$/
The ?! is the not operator (everything except this)

=== Example 6 ===
In the remapped called number mask, the following is specified:

/^(1?)450([0-9]{7})$/\1514\2/

The first regular expression is '^(1?)450([0-9]{7})$'. There are 2 capturing groups. The first one is '(1?)', the optional digit '1'. The second one is '([0-9]{7})', the 7 digits following '450'.

The second regular expression is '\1514\2' which specifies how the remapped number is composed.
In this example, let us suppose that the incoming call has the called number as '15141234567'. The digit '1' in the beginning matches the first capturing group '(1?)' and the digits '1234567' match the second capturing group '([0-9]{7})'. Therefore, the remapped called number would be '1' followed by '514' followed by '1234567', that is '15141234567'.

=== Example 7 ===
This is a simpler example in which the remapped called number mask would remove the prefix '852' while keeping the 8 digits following the prefix.

/^852([0-9]{8})$/\1/
First group between parenthesis are the 8 digits after the 852. The output number will be the 8 digits after 852 (represented by the first group "\1" used in the seconds section of the regex)

== SIP specific matching ==

=== Matching the complete SIP address ===
When matching a field like 'called', 'calling' or 'private_address' for a SIP call, extra parameters are available.

A typical SIP address is formatted like so: user@host[:port], with the port section optional.

When applying the regex, we first try the `user` substring first, then we try to match the whole SIP address.

For example, consider a route with the following regex:

/alice@telcobridge.com/

It will only match if both the user is 'alice' and the domain is 'telcobridge.com'

=== Remapping the complete SIP address ===
In a similar way, we can apply a '/regexWithCapturingGroup/replaceString/' regex to cover the complete SIP address. Just as in the matching section, we try to apply the regex on the 'user' string first, then in case of failure we try with the complete SIP address.

The resulting remapping must be in the 'user@host[:port]' format, since the replacing string is taken apart to fill each parameter.

== Related Links ==
*[[Toolpack: Commonly Used Regular Expression Pattern|Commonly Used Regular Expression Pattern]]
*[http://www.cs.tut.fi/~jkorpela/perl/regexp.html Regular expressions in Perl]

== Caution ==

It is recommended to use ^ and $ to specify the matching of beginning and end of the number if it is appropriate so as to avoid ambiguity in matching.
For example, if you specify the mask as /450[0-9]{7}/, the following numbers would match this mask and that may not be desirable.
*864501234567 (the later part of the number matches the mask)
*4501234567890 (more than 7 digits after '450' is still a match)

Routing script tutorial:Mini Development Guide

2018-07-03T19:26:19Z

Lucas Joyal: /* Script parameters protocol mapping */ Add link pointing to How_to_Use_RegEx_in_Remapped_Called_and_Calling_Number_Mask

== 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 "[[Routing_script_tutorial:Mini_Development_Guide#Reason_values|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 [[Toolpack:_How_to_Use_RegEx_in_Remapped_Called_and_Calling_Number_Mask | How to use regex in Remapped Called and Calling Number Mask]]

{| cellspacing="1" cellpadding="1" border="1" style="width: 921px; height: 805px;"
|-
! scope="col" | '''Script parameter name'''
! scope="col" | '''ISDN '''
! scope="col" | '''R2 CAS''' 
! scope="col" | '''SS7 '''
! scope="col" | '''SIP '''
! scope="col" | '''Comment '''
! scope="col" | '''Toolpack version '''
|-
| leg_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Leg ID 
| 
|-
| session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Session ID 
| 
|-
| 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_sip_host 
| N/A 
| N/A 
| N/A 
| SIP:From - host (domain or IP) 
| For example : The 'telcobridges.com' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| calling_sip_port 
| N/A 
| N/A 
| N/A 
| SIP:From - port 
| For example : The '6060' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| 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 
Q931: 'Facility CNAM' IE when presentation is allowed for DMS/NI2 variants 
| N/A 
| Q763
ITU97: 'Display information' IE - display information
ANSI95: 'Generic name' 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 

| 
| 
|-
| calling_subscriber
(Generic Number / NDS) 
| Q931: 2nd 'Calling party number' IE - Number digits 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - Number digits 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| Requires option 'support 2 calling number IE' in the profile. This variable has priority over 'private_address' in the outgoing direction. 
| 
|-
| calling_subscriber_noa 
| Q931: 2nd 'Calling party number' IE - Type of number 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - nature of address indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_npi 
| Q931: 2nd 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - numbering plan indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
 
| 
|-
| calling_subscriber_presentation 
| Q931: 2nd 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - presentation restricted indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_screening 
| Q931: 2nd 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - screening 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| private_display 
| Q931: 'Facility CNAM' IE when presentation is restricted for DMS/NI2 variants 
| 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 

| For example : The 'fluffy' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_sip_host 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - host (domain or IP)

SIP:Remote-party-id - host (domain or IP) 

| For example : The 'telcobridges.com' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_sip_port 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - port

SIP:Remote-party-id - port 

| For example : The '6060' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| 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_sip_host 
| N/A 
| N/A 
| N/A 
| SIP:To - host 
| For example : The 'telcobridges.com' in To: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| called_sip_port 
| N/A 
| N/A 
| N/A 
| SIP:To - port number 
| For example : The '6060' in To: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| 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 and original called 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_indicator 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirecting indicator 
| N/A 
| 
| 
|-
| 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
(OCN) 
| 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_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_npdi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - with qualifier=Ported number is present 
| SIP:RequestURI - npdi=yes is present 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number 
| N/A 
| N/A 
| Q763: 'Generic number' IE - address signals with qualifier=Ported number 
| SIP:RequestURI - to user part when rn is present 
| rn is stored in the called number 
| 
|-
| ported_number_noa 
| N/A 
| N/A 
| Q763: 'Generic number' IE - nature of address indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number_npi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - numbering plan indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| oli
(Originating line information) 
| 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 
| Requires option 'Forward custom headers' in Profiles->SIP 
| 2.7.63 
|-
| nap
(Network Access Point) 
| N/A 
| N/A 
| N/A 
| N/A 
| Incoming leg NAP name (read-only) 
| 
|-
| type_of_network_identification 
| Q931: 'Transit network selection' IE - Type of network identification 
| N/A 
| Q763: 'Transit network selection' IE - Type of network identification 
| N/A 
| 
| 2.7 
|-
| network_identification 
| Q931: 'Transit network selection' IE - Network identification 
| N/A 
| Q763: 'Transit network selection' IE - Network identification 
| SIP: Request-Line - cic 
| 
| 2.7 
|-
| network_identification_plan 
| Q931: 'Transit network selection' IE - Network identification plan 
| N/A 
| Q763: 'Transit network selection' IE - Network identification plan 
| N/A 
| 
| 2.7 
|-
| location_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default location number forwarding behavior from incoming to outgoing leg 
| 2.7 
|-
| location_number 
| N/A 
| N/A 
| Q763: 'Location number' IE - address signals 
| N/A 
| 
| 2.7 
|-
| location_number_noa 
| N/A 
| N/A 
| Q763: 'Location number' IE - nature of address indicator 
| N/A 
| 
| 2.7 
|-
| location_number_npi 
| N/A 
| N/A 
| Q763: 'Location number' IE - numbering plan indicator 
| N/A 
| 
| 2.7 
|-
| location_number_presentation 
| N/A 
| N/A 
| Q763: 'Location number' IE - presentation restricted indicator 
| N/A 
| 
| 2.7 
|-
| location_number_screening 
| N/A 
| N/A 
| Q763: 'Location number' IE - screening 
| N/A 
| 
| 2.7 
|-
| mlpp_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| A script needs to set this to true if it wants to overwrite MLPP information in the outgoing leg. Otherwise, profile relay 'outgoing mode' applies automatically. 
| 2.7 
|-
| mlpp_look_for_busy 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - look ahead for busy 
| N/A 
| 
| 2.7 
|-
| mlpp_precedence_level 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - precedence level 
| SIP:Resource-Priority - q735 
| 
| 2.7 
|-
| mlpp_network_identity 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - network identity 
| N/A 
| 
| 2.7 
|-
| mlpp_service_domain 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - MLPP service domain 
| N/A 
| 
| 2.7 
|-
| called_isub 
| Q931: 'Called party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub parameter 
| 
| 2.7 
|-
| called_isub_type 
| Q931: 'Called party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub-encoding parameter 
| 
| 2.7 
|-
| calling_isub 
| Q931: 'Calling party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub 
| 
| 2.7 
|-
| calling_isub_type 
| Q931: 'Callinf party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub-encoding 
| 
| 2.7 
|-
| ss7_fci_default 
| N/A 
| N/A 
| Default forward call indicator (FCI) value. 
| N/A 
| Toolpack will overwrite FCI bits A, D, F, I and M with appropriate values according to call conditions 
| 2.7 
|-
| ss7_fci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_fci_default that must be forced. 
| N/A 
| Bits from ss7_fci_default which corresponding bit in ss7_fci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| ss7_bci_default 
| N/A 
| N/A 
| Default backward call indicator (BCI) value. 
| N/A 
| Toolpack will overwrite BCI bits AB, I, K, M and N with appropriate values according to call conditions 
| 2.7 
|-
| ss7_bci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_bci_default that must be forced. 
| N/A 
| Bits from ss7_bci_default which corresponding bit in ss7_bci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| tdm_ls_name_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable line service and timeslot selection to create the outgoing leg 
| 3.0 
|-
| tdm_ls_name
(Line Service or T1/E1 trunk) 
| Incoming leg line service name 
| Incoming leg line service name 
| Incoming leg line service name 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this line service name to create outgoing leg 
| 2.7 
|-
| tdm_timeslot_nb 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this timeslot number to create outgoing leg 
| 2.7 
|-
| rtp_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP port 
| (read-only) 
| 2.7 
|-
| rtp_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP port 
| (read-only) 
| 2.7 
|-
| ss7_cot_enabled 
| N/A 
| N/A 
| Requests SS7 in-call continuity test for this outgoing SS7 call 
| N/A 
| Toolpack will request a continuity test on the timeslot before making the outgoing call. If COT fails, the call will be dropped (then another route may be attempted) 
| 2.8 
|-
| reverse_charging_indication 
| Incoming leg Reverse charging indication IE present 
| N/A 
| N/A 
| N/A 
| If set in routing script, will add Reverse charging indication IE in outgoing leg (also use reverse_charging_indication_forward_enabled) 
| 2.8.12 
|-
| reverse_charging_indication_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable forwarding of reverse charging indication from incoming to outgoing leg 
| 2.8.12 
|-
| sip_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP UDP port 
| (read-only) 
| 2.8.13 
|-
| sip_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP UDP port 
| (read-only) 
| 2.8.13 
|}

 

=== Noa values ===

*<tt>unknown_number (0x2)</tt>
*<tt>international_number (0x4)</tt>
*<tt>national_number (0x3)</tt>
*<tt>subscriber_number (0x1)</tt>
*<tt>network_specific (0x5)</tt>
*<tt>network_routing_national_format (0x7)</tt>
*<tt>network_routing_international_format (0x8)</tt>
*<tt>abbreviated_number (0x6)</tt>
*<tt>subscriber_number_operator_requested (0x71)</tt>
*<tt>national_number_operator_requested (0x72)</tt>
*<tt>international_number_operator_requested (0x73)</tt>
*<tt>no_number_present_operator_requested (0x74)</tt>
*<tt>no_number_present_cut_through_call_to_carrier (0x75)</tt>
*<tt>test_line_test_code (0x77)</tt>
*<tt>non_unique_subscriber_number (0x71)</tt>
*<tt>non_unique_national_number (0x73)</tt>
*<tt>non_unique_international_number (0x74)</tt>
*<tt>call_950_numbe (0x76)</tt>
*<tt>special_number (0x73)</tt>
*<tt>national_number_with_transit_network_selection (0x74)</tt>
*<tt>international_number_with_transit_network_selection (0x75)</tt>

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

*<tt>call_params[:called_noa] = 0x70</tt>

or

*<tt>call_params[:called_noa] = 112</tt>

=== Npi values ===

*<tt>unknown_number</tt>
*<tt>isdn</tt>
*<tt>telephony</tt>
*<tt>private</tt>
*<tt>data</tt>
*<tt>telex</tt>
*<tt>national</tt>

=== Calling Display Type values ===

*<tt>unspecified</tt> => Type is unspecified.
*<tt>calling_party_name</tt> => Type is 0xB1.

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

*<tt>call_params[:calling_display_type] = 0xB1</tt>

or

*<tt>call_params[:calling_display_type] = 177</tt>

=== Calling Display value ===

*<tt>call_params[:calling_display] = "Roger Fluffy"</tt>

=== Presentation values for Calling number, Calling Subscriber (Generic Number), Redirecting Number, Original Called Number (OCN) and Location Number ===

*<tt>unspecified</tt>
*<tt>not_available (0x2)</tt>
*<tt>allowed (0x0)</tt>
*<tt>restricted (0x1)</tt>
*<tt>addr_restricted</tt>
*<tt>name_restricted</tt>

=== Calling Party Category ===
values for calling_category
*<tt>unspecified</tt> <tt>(0xa)</tt>
*<tt>unknown</tt> <tt>(0x0)</tt>
*<tt>operator_french</tt> <tt>(0x1)</tt>
*<tt>operator_english</tt> <tt>(0x2)</tt>
*<tt>operator_german</tt> <tt>(0x3)</tt>
*<tt>operator_russian</tt> <tt>(0x4)</tt>
*<tt>operator_spanish</tt> <tt>(0x5)</tt>
*<tt>subscriber</tt> <tt>(0xa)</tt>
*<tt>subscriber_with_priority</tt> <tt>(0xb)</tt>
*<tt>data</tt> <tt>(0xc)</tt>
*<tt>test</tt> <tt>(0xd)</tt>
*<tt>payphone</tt> <tt>(0xf)</tt>

=== Screening values for Calling number, Calling Subscriber (Generic Number), and Location Number ===

*<tt>unspecified</tt>
*<tt>no (0x0)</tt>
*<tt>pass (0x1)</tt>
*<tt>fail (0x2)</tt>
*<tt>network_provided (0x3)</tt>

=== Redirecting indicator values ===

SS7:

*<tt>no_redirection</tt>
*<tt>call_rerouted</tt>
*<tt>call_rerouted_all_restricted</tt>
*<tt>call_diverted</tt>
*<tt>call_diverted_all_restricted</tt>
*<tt>call_rerouted_restricted</tt>
*<tt>call_diverted_restricted</tt>
*<tt>spare</tt>

=== Redirecting number, Original Called Number and Diversion Reason ===

ISDN:

*<tt>unknown</tt>
*<tt>busy</tt>
*<tt>no_reply</tt>
*<tt>deflection</tt>
*<tt>dte_out_of_order</tt>
*<tt>forwarding_by_called_dte</tt>
*<tt>unconditional</tt>

SS7:

*<tt>unknown</tt>
*<tt>busy (SIP: user-busy)</tt>
*<tt>no_reply (SIP: no-answer)</tt>
*<tt>unconditional</tt>
*<tt>deflection</tt>
*<tt>deflection_immediate</tt>
*<tt>mobile_not_reachable</tt>

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

*<tt>digital</tt>
*<tt>restricted_digital</tt>
*<tt>digital_with_tones</tt>
*<tt>speech</tt>
*<tt>3_1_khz_audio</tt>
*<tt>video</tt>

=== 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:
<pre>Request-Line: INVITE sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0</pre>
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: 
<pre> if call_params[:request_uri] && call_params[:request_uri] =~ /sip:(.*)@.*/
call_params[:called] = $1
end
</pre>
=== 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. 

=== 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 hash format for a releases older than rel2.7.161.

It has been changed to string format because using a hash does not allow having multiple times the same header for certain releases of rel2.8 and rel2.9

Beginning from rel2.10.21, both hash and string format are supported to construct the outgoing SIP header; however, only string format is used for the incoming SIP header.

'''hash format:'''
<pre>call[ :sip_header ] = {"P-my-custom-header"=>"value1", "P-my-custom-header2"=>"value2", "P-my-custom-header3"=>"value3"}</pre>

'''string format:'''
<pre>call[ :sip_header ] = "P-my-custom-header:value1 \nP-my-custom-header2:value2 \nP-my-custom-header3:value3"
</pre>
(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:
<pre>
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
</pre>

=== sip uri parameters ===
Access to parameters of several SIP headers (To, From, P-Asserted-Identity, Remote-Party-ID, Contact).

<pre>
call[ :calling_parameters ]
call[ :called_parameters ]
call[ :private_address_parameters ] (for P-Asserted-Identity or Remote-Party-ID)
call[ :contact_parameters ]
</pre>

These parameters (if present) contain a hash with 3 keys: user_param, uri_param and header_param.
If a parameter already has a specific field (oli, isub, cpc, transport), it won't be present in the new generic structure.

By default, the parameters are not forwarded in a SIP to SIP call flow. The parameters '''will be forwarded''' only if:
* accessed (read) from either the inbound or outbound call parameters
* written in either the inbound or outbound call parameters

Using this code in routing script:
<pre>
puts "calling_param = #{ call[ :calling_parameters].inspect}"
</pre>

Example, From header format and what you will see in call[ :calling_parameters]:
<pre>
From:"test"<sip:4440000;user_param1=1;user_param2@10.3.10.217;uri_param3=3>;header_param4=4;tag=6F97303034343030002A2484
calling_param = {"user_param"=>"user_param1=1;user_param2", "uri_param"=>"uri_param3=3", "header_param"=>"header_param4=4"}
</pre>

'''Note''' that printing the inbound or outbound call parameters is considered as a "read" action and would result in forwarding the parameter on the outbound leg.

<pre>
From:"test"<sip:4440000@10.3.10.217;user=phone>;tag=6F97303034343030002A2484
calling_param = {"uri_param"=>"user=phone"}
</pre>

Example to insert outgoing parameters and overwrite received values.
<pre>
call [:calling_parameters] = {"user_param"=>"user_param7=7;user_param8", "uri_param"=>"uri_param9=9", "header_param"=>"header_paramA=A"}
</pre>

Example to add user=phone and keep all other uri parameters.
<pre>
if call [:calling_parameters]
if call [:calling_parameters]["uri_param"]
call[:calling_parameters]["uri_param"] << ";user=phone"
else
call [:calling_parameters]["uri_param"] = "user=phone"
end
else
call [:calling_parameters] = {"uri_param"=>"user=phone"}
end
</pre>

=== MLPP Precedence values ===

mlpp_look_for_busy:

*<tt>allowed</tt>
*<tt>path_reserved</tt>
*<tt>not_allowed</tt>

mlpp_precedence_level:

*<tt>flash_override</tt>
*<tt>flash</tt>
*<tt>immediate</tt>
*<tt>priority</tt>
*<tt>routine</tt>

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:

*<tt>nsap</tt>
*<tt>nsap_ia5</tt>
*<tt>nsap_bcd</tt>
*<tt>user</tt>

called_isub:
calling_isub:

Digits for the subaddress information.

=== Network Identification Plan ===

network_identification_plan:

*<tt>Unknown</tt> (value 0)
*<tt>cic</tt> (3 digits carrier identification code plus circuit code, value 1, SS7 or ISDN)
*<tt>user</tt> (User, value 2, ISDN only)
*<tt>cic4</tt> (4 digits carrier identification code plus circuit code, value 2, SS7 only)
*<tt>dnic</tt> (public Data Network ID, value 3, SS7 only)
*<tt>mnic</tt> (public land mobile network, value 6, SS7 only)

== 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 ==
Static routes normally chose an outbound NAP to forward the call to.

But it's also possible to create routes which outbound NAP is dynamically chosen by matching a registered user (when using [[Sip_registration_forwarding|SIP registration forwarding]]).

More information can be found [[Sip_registration_forwarding#SIP_Calls_routing|here]] about the way to control the [[Sip_registration_forwarding#SIP_Calls_routing|priority of "dynamic" vs "static" routes]].

== 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.
<pre>"file1.wav:repeat:start_off:end_off,file2.wav:repeat:start_off:end_off,file3.wav:repeat:start_off:end_off"
</pre>
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: [[Customer_application_framework:play_audio_files#Play_path_format|Path format]]

==== Example 1 ====
The following example will play file1.wav once, and then play file2.wav in loop:
"file1.wav,file2.wav:-1"

==== Example 2 ====
The following example will play file1.wav from start offset of 1 second to end offset of 3 seconds, then twice file2.wav 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 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 apply when params[:bridge][:ring_tone] is not used, because it also apply 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:
[[Toolpack:Configuring_Audio_Prompts_A|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: [[Customer_application_framework:play_audio_files#Helpful_variables_to_build_play_or_record_file_paths|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 [[#Refuse|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.

== 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 [[Routing_script_tutorial:Mini_Development_Guide#Redirecting_number,_Original_Called_Number_and_Diversion_Reason|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"
}

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

To get more information, see:
*[[Routing_script_tutorial:SIP_Redirection_Contacts|SIP Redirection Contacts Parameters in a Call Flow]]

== Connected number ==
Insert a connected number in the answer message of the call flow.

<code> 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</code>

== Terminating calls ==
In release 2.8, it is now possible to terminate a call through the routing scripts. The [[#Reason values|reason code]] must be specified in <code>params[:bridge][:reason]</code>. The <code>:terminate</code> hash must be created and copied into <code>params</code>:
terminate = {}
params[:terminate] = terminate
The following fields can then be set in <code>:terminate</code>:
* <code>:sip_header</code>
* <code>:contacts</code> # list of contacts as described in the [[#Redirection|redirection]] section
* <code>:isup_raw</code>
* <code>:isup_raw_variant</code>
* <code>:redirecting_number</code>
* <code>:redirecting_number_noa</code>
* <code>:redirecting_number_npi</code>
* <code>:redirecting_number_presentation</code>
* <code>:redirecting_number_reason</code>
* <code>:redirecting_number_counter</code>
* <code>:redirecting_number_indicator</code>
* <code>:original_called_number</code>
* <code>:original_called_number_noa</code>
* <code>:original_called_number_npi</code>
* <code>:original_called_number_presentation</code>
* <code>:original_called_number_reason</code>
* <code>:original_called_number_counter</code>

== Reason values ==

Check here for Termination Reason Cause codes: 

[[Termination_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 ==

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.

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

 If the nap status is part of a substructure, the substructure will be a hash containing all subfield elements.

Example to access the signaling type and the number of incoming call count for the NAP of the current call:

incoming_nap = params[:naps][ params[:call][ :nap ].to_sym]
log_trace 4,"Incoming NAP parameters=" + incoming_nap.inspect
log_trace 4,"Incoming NAP signaling type=" + incoming_nap[:signaling_type].inspect
log_trace 4,"Incoming NAP call cnt=" + incoming_nap[:asr_stats_incoming_struct][:total_call_cnt].inspect

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

== 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 time 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|Routing Script Tutorial]].

Routing script tutorial:Mini Development Guide

2018-07-03T19:17:17Z

Lucas Joyal: /* Script parameters protocol mapping */ Corrected the parameters name (*_sip_host instead of *_host)

== 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 "[[Routing_script_tutorial:Mini_Development_Guide#Reason_values|Reason values]]".

=== Script parameters protocol mapping ===

The following call parameters are available in the call object. For example:

called_number = call[:called]

{| cellspacing="1" cellpadding="1" border="1" style="width: 921px; height: 805px;"
|-
! scope="col" | '''Script parameter name'''
! scope="col" | '''ISDN '''
! scope="col" | '''R2 CAS''' 
! scope="col" | '''SS7 '''
! scope="col" | '''SIP '''
! scope="col" | '''Comment '''
! scope="col" | '''Toolpack version '''
|-
| leg_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Leg ID 
| 
|-
| session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Session ID 
| 
|-
| 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_sip_host 
| N/A 
| N/A 
| N/A 
| SIP:From - host (domain or IP) 
| For example : The 'telcobridges.com' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| calling_sip_port 
| N/A 
| N/A 
| N/A 
| SIP:From - port 
| For example : The '6060' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| 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 
Q931: 'Facility CNAM' IE when presentation is allowed for DMS/NI2 variants 
| N/A 
| Q763
ITU97: 'Display information' IE - display information
ANSI95: 'Generic name' 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 

| 
| 
|-
| calling_subscriber
(Generic Number / NDS) 
| Q931: 2nd 'Calling party number' IE - Number digits 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - Number digits 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| Requires option 'support 2 calling number IE' in the profile. This variable has priority over 'private_address' in the outgoing direction. 
| 
|-
| calling_subscriber_noa 
| Q931: 2nd 'Calling party number' IE - Type of number 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - nature of address indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_npi 
| Q931: 2nd 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - numbering plan indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
 
| 
|-
| calling_subscriber_presentation 
| Q931: 2nd 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - presentation restricted indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_screening 
| Q931: 2nd 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - screening 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| private_display 
| Q931: 'Facility CNAM' IE when presentation is restricted for DMS/NI2 variants 
| 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 

| For example : The 'fluffy' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_sip_host 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - host (domain or IP)

SIP:Remote-party-id - host (domain or IP) 

| For example : The 'telcobridges.com' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_sip_port 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - port

SIP:Remote-party-id - port 

| For example : The '6060' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| 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_sip_host 
| N/A 
| N/A 
| N/A 
| SIP:To - host 
| For example : The 'telcobridges.com' in To: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| called_sip_port 
| N/A 
| N/A 
| N/A 
| SIP:To - port number 
| For example : The '6060' in To: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| 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 and original called 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_indicator 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirecting indicator 
| N/A 
| 
| 
|-
| 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
(OCN) 
| 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_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_npdi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - with qualifier=Ported number is present 
| SIP:RequestURI - npdi=yes is present 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number 
| N/A 
| N/A 
| Q763: 'Generic number' IE - address signals with qualifier=Ported number 
| SIP:RequestURI - to user part when rn is present 
| rn is stored in the called number 
| 
|-
| ported_number_noa 
| N/A 
| N/A 
| Q763: 'Generic number' IE - nature of address indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number_npi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - numbering plan indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| oli
(Originating line information) 
| 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 
| Requires option 'Forward custom headers' in Profiles->SIP 
| 2.7.63 
|-
| nap
(Network Access Point) 
| N/A 
| N/A 
| N/A 
| N/A 
| Incoming leg NAP name (read-only) 
| 
|-
| type_of_network_identification 
| Q931: 'Transit network selection' IE - Type of network identification 
| N/A 
| Q763: 'Transit network selection' IE - Type of network identification 
| N/A 
| 
| 2.7 
|-
| network_identification 
| Q931: 'Transit network selection' IE - Network identification 
| N/A 
| Q763: 'Transit network selection' IE - Network identification 
| SIP: Request-Line - cic 
| 
| 2.7 
|-
| network_identification_plan 
| Q931: 'Transit network selection' IE - Network identification plan 
| N/A 
| Q763: 'Transit network selection' IE - Network identification plan 
| N/A 
| 
| 2.7 
|-
| location_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default location number forwarding behavior from incoming to outgoing leg 
| 2.7 
|-
| location_number 
| N/A 
| N/A 
| Q763: 'Location number' IE - address signals 
| N/A 
| 
| 2.7 
|-
| location_number_noa 
| N/A 
| N/A 
| Q763: 'Location number' IE - nature of address indicator 
| N/A 
| 
| 2.7 
|-
| location_number_npi 
| N/A 
| N/A 
| Q763: 'Location number' IE - numbering plan indicator 
| N/A 
| 
| 2.7 
|-
| location_number_presentation 
| N/A 
| N/A 
| Q763: 'Location number' IE - presentation restricted indicator 
| N/A 
| 
| 2.7 
|-
| location_number_screening 
| N/A 
| N/A 
| Q763: 'Location number' IE - screening 
| N/A 
| 
| 2.7 
|-
| mlpp_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| A script needs to set this to true if it wants to overwrite MLPP information in the outgoing leg. Otherwise, profile relay 'outgoing mode' applies automatically. 
| 2.7 
|-
| mlpp_look_for_busy 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - look ahead for busy 
| N/A 
| 
| 2.7 
|-
| mlpp_precedence_level 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - precedence level 
| SIP:Resource-Priority - q735 
| 
| 2.7 
|-
| mlpp_network_identity 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - network identity 
| N/A 
| 
| 2.7 
|-
| mlpp_service_domain 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - MLPP service domain 
| N/A 
| 
| 2.7 
|-
| called_isub 
| Q931: 'Called party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub parameter 
| 
| 2.7 
|-
| called_isub_type 
| Q931: 'Called party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub-encoding parameter 
| 
| 2.7 
|-
| calling_isub 
| Q931: 'Calling party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub 
| 
| 2.7 
|-
| calling_isub_type 
| Q931: 'Callinf party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub-encoding 
| 
| 2.7 
|-
| ss7_fci_default 
| N/A 
| N/A 
| Default forward call indicator (FCI) value. 
| N/A 
| Toolpack will overwrite FCI bits A, D, F, I and M with appropriate values according to call conditions 
| 2.7 
|-
| ss7_fci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_fci_default that must be forced. 
| N/A 
| Bits from ss7_fci_default which corresponding bit in ss7_fci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| ss7_bci_default 
| N/A 
| N/A 
| Default backward call indicator (BCI) value. 
| N/A 
| Toolpack will overwrite BCI bits AB, I, K, M and N with appropriate values according to call conditions 
| 2.7 
|-
| ss7_bci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_bci_default that must be forced. 
| N/A 
| Bits from ss7_bci_default which corresponding bit in ss7_bci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| tdm_ls_name_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable line service and timeslot selection to create the outgoing leg 
| 3.0 
|-
| tdm_ls_name
(Line Service or T1/E1 trunk) 
| Incoming leg line service name 
| Incoming leg line service name 
| Incoming leg line service name 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this line service name to create outgoing leg 
| 2.7 
|-
| tdm_timeslot_nb 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this timeslot number to create outgoing leg 
| 2.7 
|-
| rtp_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP port 
| (read-only) 
| 2.7 
|-
| rtp_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP port 
| (read-only) 
| 2.7 
|-
| ss7_cot_enabled 
| N/A 
| N/A 
| Requests SS7 in-call continuity test for this outgoing SS7 call 
| N/A 
| Toolpack will request a continuity test on the timeslot before making the outgoing call. If COT fails, the call will be dropped (then another route may be attempted) 
| 2.8 
|-
| reverse_charging_indication 
| Incoming leg Reverse charging indication IE present 
| N/A 
| N/A 
| N/A 
| If set in routing script, will add Reverse charging indication IE in outgoing leg (also use reverse_charging_indication_forward_enabled) 
| 2.8.12 
|-
| reverse_charging_indication_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable forwarding of reverse charging indication from incoming to outgoing leg 
| 2.8.12 
|-
| sip_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP UDP port 
| (read-only) 
| 2.8.13 
|-
| sip_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP UDP port 
| (read-only) 
| 2.8.13 
|}

 

=== Noa values ===

*<tt>unknown_number (0x2)</tt>
*<tt>international_number (0x4)</tt>
*<tt>national_number (0x3)</tt>
*<tt>subscriber_number (0x1)</tt>
*<tt>network_specific (0x5)</tt>
*<tt>network_routing_national_format (0x7)</tt>
*<tt>network_routing_international_format (0x8)</tt>
*<tt>abbreviated_number (0x6)</tt>
*<tt>subscriber_number_operator_requested (0x71)</tt>
*<tt>national_number_operator_requested (0x72)</tt>
*<tt>international_number_operator_requested (0x73)</tt>
*<tt>no_number_present_operator_requested (0x74)</tt>
*<tt>no_number_present_cut_through_call_to_carrier (0x75)</tt>
*<tt>test_line_test_code (0x77)</tt>
*<tt>non_unique_subscriber_number (0x71)</tt>
*<tt>non_unique_national_number (0x73)</tt>
*<tt>non_unique_international_number (0x74)</tt>
*<tt>call_950_numbe (0x76)</tt>
*<tt>special_number (0x73)</tt>
*<tt>national_number_with_transit_network_selection (0x74)</tt>
*<tt>international_number_with_transit_network_selection (0x75)</tt>

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

*<tt>call_params[:called_noa] = 0x70</tt>

or

*<tt>call_params[:called_noa] = 112</tt>

=== Npi values ===

*<tt>unknown_number</tt>
*<tt>isdn</tt>
*<tt>telephony</tt>
*<tt>private</tt>
*<tt>data</tt>
*<tt>telex</tt>
*<tt>national</tt>

=== Calling Display Type values ===

*<tt>unspecified</tt> => Type is unspecified.
*<tt>calling_party_name</tt> => Type is 0xB1.

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

*<tt>call_params[:calling_display_type] = 0xB1</tt>

or

*<tt>call_params[:calling_display_type] = 177</tt>

=== Calling Display value ===

*<tt>call_params[:calling_display] = "Roger Fluffy"</tt>

=== Presentation values for Calling number, Calling Subscriber (Generic Number), Redirecting Number, Original Called Number (OCN) and Location Number ===

*<tt>unspecified</tt>
*<tt>not_available (0x2)</tt>
*<tt>allowed (0x0)</tt>
*<tt>restricted (0x1)</tt>
*<tt>addr_restricted</tt>
*<tt>name_restricted</tt>

=== Calling Party Category ===
values for calling_category
*<tt>unspecified</tt> <tt>(0xa)</tt>
*<tt>unknown</tt> <tt>(0x0)</tt>
*<tt>operator_french</tt> <tt>(0x1)</tt>
*<tt>operator_english</tt> <tt>(0x2)</tt>
*<tt>operator_german</tt> <tt>(0x3)</tt>
*<tt>operator_russian</tt> <tt>(0x4)</tt>
*<tt>operator_spanish</tt> <tt>(0x5)</tt>
*<tt>subscriber</tt> <tt>(0xa)</tt>
*<tt>subscriber_with_priority</tt> <tt>(0xb)</tt>
*<tt>data</tt> <tt>(0xc)</tt>
*<tt>test</tt> <tt>(0xd)</tt>
*<tt>payphone</tt> <tt>(0xf)</tt>

=== Screening values for Calling number, Calling Subscriber (Generic Number), and Location Number ===

*<tt>unspecified</tt>
*<tt>no (0x0)</tt>
*<tt>pass (0x1)</tt>
*<tt>fail (0x2)</tt>
*<tt>network_provided (0x3)</tt>

=== Redirecting indicator values ===

SS7:

*<tt>no_redirection</tt>
*<tt>call_rerouted</tt>
*<tt>call_rerouted_all_restricted</tt>
*<tt>call_diverted</tt>
*<tt>call_diverted_all_restricted</tt>
*<tt>call_rerouted_restricted</tt>
*<tt>call_diverted_restricted</tt>
*<tt>spare</tt>

=== Redirecting number, Original Called Number and Diversion Reason ===

ISDN:

*<tt>unknown</tt>
*<tt>busy</tt>
*<tt>no_reply</tt>
*<tt>deflection</tt>
*<tt>dte_out_of_order</tt>
*<tt>forwarding_by_called_dte</tt>
*<tt>unconditional</tt>

SS7:

*<tt>unknown</tt>
*<tt>busy (SIP: user-busy)</tt>
*<tt>no_reply (SIP: no-answer)</tt>
*<tt>unconditional</tt>
*<tt>deflection</tt>
*<tt>deflection_immediate</tt>
*<tt>mobile_not_reachable</tt>

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

*<tt>digital</tt>
*<tt>restricted_digital</tt>
*<tt>digital_with_tones</tt>
*<tt>speech</tt>
*<tt>3_1_khz_audio</tt>
*<tt>video</tt>

=== 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:
<pre>Request-Line: INVITE sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0</pre>
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: 
<pre> if call_params[:request_uri] && call_params[:request_uri] =~ /sip:(.*)@.*/
call_params[:called] = $1
end
</pre>
=== 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. 

=== 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 hash format for a releases older than rel2.7.161.

It has been changed to string format because using a hash does not allow having multiple times the same header for certain releases of rel2.8 and rel2.9

Beginning from rel2.10.21, both hash and string format are supported to construct the outgoing SIP header; however, only string format is used for the incoming SIP header.

'''hash format:'''
<pre>call[ :sip_header ] = {"P-my-custom-header"=>"value1", "P-my-custom-header2"=>"value2", "P-my-custom-header3"=>"value3"}</pre>

'''string format:'''
<pre>call[ :sip_header ] = "P-my-custom-header:value1 \nP-my-custom-header2:value2 \nP-my-custom-header3:value3"
</pre>
(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:
<pre>
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
</pre>

=== sip uri parameters ===
Access to parameters of several SIP headers (To, From, P-Asserted-Identity, Remote-Party-ID, Contact).

<pre>
call[ :calling_parameters ]
call[ :called_parameters ]
call[ :private_address_parameters ] (for P-Asserted-Identity or Remote-Party-ID)
call[ :contact_parameters ]
</pre>

These parameters (if present) contain a hash with 3 keys: user_param, uri_param and header_param.
If a parameter already has a specific field (oli, isub, cpc, transport), it won't be present in the new generic structure.

By default, the parameters are not forwarded in a SIP to SIP call flow. The parameters '''will be forwarded''' only if:
* accessed (read) from either the inbound or outbound call parameters
* written in either the inbound or outbound call parameters

Using this code in routing script:
<pre>
puts "calling_param = #{ call[ :calling_parameters].inspect}"
</pre>

Example, From header format and what you will see in call[ :calling_parameters]:
<pre>
From:"test"<sip:4440000;user_param1=1;user_param2@10.3.10.217;uri_param3=3>;header_param4=4;tag=6F97303034343030002A2484
calling_param = {"user_param"=>"user_param1=1;user_param2", "uri_param"=>"uri_param3=3", "header_param"=>"header_param4=4"}
</pre>

'''Note''' that printing the inbound or outbound call parameters is considered as a "read" action and would result in forwarding the parameter on the outbound leg.

<pre>
From:"test"<sip:4440000@10.3.10.217;user=phone>;tag=6F97303034343030002A2484
calling_param = {"uri_param"=>"user=phone"}
</pre>

Example to insert outgoing parameters and overwrite received values.
<pre>
call [:calling_parameters] = {"user_param"=>"user_param7=7;user_param8", "uri_param"=>"uri_param9=9", "header_param"=>"header_paramA=A"}
</pre>

Example to add user=phone and keep all other uri parameters.
<pre>
if call [:calling_parameters]
if call [:calling_parameters]["uri_param"]
call[:calling_parameters]["uri_param"] << ";user=phone"
else
call [:calling_parameters]["uri_param"] = "user=phone"
end
else
call [:calling_parameters] = {"uri_param"=>"user=phone"}
end
</pre>

=== MLPP Precedence values ===

mlpp_look_for_busy:

*<tt>allowed</tt>
*<tt>path_reserved</tt>
*<tt>not_allowed</tt>

mlpp_precedence_level:

*<tt>flash_override</tt>
*<tt>flash</tt>
*<tt>immediate</tt>
*<tt>priority</tt>
*<tt>routine</tt>

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:

*<tt>nsap</tt>
*<tt>nsap_ia5</tt>
*<tt>nsap_bcd</tt>
*<tt>user</tt>

called_isub:
calling_isub:

Digits for the subaddress information.

=== Network Identification Plan ===

network_identification_plan:

*<tt>Unknown</tt> (value 0)
*<tt>cic</tt> (3 digits carrier identification code plus circuit code, value 1, SS7 or ISDN)
*<tt>user</tt> (User, value 2, ISDN only)
*<tt>cic4</tt> (4 digits carrier identification code plus circuit code, value 2, SS7 only)
*<tt>dnic</tt> (public Data Network ID, value 3, SS7 only)
*<tt>mnic</tt> (public land mobile network, value 6, SS7 only)

== 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 ==
Static routes normally chose an outbound NAP to forward the call to.

But it's also possible to create routes which outbound NAP is dynamically chosen by matching a registered user (when using [[Sip_registration_forwarding|SIP registration forwarding]]).

More information can be found [[Sip_registration_forwarding#SIP_Calls_routing|here]] about the way to control the [[Sip_registration_forwarding#SIP_Calls_routing|priority of "dynamic" vs "static" routes]].

== 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.
<pre>"file1.wav:repeat:start_off:end_off,file2.wav:repeat:start_off:end_off,file3.wav:repeat:start_off:end_off"
</pre>
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: [[Customer_application_framework:play_audio_files#Play_path_format|Path format]]

==== Example 1 ====
The following example will play file1.wav once, and then play file2.wav in loop:
"file1.wav,file2.wav:-1"

==== Example 2 ====
The following example will play file1.wav from start offset of 1 second to end offset of 3 seconds, then twice file2.wav 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 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 apply when params[:bridge][:ring_tone] is not used, because it also apply 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:
[[Toolpack:Configuring_Audio_Prompts_A|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: [[Customer_application_framework:play_audio_files#Helpful_variables_to_build_play_or_record_file_paths|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 [[#Refuse|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.

== 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 [[Routing_script_tutorial:Mini_Development_Guide#Redirecting_number,_Original_Called_Number_and_Diversion_Reason|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"
}

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

To get more information, see:
*[[Routing_script_tutorial:SIP_Redirection_Contacts|SIP Redirection Contacts Parameters in a Call Flow]]

== Connected number ==
Insert a connected number in the answer message of the call flow.

<code> 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</code>

== Terminating calls ==
In release 2.8, it is now possible to terminate a call through the routing scripts. The [[#Reason values|reason code]] must be specified in <code>params[:bridge][:reason]</code>. The <code>:terminate</code> hash must be created and copied into <code>params</code>:
terminate = {}
params[:terminate] = terminate
The following fields can then be set in <code>:terminate</code>:
* <code>:sip_header</code>
* <code>:contacts</code> # list of contacts as described in the [[#Redirection|redirection]] section
* <code>:isup_raw</code>
* <code>:isup_raw_variant</code>
* <code>:redirecting_number</code>
* <code>:redirecting_number_noa</code>
* <code>:redirecting_number_npi</code>
* <code>:redirecting_number_presentation</code>
* <code>:redirecting_number_reason</code>
* <code>:redirecting_number_counter</code>
* <code>:redirecting_number_indicator</code>
* <code>:original_called_number</code>
* <code>:original_called_number_noa</code>
* <code>:original_called_number_npi</code>
* <code>:original_called_number_presentation</code>
* <code>:original_called_number_reason</code>
* <code>:original_called_number_counter</code>

== Reason values ==

Check here for Termination Reason Cause codes: 

[[Termination_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 ==

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.

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

 If the nap status is part of a substructure, the substructure will be a hash containing all subfield elements.

Example to access the signaling type and the number of incoming call count for the NAP of the current call:

incoming_nap = params[:naps][ params[:call][ :nap ].to_sym]
log_trace 4,"Incoming NAP parameters=" + incoming_nap.inspect
log_trace 4,"Incoming NAP signaling type=" + incoming_nap[:signaling_type].inspect
log_trace 4,"Incoming NAP call cnt=" + incoming_nap[:asr_stats_incoming_struct][:total_call_cnt].inspect

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

== 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 time 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|Routing Script Tutorial]].

Routing script tutorial:Mini Development Guide

2018-07-03T19:13:46Z

Lucas Joyal: /* Script parameters protocol mapping */ Updated 'called' parameters

== 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 "[[Routing_script_tutorial:Mini_Development_Guide#Reason_values|Reason values]]".

=== Script parameters protocol mapping ===

The following call parameters are available in the call object. For example:

called_number = call[:called]

{| cellspacing="1" cellpadding="1" border="1" style="width: 921px; height: 805px;"
|-
! scope="col" | '''Script parameter name'''
! scope="col" | '''ISDN '''
! scope="col" | '''R2 CAS''' 
! scope="col" | '''SS7 '''
! scope="col" | '''SIP '''
! scope="col" | '''Comment '''
! scope="col" | '''Toolpack version '''
|-
| leg_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Leg ID 
| 
|-
| session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Session ID 
| 
|-
| 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_host 
| N/A 
| N/A 
| N/A 
| SIP:From - host section 
| For example : The 'telcobridges.com' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| calling_port 
| N/A 
| N/A 
| N/A 
| SIP:From - host section 
| For example : The '6060' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| 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 
Q931: 'Facility CNAM' IE when presentation is allowed for DMS/NI2 variants 
| N/A 
| Q763
ITU97: 'Display information' IE - display information
ANSI95: 'Generic name' 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 

| 
| 
|-
| calling_subscriber
(Generic Number / NDS) 
| Q931: 2nd 'Calling party number' IE - Number digits 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - Number digits 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| Requires option 'support 2 calling number IE' in the profile. This variable has priority over 'private_address' in the outgoing direction. 
| 
|-
| calling_subscriber_noa 
| Q931: 2nd 'Calling party number' IE - Type of number 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - nature of address indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_npi 
| Q931: 2nd 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - numbering plan indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
 
| 
|-
| calling_subscriber_presentation 
| Q931: 2nd 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - presentation restricted indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_screening 
| Q931: 2nd 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - screening 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| private_display 
| Q931: 'Facility CNAM' IE when presentation is restricted for DMS/NI2 variants 
| 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 

| For example : The 'fluffy' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_host 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - host

SIP:Remote-party-id - host 

| For example : The 'telcobridges.com' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_port 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - port

SIP:Remote-party-id - port 

| For example : The '6060' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| 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_sip_host 
| N/A 
| N/A 
| N/A 
| SIP:To - host 
| For example : The 'telcobridges.com' in To: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| called_sip_port 
| N/A 
| N/A 
| N/A 
| SIP:To - port number 
| For example : The '6060' in To: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| 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 and original called 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_indicator 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirecting indicator 
| N/A 
| 
| 
|-
| 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
(OCN) 
| 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_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_npdi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - with qualifier=Ported number is present 
| SIP:RequestURI - npdi=yes is present 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number 
| N/A 
| N/A 
| Q763: 'Generic number' IE - address signals with qualifier=Ported number 
| SIP:RequestURI - to user part when rn is present 
| rn is stored in the called number 
| 
|-
| ported_number_noa 
| N/A 
| N/A 
| Q763: 'Generic number' IE - nature of address indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number_npi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - numbering plan indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| oli
(Originating line information) 
| 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 
| Requires option 'Forward custom headers' in Profiles->SIP 
| 2.7.63 
|-
| nap
(Network Access Point) 
| N/A 
| N/A 
| N/A 
| N/A 
| Incoming leg NAP name (read-only) 
| 
|-
| type_of_network_identification 
| Q931: 'Transit network selection' IE - Type of network identification 
| N/A 
| Q763: 'Transit network selection' IE - Type of network identification 
| N/A 
| 
| 2.7 
|-
| network_identification 
| Q931: 'Transit network selection' IE - Network identification 
| N/A 
| Q763: 'Transit network selection' IE - Network identification 
| SIP: Request-Line - cic 
| 
| 2.7 
|-
| network_identification_plan 
| Q931: 'Transit network selection' IE - Network identification plan 
| N/A 
| Q763: 'Transit network selection' IE - Network identification plan 
| N/A 
| 
| 2.7 
|-
| location_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default location number forwarding behavior from incoming to outgoing leg 
| 2.7 
|-
| location_number 
| N/A 
| N/A 
| Q763: 'Location number' IE - address signals 
| N/A 
| 
| 2.7 
|-
| location_number_noa 
| N/A 
| N/A 
| Q763: 'Location number' IE - nature of address indicator 
| N/A 
| 
| 2.7 
|-
| location_number_npi 
| N/A 
| N/A 
| Q763: 'Location number' IE - numbering plan indicator 
| N/A 
| 
| 2.7 
|-
| location_number_presentation 
| N/A 
| N/A 
| Q763: 'Location number' IE - presentation restricted indicator 
| N/A 
| 
| 2.7 
|-
| location_number_screening 
| N/A 
| N/A 
| Q763: 'Location number' IE - screening 
| N/A 
| 
| 2.7 
|-
| mlpp_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| A script needs to set this to true if it wants to overwrite MLPP information in the outgoing leg. Otherwise, profile relay 'outgoing mode' applies automatically. 
| 2.7 
|-
| mlpp_look_for_busy 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - look ahead for busy 
| N/A 
| 
| 2.7 
|-
| mlpp_precedence_level 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - precedence level 
| SIP:Resource-Priority - q735 
| 
| 2.7 
|-
| mlpp_network_identity 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - network identity 
| N/A 
| 
| 2.7 
|-
| mlpp_service_domain 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - MLPP service domain 
| N/A 
| 
| 2.7 
|-
| called_isub 
| Q931: 'Called party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub parameter 
| 
| 2.7 
|-
| called_isub_type 
| Q931: 'Called party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub-encoding parameter 
| 
| 2.7 
|-
| calling_isub 
| Q931: 'Calling party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub 
| 
| 2.7 
|-
| calling_isub_type 
| Q931: 'Callinf party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub-encoding 
| 
| 2.7 
|-
| ss7_fci_default 
| N/A 
| N/A 
| Default forward call indicator (FCI) value. 
| N/A 
| Toolpack will overwrite FCI bits A, D, F, I and M with appropriate values according to call conditions 
| 2.7 
|-
| ss7_fci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_fci_default that must be forced. 
| N/A 
| Bits from ss7_fci_default which corresponding bit in ss7_fci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| ss7_bci_default 
| N/A 
| N/A 
| Default backward call indicator (BCI) value. 
| N/A 
| Toolpack will overwrite BCI bits AB, I, K, M and N with appropriate values according to call conditions 
| 2.7 
|-
| ss7_bci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_bci_default that must be forced. 
| N/A 
| Bits from ss7_bci_default which corresponding bit in ss7_bci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| tdm_ls_name_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable line service and timeslot selection to create the outgoing leg 
| 3.0 
|-
| tdm_ls_name
(Line Service or T1/E1 trunk) 
| Incoming leg line service name 
| Incoming leg line service name 
| Incoming leg line service name 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this line service name to create outgoing leg 
| 2.7 
|-
| tdm_timeslot_nb 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this timeslot number to create outgoing leg 
| 2.7 
|-
| rtp_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP port 
| (read-only) 
| 2.7 
|-
| rtp_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP port 
| (read-only) 
| 2.7 
|-
| ss7_cot_enabled 
| N/A 
| N/A 
| Requests SS7 in-call continuity test for this outgoing SS7 call 
| N/A 
| Toolpack will request a continuity test on the timeslot before making the outgoing call. If COT fails, the call will be dropped (then another route may be attempted) 
| 2.8 
|-
| reverse_charging_indication 
| Incoming leg Reverse charging indication IE present 
| N/A 
| N/A 
| N/A 
| If set in routing script, will add Reverse charging indication IE in outgoing leg (also use reverse_charging_indication_forward_enabled) 
| 2.8.12 
|-
| reverse_charging_indication_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable forwarding of reverse charging indication from incoming to outgoing leg 
| 2.8.12 
|-
| sip_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP UDP port 
| (read-only) 
| 2.8.13 
|-
| sip_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP UDP port 
| (read-only) 
| 2.8.13 
|}

 

=== Noa values ===

*<tt>unknown_number (0x2)</tt>
*<tt>international_number (0x4)</tt>
*<tt>national_number (0x3)</tt>
*<tt>subscriber_number (0x1)</tt>
*<tt>network_specific (0x5)</tt>
*<tt>network_routing_national_format (0x7)</tt>
*<tt>network_routing_international_format (0x8)</tt>
*<tt>abbreviated_number (0x6)</tt>
*<tt>subscriber_number_operator_requested (0x71)</tt>
*<tt>national_number_operator_requested (0x72)</tt>
*<tt>international_number_operator_requested (0x73)</tt>
*<tt>no_number_present_operator_requested (0x74)</tt>
*<tt>no_number_present_cut_through_call_to_carrier (0x75)</tt>
*<tt>test_line_test_code (0x77)</tt>
*<tt>non_unique_subscriber_number (0x71)</tt>
*<tt>non_unique_national_number (0x73)</tt>
*<tt>non_unique_international_number (0x74)</tt>
*<tt>call_950_numbe (0x76)</tt>
*<tt>special_number (0x73)</tt>
*<tt>national_number_with_transit_network_selection (0x74)</tt>
*<tt>international_number_with_transit_network_selection (0x75)</tt>

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

*<tt>call_params[:called_noa] = 0x70</tt>

or

*<tt>call_params[:called_noa] = 112</tt>

=== Npi values ===

*<tt>unknown_number</tt>
*<tt>isdn</tt>
*<tt>telephony</tt>
*<tt>private</tt>
*<tt>data</tt>
*<tt>telex</tt>
*<tt>national</tt>

=== Calling Display Type values ===

*<tt>unspecified</tt> => Type is unspecified.
*<tt>calling_party_name</tt> => Type is 0xB1.

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

*<tt>call_params[:calling_display_type] = 0xB1</tt>

or

*<tt>call_params[:calling_display_type] = 177</tt>

=== Calling Display value ===

*<tt>call_params[:calling_display] = "Roger Fluffy"</tt>

=== Presentation values for Calling number, Calling Subscriber (Generic Number), Redirecting Number, Original Called Number (OCN) and Location Number ===

*<tt>unspecified</tt>
*<tt>not_available (0x2)</tt>
*<tt>allowed (0x0)</tt>
*<tt>restricted (0x1)</tt>
*<tt>addr_restricted</tt>
*<tt>name_restricted</tt>

=== Calling Party Category ===
values for calling_category
*<tt>unspecified</tt> <tt>(0xa)</tt>
*<tt>unknown</tt> <tt>(0x0)</tt>
*<tt>operator_french</tt> <tt>(0x1)</tt>
*<tt>operator_english</tt> <tt>(0x2)</tt>
*<tt>operator_german</tt> <tt>(0x3)</tt>
*<tt>operator_russian</tt> <tt>(0x4)</tt>
*<tt>operator_spanish</tt> <tt>(0x5)</tt>
*<tt>subscriber</tt> <tt>(0xa)</tt>
*<tt>subscriber_with_priority</tt> <tt>(0xb)</tt>
*<tt>data</tt> <tt>(0xc)</tt>
*<tt>test</tt> <tt>(0xd)</tt>
*<tt>payphone</tt> <tt>(0xf)</tt>

=== Screening values for Calling number, Calling Subscriber (Generic Number), and Location Number ===

*<tt>unspecified</tt>
*<tt>no (0x0)</tt>
*<tt>pass (0x1)</tt>
*<tt>fail (0x2)</tt>
*<tt>network_provided (0x3)</tt>

=== Redirecting indicator values ===

SS7:

*<tt>no_redirection</tt>
*<tt>call_rerouted</tt>
*<tt>call_rerouted_all_restricted</tt>
*<tt>call_diverted</tt>
*<tt>call_diverted_all_restricted</tt>
*<tt>call_rerouted_restricted</tt>
*<tt>call_diverted_restricted</tt>
*<tt>spare</tt>

=== Redirecting number, Original Called Number and Diversion Reason ===

ISDN:

*<tt>unknown</tt>
*<tt>busy</tt>
*<tt>no_reply</tt>
*<tt>deflection</tt>
*<tt>dte_out_of_order</tt>
*<tt>forwarding_by_called_dte</tt>
*<tt>unconditional</tt>

SS7:

*<tt>unknown</tt>
*<tt>busy (SIP: user-busy)</tt>
*<tt>no_reply (SIP: no-answer)</tt>
*<tt>unconditional</tt>
*<tt>deflection</tt>
*<tt>deflection_immediate</tt>
*<tt>mobile_not_reachable</tt>

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

*<tt>digital</tt>
*<tt>restricted_digital</tt>
*<tt>digital_with_tones</tt>
*<tt>speech</tt>
*<tt>3_1_khz_audio</tt>
*<tt>video</tt>

=== 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:
<pre>Request-Line: INVITE sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0</pre>
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: 
<pre> if call_params[:request_uri] && call_params[:request_uri] =~ /sip:(.*)@.*/
call_params[:called] = $1
end
</pre>
=== 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. 

=== 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 hash format for a releases older than rel2.7.161.

It has been changed to string format because using a hash does not allow having multiple times the same header for certain releases of rel2.8 and rel2.9

Beginning from rel2.10.21, both hash and string format are supported to construct the outgoing SIP header; however, only string format is used for the incoming SIP header.

'''hash format:'''
<pre>call[ :sip_header ] = {"P-my-custom-header"=>"value1", "P-my-custom-header2"=>"value2", "P-my-custom-header3"=>"value3"}</pre>

'''string format:'''
<pre>call[ :sip_header ] = "P-my-custom-header:value1 \nP-my-custom-header2:value2 \nP-my-custom-header3:value3"
</pre>
(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:
<pre>
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
</pre>

=== sip uri parameters ===
Access to parameters of several SIP headers (To, From, P-Asserted-Identity, Remote-Party-ID, Contact).

<pre>
call[ :calling_parameters ]
call[ :called_parameters ]
call[ :private_address_parameters ] (for P-Asserted-Identity or Remote-Party-ID)
call[ :contact_parameters ]
</pre>

These parameters (if present) contain a hash with 3 keys: user_param, uri_param and header_param.
If a parameter already has a specific field (oli, isub, cpc, transport), it won't be present in the new generic structure.

By default, the parameters are not forwarded in a SIP to SIP call flow. The parameters '''will be forwarded''' only if:
* accessed (read) from either the inbound or outbound call parameters
* written in either the inbound or outbound call parameters

Using this code in routing script:
<pre>
puts "calling_param = #{ call[ :calling_parameters].inspect}"
</pre>

Example, From header format and what you will see in call[ :calling_parameters]:
<pre>
From:"test"<sip:4440000;user_param1=1;user_param2@10.3.10.217;uri_param3=3>;header_param4=4;tag=6F97303034343030002A2484
calling_param = {"user_param"=>"user_param1=1;user_param2", "uri_param"=>"uri_param3=3", "header_param"=>"header_param4=4"}
</pre>

'''Note''' that printing the inbound or outbound call parameters is considered as a "read" action and would result in forwarding the parameter on the outbound leg.

<pre>
From:"test"<sip:4440000@10.3.10.217;user=phone>;tag=6F97303034343030002A2484
calling_param = {"uri_param"=>"user=phone"}
</pre>

Example to insert outgoing parameters and overwrite received values.
<pre>
call [:calling_parameters] = {"user_param"=>"user_param7=7;user_param8", "uri_param"=>"uri_param9=9", "header_param"=>"header_paramA=A"}
</pre>

Example to add user=phone and keep all other uri parameters.
<pre>
if call [:calling_parameters]
if call [:calling_parameters]["uri_param"]
call[:calling_parameters]["uri_param"] << ";user=phone"
else
call [:calling_parameters]["uri_param"] = "user=phone"
end
else
call [:calling_parameters] = {"uri_param"=>"user=phone"}
end
</pre>

=== MLPP Precedence values ===

mlpp_look_for_busy:

*<tt>allowed</tt>
*<tt>path_reserved</tt>
*<tt>not_allowed</tt>

mlpp_precedence_level:

*<tt>flash_override</tt>
*<tt>flash</tt>
*<tt>immediate</tt>
*<tt>priority</tt>
*<tt>routine</tt>

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:

*<tt>nsap</tt>
*<tt>nsap_ia5</tt>
*<tt>nsap_bcd</tt>
*<tt>user</tt>

called_isub:
calling_isub:

Digits for the subaddress information.

=== Network Identification Plan ===

network_identification_plan:

*<tt>Unknown</tt> (value 0)
*<tt>cic</tt> (3 digits carrier identification code plus circuit code, value 1, SS7 or ISDN)
*<tt>user</tt> (User, value 2, ISDN only)
*<tt>cic4</tt> (4 digits carrier identification code plus circuit code, value 2, SS7 only)
*<tt>dnic</tt> (public Data Network ID, value 3, SS7 only)
*<tt>mnic</tt> (public land mobile network, value 6, SS7 only)

== 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 ==
Static routes normally chose an outbound NAP to forward the call to.

But it's also possible to create routes which outbound NAP is dynamically chosen by matching a registered user (when using [[Sip_registration_forwarding|SIP registration forwarding]]).

More information can be found [[Sip_registration_forwarding#SIP_Calls_routing|here]] about the way to control the [[Sip_registration_forwarding#SIP_Calls_routing|priority of "dynamic" vs "static" routes]].

== 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.
<pre>"file1.wav:repeat:start_off:end_off,file2.wav:repeat:start_off:end_off,file3.wav:repeat:start_off:end_off"
</pre>
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: [[Customer_application_framework:play_audio_files#Play_path_format|Path format]]

==== Example 1 ====
The following example will play file1.wav once, and then play file2.wav in loop:
"file1.wav,file2.wav:-1"

==== Example 2 ====
The following example will play file1.wav from start offset of 1 second to end offset of 3 seconds, then twice file2.wav 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 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 apply when params[:bridge][:ring_tone] is not used, because it also apply 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:
[[Toolpack:Configuring_Audio_Prompts_A|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: [[Customer_application_framework:play_audio_files#Helpful_variables_to_build_play_or_record_file_paths|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 [[#Refuse|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.

== 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 [[Routing_script_tutorial:Mini_Development_Guide#Redirecting_number,_Original_Called_Number_and_Diversion_Reason|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"
}

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

To get more information, see:
*[[Routing_script_tutorial:SIP_Redirection_Contacts|SIP Redirection Contacts Parameters in a Call Flow]]

== Connected number ==
Insert a connected number in the answer message of the call flow.

<code> 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</code>

== Terminating calls ==
In release 2.8, it is now possible to terminate a call through the routing scripts. The [[#Reason values|reason code]] must be specified in <code>params[:bridge][:reason]</code>. The <code>:terminate</code> hash must be created and copied into <code>params</code>:
terminate = {}
params[:terminate] = terminate
The following fields can then be set in <code>:terminate</code>:
* <code>:sip_header</code>
* <code>:contacts</code> # list of contacts as described in the [[#Redirection|redirection]] section
* <code>:isup_raw</code>
* <code>:isup_raw_variant</code>
* <code>:redirecting_number</code>
* <code>:redirecting_number_noa</code>
* <code>:redirecting_number_npi</code>
* <code>:redirecting_number_presentation</code>
* <code>:redirecting_number_reason</code>
* <code>:redirecting_number_counter</code>
* <code>:redirecting_number_indicator</code>
* <code>:original_called_number</code>
* <code>:original_called_number_noa</code>
* <code>:original_called_number_npi</code>
* <code>:original_called_number_presentation</code>
* <code>:original_called_number_reason</code>
* <code>:original_called_number_counter</code>

== Reason values ==

Check here for Termination Reason Cause codes: 

[[Termination_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 ==

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.

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

 If the nap status is part of a substructure, the substructure will be a hash containing all subfield elements.

Example to access the signaling type and the number of incoming call count for the NAP of the current call:

incoming_nap = params[:naps][ params[:call][ :nap ].to_sym]
log_trace 4,"Incoming NAP parameters=" + incoming_nap.inspect
log_trace 4,"Incoming NAP signaling type=" + incoming_nap[:signaling_type].inspect
log_trace 4,"Incoming NAP call cnt=" + incoming_nap[:asr_stats_incoming_struct][:total_call_cnt].inspect

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

== 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 time 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|Routing Script Tutorial]].

Routing script tutorial:Mini Development Guide

2018-07-03T19:06:00Z

Lucas Joyal: /* Script parameters protocol mapping */ Update calling parameter doc

== 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 "[[Routing_script_tutorial:Mini_Development_Guide#Reason_values|Reason values]]".

=== Script parameters protocol mapping ===

The following call parameters are available in the call object. For example:

called_number = call[:called]

{| cellspacing="1" cellpadding="1" border="1" style="width: 921px; height: 805px;"
|-
! scope="col" | '''Script parameter name'''
! scope="col" | '''ISDN '''
! scope="col" | '''R2 CAS''' 
! scope="col" | '''SS7 '''
! scope="col" | '''SIP '''
! scope="col" | '''Comment '''
! scope="col" | '''Toolpack version '''
|-
| leg_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Leg ID 
| 
|-
| session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Session ID 
| 
|-
| 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_host 
| N/A 
| N/A 
| N/A 
| SIP:From - host section 
| For example : The 'telcobridges.com' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| calling_port 
| N/A 
| N/A 
| N/A 
| SIP:From - host section 
| For example : The '6060' in From: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| 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 
Q931: 'Facility CNAM' IE when presentation is allowed for DMS/NI2 variants 
| N/A 
| Q763
ITU97: 'Display information' IE - display information
ANSI95: 'Generic name' 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 

| 
| 
|-
| calling_subscriber
(Generic Number / NDS) 
| Q931: 2nd 'Calling party number' IE - Number digits 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - Number digits 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| Requires option 'support 2 calling number IE' in the profile. This variable has priority over 'private_address' in the outgoing direction. 
| 
|-
| calling_subscriber_noa 
| Q931: 2nd 'Calling party number' IE - Type of number 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - nature of address indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_npi 
| Q931: 2nd 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - numbering plan indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
 
| 
|-
| calling_subscriber_presentation 
| Q931: 2nd 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - presentation restricted indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_screening 
| Q931: 2nd 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - screening 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| private_display 
| Q931: 'Facility CNAM' IE when presentation is restricted for DMS/NI2 variants 
| 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 

| For example : The 'fluffy' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_host 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - host

SIP:Remote-party-id - host 

| For example : The 'telcobridges.com' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_port 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - port

SIP:Remote-party-id - port 

| For example : The '6060' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| 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 and original called 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_indicator 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirecting indicator 
| N/A 
| 
| 
|-
| 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
(OCN) 
| 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_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_npdi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - with qualifier=Ported number is present 
| SIP:RequestURI - npdi=yes is present 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number 
| N/A 
| N/A 
| Q763: 'Generic number' IE - address signals with qualifier=Ported number 
| SIP:RequestURI - to user part when rn is present 
| rn is stored in the called number 
| 
|-
| ported_number_noa 
| N/A 
| N/A 
| Q763: 'Generic number' IE - nature of address indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number_npi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - numbering plan indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| oli
(Originating line information) 
| 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 
| Requires option 'Forward custom headers' in Profiles->SIP 
| 2.7.63 
|-
| nap
(Network Access Point) 
| N/A 
| N/A 
| N/A 
| N/A 
| Incoming leg NAP name (read-only) 
| 
|-
| type_of_network_identification 
| Q931: 'Transit network selection' IE - Type of network identification 
| N/A 
| Q763: 'Transit network selection' IE - Type of network identification 
| N/A 
| 
| 2.7 
|-
| network_identification 
| Q931: 'Transit network selection' IE - Network identification 
| N/A 
| Q763: 'Transit network selection' IE - Network identification 
| SIP: Request-Line - cic 
| 
| 2.7 
|-
| network_identification_plan 
| Q931: 'Transit network selection' IE - Network identification plan 
| N/A 
| Q763: 'Transit network selection' IE - Network identification plan 
| N/A 
| 
| 2.7 
|-
| location_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default location number forwarding behavior from incoming to outgoing leg 
| 2.7 
|-
| location_number 
| N/A 
| N/A 
| Q763: 'Location number' IE - address signals 
| N/A 
| 
| 2.7 
|-
| location_number_noa 
| N/A 
| N/A 
| Q763: 'Location number' IE - nature of address indicator 
| N/A 
| 
| 2.7 
|-
| location_number_npi 
| N/A 
| N/A 
| Q763: 'Location number' IE - numbering plan indicator 
| N/A 
| 
| 2.7 
|-
| location_number_presentation 
| N/A 
| N/A 
| Q763: 'Location number' IE - presentation restricted indicator 
| N/A 
| 
| 2.7 
|-
| location_number_screening 
| N/A 
| N/A 
| Q763: 'Location number' IE - screening 
| N/A 
| 
| 2.7 
|-
| mlpp_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| A script needs to set this to true if it wants to overwrite MLPP information in the outgoing leg. Otherwise, profile relay 'outgoing mode' applies automatically. 
| 2.7 
|-
| mlpp_look_for_busy 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - look ahead for busy 
| N/A 
| 
| 2.7 
|-
| mlpp_precedence_level 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - precedence level 
| SIP:Resource-Priority - q735 
| 
| 2.7 
|-
| mlpp_network_identity 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - network identity 
| N/A 
| 
| 2.7 
|-
| mlpp_service_domain 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - MLPP service domain 
| N/A 
| 
| 2.7 
|-
| called_isub 
| Q931: 'Called party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub parameter 
| 
| 2.7 
|-
| called_isub_type 
| Q931: 'Called party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub-encoding parameter 
| 
| 2.7 
|-
| calling_isub 
| Q931: 'Calling party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub 
| 
| 2.7 
|-
| calling_isub_type 
| Q931: 'Callinf party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub-encoding 
| 
| 2.7 
|-
| ss7_fci_default 
| N/A 
| N/A 
| Default forward call indicator (FCI) value. 
| N/A 
| Toolpack will overwrite FCI bits A, D, F, I and M with appropriate values according to call conditions 
| 2.7 
|-
| ss7_fci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_fci_default that must be forced. 
| N/A 
| Bits from ss7_fci_default which corresponding bit in ss7_fci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| ss7_bci_default 
| N/A 
| N/A 
| Default backward call indicator (BCI) value. 
| N/A 
| Toolpack will overwrite BCI bits AB, I, K, M and N with appropriate values according to call conditions 
| 2.7 
|-
| ss7_bci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_bci_default that must be forced. 
| N/A 
| Bits from ss7_bci_default which corresponding bit in ss7_bci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| tdm_ls_name_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable line service and timeslot selection to create the outgoing leg 
| 3.0 
|-
| tdm_ls_name
(Line Service or T1/E1 trunk) 
| Incoming leg line service name 
| Incoming leg line service name 
| Incoming leg line service name 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this line service name to create outgoing leg 
| 2.7 
|-
| tdm_timeslot_nb 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this timeslot number to create outgoing leg 
| 2.7 
|-
| rtp_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP port 
| (read-only) 
| 2.7 
|-
| rtp_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP port 
| (read-only) 
| 2.7 
|-
| ss7_cot_enabled 
| N/A 
| N/A 
| Requests SS7 in-call continuity test for this outgoing SS7 call 
| N/A 
| Toolpack will request a continuity test on the timeslot before making the outgoing call. If COT fails, the call will be dropped (then another route may be attempted) 
| 2.8 
|-
| reverse_charging_indication 
| Incoming leg Reverse charging indication IE present 
| N/A 
| N/A 
| N/A 
| If set in routing script, will add Reverse charging indication IE in outgoing leg (also use reverse_charging_indication_forward_enabled) 
| 2.8.12 
|-
| reverse_charging_indication_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable forwarding of reverse charging indication from incoming to outgoing leg 
| 2.8.12 
|-
| sip_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP UDP port 
| (read-only) 
| 2.8.13 
|-
| sip_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP UDP port 
| (read-only) 
| 2.8.13 
|}

 

=== Noa values ===

*<tt>unknown_number (0x2)</tt>
*<tt>international_number (0x4)</tt>
*<tt>national_number (0x3)</tt>
*<tt>subscriber_number (0x1)</tt>
*<tt>network_specific (0x5)</tt>
*<tt>network_routing_national_format (0x7)</tt>
*<tt>network_routing_international_format (0x8)</tt>
*<tt>abbreviated_number (0x6)</tt>
*<tt>subscriber_number_operator_requested (0x71)</tt>
*<tt>national_number_operator_requested (0x72)</tt>
*<tt>international_number_operator_requested (0x73)</tt>
*<tt>no_number_present_operator_requested (0x74)</tt>
*<tt>no_number_present_cut_through_call_to_carrier (0x75)</tt>
*<tt>test_line_test_code (0x77)</tt>
*<tt>non_unique_subscriber_number (0x71)</tt>
*<tt>non_unique_national_number (0x73)</tt>
*<tt>non_unique_international_number (0x74)</tt>
*<tt>call_950_numbe (0x76)</tt>
*<tt>special_number (0x73)</tt>
*<tt>national_number_with_transit_network_selection (0x74)</tt>
*<tt>international_number_with_transit_network_selection (0x75)</tt>

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

*<tt>call_params[:called_noa] = 0x70</tt>

or

*<tt>call_params[:called_noa] = 112</tt>

=== Npi values ===

*<tt>unknown_number</tt>
*<tt>isdn</tt>
*<tt>telephony</tt>
*<tt>private</tt>
*<tt>data</tt>
*<tt>telex</tt>
*<tt>national</tt>

=== Calling Display Type values ===

*<tt>unspecified</tt> => Type is unspecified.
*<tt>calling_party_name</tt> => Type is 0xB1.

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

*<tt>call_params[:calling_display_type] = 0xB1</tt>

or

*<tt>call_params[:calling_display_type] = 177</tt>

=== Calling Display value ===

*<tt>call_params[:calling_display] = "Roger Fluffy"</tt>

=== Presentation values for Calling number, Calling Subscriber (Generic Number), Redirecting Number, Original Called Number (OCN) and Location Number ===

*<tt>unspecified</tt>
*<tt>not_available (0x2)</tt>
*<tt>allowed (0x0)</tt>
*<tt>restricted (0x1)</tt>
*<tt>addr_restricted</tt>
*<tt>name_restricted</tt>

=== Calling Party Category ===
values for calling_category
*<tt>unspecified</tt> <tt>(0xa)</tt>
*<tt>unknown</tt> <tt>(0x0)</tt>
*<tt>operator_french</tt> <tt>(0x1)</tt>
*<tt>operator_english</tt> <tt>(0x2)</tt>
*<tt>operator_german</tt> <tt>(0x3)</tt>
*<tt>operator_russian</tt> <tt>(0x4)</tt>
*<tt>operator_spanish</tt> <tt>(0x5)</tt>
*<tt>subscriber</tt> <tt>(0xa)</tt>
*<tt>subscriber_with_priority</tt> <tt>(0xb)</tt>
*<tt>data</tt> <tt>(0xc)</tt>
*<tt>test</tt> <tt>(0xd)</tt>
*<tt>payphone</tt> <tt>(0xf)</tt>

=== Screening values for Calling number, Calling Subscriber (Generic Number), and Location Number ===

*<tt>unspecified</tt>
*<tt>no (0x0)</tt>
*<tt>pass (0x1)</tt>
*<tt>fail (0x2)</tt>
*<tt>network_provided (0x3)</tt>

=== Redirecting indicator values ===

SS7:

*<tt>no_redirection</tt>
*<tt>call_rerouted</tt>
*<tt>call_rerouted_all_restricted</tt>
*<tt>call_diverted</tt>
*<tt>call_diverted_all_restricted</tt>
*<tt>call_rerouted_restricted</tt>
*<tt>call_diverted_restricted</tt>
*<tt>spare</tt>

=== Redirecting number, Original Called Number and Diversion Reason ===

ISDN:

*<tt>unknown</tt>
*<tt>busy</tt>
*<tt>no_reply</tt>
*<tt>deflection</tt>
*<tt>dte_out_of_order</tt>
*<tt>forwarding_by_called_dte</tt>
*<tt>unconditional</tt>

SS7:

*<tt>unknown</tt>
*<tt>busy (SIP: user-busy)</tt>
*<tt>no_reply (SIP: no-answer)</tt>
*<tt>unconditional</tt>
*<tt>deflection</tt>
*<tt>deflection_immediate</tt>
*<tt>mobile_not_reachable</tt>

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

*<tt>digital</tt>
*<tt>restricted_digital</tt>
*<tt>digital_with_tones</tt>
*<tt>speech</tt>
*<tt>3_1_khz_audio</tt>
*<tt>video</tt>

=== 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:
<pre>Request-Line: INVITE sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0</pre>
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: 
<pre> if call_params[:request_uri] && call_params[:request_uri] =~ /sip:(.*)@.*/
call_params[:called] = $1
end
</pre>
=== 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. 

=== 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 hash format for a releases older than rel2.7.161.

It has been changed to string format because using a hash does not allow having multiple times the same header for certain releases of rel2.8 and rel2.9

Beginning from rel2.10.21, both hash and string format are supported to construct the outgoing SIP header; however, only string format is used for the incoming SIP header.

'''hash format:'''
<pre>call[ :sip_header ] = {"P-my-custom-header"=>"value1", "P-my-custom-header2"=>"value2", "P-my-custom-header3"=>"value3"}</pre>

'''string format:'''
<pre>call[ :sip_header ] = "P-my-custom-header:value1 \nP-my-custom-header2:value2 \nP-my-custom-header3:value3"
</pre>
(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:
<pre>
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
</pre>

=== sip uri parameters ===
Access to parameters of several SIP headers (To, From, P-Asserted-Identity, Remote-Party-ID, Contact).

<pre>
call[ :calling_parameters ]
call[ :called_parameters ]
call[ :private_address_parameters ] (for P-Asserted-Identity or Remote-Party-ID)
call[ :contact_parameters ]
</pre>

These parameters (if present) contain a hash with 3 keys: user_param, uri_param and header_param.
If a parameter already has a specific field (oli, isub, cpc, transport), it won't be present in the new generic structure.

By default, the parameters are not forwarded in a SIP to SIP call flow. The parameters '''will be forwarded''' only if:
* accessed (read) from either the inbound or outbound call parameters
* written in either the inbound or outbound call parameters

Using this code in routing script:
<pre>
puts "calling_param = #{ call[ :calling_parameters].inspect}"
</pre>

Example, From header format and what you will see in call[ :calling_parameters]:
<pre>
From:"test"<sip:4440000;user_param1=1;user_param2@10.3.10.217;uri_param3=3>;header_param4=4;tag=6F97303034343030002A2484
calling_param = {"user_param"=>"user_param1=1;user_param2", "uri_param"=>"uri_param3=3", "header_param"=>"header_param4=4"}
</pre>

'''Note''' that printing the inbound or outbound call parameters is considered as a "read" action and would result in forwarding the parameter on the outbound leg.

<pre>
From:"test"<sip:4440000@10.3.10.217;user=phone>;tag=6F97303034343030002A2484
calling_param = {"uri_param"=>"user=phone"}
</pre>

Example to insert outgoing parameters and overwrite received values.
<pre>
call [:calling_parameters] = {"user_param"=>"user_param7=7;user_param8", "uri_param"=>"uri_param9=9", "header_param"=>"header_paramA=A"}
</pre>

Example to add user=phone and keep all other uri parameters.
<pre>
if call [:calling_parameters]
if call [:calling_parameters]["uri_param"]
call[:calling_parameters]["uri_param"] << ";user=phone"
else
call [:calling_parameters]["uri_param"] = "user=phone"
end
else
call [:calling_parameters] = {"uri_param"=>"user=phone"}
end
</pre>

=== MLPP Precedence values ===

mlpp_look_for_busy:

*<tt>allowed</tt>
*<tt>path_reserved</tt>
*<tt>not_allowed</tt>

mlpp_precedence_level:

*<tt>flash_override</tt>
*<tt>flash</tt>
*<tt>immediate</tt>
*<tt>priority</tt>
*<tt>routine</tt>

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:

*<tt>nsap</tt>
*<tt>nsap_ia5</tt>
*<tt>nsap_bcd</tt>
*<tt>user</tt>

called_isub:
calling_isub:

Digits for the subaddress information.

=== Network Identification Plan ===

network_identification_plan:

*<tt>Unknown</tt> (value 0)
*<tt>cic</tt> (3 digits carrier identification code plus circuit code, value 1, SS7 or ISDN)
*<tt>user</tt> (User, value 2, ISDN only)
*<tt>cic4</tt> (4 digits carrier identification code plus circuit code, value 2, SS7 only)
*<tt>dnic</tt> (public Data Network ID, value 3, SS7 only)
*<tt>mnic</tt> (public land mobile network, value 6, SS7 only)

== 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 ==
Static routes normally chose an outbound NAP to forward the call to.

But it's also possible to create routes which outbound NAP is dynamically chosen by matching a registered user (when using [[Sip_registration_forwarding|SIP registration forwarding]]).

More information can be found [[Sip_registration_forwarding#SIP_Calls_routing|here]] about the way to control the [[Sip_registration_forwarding#SIP_Calls_routing|priority of "dynamic" vs "static" routes]].

== 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.
<pre>"file1.wav:repeat:start_off:end_off,file2.wav:repeat:start_off:end_off,file3.wav:repeat:start_off:end_off"
</pre>
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: [[Customer_application_framework:play_audio_files#Play_path_format|Path format]]

==== Example 1 ====
The following example will play file1.wav once, and then play file2.wav in loop:
"file1.wav,file2.wav:-1"

==== Example 2 ====
The following example will play file1.wav from start offset of 1 second to end offset of 3 seconds, then twice file2.wav 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 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 apply when params[:bridge][:ring_tone] is not used, because it also apply 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:
[[Toolpack:Configuring_Audio_Prompts_A|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: [[Customer_application_framework:play_audio_files#Helpful_variables_to_build_play_or_record_file_paths|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 [[#Refuse|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.

== 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 [[Routing_script_tutorial:Mini_Development_Guide#Redirecting_number,_Original_Called_Number_and_Diversion_Reason|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"
}

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

To get more information, see:
*[[Routing_script_tutorial:SIP_Redirection_Contacts|SIP Redirection Contacts Parameters in a Call Flow]]

== Connected number ==
Insert a connected number in the answer message of the call flow.

<code> 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</code>

== Terminating calls ==
In release 2.8, it is now possible to terminate a call through the routing scripts. The [[#Reason values|reason code]] must be specified in <code>params[:bridge][:reason]</code>. The <code>:terminate</code> hash must be created and copied into <code>params</code>:
terminate = {}
params[:terminate] = terminate
The following fields can then be set in <code>:terminate</code>:
* <code>:sip_header</code>
* <code>:contacts</code> # list of contacts as described in the [[#Redirection|redirection]] section
* <code>:isup_raw</code>
* <code>:isup_raw_variant</code>
* <code>:redirecting_number</code>
* <code>:redirecting_number_noa</code>
* <code>:redirecting_number_npi</code>
* <code>:redirecting_number_presentation</code>
* <code>:redirecting_number_reason</code>
* <code>:redirecting_number_counter</code>
* <code>:redirecting_number_indicator</code>
* <code>:original_called_number</code>
* <code>:original_called_number_noa</code>
* <code>:original_called_number_npi</code>
* <code>:original_called_number_presentation</code>
* <code>:original_called_number_reason</code>
* <code>:original_called_number_counter</code>

== Reason values ==

Check here for Termination Reason Cause codes: 

[[Termination_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 ==

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.

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

 If the nap status is part of a substructure, the substructure will be a hash containing all subfield elements.

Example to access the signaling type and the number of incoming call count for the NAP of the current call:

incoming_nap = params[:naps][ params[:call][ :nap ].to_sym]
log_trace 4,"Incoming NAP parameters=" + incoming_nap.inspect
log_trace 4,"Incoming NAP signaling type=" + incoming_nap[:signaling_type].inspect
log_trace 4,"Incoming NAP call cnt=" + incoming_nap[:asr_stats_incoming_struct][:total_call_cnt].inspect

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

== 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 time 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|Routing Script Tutorial]].

Routing script tutorial:Mini Development Guide

2018-07-03T18:49:51Z

Lucas Joyal: /* Script parameters protocol mapping */ Updating the list of parameters for private_address

== 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 "[[Routing_script_tutorial:Mini_Development_Guide#Reason_values|Reason values]]".

=== Script parameters protocol mapping ===

The following call parameters are available in the call object. For example:

called_number = call[:called]

{| cellspacing="1" cellpadding="1" border="1" style="width: 921px; height: 805px;"
|-
! scope="col" | '''Script parameter name'''
! scope="col" | '''ISDN '''
! scope="col" | '''R2 CAS''' 
! scope="col" | '''SS7 '''
! scope="col" | '''SIP '''
! scope="col" | '''Comment '''
! scope="col" | '''Toolpack version '''
|-
| leg_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Leg ID 
| 
|-
| session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Session ID 
| 
|-
| 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 
Q931: 'Facility CNAM' IE when presentation is allowed for DMS/NI2 variants 
| N/A 
| Q763
ITU97: 'Display information' IE - display information
ANSI95: 'Generic name' 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 

| 
| 
|-
| calling_subscriber
(Generic Number / NDS) 
| Q931: 2nd 'Calling party number' IE - Number digits 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - Number digits 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| Requires option 'support 2 calling number IE' in the profile. This variable has priority over 'private_address' in the outgoing direction. 
| 
|-
| calling_subscriber_noa 
| Q931: 2nd 'Calling party number' IE - Type of number 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - nature of address indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_npi 
| Q931: 2nd 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - numbering plan indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
 
| 
|-
| calling_subscriber_presentation 
| Q931: 2nd 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - presentation restricted indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_screening 
| Q931: 2nd 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - screening 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| private_display 
| Q931: 'Facility CNAM' IE when presentation is restricted for DMS/NI2 variants 
| 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 

| For example : The 'fluffy' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_host 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - host

SIP:Remote-party-id - host 

| For example : The 'telcobridges.com' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com> 
| 
|-
| private_address_port 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - port

SIP:Remote-party-id - port 

| For example : The '6060' in P-Asserted-Identity: "Cullen Jennings" <sip:fluffy@telcobridges.com:6060> 
| 
|-
| 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 and original called 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_indicator 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirecting indicator 
| N/A 
| 
| 
|-
| 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
(OCN) 
| 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_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_npdi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - with qualifier=Ported number is present 
| SIP:RequestURI - npdi=yes is present 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number 
| N/A 
| N/A 
| Q763: 'Generic number' IE - address signals with qualifier=Ported number 
| SIP:RequestURI - to user part when rn is present 
| rn is stored in the called number 
| 
|-
| ported_number_noa 
| N/A 
| N/A 
| Q763: 'Generic number' IE - nature of address indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number_npi 
| N/A 
| N/A 
| Q763: 'Generic number' IE - numbering plan indicator with qualifier=Ported number 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| oli
(Originating line information) 
| 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 
| Requires option 'Forward custom headers' in Profiles->SIP 
| 2.7.63 
|-
| nap
(Network Access Point) 
| N/A 
| N/A 
| N/A 
| N/A 
| Incoming leg NAP name (read-only) 
| 
|-
| type_of_network_identification 
| Q931: 'Transit network selection' IE - Type of network identification 
| N/A 
| Q763: 'Transit network selection' IE - Type of network identification 
| N/A 
| 
| 2.7 
|-
| network_identification 
| Q931: 'Transit network selection' IE - Network identification 
| N/A 
| Q763: 'Transit network selection' IE - Network identification 
| SIP: Request-Line - cic 
| 
| 2.7 
|-
| network_identification_plan 
| Q931: 'Transit network selection' IE - Network identification plan 
| N/A 
| Q763: 'Transit network selection' IE - Network identification plan 
| N/A 
| 
| 2.7 
|-
| location_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default location number forwarding behavior from incoming to outgoing leg 
| 2.7 
|-
| location_number 
| N/A 
| N/A 
| Q763: 'Location number' IE - address signals 
| N/A 
| 
| 2.7 
|-
| location_number_noa 
| N/A 
| N/A 
| Q763: 'Location number' IE - nature of address indicator 
| N/A 
| 
| 2.7 
|-
| location_number_npi 
| N/A 
| N/A 
| Q763: 'Location number' IE - numbering plan indicator 
| N/A 
| 
| 2.7 
|-
| location_number_presentation 
| N/A 
| N/A 
| Q763: 'Location number' IE - presentation restricted indicator 
| N/A 
| 
| 2.7 
|-
| location_number_screening 
| N/A 
| N/A 
| Q763: 'Location number' IE - screening 
| N/A 
| 
| 2.7 
|-
| mlpp_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| A script needs to set this to true if it wants to overwrite MLPP information in the outgoing leg. Otherwise, profile relay 'outgoing mode' applies automatically. 
| 2.7 
|-
| mlpp_look_for_busy 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - look ahead for busy 
| N/A 
| 
| 2.7 
|-
| mlpp_precedence_level 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - precedence level 
| SIP:Resource-Priority - q735 
| 
| 2.7 
|-
| mlpp_network_identity 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - network identity 
| N/A 
| 
| 2.7 
|-
| mlpp_service_domain 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - MLPP service domain 
| N/A 
| 
| 2.7 
|-
| called_isub 
| Q931: 'Called party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub parameter 
| 
| 2.7 
|-
| called_isub_type 
| Q931: 'Called party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub-encoding parameter 
| 
| 2.7 
|-
| calling_isub 
| Q931: 'Calling party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub 
| 
| 2.7 
|-
| calling_isub_type 
| Q931: 'Callinf party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub-encoding 
| 
| 2.7 
|-
| ss7_fci_default 
| N/A 
| N/A 
| Default forward call indicator (FCI) value. 
| N/A 
| Toolpack will overwrite FCI bits A, D, F, I and M with appropriate values according to call conditions 
| 2.7 
|-
| ss7_fci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_fci_default that must be forced. 
| N/A 
| Bits from ss7_fci_default which corresponding bit in ss7_fci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| ss7_bci_default 
| N/A 
| N/A 
| Default backward call indicator (BCI) value. 
| N/A 
| Toolpack will overwrite BCI bits AB, I, K, M and N with appropriate values according to call conditions 
| 2.7 
|-
| ss7_bci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_bci_default that must be forced. 
| N/A 
| Bits from ss7_bci_default which corresponding bit in ss7_bci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| tdm_ls_name_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable line service and timeslot selection to create the outgoing leg 
| 3.0 
|-
| tdm_ls_name
(Line Service or T1/E1 trunk) 
| Incoming leg line service name 
| Incoming leg line service name 
| Incoming leg line service name 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this line service name to create outgoing leg 
| 2.7 
|-
| tdm_timeslot_nb 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| N/A 
| if tdm_ls_name_forward_enabled is set, try to use this timeslot number to create outgoing leg 
| 2.7 
|-
| rtp_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP port 
| (read-only) 
| 2.7 
|-
| rtp_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP port 
| (read-only) 
| 2.7 
|-
| ss7_cot_enabled 
| N/A 
| N/A 
| Requests SS7 in-call continuity test for this outgoing SS7 call 
| N/A 
| Toolpack will request a continuity test on the timeslot before making the outgoing call. If COT fails, the call will be dropped (then another route may be attempted) 
| 2.8 
|-
| reverse_charging_indication 
| Incoming leg Reverse charging indication IE present 
| N/A 
| N/A 
| N/A 
| If set in routing script, will add Reverse charging indication IE in outgoing leg (also use reverse_charging_indication_forward_enabled) 
| 2.8.12 
|-
| reverse_charging_indication_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable forwarding of reverse charging indication from incoming to outgoing leg 
| 2.8.12 
|-
| sip_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP UDP port 
| (read-only) 
| 2.8.13 
|-
| sip_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP UDP port 
| (read-only) 
| 2.8.13 
|}

 

=== Noa values ===

*<tt>unknown_number (0x2)</tt>
*<tt>international_number (0x4)</tt>
*<tt>national_number (0x3)</tt>
*<tt>subscriber_number (0x1)</tt>
*<tt>network_specific (0x5)</tt>
*<tt>network_routing_national_format (0x7)</tt>
*<tt>network_routing_international_format (0x8)</tt>
*<tt>abbreviated_number (0x6)</tt>
*<tt>subscriber_number_operator_requested (0x71)</tt>
*<tt>national_number_operator_requested (0x72)</tt>
*<tt>international_number_operator_requested (0x73)</tt>
*<tt>no_number_present_operator_requested (0x74)</tt>
*<tt>no_number_present_cut_through_call_to_carrier (0x75)</tt>
*<tt>test_line_test_code (0x77)</tt>
*<tt>non_unique_subscriber_number (0x71)</tt>
*<tt>non_unique_national_number (0x73)</tt>
*<tt>non_unique_international_number (0x74)</tt>
*<tt>call_950_numbe (0x76)</tt>
*<tt>special_number (0x73)</tt>
*<tt>national_number_with_transit_network_selection (0x74)</tt>
*<tt>international_number_with_transit_network_selection (0x75)</tt>

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

*<tt>call_params[:called_noa] = 0x70</tt>

or

*<tt>call_params[:called_noa] = 112</tt>

=== Npi values ===

*<tt>unknown_number</tt>
*<tt>isdn</tt>
*<tt>telephony</tt>
*<tt>private</tt>
*<tt>data</tt>
*<tt>telex</tt>
*<tt>national</tt>

=== Calling Display Type values ===

*<tt>unspecified</tt> => Type is unspecified.
*<tt>calling_party_name</tt> => Type is 0xB1.

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

*<tt>call_params[:calling_display_type] = 0xB1</tt>

or

*<tt>call_params[:calling_display_type] = 177</tt>

=== Calling Display value ===

*<tt>call_params[:calling_display] = "Roger Fluffy"</tt>

=== Presentation values for Calling number, Calling Subscriber (Generic Number), Redirecting Number, Original Called Number (OCN) and Location Number ===

*<tt>unspecified</tt>
*<tt>not_available (0x2)</tt>
*<tt>allowed (0x0)</tt>
*<tt>restricted (0x1)</tt>
*<tt>addr_restricted</tt>
*<tt>name_restricted</tt>

=== Calling Party Category ===
values for calling_category
*<tt>unspecified</tt> <tt>(0xa)</tt>
*<tt>unknown</tt> <tt>(0x0)</tt>
*<tt>operator_french</tt> <tt>(0x1)</tt>
*<tt>operator_english</tt> <tt>(0x2)</tt>
*<tt>operator_german</tt> <tt>(0x3)</tt>
*<tt>operator_russian</tt> <tt>(0x4)</tt>
*<tt>operator_spanish</tt> <tt>(0x5)</tt>
*<tt>subscriber</tt> <tt>(0xa)</tt>
*<tt>subscriber_with_priority</tt> <tt>(0xb)</tt>
*<tt>data</tt> <tt>(0xc)</tt>
*<tt>test</tt> <tt>(0xd)</tt>
*<tt>payphone</tt> <tt>(0xf)</tt>

=== Screening values for Calling number, Calling Subscriber (Generic Number), and Location Number ===

*<tt>unspecified</tt>
*<tt>no (0x0)</tt>
*<tt>pass (0x1)</tt>
*<tt>fail (0x2)</tt>
*<tt>network_provided (0x3)</tt>

=== Redirecting indicator values ===

SS7:

*<tt>no_redirection</tt>
*<tt>call_rerouted</tt>
*<tt>call_rerouted_all_restricted</tt>
*<tt>call_diverted</tt>
*<tt>call_diverted_all_restricted</tt>
*<tt>call_rerouted_restricted</tt>
*<tt>call_diverted_restricted</tt>
*<tt>spare</tt>

=== Redirecting number, Original Called Number and Diversion Reason ===

ISDN:

*<tt>unknown</tt>
*<tt>busy</tt>
*<tt>no_reply</tt>
*<tt>deflection</tt>
*<tt>dte_out_of_order</tt>
*<tt>forwarding_by_called_dte</tt>
*<tt>unconditional</tt>

SS7:

*<tt>unknown</tt>
*<tt>busy (SIP: user-busy)</tt>
*<tt>no_reply (SIP: no-answer)</tt>
*<tt>unconditional</tt>
*<tt>deflection</tt>
*<tt>deflection_immediate</tt>
*<tt>mobile_not_reachable</tt>

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

*<tt>digital</tt>
*<tt>restricted_digital</tt>
*<tt>digital_with_tones</tt>
*<tt>speech</tt>
*<tt>3_1_khz_audio</tt>
*<tt>video</tt>

=== 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:
<pre>Request-Line: INVITE sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0</pre>
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: 
<pre> if call_params[:request_uri] && call_params[:request_uri] =~ /sip:(.*)@.*/
call_params[:called] = $1
end
</pre>
=== 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. 

=== 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 hash format for a releases older than rel2.7.161.

It has been changed to string format because using a hash does not allow having multiple times the same header for certain releases of rel2.8 and rel2.9

Beginning from rel2.10.21, both hash and string format are supported to construct the outgoing SIP header; however, only string format is used for the incoming SIP header.

'''hash format:'''
<pre>call[ :sip_header ] = {"P-my-custom-header"=>"value1", "P-my-custom-header2"=>"value2", "P-my-custom-header3"=>"value3"}</pre>

'''string format:'''
<pre>call[ :sip_header ] = "P-my-custom-header:value1 \nP-my-custom-header2:value2 \nP-my-custom-header3:value3"
</pre>
(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:
<pre>
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
</pre>

=== sip uri parameters ===
Access to parameters of several SIP headers (To, From, P-Asserted-Identity, Remote-Party-ID, Contact).

<pre>
call[ :calling_parameters ]
call[ :called_parameters ]
call[ :private_address_parameters ] (for P-Asserted-Identity or Remote-Party-ID)
call[ :contact_parameters ]
</pre>

These parameters (if present) contain a hash with 3 keys: user_param, uri_param and header_param.
If a parameter already has a specific field (oli, isub, cpc, transport), it won't be present in the new generic structure.

By default, the parameters are not forwarded in a SIP to SIP call flow. The parameters '''will be forwarded''' only if:
* accessed (read) from either the inbound or outbound call parameters
* written in either the inbound or outbound call parameters

Using this code in routing script:
<pre>
puts "calling_param = #{ call[ :calling_parameters].inspect}"
</pre>

Example, From header format and what you will see in call[ :calling_parameters]:
<pre>
From:"test"<sip:4440000;user_param1=1;user_param2@10.3.10.217;uri_param3=3>;header_param4=4;tag=6F97303034343030002A2484
calling_param = {"user_param"=>"user_param1=1;user_param2", "uri_param"=>"uri_param3=3", "header_param"=>"header_param4=4"}
</pre>

'''Note''' that printing the inbound or outbound call parameters is considered as a "read" action and would result in forwarding the parameter on the outbound leg.

<pre>
From:"test"<sip:4440000@10.3.10.217;user=phone>;tag=6F97303034343030002A2484
calling_param = {"uri_param"=>"user=phone"}
</pre>

Example to insert outgoing parameters and overwrite received values.
<pre>
call [:calling_parameters] = {"user_param"=>"user_param7=7;user_param8", "uri_param"=>"uri_param9=9", "header_param"=>"header_paramA=A"}
</pre>

Example to add user=phone and keep all other uri parameters.
<pre>
if call [:calling_parameters]
if call [:calling_parameters]["uri_param"]
call[:calling_parameters]["uri_param"] << ";user=phone"
else
call [:calling_parameters]["uri_param"] = "user=phone"
end
else
call [:calling_parameters] = {"uri_param"=>"user=phone"}
end
</pre>

=== MLPP Precedence values ===

mlpp_look_for_busy:

*<tt>allowed</tt>
*<tt>path_reserved</tt>
*<tt>not_allowed</tt>

mlpp_precedence_level:

*<tt>flash_override</tt>
*<tt>flash</tt>
*<tt>immediate</tt>
*<tt>priority</tt>
*<tt>routine</tt>

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:

*<tt>nsap</tt>
*<tt>nsap_ia5</tt>
*<tt>nsap_bcd</tt>
*<tt>user</tt>

called_isub:
calling_isub:

Digits for the subaddress information.

=== Network Identification Plan ===

network_identification_plan:

*<tt>Unknown</tt> (value 0)
*<tt>cic</tt> (3 digits carrier identification code plus circuit code, value 1, SS7 or ISDN)
*<tt>user</tt> (User, value 2, ISDN only)
*<tt>cic4</tt> (4 digits carrier identification code plus circuit code, value 2, SS7 only)
*<tt>dnic</tt> (public Data Network ID, value 3, SS7 only)
*<tt>mnic</tt> (public land mobile network, value 6, SS7 only)

== 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 ==
Static routes normally chose an outbound NAP to forward the call to.

But it's also possible to create routes which outbound NAP is dynamically chosen by matching a registered user (when using [[Sip_registration_forwarding|SIP registration forwarding]]).

More information can be found [[Sip_registration_forwarding#SIP_Calls_routing|here]] about the way to control the [[Sip_registration_forwarding#SIP_Calls_routing|priority of "dynamic" vs "static" routes]].

== 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.
<pre>"file1.wav:repeat:start_off:end_off,file2.wav:repeat:start_off:end_off,file3.wav:repeat:start_off:end_off"
</pre>
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: [[Customer_application_framework:play_audio_files#Play_path_format|Path format]]

==== Example 1 ====
The following example will play file1.wav once, and then play file2.wav in loop:
"file1.wav,file2.wav:-1"

==== Example 2 ====
The following example will play file1.wav from start offset of 1 second to end offset of 3 seconds, then twice file2.wav 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 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 apply when params[:bridge][:ring_tone] is not used, because it also apply 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:
[[Toolpack:Configuring_Audio_Prompts_A|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: [[Customer_application_framework:play_audio_files#Helpful_variables_to_build_play_or_record_file_paths|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 [[#Refuse|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.

== 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 [[Routing_script_tutorial:Mini_Development_Guide#Redirecting_number,_Original_Called_Number_and_Diversion_Reason|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"
}

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

To get more information, see:
*[[Routing_script_tutorial:SIP_Redirection_Contacts|SIP Redirection Contacts Parameters in a Call Flow]]

== Connected number ==
Insert a connected number in the answer message of the call flow.

<code> 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</code>

== Terminating calls ==
In release 2.8, it is now possible to terminate a call through the routing scripts. The [[#Reason values|reason code]] must be specified in <code>params[:bridge][:reason]</code>. The <code>:terminate</code> hash must be created and copied into <code>params</code>:
terminate = {}
params[:terminate] = terminate
The following fields can then be set in <code>:terminate</code>:
* <code>:sip_header</code>
* <code>:contacts</code> # list of contacts as described in the [[#Redirection|redirection]] section
* <code>:isup_raw</code>
* <code>:isup_raw_variant</code>
* <code>:redirecting_number</code>
* <code>:redirecting_number_noa</code>
* <code>:redirecting_number_npi</code>
* <code>:redirecting_number_presentation</code>
* <code>:redirecting_number_reason</code>
* <code>:redirecting_number_counter</code>
* <code>:redirecting_number_indicator</code>
* <code>:original_called_number</code>
* <code>:original_called_number_noa</code>
* <code>:original_called_number_npi</code>
* <code>:original_called_number_presentation</code>
* <code>:original_called_number_reason</code>
* <code>:original_called_number_counter</code>

== Reason values ==

Check here for Termination Reason Cause codes: 

[[Termination_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 ==

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.

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

 If the nap status is part of a substructure, the substructure will be a hash containing all subfield elements.

Example to access the signaling type and the number of incoming call count for the NAP of the current call:

incoming_nap = params[:naps][ params[:call][ :nap ].to_sym]
log_trace 4,"Incoming NAP parameters=" + incoming_nap.inspect
log_trace 4,"Incoming NAP signaling type=" + incoming_nap[:signaling_type].inspect
log_trace 4,"Incoming NAP call cnt=" + incoming_nap[:asr_stats_incoming_struct][:total_call_cnt].inspect

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

== 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 time 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|Routing Script Tutorial]].

FreeSBC:Cloud:AWS Installation A

2018-04-13T12:39:50Z

Lucas Joyal: Add region explaination

{{DISPLAYTITLE:FreeSBC:Cloud:AWS Installation}}

This page is intended to give assistance to people launching an instance of ''FreeSBC'' using an Amazon Machine Image (AMI) on Amazon Web Service (AWS).

== Instantiate a FreeSBC ==
* After logging in your Amazon account, click on “EC2” in the main AWS console:
[[File:ConsoleEC2.png| 600px]]

* On the left menu, click on “AMIs”:
[[File:AMIs.png| 100px]]

* Click on the filter drop list and select “Private image” to locate FreeSBC AMI:
[[File:PrivateImages.png| 500px]]

* Select the region matching the region of the FreeSBC AMI you want to test. If you don't know it, try "Canada (Central)".

[[File:RegionAMI.png| 700px]]

* Select the image and click “Launch”:
[[File:SelectAMI.png| 700px]]

* Select the instance type and its resources. The recommended instance type is:
** m4.large (2 vCPU, 8 GiB)
* Supported instance type are:
** C3, C4, D2, I2, M4 (excluding m4.16xlarge), and R3 instances ([https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enhanced-networking.html Supported instances from Amazon documentation])
[[File:SelectResources.png| 800px]]

* Choose an existing subnet from the list (Do not leave it to default, to allow for multiple network interfaces):
* Click "Add Device" under Network Interface section to add a second IP interface (as FreeSBC requires 2 network interfaces)
* Click “Add Storage” to proceed to the next page:
[[File:ChooseSubnet.png| 1000px]]

* Change the Volume Size to 40Gb.
* Select "Volume Type": gp2
* Click “Add Tags” to proceed to the next page.
[[File:NextTag.png| 800px]]

* You can leave the default parameters as they are.
* Click “Configure Security Group” to proceed to the next page:
[[File:NextSecurityGroup.png| 800px]]

* Select "Create a new security group". We recommend that you simply open all ports on your own IP address, since the SBC contains its own internal firewall:

{| class="wikitable"
|-
! Rule !! Type !! Port Range !! Source IP
|-
| All traffic || All traffic || 0 - 65535 || (Use your own public IP)
|}
[[File:AddRule.png| 600px ]]

* Click “Launch”. Please note that FreeSBC is free of charges. However, you will still be billed by Amazon for the instance resources:
[[File:Launch.png| 1000px]]

* You will be prompted to create a key pair, allowing you to securely connect to your instance. Select “Create a new key pair” if you do not own one, and give it a name. Then, click on “Download Key Pair” to download a .pem file since it is needed for a SSH connection. (Note: Make sure to not lose it, since you would then lose access the the SSH connection for the instance):
[[File:DownloadKey.png| 800px]]

* Click on “Launch Instances”:
[[File:LaunchWithKey.png| 800px]]

* You can view your instance by clicking on “View Instances”:
[[File:ViewInstance.png| 800px]]

* Select the instance you just created and feel free to give it a name:
[[File:RenameInstance.png| 800px]]

* For your instance to become accessible, you need to associate a public IP generated by Amazon (called "Elastic IP"). Click on "Elastic IP" on the left, then click on "Allocate new address":
[[File:ElasticIP.png| 300px]]

* Click on "Allocate IP". A new public IP will be generated by Amazon:
[[File:AllocateIP.png| 600px]]

* Click on "Close":
[[File:NewIP.png| 600px]]

* Go to the left pane and click on "Instance". Then select the instance "FreeSBC" to display its description:
[[File:IPforInstance.png| 600px]]

* Find the '''eth1''' network interface in the instance description:
[[File:GetTheRightNetworkInterface.png| 1100px]]

* Click on the '''eth1''' Network Interface, then click on the "Interface ID" link:
[[File:InterfaceID.png| 1100px]]

* Right-click on the selected Network Interface, then click "Associate Address":
[[File:AssociateAddress.png| 800px]]

* In the Address list, select the public IP to associate with the main Network Interface. Then, click on "Associate Address":
[[File:SelectAddress.png| 800px]]

* Click on "Instances" on the left pane and select "FreeSBC" instance. Check if your instance is associated with a public IP:
[[File:Ready.png| 1100px]]

You are ready to connect to '''FreeSBC''' instance on AWS through the Web Portal. To connect to the Web Portal, use the public IP address with the port
like this: [http://<Public IP>:12358/]

*Username:
** root
*Password:
** <The ID of the instance on which the web portal is running.>

Take note that it may take a while for the FreeSBC system to make the Web Portal available (around 3-5 minutes).

== Validating the installation ==
To test that the FreeSBC was correctly installed, you can call a special number via any SIP phone to get an automated message from the FreeSBC

* Call the number 5551234@<FreeSBC's public IP address>

You should get a message from the FreeSBC along with a "special treat" :).

== Troubleshooting ==
* [[FreeSBC:Cloud:AWS_Installation_Troubleshooting_A|Installation troubleshooting]]

[[Category:Revise on Major]]

File:RegionAMI.png

2018-04-13T12:39:06Z

Lucas Joyal: Region to select to view the AMIs

Region to select to view the AMIs

File:Launch.png

2018-03-28T15:42:18Z

Lucas Joyal: uploaded a new version of "File:Launch.png"

File:Launch.png

2018-03-28T15:40:50Z

Lucas Joyal: uploaded a new version of "File:Launch.png"

File:AddRule.png

2018-03-28T15:40:06Z

Lucas Joyal: uploaded a new version of "File:AddRule.png"

File:Ready.png

2018-03-28T15:39:11Z

Lucas Joyal: uploaded a new version of "File:Ready.png"

File:InterfaceID.png

2018-03-28T15:38:30Z

Lucas Joyal: uploaded a new version of "File:InterfaceID.png"

File:GetTheRightNetworkInterface.png

2018-03-28T15:37:36Z

Lucas Joyal: uploaded a new version of "File:GetTheRightNetworkInterface.png"

FreeSBC:Cloud:AWS Installation A

2018-03-28T15:34:32Z

Lucas Joyal: Update text copied from old system

{{DISPLAYTITLE:FreeSBC:Cloud:AWS Installation}}

This page is intended to give assistance to people launching an instance of ''FreeSBC'' using an Amazon Machine Image (AMI) on Amazon Web Service (AWS).

== Instantiate a FreeSBC ==
* After logging in your Amazon account, click on “EC2” in the main AWS console:
[[File:ConsoleEC2.png| 600px]]

* On the left menu, click on “AMIs”:
[[File:AMIs.png| 100px]]

* Click on the filter drop list and select “Private image” to locate FreeSBC AMI:
[[File:PrivateImages.png| 500px]]

* Select the image and click “Launch”:
[[File:SelectAMI.png| 700px]]

* Select the instance type and its resources. The recommended instance type is:
** m4.large (2 vCPU, 8 GiB)
* Supported instance type are:
** C3, C4, D2, I2, M4 (excluding m4.16xlarge), and R3 instances ([https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enhanced-networking.html Supported instances from Amazon documentation])
[[File:SelectResources.png| 800px]]

* Choose an existing subnet from the list (Do not leave it to default, to allow for multiple network interfaces):
* Click "Add Device" under Network Interface section to add a second IP interface (as FreeSBC requires 2 network interfaces)
* Click “Add Storage” to proceed to the next page:
[[File:ChooseSubnet.png| 1000px]]

* Change the Volume Size to 40Gb.
* Select "Volume Type": gp2
* Click “Add Tags” to proceed to the next page.
[[File:NextTag.png| 800px]]

* You can leave the default parameters as they are.
* Click “Configure Security Group” to proceed to the next page:
[[File:NextSecurityGroup.png| 800px]]

* Select "Create a new security group". We recommend that you simply open all ports on your own IP address, since the SBC contains its own internal firewall:

{| class="wikitable"
|-
! Rule !! Type !! Port Range !! Source IP
|-
| All traffic || All traffic || 0 - 65535 || (Use your own public IP)
|}
[[File:AddRule.png| 600px ]]

* Click “Launch”. Please note that FreeSBC is free of charges. However, you will still be billed by Amazon for the instance resources:
[[File:Launch.png| 1000px]]

* You will be prompted to create a key pair, allowing you to securely connect to your instance. Select “Create a new key pair” if you do not own one, and give it a name. Then, click on “Download Key Pair” to download a .pem file since it is needed for a SSH connection. (Note: Make sure to not lose it, since you would then lose access the the SSH connection for the instance):
[[File:DownloadKey.png| 800px]]

* Click on “Launch Instances”:
[[File:LaunchWithKey.png| 800px]]

* You can view your instance by clicking on “View Instances”:
[[File:ViewInstance.png| 800px]]

* Select the instance you just created and feel free to give it a name:
[[File:RenameInstance.png| 800px]]

* For your instance to become accessible, you need to associate a public IP generated by Amazon (called "Elastic IP"). Click on "Elastic IP" on the left, then click on "Allocate new address":
[[File:ElasticIP.png| 300px]]

* Click on "Allocate IP". A new public IP will be generated by Amazon:
[[File:AllocateIP.png| 600px]]

* Click on "Close":
[[File:NewIP.png| 600px]]

* Go to the left pane and click on "Instance". Then select the instance "FreeSBC" to display its description:
[[File:IPforInstance.png| 600px]]

* Find the '''eth1''' network interface in the instance description:
[[File:GetTheRightNetworkInterface.png| 1100px]]

* Click on the '''eth1''' Network Interface, then click on the "Interface ID" link:
[[File:InterfaceID.png| 1100px]]

* Right-click on the selected Network Interface, then click "Associate Address":
[[File:AssociateAddress.png| 800px]]

* In the Address list, select the public IP to associate with the main Network Interface. Then, click on "Associate Address":
[[File:SelectAddress.png| 800px]]

* Click on "Instances" on the left pane and select "FreeSBC" instance. Check if your instance is associated with a public IP:
[[File:Ready.png| 1100px]]

You are ready to connect to '''FreeSBC''' instance on AWS through the Web Portal. To connect to the Web Portal, use the public IP address with the port
like this: [http://<Public IP>:12358/]

*Username:
** root
*Password:
** <The ID of the instance on which the web portal is running.>

Take note that it may take a while for the FreeSBC system to make the Web Portal available (around 3-5 minutes).

== Validating the installation ==
To test that the FreeSBC was correctly installed, you can call a special number via any SIP phone to get an automated message from the FreeSBC

* Call the number 5551234@<FreeSBC's public IP address>

You should get a message from the FreeSBC along with a "special treat" :).

== Troubleshooting ==
* [[FreeSBC:Cloud:AWS_Installation_Troubleshooting_A|Installation troubleshooting]]

[[Category:Revise on Major]]

Filter parameters reference guide A

2017-12-04T21:28:33Z

Lucas Joyal: Explain the new changes in the timestamp and duration

{{DISPLAYTITLE:Filter parameters reference guide}}

===Filter parameter===

When using the Call trace API to select a subset of calls, these are the parameter that can be used in the query.

{| cellpadding="5" border="1" class="wikitable"
! Parameter
! Format
! Description
|-
|uct_call_id
|Hexadecimal
|Will return the call matching this ID.
|-
|direction
|Integer
|Incoming (1), outgoing (2), Mixer(3), Media only (4) .
|-
|max
|Integer
|Max number of call that will be matched by the filter.
|-
|called
|String
|Called number. Will match partial substrings of phone numbers.
|-
|calling
|String
|Calling number. Will match partial substrings of phone numbers.
|-
|nap
|String
|Nap used by the call.
|-
|protocol
|String
|Protocol used by the call (SS7, SIP, ISDN, CAS).
|-
|route
|String
|Name of the route used by the call.
|-
|call_id
|String
|Call Id.
|-
|recorded
|String
| String can either be "RECORDED" or "NOTRECORDED".
|-
|call_state
|String
|"ACTIVE" or "INACTIVE"
|-
|terminate_reason
|String or Integer
|"NORMAL", "NOT_NORMAL" or the cause Integer value.
|-
|call_duration
|Integer
|All calls with a duration (in seconds) under the value of "call_duration". When the value prefixed by a '>', it will return all calls greater than the value.
A range can be obtained by inputing 2 values in the format 'x-y', where x is the minimum duration and y is the maximum.
|-
|intercepted
|Boolean
|True or false: Match all legs that are intercepted (if true) or all that are not (if false).
|-
|interception_leg
|Boolean
|Match all legs that are Interception legs
|-
|interception_liid
|String
|Match all legs that match the interception LIID
|-
|start
|Integer or String
|Unix timestamp (in milliseconds) for the beginning of the call. Match calls with a greater timestamp value. An [https://www.epochconverter.com/ external website] can be used for converting the time into a timestamp. Can also use a string in the following format: 'YYYY-mm-dd HH:MM:SS'. Note that the timezone used will be the one on the queried system.
|-
|end
|Integer or String
|Unix timestamp (in milliseconds) for the end of the call. Match calls with a lesser timestamp value. An [https://www.epochconverter.com/ external website] can be used for converting the time into a timestamp. Can also use a string in the following format: 'YYYY-mm-dd HH:MM:SS'. Note that the timezone used will be the one on the queried system.
|-
|drop_call
|Boolean
|Flag used to signify that all calls matching the filter parameters will be terminated. Use with caution when dropping multiple calls at once.
|-
|}

[[Category:Revise on Major]]

Filter parameters reference guide A

2017-12-01T20:39:12Z

Lucas Joyal: Explain detail about calling and called numbers in string

{{DISPLAYTITLE:Filter parameters reference guide}}

===Filter parameter===

When using the Call trace API to select a subset of calls, these are the parameter that can be used in the query.

{| cellpadding="5" border="1" class="wikitable"
! Parameter
! Format
! Description
|-
|uct_call_id
|Hexadecimal
|Will return the call matching this ID.
|-
|direction
|Integer
|Incoming (1), outgoing (2), Mixer(3), Media only (4) .
|-
|max
|Integer
|Max number of call that will be matched by the filter.
|-
|called
|String
|Called number. Will match partial substrings of phone numbers.
|-
|calling
|String
|Calling number. Will match partial substrings of phone numbers.
|-
|nap
|String
|Nap used by the call.
|-
|protocol
|String
|Protocol used by the call (SS7, SIP, ISDN, CAS).
|-
|route
|String
|Name of the route used by the call.
|-
|call_id
|String
|Call Id.
|-
|recorded
|String
| String can either be "RECORDED" or "NOTRECORDED".
|-
|call_state
|String
|"ACTIVE" or "INACTIVE"
|-
|terminate_reason
|String or Integer
|"NORMAL", "NOT_NORMAL" or the cause Integer value.
|-
|call_duration
|Integer
|All calls with a duration (in seconds) under the value of "call_duration".
|-
|intercepted
|Boolean
|True or false: Match all legs that are intercepted (if true) or all that are not (if false).
|-
|interception_leg
|Boolean
|Match all legs that are Interception legs
|-
|interception_liid
|String
|Match all legs that match the interception LIID
|-
|start
|Integer
|Unix timestamp (in seconds) for the beginning of the call. Match calls with a greater timestamp value. An [https://www.epochconverter.com/ external website] can be used for converting the time into a timestamp
|-
|end
|Integer
|Unix timestamp (in seconds) for the end of the call. Match calls with a lesser timestamp value. An [https://www.epochconverter.com/ external website] can be used for converting the time into a timestamp
|-
|drop_call
|Boolean
|Flag used to signify that all calls matching the filter parameters will be terminated. Use with caution when dropping multiple calls at once.
|-
|}

[[Category:Revise on Major]]

RESTful API: Dropping calls

2017-12-01T20:37:27Z

Lucas Joyal: Add missing hostname in command

The following use case provide guidance for dropping multiple calls:

== Usage Example ==
<code>
tbconfig -h <hostname> --port <port> -u <username> -p <password> -d -q "parameter1=value1,parameter2=value2" /call_traces/destroy_all
</code>

* -d flag is used to send a HTTP DELETE request method
* -q is used to append the argument in the HTTP request

Be careful when sending this command, as a too broad request '''will''' drop all active calls.

== Reference ==
[[Filter_parameters_reference_guide_A|Filter parameters reference guide]]

RESTful API: Dropping calls

2017-11-28T17:58:29Z

Lucas Joyal: Change order of arguments to have the URL at the end (cleaner)

The following use case provide guidance for dropping multiple calls:

<code>
tbconfig --port <port> -u <username> -p <password> -d -q "parameter1=value1,parameter2=value2" /call_traces/destroy_all
</code>

The -d flag is used to send a HTTP DELETE request method and the -q is used to append the argument in the HTTP request.

Be careful when sending this command, as a too broad request '''will''' drop all active calls.

For a list of parameters that can be used, consult: [[Filter_parameters_reference_guide_A|Filter parameters reference guide]]

Filter parameters reference guide A

2017-11-27T20:11:45Z

Lucas Joyal: Add parameters

{{DISPLAYTITLE:Filter parameters reference guide}}

===Filter parameter===

When using the Call trace API to select a subset of calls, these are the parameter that can be used in the query.

{| cellpadding="5" border="1" class="wikitable"
! Parameter
! Format
! Description
|-
|uct_call_id
|Hexadecimal
|Will return the call matching this ID.
|-
|direction
|Integer
|Incoming (1), outgoing (2), Mixer(3), Media only (4) .
|-
|max
|Integer
|Max number of call that will be matched by the filter.
|-
|called
|String
|Called number.
|-
|calling
|String
|Calling number.
|-
|nap
|String
|Nap used by the call.
|-
|protocol
|String
|Protocol used by the call (SS7, SIP, ISDN, CAS).
|-
|route
|String
|Name of the route used by the call.
|-
|call_id
|String
|Call Id.
|-
|recorded
|String
| String can either be "RECORDED" or "NOTRECORDED".
|-
|call_state
|String
|"ACTIVE" or "INACTIVE"
|-
|terminate_reason
|String or Integer
|"NORMAL", "NOT_NORMAL" or the cause Integer value.
|-
|call_duration
|Integer
|All calls with a duration (in seconds) under the value of "call_duration".
|-
|intercepted
|Boolean
|True or false: Match all legs that are intercepted (if true) or all that are not (if false).
|-
|interception_leg
|Boolean
|Match all legs that are Interception legs
|-
|interception_liid
|String
|Match all legs that match the interception LIID
|-
|start
|Integer
|Unix timestamp (in seconds) for the beginning of the call. Match calls with a greater timestamp value. An [https://www.epochconverter.com/ external website] can be used for converting the time into a timestamp
|-
|end
|Integer
|Unix timestamp (in seconds) for the end of the call. Match calls with a lesser timestamp value. An [https://www.epochconverter.com/ external website] can be used for converting the time into a timestamp
|-
|drop_call
|Boolean
|Flag used to signify that all calls matching the filter parameters will be terminated. Use with caution when dropping multiple calls at once.
|-
|}

Filter parameters reference guide A

2017-11-27T19:52:46Z

Lucas Joyal:

Use Cases: Dropping calls with Tbstatus

2017-11-27T18:54:14Z

Lucas Joyal:

The following use case provide guidance for dropping multiple calls with tbstatus:

<code>
tbstatus /uct/call:"filter(drop_call=true,parameter1=value1,parameter2=value2,...)"
</code>

Be careful when sending this command, as a too broad request '''will''' drop all active calls.

For a list of parameters that can be used, consult: [[Filter_parameters_reference_guide_A|Filter parameters reference guide]]

Use Cases: Dropping calls with Tbstatus

2017-11-27T18:53:55Z

Lucas Joyal: Add tbstatus use case

The following use case provide guidance for dropping multiple calls with tbstatus:

<code>
tbstatus /uct/call:"filter(drop_call=true,parameter1=value1,parameter1=value1,...)"
</code>

Be careful when sending this command, as a too broad request '''will''' drop all active calls.

For a list of parameters that can be used, consult: [[Filter_parameters_reference_guide_A|Filter parameters reference guide]]

Use Cases:Call Trace A

2017-11-27T18:27:24Z

Lucas Joyal: Add reference guide

=== '''''Applies to version(s): v3.0''''' ===
{{DISPLAYTITLE:Use Cases:Call Trace}}
==Dropping multiple calls==
{| cellpadding="5" border="1" class="wikitable"
! width="250" style="background: none repeat scroll 0% 0% rgb(239, 239, 239); -moz-background-inline-policy: continuous;" | Via [[Toolpack_Application:tbconfig|Tbconfig]]
! width="250" style="background: none repeat scroll 0% 0% rgb(239, 239, 239); -moz-background-inline-policy: continuous;" | Via [[Toolpack_Application:tbstatus|Tbstatus]]
|-
| valign="top" |
*[[RESTful_API:_Dropping_calls|Dropping calls via Tbconfig]]
| valign="top" |
* [[Use_Cases:_Dropping_calls_with_Tbstatus|Dropping calls via Tbstatus]]
|}

=== Filter parameters ===
* [[Filter_parameters_reference_guide_A|Filter parameters reference guide]]

RESTful API: Dropping calls

2017-11-27T18:11:57Z

Lucas Joyal: Drop call via tbconfig, first draft.

The following use case provide guidance for dropping multiple calls:

<code>
tbconfig --port <port> -u <username> -p <password> /call_traces/destroy_all -d -q "parameter1=value1,parameter2=value2"
</code>

The -d flag is used to send a HTTP DELETE request method and the -q is used to append the argument in the HTTP request.

Be careful when sending this command, as a too broad request '''will''' drop all active calls.

For a list of parameters that can be used, consult: [[Filter_parameters_reference_guide_A|Filter parameters reference guide]]

Use Cases:Call Trace A

2017-11-27T17:52:19Z

Lucas Joyal: DISPLAYTITLE

Filter parameters reference guide A

2017-11-27T17:49:30Z

Lucas Joyal: display title

Call Trace

2017-11-27T17:48:20Z

Lucas Joyal:

Call trace (uct) was created to trace the callflow from any incoming call through the Tmedia system. It allows to see the incoming call, the routing decision, outgoing calls, other outgoing calls if there is route retry, the parameters selected for SIP SDP, the SIP Call-id, the trunk and timeslot chosen for TDM protocols, the termination result code, and more.

It allows to store information for long periods of time and search for calls in history. The last 10,000 call legs (default size) can be seen directly in the web portal. Older logs can be loaded and viewed on the same system, or exported to other systems. Once a specific call has been consulted, it will remain in memory for a longer period of time, so that it can be consulted later on. Calls to view can be filtered according to called number, calling number, Network Access Point (NAP), time of day range, protocol and direction.

== Features ==
* Troubleshooting call flows
* Download audio from recorded calls
* Terminate suspicious calls

=== Filter parameters ===
* [[Filter_parameters_reference_guide_A|Filter parameters reference guide]]

== Configuration ==
* Web Portal v3.0
**[[Toolpack:Tsbc_Troubleshooting_3.0|FreeSBC Call Trace]]
**[[Toolpack:Troubleshooting_D|Tmedia Call Trace]]
* Web Portal v2.10
**[[Toolpack:Tsbc_Troubleshooting_A#Call_Trace|Tsbc Call Trace]]
**[[Toolpack:Troubleshooting_C#Call_Trace|Tmedia Call Trace]]
*[[Toolpack:Troubleshooting_B#Call_Trace|Web Portal v2.9: Call Trace]]

[[Category:Revise on Major]]

Filter parameters reference guide A

2017-11-27T17:25:03Z

Lucas Joyal: Initial parameter table format (complete)

===Filter parameter===

When using the Call trace API to select a subset of calls, these are the parameter that can be used in the query.

{| cellpadding="5" border="1" class="wikitable"
! Parameter
! Format
! Description
|-
|uct_call_id
|Hexadecimal
|Will return the call matching this ID.
|-
|direction
|Integer
|Incoming (1), outgoing (2), Mixer(3), Media only (4) .
|-
|called
|String
|Called number.
|-
|calling
|String
|Calling number.
|-
|nap
|String
|Nap used by the call.
|-
|protocol
|String
|Protocol used by the call (SS7, SIP, ISDN, CAS).
|-
|route
|String
|Name of the route used by the call.
|-
|call_id
|String
|Call Id.
|-
|recorded
|String
| String can either be "RECORDED" or "NOTRECORDED".
|-
|call_state
|String
|"Active" or "INACTIVE"
|-
|terminate_reason
|String or Integer
|"NORMAL", "NOT_NORMAL" or the cause Integer value.
|-
|call_duration
|Integer
|All calls with a duration (in seconds) under the value of "call_duration".
|-
|intercepted
|Boolean
|True or false: Match all legs that are intercepted (if true) or all that are not (if false).
|-
|interception_leg
|Boolean
|Match all legs that are Interception legs
|-
|interception_liid
|String
|Match all legs that match the interception LIID
|-
|drop_call
|Boolean
|Flag used to signify that all calls matching the filter parameters will be terminated. Use with caution when dropping multiple calls at once.
|-
|}

Filter parameters reference guide A

2017-11-27T16:29:02Z

Lucas Joyal: Initial parameter table format (incomplete)

===Filter parameter===

{| cellpadding="5" border="1" class="wikitable"
! Parameter
! Format
! Description
|-
|uct_call_id
|Hexadecimal
|Will return the call matching this ID.
|-
|direction
|Integer
|Incoming (1), outgoing (2), Mixer(3), Media only (4) .
|-
|called
|String
|Called number.
|-
|}

Toolpack:Tsbc Use Cases A

2017-11-27T15:58:27Z

Lucas Joyal: Add link to call trace

=== '''''Applies to version(s): v3.0''''' ===
{{DISPLAYTITLE:Use Cases}}

This article presents a series of use cases, which are designed to demonstrate how to configure your system for real-life scenarios encountered in the field.

==IP Network==

==Redirect==

==Transcoding Unit==
*[[Use_Cases:HW_Transcoding_Configuration_A|Transcoding Unit]]

==Call traces==
*[[Use_Cases:Call_Trace_A|Call Traces]]

Use Cases:Call Trace A

2017-11-27T15:55:53Z

Lucas Joyal: Creating the page for call trace use case

=== '''''Applies to version(s): v3.0''''' ===

==Dropping multiple calls==
{| cellpadding="5" border="1" class="wikitable"
! width="250" style="background: none repeat scroll 0% 0% rgb(239, 239, 239); -moz-background-inline-policy: continuous;" | Via [[Toolpack_Application:tbconfig|Tbconfig]]
! width="250" style="background: none repeat scroll 0% 0% rgb(239, 239, 239); -moz-background-inline-policy: continuous;" | Via [[Toolpack_Application:tbstatus|Tbstatus]]
|-
| valign="top" |
*[[RESTful_API:_Dropping_calls|Dropping calls via Tbconfig]]
| valign="top" |
* [[Use_Cases:_Dropping_calls_with_Tbstatus|Dropping calls via Tbstatus]]
|}

Status API

2017-11-27T15:46:54Z

Lucas Joyal: /* How to write code that use that API */ fix typo

The Status API allows to fetch statistics from the software components running in Toolpack or TMG-CONTROL.

== Getting used with Status API ==

Status API consists of status request queries based on a "path". Each status has a path, like:
/adapter
/adapter/ip_interface
/isup/interface
/clock/ref
etc.

We already provide two ways of accessing the Toolpack Status:
- Web Portal
- Command-line tool "tbstatus", that you will find installed within toolpack installation under /lib/tb/toolpack/pkg/2.X.X/bin/release/[your_platform]/tbstatus

== Viewing status tree using Web Portal ==

I suggest that you start by using the "browse" option in the WEB portal: 
Go to the Web Portal -> Status -> Browse 
This tool will list available paths that can be queried. 
When you click one of these paths, the web page will show a table that list all fields returned from that path.

'''Note:''' If you bring the mouse over a field name, a tool tip will appear and show a short description.

== Viewing status tree using the command-line tool ==

The command-line tool will also allow getting a list of available paths:
./tbstatus
You can also query stats using one of these path, result is formatted as text output:
./tbstatus /adapter
Example above show stat of all adapters. You can query more specific stats too:
./tbstatus /adapter:TB005432
Or you can query "recursive" information that also includes paths "under" a base path:
./tbstatus /adapter:TB005432/*
Or you can query very deep and specific information:
./tbstatus /isup:ISUP/interface:ISUP_INTERFACE/cic_group:C002020_2_0_12

== Viewing statistics field description with the command-line tool ==

You can query a short description of each statistic field by providing the '-D' option to the command-line tool.
./tbstatus /isup/interface/cic_group -D

For example:
[root@TB011107 monitoring]# tbstatus /isup/interface/cic_group -D
The requested path is '/isup/interface/cic_group'.
0:/isup:ISUP/interface:ISUP_IF0/cic_group:C011107_00
C011107_00 -
- desired_group_state : Default (Default,Blocked,Unblocked) Circuit Group desired state.
- toggle_group_reset : No (No,Yes) Setting this flag will toggle a Circuit Group reset.
- start_continuity_check : No (No,Yes) Setting this flag will send a Continuity Check Request (CCR) on all CICs of the group (not available if no drop box).
- interface_down false Circuit group's interface is down.
- idle_cnt 30 Number of idle circuits.
- incoming_cnt 0 Number of active incoming circuits.
- outgoing_cnt 0 Number of active outgoing circuits.
- locally_blocked_cnt 0 Number of circuits in locally blocked state (maintenance).
- remotely_blocked_cnt 0 Number of circuits in remotely blocked state (maintenance)).
- locally_remotely_blocked_cnt 0 Number of circuits in locally remotely blocked state.
- reset_cnt 0 Number of circuits in reset state.
- total_ccr_success_cnt 0 Total number of CCR tests that were succesful for any CIC of this group.
- total_ccr_fail_cnt 0 Total number of CCR tests that failed for any CIC of this group.
- last_ccr_unknown_cnt 30 Number of circuits for which no CCR test was started.
- last_ccr_in_progress_cnt 0 Number of circuits for which a CCR test is in progress
- last_ccr_success_cnt 0 Number of circuits for which the last CCR test was succesful.
- last_ccr_fail_cnt 0 Number of circuits for which the last CCR test failed.
- last_ccr_error_cnt 0 Number of circuits for which an internal error occured in the last CCR test. Might be because circuit was not idle prior to launching the test

== Paths for ISUP Circuit states ==

You can query states for one circuit group using a path like this one (replace C002020_2_0_12 by your circuit group name, as seen in it's Web portal configuration):
./tbstatus /isup/interface/cic_group:C002020_2_0_12

If you're using version 2.4 or up, you also have access to individual circuits states... but you HAVE to use "-x" option (extended stats mode) to get these.
To get states for all CICs of a group:
./tbstatus [u]-x[/u] /isup/interface/cic_group:C002020_2_0_12/*
For example, to get states for CIC #1705, you can use:
./tbstatus -x /isup/interface/cic_group/cic:1705

== Querying/modifying individual field value using the command-line tool ==

To query individual field value, you add "::" after the path, then specify the specific field name.
For example:
./tbstatus /isup/interface/cic_group/cic:1705::desired_cic_state
Or to modify the circuit state (here to force blocking state):
./tbstatus /isup/interface/cic_group/cic:1705::desired_cic_state=Blocked

* Note: Remember that this change is PERSISTENT, which means circuit will remain blocked forever (no matter trunk state) until you change it again (to "Default", or "Unblocked" for example).

== How to write code that use that API ==

Now that you understand a bit how Status API works, here is a short explanation on how to write code to manipulate these states.

In short you need to create and start the status client service in your application:
pClient = tbnew CTBCAFServiceStatusClient();
pClient->Start();

Then each available stat is reported under a "path". Your code can call the following function to get available paths:
pClient->GetRegisteredPaths();

Once you know the path you want to query, you can retrieve the stats, either synchronously or asynchronously:
Synchronously:
pStatList = pClient->GetStat(
"your_path",
"x"
);

Asynchronously:
pClient->ReqStat(
pMyStatPipe,
"your_path",
"x"
);

Available options:
- Option "x" passed to in_pszOptions means "extended" stats query (provides more detailed stats in some cases, like individual circuits)
- Option "d" will make documentation be returned for each field with the query response (by default, only field names and values are returned)
For more information on "pMyStatPipe", please read documentation from the header files in the code.

Once you get your "pStatList", you can get each item it ret'''Bold text'''urned (there can be many if your request matches many):
pStat = pStatList->GetItem( un32StatIdx );

And for each item, you can get list of fields:
pFieldList = pStat->GetFields();

... and list each field (one field is one individual stat value):
pField = pFieldList->GetItem( un32FieldIdx );

Now, as you traverse the stat tree, you will encounter some values that can be changed using:
pField->Set( "new value" );

Once you have changed one or more fields of the stat, you can commit it:
pStat->CommitStates();

For more detailed information, please refer to the source code of the "tbstatus" application, and to documentation in appropriate header files.

'''Note'''
In order to get/set individual circuits states, you need:
- Release 2.4 or more recent, since release 2.3 allowed only to change state per circuit group... (per trunk in other words)
- Need to use "-x" in the options field of GetStat, as per-circuit stats are shown only in "extended" mode

Toolpack:Retrieving Call Trace C

2017-11-13T20:16:50Z

Lucas Joyal:

<pre style="color:#2f6fab;font-family:Times,'Times New Roman';font:sans-serif;background:none;font-style:italic;margin:0;overflow:hidden; padding-top:.5em;padding-bottom:.17em;font-size:188%;font-weight:bold;border-bottom:1px ;solid: #aaa">Applies to version(s) v3.0
</pre>

{{DISPLAYTITLE:Retrieving Call Trace}}

====Retrieving calls from memory====

1- Click '''Call Trace''' in the navigation panel

[[Image:RetrievingCallTrace_0.png]]

2- Set various parameters for call trace, such as
*Time and date range
*Called or calling number
*Network Access Point (NAP)
*Incoming or outgoing calls
*Call Duration, Reason Code
*Active call
[[Image:RetrievingCallTrace_1C.png]]

Once you are satisfied with the filter criteria, click '''Apply'''

The filter results are displayed.

[[Image:FileAccessingCallTrace_2C.png]]

====Dropping an active call====
Active calls can be manually interrupted via the results window.

1- Find the call to drop in the results window.

2a - Click on the 'Drop Call' link under the 'Action' column.

[[Image:FileAccessingCallTrace_6C.png]]

2b - Alternatively, you can select the call you want in the result windows and drop it via the the top-left link 'Drop Call'.

3 - The call will be dropped. The page might need to be refresh after the command, since the dropping process might not be completed immediately after the first refresh.

====View detailed call traces for a call====

1- Select a call in the results window to display further information about the call.

2- Choose the concerned call entry to view the details.
* Click '''Download Audio File'''

[[Image:FileAccessingCallTrace_3.png]]

3- You can choose to export the call trace file as an HTML file.
* Click '''Export'''

[[Image:FileAccessingCallTrace_4.png]]

4- For active calls, you can also choose to drop the call.
* Click '''Drop call'''

[[Image:FileAccessingCallTrace_5.png]]

==== Retrieving calls from files ====
By default, the system stores up to 10,000 call legs in memory. If the call is no longer in memory, it may be retrieved by using information from the uctdata log files.
To search for calls that are no longer in memory, do the following:

1- Start [[How_to_use_tbx_cli_tools_remote_program|tbx_cli_tools_remote]] 
2- Select tbuctwriter 
3- To know which files are available, as well as the start and end time of each file, use the following options:
* 'p' to print all uctdata files on disk

To load a file into memory for viewing with the Web Portal: 
* Option 'o' followed by the data filename (uctdata*)

Use the Web Portal to search for calls using the appropriate filter criteria. The memory will not be overwritten until you restore normal process.

To restore normal process: 

*Option ‘c’ to clear memory
*Option ‘l’ to have calls put in memory again

By default the file is located in the following path:
<pre>/lib/tb/toolpack/setup/12358/2.8/apps/tbuctwriter/uctdata*</pre>

Toolpack:Retrieving Call Trace C

2017-11-13T20:15:27Z

Lucas Joyal: Attempt at recreating the header 3 for the "Applies only to" section.

<pre style="color:#2f6fab;font-family:Times,'Times New Roman';font:sans-serif;background:none;font-weight:normal;font-style:italic;margin:0;overflow:hidden; padding-top:.5em;padding-bottom:.17em;font-size:188%;font-weight:bold;border-bottom:1px ;solid: #aaa">Applies to version(s) v3.0
</pre>

{{DISPLAYTITLE:Retrieving Call Trace}}

====Retrieving calls from memory====

1- Click '''Call Trace''' in the navigation panel

[[Image:RetrievingCallTrace_0.png]]

2- Set various parameters for call trace, such as
*Time and date range
*Called or calling number
*Network Access Point (NAP)
*Incoming or outgoing calls
*Call Duration, Reason Code
*Active call
[[Image:RetrievingCallTrace_1C.png]]

Once you are satisfied with the filter criteria, click '''Apply'''

The filter results are displayed.

[[Image:FileAccessingCallTrace_2C.png]]

====Dropping an active call====
Active calls can be manually interrupted via the results window.

1- Find the call to drop in the results window.

2a - Click on the 'Drop Call' link under the 'Action' column.

[[Image:FileAccessingCallTrace_6C.png]]

2b - Alternatively, you can select the call you want in the result windows and drop it via the the top-left link 'Drop Call'.

3 - The call will be dropped. The page might need to be refresh after the command, since the dropping process might not be completed immediately after the first refresh.

====View detailed call traces for a call====

1- Select a call in the results window to display further information about the call.

2- Choose the concerned call entry to view the details.
* Click '''Download Audio File'''

[[Image:FileAccessingCallTrace_3.png]]

3- You can choose to export the call trace file as an HTML file.
* Click '''Export'''

[[Image:FileAccessingCallTrace_4.png]]

4- For active calls, you can also choose to drop the call.
* Click '''Drop call'''

[[Image:FileAccessingCallTrace_5.png]]

==== Retrieving calls from files ====
By default, the system stores up to 10,000 call legs in memory. If the call is no longer in memory, it may be retrieved by using information from the uctdata log files.
To search for calls that are no longer in memory, do the following:

1- Start [[How_to_use_tbx_cli_tools_remote_program|tbx_cli_tools_remote]] 
2- Select tbuctwriter 
3- To know which files are available, as well as the start and end time of each file, use the following options:
* 'p' to print all uctdata files on disk

To load a file into memory for viewing with the Web Portal: 
* Option 'o' followed by the data filename (uctdata*)

Use the Web Portal to search for calls using the appropriate filter criteria. The memory will not be overwritten until you restore normal process.

To restore normal process: 

*Option ‘c’ to clear memory
*Option ‘l’ to have calls put in memory again

By default the file is located in the following path:
<pre>/lib/tb/toolpack/setup/12358/2.8/apps/tbuctwriter/uctdata*</pre>

File:FileAccessingCallTrace 6C.png

2017-11-13T19:52:08Z

Lucas Joyal:

Toolpack:Retrieving Call Trace C

2017-11-13T19:51:57Z

Lucas Joyal:

=== '''''Applies to version(s) v3.0''''' ===
{{DISPLAYTITLE:Retrieving Call Trace}}

====Retrieving calls from memory====

1- Click '''Call Trace''' in the navigation panel

[[Image:RetrievingCallTrace_0.png]]

2- Set various parameters for call trace, such as
*Time and date range
*Called or calling number
*Network Access Point (NAP)
*Incoming or outgoing calls
*Call Duration, Reason Code
*Active call
[[Image:RetrievingCallTrace_1C.png]]

Once you are satisfied with the filter criteria, click '''Apply'''

The filter results are displayed.

[[Image:FileAccessingCallTrace_2C.png]]

====Dropping an active call====
Active calls can be manually interrupted via the results window.

1- Find the call to drop in the results window.

2a - Click on the 'Drop Call' link under the 'Action' column.

[[Image:FileAccessingCallTrace_6C.png]]

2b - Alternatively, you can select the call you want in the result windows and drop it via the the top-left link 'Drop Call'.

3 - The call will be dropped. The page might need to be refresh after the command, since the dropping process might not be completed immediately after the first refresh.

====View detailed call traces for a call====

1- Select a call in the results window to display further information about the call.

2- Choose the concerned call entry to view the details.
* Click '''Download Audio File'''

[[Image:FileAccessingCallTrace_3.png]]

3- You can choose to export the call trace file as an HTML file.
* Click '''Export'''

[[Image:FileAccessingCallTrace_4.png]]

4- For active calls, you can also choose to drop the call.
* Click '''Drop call'''

[[Image:FileAccessingCallTrace_5.png]]

==== Retrieving calls from files ====
By default, the system stores up to 10,000 call legs in memory. If the call is no longer in memory, it may be retrieved by using information from the uctdata log files.
To search for calls that are no longer in memory, do the following:

1- Start [[How_to_use_tbx_cli_tools_remote_program|tbx_cli_tools_remote]] 
2- Select tbuctwriter 
3- To know which files are available, as well as the start and end time of each file, use the following options:
* 'p' to print all uctdata files on disk

To load a file into memory for viewing with the Web Portal: 
* Option 'o' followed by the data filename (uctdata*)

Use the Web Portal to search for calls using the appropriate filter criteria. The memory will not be overwritten until you restore normal process.

To restore normal process: 

*Option ‘c’ to clear memory
*Option ‘l’ to have calls put in memory again

By default the file is located in the following path:
<pre>/lib/tb/toolpack/setup/12358/2.8/apps/tbuctwriter/uctdata*</pre>

File:FileAccessingCallTrace 2C.png

2017-11-13T19:48:45Z

Lucas Joyal:

File:RetrievingCallTrace 1C.png

2017-11-13T19:40:58Z

Lucas Joyal:

Toolpack:Retrieving Call Trace C

2017-11-13T19:40:41Z

Lucas Joyal: Updating link to picture

=== '''''Applies to version(s) v3.0''''' ===
{{DISPLAYTITLE:Retrieving Call Trace}}

====Retrieving calls from memory====

1- Click '''Call Trace''' in the navigation panel

[[Image:RetrievingCallTrace_0.png]]

2- Set various parameters for call trace, such as
*Time and date range
*Called or calling number
*Network Access Point (NAP)
*Incoming or outgoing calls
*Call Duration, Reason Code
*Active call
[[Image:RetrievingCallTrace_1C.png]]

Once you are satisfied with the filter criteria, click '''Apply'''

The filter results are displayed.

[[Image:FileAccessingCallTrace_2C.png]]

====Dropping an active call====
Active calls can be manually interrupted via the results window.

1- Find the call to drop in the results window.

2a - Click on the 'Drop Call' link under the 'Action' column.

2b - Alternatively, you can select the call you want in the result windows and drop it via the the top-left link 'Drop Call'.

3 - The call will be dropped. The page might need to be refresh after the command, since the dropping process might not be completed immediately after the first refresh.

====View detailed call traces for a call====

1- Select a call in the results window to display further information about the call.

2- Choose the concerned call entry to view the details.
* Click '''Download Audio File'''

[[Image:FileAccessingCallTrace_3.png]]

3- You can choose to export the call trace file as an HTML file.
* Click '''Export'''

[[Image:FileAccessingCallTrace_4.png]]

4- For active calls, you can also choose to drop the call.
* Click '''Drop call'''

[[Image:FileAccessingCallTrace_5.png]]

==== Retrieving calls from files ====
By default, the system stores up to 10,000 call legs in memory. If the call is no longer in memory, it may be retrieved by using information from the uctdata log files.
To search for calls that are no longer in memory, do the following:

1- Start [[How_to_use_tbx_cli_tools_remote_program|tbx_cli_tools_remote]] 
2- Select tbuctwriter 
3- To know which files are available, as well as the start and end time of each file, use the following options:
* 'p' to print all uctdata files on disk

To load a file into memory for viewing with the Web Portal: 
* Option 'o' followed by the data filename (uctdata*)

Use the Web Portal to search for calls using the appropriate filter criteria. The memory will not be overwritten until you restore normal process.

To restore normal process: 

*Option ‘c’ to clear memory
*Option ‘l’ to have calls put in memory again

By default the file is located in the following path:
<pre>/lib/tb/toolpack/setup/12358/2.8/apps/tbuctwriter/uctdata*</pre>

File:FileAccessingCallTrace 5.png

2017-11-13T19:37:32Z

Lucas Joyal: uploaded a new version of "File:FileAccessingCallTrace 5.png"

Toolpack:Retrieving Call Trace C

2017-11-13T18:05:21Z

Lucas Joyal: /* Dropping an active call - completing the steps*/

=== '''''Applies to version(s) v3.0''''' ===
{{DISPLAYTITLE:Retrieving Call Trace}}

====Retrieving calls from memory====

1- Click '''Call Trace''' in the navigation panel

[[Image:RetrievingCallTrace_0.png]]

2- Set various parameters for call trace, such as
*Time and date range
*Called or calling number
*Network Access Point (NAP)
*Incoming or outgoing calls
*Call Duration, Reason Code
*Active call
[[Image:RetrievingCallTrace_1.png]]

Once you are satisfied with the filter criteria, click '''Apply'''

The filter results are displayed.

[[Image:FileAccessingCallTrace_2.png]]

====Dropping an active call====
Active calls can be manually interrupted via the results window.

1- Find the call to drop in the results window.

2a - Click on the 'Drop Call' link under the 'Action' column.

2b - Alternatively, you can select the call you want in the result windows and drop it via the the top-left link 'Drop Call'.

3 - The call will be dropped. The page might need to be refresh after the command, since the dropping process might not be completed immediately after the first refresh.

====View detailed call traces for a call====

1- Select a call in the results window to display further information about the call.

2- Choose the concerned call entry to view the details.
* Click '''Download Audio File'''

[[Image:FileAccessingCallTrace_3.png]]

3- You can choose to export the call trace file as an HTML file.
* Click '''Export'''

[[Image:FileAccessingCallTrace_4.png]]

4- For active calls, you can also choose to drop the call.
* Click '''Drop call'''

[[Image:FileAccessingCallTrace_5.png]]

==== Retrieving calls from files ====
By default, the system stores up to 10,000 call legs in memory. If the call is no longer in memory, it may be retrieved by using information from the uctdata log files.
To search for calls that are no longer in memory, do the following:

1- Start [[How_to_use_tbx_cli_tools_remote_program|tbx_cli_tools_remote]] 
2- Select tbuctwriter 
3- To know which files are available, as well as the start and end time of each file, use the following options:
* 'p' to print all uctdata files on disk

To load a file into memory for viewing with the Web Portal: 
* Option 'o' followed by the data filename (uctdata*)

Use the Web Portal to search for calls using the appropriate filter criteria. The memory will not be overwritten until you restore normal process.

To restore normal process: 

*Option ‘c’ to clear memory
*Option ‘l’ to have calls put in memory again

By default the file is located in the following path:
<pre>/lib/tb/toolpack/setup/12358/2.8/apps/tbuctwriter/uctdata*</pre>

File:FileAccessingCallTrace 5.png

2017-11-13T17:52:37Z

Lucas Joyal:

Toolpack:Retrieving Call Trace C

2017-11-13T17:52:13Z

Lucas Joyal: /* View detailed call traces for a call */

=== '''''Applies to version(s) v3.0''''' ===
{{DISPLAYTITLE:Retrieving Call Trace}}

====Retrieving calls from memory====

1- Click '''Call Trace''' in the navigation panel

[[Image:RetrievingCallTrace_0.png]]

2- Set various parameters for call trace, such as
*Time and date range
*Called or calling number
*Network Access Point (NAP)
*Incoming or outgoing calls
*Call Duration, Reason Code
*Active call
[[Image:RetrievingCallTrace_1.png]]

Once you are satisfied with the filter criteria, click '''Apply'''

The filter results are displayed.

[[Image:FileAccessingCallTrace_2.png]]

====Dropping an active call====

1- Select the call to drop in the results window.

====View detailed call traces for a call====

1- Select a call in the results window to display further information about the call.

2- Choose the concerned call entry to view the details.
* Click '''Download Audio File'''

[[Image:FileAccessingCallTrace_3.png]]

3- You can choose to export the call trace file as an HTML file.
* Click '''Export'''

[[Image:FileAccessingCallTrace_4.png]]

4- For active calls, you can also choose to drop the call.
* Click '''Drop call'''

[[Image:FileAccessingCallTrace_5.png]]

==== Retrieving calls from files ====
By default, the system stores up to 10,000 call legs in memory. If the call is no longer in memory, it may be retrieved by using information from the uctdata log files.
To search for calls that are no longer in memory, do the following:

1- Start [[How_to_use_tbx_cli_tools_remote_program|tbx_cli_tools_remote]] 
2- Select tbuctwriter 
3- To know which files are available, as well as the start and end time of each file, use the following options:
* 'p' to print all uctdata files on disk

To load a file into memory for viewing with the Web Portal: 
* Option 'o' followed by the data filename (uctdata*)

Use the Web Portal to search for calls using the appropriate filter criteria. The memory will not be overwritten until you restore normal process.

To restore normal process: 

*Option ‘c’ to clear memory
*Option ‘l’ to have calls put in memory again

By default the file is located in the following path:
<pre>/lib/tb/toolpack/setup/12358/2.8/apps/tbuctwriter/uctdata*</pre>

FreeSBC:Baremetal:Installation A

2017-08-15T17:59:04Z

Lucas Joyal: Add step for explaining how to burn the iso onto a USB flash drive and modify the steps to take into account the different installation methods.

{{DISPLAYTITLE:TSBC-SW:Baremetal:Installation}}

== Requirements ==
Minimal server requirements:
* 64 bits server
* Quad core Intel CPU 2GHz
* Optical disk drive
* 80GB hard drive
* 8G RAM
* One management Ethernet
* Data Ethernet adapters
** 5,000 sessions or less: one 1Gbps interface
** 10,000 sessions or less: two 1Gbps interface
** 60,000 sessions: two 10Gbps interfaces
** See list of supported Network Interface Cards (NICs) here: [[Supported_NICs|List of supported NICs]]
* Console access through serial port or keyboard/monitor ports
* BIOS setup for maximum performance (i.e. no dynamic CPU throttling)

For better performance (see [[TSBC-SW:Baremetal:Optimizations|optimization]] section)
* NUMA tuning
* PCIe tuning

== Getting the ISO ==
Please contact our [mailto:sales@telcobridges.com sales team] to get a copy of the latest TBSC-SW ISO.

== Installing the ISO ==
The installation process will reformat the server's disks and install all the necessary software.

=== Installing using the ISO burned onto a bootable USB flash drive ===
Use a software application to burn the ISO onto a USB flash drive. On Windows, [[https://rufus.akeo.ie/ |Rufus ]] is known to work with the TSBC-SW ISO.
But generally any similar application should work. Make sure to set the volume label to "CENTOS 7 X8" and to format the drive in the FAT32 file system format.

=== Physical installation steps ===
# Identify which Ethernet networks you need and connect them to your server. Refer to [[TSBC-SW:Networking]] for more information
# Burn the ISO onto a DVD or a USB flash drive
# Get an access to the console of the server. Usually, this is achieved by connecting a keyboard and screen to the server.
# Insert the DVD in the optical drive of your server and boot from the DVD drive.
#* Alternatively, plug in your USB flash drive and boot from that drive.
# You should get the to the "Virtual Appliance Installer" menu on your display: [[File:ISO_install_prompt.jpg|350px]]
# Hit 'R' key, then 'ENTER' key to start the installation [[File:ISO_installing.jpg|350px]]
# Wait for the installation process to complete. When installation is complete, the server will reboot itself.
#* Important: Make sure to remove the DVD from the drive while the server is rebooting. If you get back to "Virtual Appliance Installer", just eject the CD or remove the USB flash drive and reboot again.

=== Changing the root password ===
# Use the console to login into the server
## user: root
## password: root
# Change the password to something stronger than root:
# passwd
New password: ........
Retype new password: ........
passwd: all authentication tokens updated successfully.

=== Assigning IP address ===
By default, all detect network interfaces will have DHCP enabled. Thus, the server might already have an IP address assigned if the network has a DHCP server running. In such case, you can display and use it to access the web portal configuration panel.

# Retrieve an IP address assigned by DHCP
# ifconfig

If there is no IP assigned, you will need to configure one manually.

# Assign a IP address to the Ethernet interface having network connectivity. Example if the NIC's name would be eth0:
# ip link set eth0 up
# ip addresss add 192.168.178.30/24 dev eth0

=== Accessing the TSBC-SW web portal ===
# Open a web browser to the IP of your server, on port 12358. Example if your server address is 192.168.178.30, the URL would be: http://192.168.178.30:12358
# You should get to the TSBC Configuration Wizard [[File:TSBC_WebPortal_Configuration_wizard.jpg|350px]]

From here, you can go to [[TSBC-SW:WebPortal:Initial Configuration|Web Portal Initial Configuration Guide]] to continue the installation, and/or [[TSBC-SW:Baremetal:Optimizations|optimize ]] your server to get the maximum out of your server.

== Web Portal Initial Configuration ==
Click on the following link to pursue installation from the web portal:
[[TSBC-SW:WebPortal:Initial Configuration]]

== Optimizations ==
Click on the following link for baremetal server optimizations:
[[TSBC-SW:Baremetal:Optimizations]]

Toolpack:Modifying Security Settings A

2016-11-04T21:02:47Z

Lucas Joyal: Adding northbound interface

=== '''''Applies to version v2.10''''' ===
{{DISPLAYTITLE:Modifying Security Settings}}

'''To modify the security settings:'''

1- Click '''Users''' in the navigation panel.

[[Image:Users_Navigation_Panel_B.png]]

2- Select the '''Security Settings''' tab, and modify the desired setting.

[[Image:Users_Security_Settings_A.png]]

 
<div class="mw-collapsible mw-collapsed" data-collapsetext="Northbound Interface" data-expandtext="Northbound Interface" style="width: 400px;">

'''Path'''
<pre>
/user_security_settings/general_security_settings
</pre>

'''Parameters (text)'''
<pre>
/user_security_settings/general_security_settings
inactive_session_timeout : "30 minutes"
password_complexity_enabled : true
</pre>

'''Parameters (json)'''
<pre>
{
"inactive_session_timeout" : "30 minutes",
"password_complexity_enabled" : true
}
</pre>
</div>

==List of Parameters==

*[[Parameter:_Enable_password_complexity | Enable password complexity ]]
*[[Parameter:_Session_Timeout | Session Timeout]]

Toolpack:Modifying Security Settings A

2016-11-04T20:57:21Z

Lucas Joyal: /* Applies to version v2.10 */ Creating a list of parameters replacing the old section

Users

2016-11-04T20:53:34Z

Lucas Joyal: /* Security settings (from 2.10 and up) */ Adding link to the parameters

Users and User Groups are the building blocks of authentication and authorization for Toolpack systems.

The proper implementation of Users and User Groups increases efficiency and reduce costs by:

* Reducing Human Error,
* Mitigating Risks,
* Improving Security,
* Speeding up and simplifying maintenance and troubleshooting.

== Users ==

Each person that uses Toolpack Web Portal should be assigned their own user name and password.

== User Groups ==

User Groups define a list of authorized actions applied to each item in the left-hand navigation menu of the Web Portal.

There are 3 authorization levels per resource:
'''Read/Write'''
Full access to the resource.
'''Read'''
Only view access to the resource. The action commands will be hidden.
'''None'''
No access to the resource. It won't be displayed in the left menu.

=== Best practices ===
*Each User needs to be in a User Group. To modify a user's access to a resource, modify the User Group it belongs to or create a new User Group with the appropriate authorization.

*The ''Admin'' User Group is not modifiable, and each User in this group has access to all the resources of the Web Portal.

*Be careful when creating a User Group that has full authorization to Users. Read/Write Access to users is a security risk because a user can create another user belonging to the Admin user group, thus gaining total access to the web portal.

== Security settings (from 2.10 and up) ==

Security settings regroup all the global settings options available in the Web Portal.

It contains the following options:

*[[Parameter:_Enable_password_complexity | Enable password complexity ]]
*[[Parameter:_Session_Timeout | Session Timeout]]

== Configuration ==

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | Tsbc
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | Tmedia/Tsig/Tdev
|-
| valign="top" |
*[[Toolpack:Tsbc_System_Settings_A#Access_and_User_Management|v2.10: Access and User Management]]
| valign="top" |
*[[Toolpack:System_Settings_C#Access_and_User_Management| v2.10: Access and User Management]]
*[[Toolpack:System_Settings_B#Access_and_User_Management| v2.9: Access and User Management]]
*[[Toolpack:System_Settings_A#Access_and_User_Management| v2.8: Access and User Management]]
|}

Parameter: Enable password complexity

2016-11-04T20:52:56Z

Lucas Joyal: Creating parameter

By default, this setting is activated. When creating a password, you will need to respect a series of complexity requirements to make sure your password is sufficiently secure. If you would like to be able to set any password, deactivate this option.

Parameter: Session Timeout

2016-11-04T20:51:01Z

Lucas Joyal: Creating parameters

The session timeout option can be modified to make sure that a session without activity will be safely logged out after a given amount of time.

Users

2016-11-04T20:47:03Z

Lucas Joyal: /* Best practices */ rewording

Users and User Groups are the building blocks of authentication and authorization for Toolpack systems.

The proper implementation of Users and User Groups increases efficiency and reduce costs by:

* Reducing Human Error,
* Mitigating Risks,
* Improving Security,
* Speeding up and simplifying maintenance and troubleshooting.

== Users ==

Each person that uses Toolpack Web Portal should be assigned their own user name and password.

== User Groups ==

User Groups define a list of authorized actions applied to each item in the left-hand navigation menu of the Web Portal.

There are 3 authorization levels per resource:
'''Read/Write'''
Full access to the resource.
'''Read'''
Only view access to the resource. The action commands will be hidden.
'''None'''
No access to the resource. It won't be displayed in the left menu.

=== Best practices ===
*Each User needs to be in a User Group. To modify a user's access to a resource, modify the User Group it belongs to or create a new User Group with the appropriate authorization.

*The ''Admin'' User Group is not modifiable, and each User in this group has access to all the resources of the Web Portal.

*Be careful when creating a User Group that has full authorization to Users. Read/Write Access to users is a security risk because a user can create another user belonging to the Admin user group, thus gaining total access to the web portal.

== Security settings (from 2.10 and up) ==

Security settings regroup all the global settings options available in the Web Portal.

It contains the following options:

*Enable password complexity
*Session timeout

== Configuration ==

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | Tsbc
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | Tmedia/Tsig/Tdev
|-
| valign="top" |
*[[Toolpack:Tsbc_System_Settings_A#Access_and_User_Management|v2.10: Access and User Management]]
| valign="top" |
*[[Toolpack:System_Settings_C#Access_and_User_Management| v2.10: Access and User Management]]
*[[Toolpack:System_Settings_B#Access_and_User_Management| v2.9: Access and User Management]]
*[[Toolpack:System_Settings_A#Access_and_User_Management| v2.8: Access and User Management]]
|}