How to configure outgoing routing rules

This article describes all the routing rules available in VoipNow and provides practical examples to help you better understand the mechanism. Also, in case of an error, you may find important details about possible reasons for failure. 

The Outgoing Routing Rules are used to manage outgoing external calls. You can block, process and route calls depending on the dialed number and the available channels.

Overview

Asterisk expressions are used to match the dialed number the outgoing routing rules will apply to. For more information regarding Asterisk expressions, check this page.

When all outgoing routing rules are applied using the first available number match criteria, it means the first rule matching the dialed number will be used, followed by the next available rule matching the dialed number and so on.

When all outgoing routing rules are applied using the dialed number match criteria, it means that, even if the dialed number is modified by several routing rules and becomes a completely different number, the rules that will apply are selected depending on the initially dialed number.

Let's see what happens when the following 3 rules are defined:

• Process Rule 1 defined for number 1 adds the 02 prefix to the number.
• Route Rule 2 defined for number 021 routes the call through Channel 2.
• Route Rule 3 defined for number 1 routes the call through Channel 1.

If an extension dials 1234, then the call will first be routed through Process Rule 1. The number will be changed into 021234 and then the next rule will be searched based on the dialed number match criteria. This means the next rule defined for number 1234 will be searched.

Then the server evaluates Route Rule 2. It will NOT be applied because it is defined for 021 and 1234 does not match it.

Finally, the server evaluates Route Rule 3. This rule will be applied because it is defined for 1 and 1234 matches it. For this reason, the call will be routed using Channel 1.

Types of outgoing routing rules

There are three outgoing routing rules types:

• Block rules stop all calls addressed to the matched number. Such rules are final, which means that no other rules will be applied afterwards.
• Process rules can add prefixes, delete digits, or replace the matched number. They have have a permanent effect on the outgoing number and the call cost.
• Route rules choose the channel the call will be routed through. They allow you to process the number in the same way as a process rule. Both the changes made by a process rule and the ones made by the route rule apply to the final number that appears in the outgoing packet sent to the provider. The difference is that the changes made in the route rule have no effect on the cost of the call. Therefore, the cost used for charging is calculated based on the outgoing number BEFORE the processing within the routing rule occurs.

Example

Let's see what happens when the following 2 outgoing routing rules are defined:

• Process Rule 1 defined for number 12 adds the 03 prefix to the number.
• Route Rule 2 defined for 12 routes the call through Channel 1 and adds the 99 prefix to the number.

Two different costs are defined for Channel 1:

• 0.01 USD per second for calls to 031.
• 0.99 USD per second for calls to 99.

If an extension dials 1234, then the call will first be routed through Process Rule 1. The number will be changed to 031234.

The server then applies Route Rule 2. It looks for a cost in Channel 1's costs list, based on the 031234 number. When the cost for 031 is found, the 99 prefix is added, the call is routed through Channel 1 and the final number sent to the provider is 99031234. The call lasts 10 seconds. For this call, the administrator will be charged for a 10-second call to prefix 031 because the number used for charging was 031234. So, he/she will have to pay a total amount of 10 x 0.01 = 0.1 USD.

As you can see from this example, both the 03 and the 99 prefixes have an effect on the outgoing number sent to the provider. However, the first prefix added by the process rule had an effect on the final cost of the call, while the second prefix added by the route rule had none.

Static or best-cost routes

When setting up an outgoing routing rule, you can choose to define it as a static or as a best cost rule.

Static routing rules route calls statically, using a selected channel.

For example, Routing Rule 1, which is set up for number 99, routes the call through Channel 1 and replaces the number with 2222. When an extension dials 12345, Routing Rule 1 is applied. This means that a cost is searched in Channel 1's costs list, based on the dialed number. When the cost is found, the number is replaced with 2222 and the call is routed through Channel 1.

Best cost routing rules route calls using the best cost available. The server finds the channel with the lowest cost (including free channels) and connects the outgoing call through it. If the transfer fails, the application will search for the next lowest cost channel available and so on, moving upwards to more expensive channels.

For example, Routing Rule 1, which is set up for number 12, routes the call through the Best Cost channel. The following four channels are defined: 

• Channel 1, with only one cost: 0.01 USD per second for calls to 1234.
• Channel 2, with only one cost: 0.02 USD per second for calls to 12.
• Channel 3, which is free.
• Channel 4, with only one cost: 0.04 USD per second for calls to 22.

If an extension dials 12345:

1. Routing Rule 1 is applied. All enabled channels are checked. The server selects all the channels with costs defined for number 12345.
2. The following channels, ordered by cost, are found: Channel 3, Channel 1 and Channel 2.
3. The number is changed to 234 because one digit must be deleted. Afterwards, the call is routed through Channel 3.
4. If the call fails and the failure reason is rejection, then the call is re-routed through Channel 1.
5. If the call fails and the failure reason is not rejection, the call is re-routed through Channel 2.
6. If the call fails again, then Routing Rule 1 is finished.

