Routing Rules

Routing rules

The routing rules are a set of rules that are applied when a call is received, and help determine how the resulting outbound call is handled. Each routing rule has 2 sections :

• the first section contains conditions on inbound properties that must be satisfied for the rule to fire. 

• the second section sets properties that configure the outbound portion of the call.

Routing Engine

When the Routing Engine receives a routing request with some incoming call properties, it does the following:

• fetches the routing rules

• applies the routing rules to the request based on the resource definitions and general Gateway properties (such as the Gateway's host name) produces the outgoing call properties.

The call is then relayed to a destination, either PSTN or VoIP, by matching the properties produced by the Routing Engine.
 

If no routing rule matches the incoming request, the incoming call is rejected with an appropriate SIP response code (see Telephony error codes on page 142). If the outbound destination is VoIP, multiple call legs can be established using the same incoming PSTN call.

Q-value

Although multiple rules may be active at the same time, not all rules have the same priority. A rule's priority level is defined by its q-value. The q-value of a rule is a floating-point number between 0 and 1, with 1 representing the highest priority.
 

The term "q-value" comes directly from the SIP standard. In SIP, an application can register to a SIP proxy and specify a q-value that represents its availability (floating-point number between 0 and 1).
 

When you create a new rule, you must assign it a q-value. The Routing Engine processes routing requests by applying the entire set of routing rules, sorted in descending order of q-value. The first rule to trigger on the incoming request's properties will produce the outbound call properties.
 

If an outbound call cannot be established using the highest priority rule that is triggered, then the Routing Engine will try to establish a call using a lower priority rule that meets all of the conditions (if any), until the maximum value is reached (specified by parameter Netborder.gw.maxRoutingRulesMatches).
 

CAUTION: Assign q-values carefully. If two rules with an equal q-value trigger a request, the Routing Engine cannot guarantee or predict which one will be used at runtime.

Inbound call properties

Finally, the routing rules can use numerous properties of the incoming call to determine the outbound properties.

A call coming into the Gateway is either a PSTN-originated call or a SIP-initiated call. A PSTN-originated call will have non-nil values in the inbound properties pstn.in.* and nil values in sip.in.*. For a SIP-initiated call, the opposite is true: it will have nil values in the inbound properties pstn.in.* and non-nil values in sip.in.*.
 

The following table list the common properties that can be accessed from the routing any inbound call:

• transfer

The following table lists the properties that can be accessed from the routing rules for a PSTN inbound call:

• pstn.in.channelName

• pstn.in.dnis

• pstn.in.ani

• pstn.in.ani.presentationIndicator

• pstn.in.ani.screeningIndicator

• pstn.in.callerName

• pstn.in.isdn.setup.iiDigits

• pstn.in.isdn.setup.ie.0xZZ.0xYY

The following table lists the properties that can be accessed from the routing rules for a SIP inbound call:

• sip.in.requestUri

• sip.in.requestUri.canonical

• sip.in.from.uri

• sip.in.from.uri.canonical

• sip.in.from.displayName

• sip.in.to.uri

• sip.in.to.uri.canonical

• sip.in.to.displayName

• sip.in.referTo

• sip.in.referTo.canonical

• sip.in.referredBy.uri

• sip.in.referredBy.displayName

• sip.in.redirect.Contact

• sip.in.header.Via

• sip.in.header.CSeq

• sip.in.header.Call-ID

• sip.in.header.Content-Length

• sip.in.header.Contact

• sip.in.header.HeaderName

NOTE: Canonical versions of the URI parameters are fully expanded of the form sip:something@hostname:portnumber. Note that 'sip' must be in lowercase, and that the hostname is expanded to dotted IP notation. For example: sip:1026@192.168.11.207:5066.

transfer

Specify weither this routing apply to an inbound call initiated by a transfer request or not. Set this parameter to "true" if you wan't to trig this rule only for call resulting from a transfer request. Set to "false" otherwise.

pstn.in.channelName

Name on which the PSTN call came in. This would be a string in the following formats.
 

For digital channels:
"b<board-index>di<interface-index>-c<logical-channel-index>"
For analog channels:
"b<board-index>ai<interface-index>-c0"

pstn.in.dnis

Dialled phone number. Available for digital configurations only.

pstn.in.ani

Calling number. In analog configurations, this is the CallerID. If not available, this property is set to "unknown-ani".

pstn.in.ani.presentationIndicator

Calling number presentation indicator; possible values are "allowed," "restricted", "unavailable" , "reserved" or "".

pstn.in.ani.screeningIndicator

Calling number screening indicator; possible values are "user-provided not screened", "user-provided verified and passed", "user-provided verified and failed", "network provided" or ""

pstn.in.callerName

In ISDN the caller name is extracted from the SETUP or FACILITY message according to the parameter in the PSTN configuration. If not available, this property is set to "unknown-callerName".
In analog configuration , this information is extracted from the CallerID if this information is available. If not available, this property is set to "unknown-callerName".

pstn.in.isdn.setup.iiDigits

Automatic Number Identification (ANI) II digits in the ISDN setup message. These digits identify the type of originating station. Only available with ISDN signalling.

pstn.in.isdn.setup.ie.0xZZ.0xYY

The content of ISDN Information Element with codeset 0xZZ and identifier 0xYY, in hexadecimal format. All ISDN Information Elements (IE) of the SETUP message can be accessed using this property. The IE content is stored in an hexadecimal format where each octet is separated by a space, without the '0x' prefix.

sip.in.requestUri or sip.in.requestUri.canonical

The URI to which the call request was made (and its canonical version).

sip.in.from.uri or sip.in.from.uri.canonical

The caller's URI(and its canonical version).

sip.in.from.displayName

The caller's display name if available.

sip.in.to.uri or sip.in.to.uri.canonical

The callee's URI (and its canonical version).

sip.in.to.displayName

The callee's display name if available.

sip.in.referTo or sip.in.referTo.canonical

The address in the "Refer To" header of a REFER message (and its canonical version).

sip.in.referredBy.uri

The URI of the application requesting the transfer.

sip.in.referredBy.displayName

The display name of the SIP application requesting the transfer.

sip.in.redirect.Contact

The content of the contact header on reception of a SIP redirect (3XX) message.

sip.in.header.Via

The content of the Via header.

sip.in.header.CSeq

The content of the CSeq header.

sip.in.header.Call-ID

The content of the Call-ID header.

sip.in.header.Content-Length

The content of the Content-Length header.

sip.in.header.Contact

The content of the Contact header.

sip.in.header.HeaderName

For acquiring the content of an arbitrary header in the incoming SIP message (incoming call or transfer request). To obtain the value of MyPrivateHeader, you would use sip.header.MyPrivateHeader. Refer to the Release Notes for limitations.

Outbound call properties

The purpose of a routing rule is to set the properties of an outgoing call (either PSTN or SIP) based on the information gathered about the incoming call, as well as global properties and resource data.
 

The following table lists common outbound call properties:

• media_type

• netborder.gw.ringTimeoutMs

• netborder.gw.connectTimeoutMs

The following table lists the properties that can be set in a routing rule when the outbound interface is the "pstn".

• pstn.out.phoneNumber

• pstn.out.phoneNumber.type

• pstn.out.phoneNumber.numberingPlan

• pstn.out.ani

• pstn.out.ani.type

• pstn.out.ani.numberingPlan

• pstn.out.ani.presentationIndicator

• pstn.out.ani.screeningIndicator

• pstn.out.callerName

• pstn.out.channelGroup

• pstn.out.earlyMediaMode

• pstn.out.earlyMedia.start.condition

• pstn.out.isdn.setup.iiDigits

• pstn.out.isdn.setup.ie.0xZZ.0xYY

• pstn.out.networkSpecific.feature

• pstn.out.networkSpecific.service

• pstn.out.networkSpecific.identification

• pstn.out.networkSpecific.identification.type

• pstn.out.networkSpecific.identification.plan

• pstn.out.transfer.type

• pstn.out.transfer.supervision

• pstn.out.ignoreISDNCauseDuringEarlyMedia

• pstn.out.transfer.timeoutMs

The following table lists the properties that can be set in a routing rule when the outbound interface is the "voip".

• sip.out.ignore180

• sip.out.accept183

• sip.out.requestUri

• sip.out.from.uri

• sip.out.from.displayName

• sip.out.to.uri

• sip.out.to.displayName

• sip.out.redirect.Contact

• sip.out.header.<MyHeaderName>

• sip.out.transport

media_type

Indicate if the outbound call media stream shall flow in both directions (sendrcv) or if the media stream shall flow in the send direction only (sendonly). The sendonly value is not supported for outbound PSTN calls.

netborder.gw.ringTimeoutMs

The maximum time in milliseconds that a leg has to accept the call. Override the global configuration propertie "netborder.gw.ringTimeoutMs"
specified in the application configuration files.

netborder.gw.connectTimeoutMs

The maximum time in milliseconds that a leg has to get connected. Override the global configuration propertie "netborder.gw.connectTimeoutMs" specified in the application configuration files.

pstn.out.phoneNumber

For setting the phone number as it should be dialed on the telephony channel.

pstn.out.phoneNumber.type

This value can take the following values:

Please refer to Table 4.9 of spefication ITU-T Q931 05/98

pstn.out.phoneNumber.numberingPlan

Numbering plan applies for type of number = 0, 1, 2 and 4. This value can take the following values:

Please refer to Table 4.9 of spefication ITU-T Q931 05/98

pstn.out.ani

For setting the ANI (CAS, default value is 5678), or the calling number information (ISDN).

pstn.out.ani.type

This value can take the following values:

Please refer to Table 4.11 of spefication ITU-T Q931 05/98

pstn.out.ani.numberingPlan

Numbering plan applies for type of number = 0, 1, 2 and 4. This value can take the following values:

Please refer to Table 4.11 of spefication ITU-T Q931 05/98

pstn.out.ani.presentationIndicator

Presentation indicator (octet 3a) of the calling party number information element.

NOTE: meaning and the use of this field is defined in clause 3/ITU-T Q.951 and clause 4/ITU-T Q.951
Please refer to Table 4.11 of spefication ITU-T Q931 05/98

pstn.out.ani.screeningIndicator

Screening indicator (octet 3a) of the calling party number information element.

NOTE: The meaning and the use of this field is defined in clause 3/ITU-T Q.951 and clause 4/ITU-T Q.951.
Please refer to Table 4.11 of spefication ITU-T Q931 05/98

pstn.out.callerName

For ISDN interfaces, the caller name could be carried either in SETUP or in a FACILITY message immediately following a SETUP message. When the caller
name is carried in the SETUP message, the caller name is stored in the DISPLAY IE. When the caller name is carried in FACILITY message, the SETUP
message contains a facility IE to inform the user if a FACILITY message with caller name is expected.
NOTE: For analog interfaces, this parameter is ignored for the current version.

pstn.out.channelGroup

For setting the resources group to select in making the outbound call.

pstn.out.earlyMediaMode

For setting the conditions, if any, under which the Gateway will start the media streams and notify the calling SIP UA (User Agent) of an '183 Session Progress' (message that there is some audio prior to call connection that the caller should hear).
Valid values are: 'never', 'always' or 'as-needed' (default).

pstn.out.earlyMedia.start.condition

Used only for the analog fxo gateway. Indicates when the gateway will start earlyMedia for analog fxo outboubnd calls. Possible values are 'immediate' or 'after-dialing'.
If set to 'immediate', the gateway will start the early media by sending a 183 Session In progress as soon as it receives the sip INVITE. If set to 'after-dialing', the gateway will start the eraly media only after having dialed the outbound dtmf digits. If pstn.out.earlyMediaMode is set to 'never', this parameter will have no effect on the gateway, since earlyMedia is disabled.

pstn.out.progressToneDetectionMode

For setting the conditions, if any, under which the Gateway analyses the PSTN audio stream to detect progress tones (BUSY, REORDER and SIT tones).
Valid values are: 'never', 'always' or 'as-needed' (default).

pstn.out.isdn.setup.iiDigits

For setting the automatic Number Identification (ANI) II digits sent with the SETUP message. These digits identify the type of originating station. Only available with ISDN signalling.

pstn.out.isdn.setup.ie.0xZZ.0xYY

For setting the content of ISDN Information Element with codeset 0xZZ and identifier 0xYY.

Any ISDN Information Elements (IE) of the SETUP message can be set using this property. The length of the information element automatically added.
 

The IE content is specified in a hexadecimal format where each octet is separated by a space, without '0x' prefix. You can also specify string. To specify one or more string, enclose each of them between 's(' your-string ')'.

Example:
<param name="pstn.out.isdn.setup.ie.0x00.0x70" expr="04 s(my string) s(%0)"/>
 

To send a NOT-END-TO-END-ISDN IE in the setup, one should add to the pstn_out routing rule the following line : <param name="pstn.out.isdn.setup.ie.0x00.0x1E" expr="80 81"/>
 

Any IE defined here will be added to the SETUP message without validation of its content, overriding any automatically generated IE. Use this feature with care as it may send corrupted message without warning being generated by the application.
 

The IE will be correctly placed in the message according to Q931 specification and many IE may be defined in the same message.

pstn.out.networkSpecific.*

4ESS and 5ESS switches sometime require you to provide the feature and/or the service you have subscribed. This information is provided by your Telco operator on your subscribtion contract. The following parameters allow you to specify them. Some features and service are specified in the ATT standard TR41459 June 1999 in section 3.6.5.19 Network-Specific Facilities.

pstn.out.networkSpecific.feature

This parameter is interpreted by ISDN channels and ignored by analog channels.
Can take any of the following values as decribed ATT standard TR41459 June 1999 on Table III - 43.
Typical feature values are:

pstn.out.networkSpecific.service

This parameter is interpreted by ISDN channels and ignored by analog channels.
Can take any of the following values as decribed ATT standard TR41459 June 1999 on Table III - 43.
Value Meaning
1 SDN (including GSDN) access and egress
2 Toll Free MEGACOM egress only
3 MEGACOM access only
6 ACCUNET Switched Digital Service (including Switched
Digital International) access and egress
8 International Toll Free Service egress only
16 ATT MultiQuest egress only
7 Long Distance Service access and egress
23 Call Redirection Service egress only

pstn.out.networkSpecific.identification

In some networks you have to provide Network identification parameters in order to use network specific services. This parameter "pstn.out.networkSpecific.identification" along with the parameters "pstn.out.networkSpecific.identification.type" and "pstn.out.networkSpecific.identification.plan" allows you to specify those.
This parameter allows you to set the optional octet 3 and 3.1+ as defined in ATT TR 41459, June 1999. The octect 3 and 3.1+ are no inserted in the Network Specific Facility when this parameter is missing.
The user can specify the type and the plan via the follow parameters:

• pstn.out.networkSpecific.identification.type

• pstn.out.networkSpecific.identification.plan

The default type is 2 (National network identification). The default plan is 1 (Carrier identification code).

pstn.out.transfer.type

For setting the type of telephony transfer protocol to use in honoring a transfer request.
Possible values are:

• "2channel-bridged": The bridge transfer is the simplest type. Two call legs result from the transfer request: "A" to gateway and the gateway to "C". These two legs are connected together within the gateway and thus hold two ports until one of the two legs disconnects (hangs up).

pstn.out.transfer.supervision

For setting the point at which the gateway will connect the Calls A" and "C" together in a conditional transfer.
Possible values are:

• connect

• blind (not supported)

• alert (not supported)

Not all types of transfers support all levels of supervision.

pstn.out.ignoreISDNCauseDuringEarlyMedia

If set to true, the gateway will not immediately disconnect the call if it receives a progress announcing some inband info prior to a disconnect with a valid cause while trying to place an inbound call. This could be helpful for users who want the gateway to let some outbound call rejection inband message be played instead of immediately terminate the call.
Possible values are:

• true

• false (default value)

pstn.out.transfer.timeoutMs

For setting the timeout in milliseconds after which the gateway will abort the transfer request and return a "408 Request Timeout" to the transfer initiator.

sip.out.ignore180

Can be true or false (default is false). When set to true, it will ignore the 180 messages from the target SIP application and not go in the 'ringing' state.
Can be useful if a SIP user agent sends a 180 without SDP followed by a 183 with SDP, as this situation cannot be reproduced in ISDN, and the Gateway will fail to establish early media.

sip.out.accept183

Can be true or false (default is false). When set to true, it will accept a 183 message as a 180 and go in the 'ringing' state. Can be useful in the same situation as the sip.out.ignore180 property.

sip.out.requestUri

For setting the URI to which the call request is going to be made.

sip.out.from.uri

For setting the caller's URI. Typically used to indicate the the ANI or CallerID of an incoming PSTN call, if available.

sip.out.from.displayName

For setting the caller's display name if available.

sip.out.to.uri

For setting the callee's URI.

sip.out.to.displayName

For setting the callee's display name.

sip.out.redirect.Contact

For setting the contact header following a redirect primitive.

sip.out.header.<MyHeaderName>

For setting arbitrary headers in the outgoing INVITE message. For example, to set Replaces to value 'foo', you would use sip.out.header.Replaces=foo. Refer to the Release Notes for limitations.

sip.out.transport

Set the transport to be used by the SIP message. Set to "udp" (default) to send and receive SIP messages over UDP packets. Set ot "tcp" to send and receive SIP messages a TCP stream. Set to "tls" to send and receive SIP messages over a secure TLSv1 stream.