Final or non-final routing

When defining an outgoing routing rule, you can specify from the start if you want to make it final or non-final.

In the case of final routing rules, if the call fails, it is considered to be completely failed. No other rule is tried and the call ends.

With non-final routing rules, if the call fails and the failure reason is rejection, the following available rules are applied. If the call fails and the failure reason is not rejection, it is considered to be completely failed, no other rules are tried and the call ends.

The number defined in a non-final routing rule does not have any effect on the subsequent routing rules.

Example

Let's see what happens when the following 3 outgoing routing rules are defined:  

• Process Rule 1 defined for number 2 adds the 1 prefix.
• Non-final Routing Rule 2 defined for number 2 routes the call through Channel 1 and adds the 03 prefix.
• Final Routing Rule 3 defined for number 2 routes the call through Channel 2 and adds the 04 prefix.

Also, let's assume two channels are defined as follows:

• Channel 1, with only one cost: 0.01 USD per second for the calls to 12.
• Channel 2, with only one cost: 0.02 USD per second for the calls to 12.

If an extension dials 2345:

1. Process Rule 1 is applied. The number is prefixed with 1, becoming 12345.
2. The Non-final Routing Rule 2 is applied. The number is prefixed with 03 and routed through Channel 1. The number sent to the provider is 0312345.
3. If routing through Channel 1 fails and failure reason is rejection, then the routing process continues.
4. The Final Routing Rule 3 is applied. The number is prefixed with 04 and routed through Channel 2. The number sent to the provider is 0412345. The previously added 03 prefix had no effect on this rule.

Rejection failure reasons

The response to the call request sent to the provider is used in order to decide whether to continue the routing process after a call through a channel fails. This response will provide an error code that has a corresponding Q.931 code. This code will be checked against a list of rejection codes. If the error code is already on the list, then the failure reason is considered to be rejection and non-final routing can be used. If the error code is not on the list, the failure reason is not rejection and non-final routing will not be used.

The rejection codes list can be found in the /etc/voipnow/local.conf file, in the CHANNEL_FAILURE_CODES parameter. We do not recommend editing this parameter. However, if you choose differently, make sure you restart your Asterisk server in order for the changes to apply.

The Q.931 codes apply directly to PRI and IAX channels. The following Q.931 codes have been included by default in the rejection failure list:

For SIP channels, each SIP failure codes is mapped to a Q.931 code. The following SIP failure codes are associated to the Q.931 codes currently in the list:

Further examples

There are five outgoing routing rules defined:

• Process Rule 1 defined for number 3, adding the 2 prefix.
• Non-final Route Rule 2 defined for number 3, routing the call through the best cost channel and adding the03 prefix.
• Process Rule 3 defined for number 3, adding the 1 prefix.
• Final Route Rule 4 defined for number 3, routing the call through best cost channel.
• Final Route Rule 5 defined for number 3, routing the call through Channel 1.

There are three channels defined:

• Channel 1, with only one cost: 0.01 USD per second for the calls to 1.
• Channel 2, with only one cost: 0.02 USD per second for the calls to 2.
• Channel 3, which is free.

If an extension dials 345:

1. The Process Rule 1 is applied. The number is prefixed with 2, becoming 2345.
2. The Non-final Route Rule 2 is applied. The channels available are Channel 3 and Channel 2. Channel 1 is not available for the current state of the call because it has no matching cost for number 2345.
3. The number is prefixed with 03 and routed through Channel 3. The number sent to the provider is 032345. Routing through Channel 3 fails, failure reason is rejection and the routing process continues.
4. The number is routed through Channel 2. The number sent to the provider is 032345. Routing through Channel 2 fails, failure reason is rejection and the routing process continues.
5. Rule 2 was non-final, so the call process continues. The Process Rule 3 is applied. The number is prefixed with1, becoming 12345.
6. The Final Route Rule 4 is applied. The channels available are Channel 3 and Channel 1. Channel 2 is not available for the current state of the call because it has no matching cost for number 12345.
7. The number is routed through Channel 3. The number sent to the provider is 12345. Routing through Channel 3 fails, failure reason is rejection, and the routing process continues.
8. The number is routed through Channel 1. The number sent to the provider is 12345. Routing through Channel 1 fails, failure reason is rejection, and the routing process continues.
9. Rule 4 was final, so the call process stops. Route 5 is never reached. The call ends as unsuccessful.

Related articles

• Page:
  How to match calls outside business hours
• Page:
  How to place automatic test calls
• Page:
  How to prevent frauds using SIP devices against VoipNow
• Page:
  How to use Hunt Groups in VoipNow
• Page:
  How call setup influences best cost algorithm