Course12:Advanced - Routing Engine

From innovaphone-wiki

Jump to: navigation, search

About the powerful Routing engine in the relay (gateway).



An important task of the gateway is call routing. It determines where the calls are switched to. Call routing is carried out by the routing engine in the gateway layer (a.k.a. RELAY). In order for a call to be switched through a gateway, there must be a route defining its path from the source interface to the destination interface. A route defines a screenshot.png permitted path for a call, from the interface where the call departs, to the interface from which the call arrives.
All defined routes are organized as a sequential list, known as the routing table. For each individual call, the routing table is searched from top to bottom for the first matching route. This route is then used. If there is no such route defined, no call is passed. If calls should be able to flow in both directions, screenshot.png 2 routes are required.

Calls from different interfaces are often handled in the same way. This is why it is possible to define screenshot.png multiple source interfaces for a single route. Call switching also often depends on the called party number (CDPN) and/or the calling party number (CGPN). Using maps (fish-help.png Gateway/Routes/Map and fish-help.png Gateway/CGPN-Maps), you can screenshot.png restrict routes so that they are applied only to calls with specific calling or called party numbers. For example, if you have a second trunk line from a different provider that offers cheap calls to Austria, you could set up the routes so that screenshot.png only calls to Austria are routed to the secondary trunk.

When a route is applied, both calling and called party number may be modified. Let us assume you have a call-by-call provider which offers cheap calls to Austria. Calls must be prefixed with the providers selection code to take advantage of this offer. You could then define routes which still route the calls to Austria to your ISDN trunk line, but screenshot.png prefix the carrier selection code.

If it is not possible to pass the call to the identified interface (e.g. because it has an ISDN line as destination interface which is already fully used), then the routing table is searched for the next suitable route. If no suitable map entry was found in the routing table, the call will be disconnected with an "unallocated number" fish-help.png cause code. If passing the call failed for all destination interfaces, the call is disconnected with the cause code returned from the last attempt.

As noted before, it is important to understand that routes will be searched in the routing table from top to bottom. The routing table works with "first match" so it's a must to configure more specific routes before the less specific routes. In the previous example this order is essential. If you would flip the order of route #1 and #2 in such a manner that #2 comes first, calls would never get sent to the call-by-call provider as the new first route (having no restrictions defined) would always match and thus be used.

When looking at the PBX trunking scenario below, it might be confusing that we deal with total 4 interfaces (1 BRI and 1 GWx on the left gateway and 1 BRI and 1 GWx on the right gateway). So in order to allow bi-directional calls, we need at least screenshot.png 4 routes.

Call routing is applied to all calls regardless of the type of media. So voice, fax, modem and data calls are routed the same way applying the same routes.

Routing Table

The routing table (as defined in fish-help.png Gateway/Routes) consists of an ordered list of routes. A route entry defines a set of interfaces the route should be valid for when a call from them has to be routed. Each route has one or more maps, which define which called numbers are valid, if the called number will be modified and which destination interface is used.

Here we see a screenshot.png gateway with a simple routing table. It has 2 routes. The first route calls from BRI1 or BRI2 to GW1, the second vice versa. The first route has one fish-help.png map (which is empty, that is, it accepts all called numbers and does no change). The second has 2 maps (which are both empty too. 2 maps are required to address 2 different destination interfaces).

The editor actually screenshot.png shows a single map along with the route data of the route the map belongs to. If we open the second route, we see screenshot.png the first map of the second route.

If we implement the screenshot.png call-by-call provider example shown in the Overview section, the order of entries is important. The first map of the second route now screenshot.png looks different.

Let us look at this example a bit closer. Let's assume this gateway provides the trunk line for an innovaphone PBX and we are using overlapped dialling. When the user picks up the phone and dials the trunk access prefix (e.g. 0), the call setup will be sent through the PBX trunk object (where GW1 is registered with) to GW1. The routing engine will search for a valid route in the routing table. The first route is not applicable because the source interface (which must be GW1) is wrong. The second route is OK, so the first map of this route is tried. Remember that the called party number in the call setup is still empty (as the 0 has been taken away by the PBX trunk object). So when the routing engine checks if the number matches the map restriction (0043), then it finds that it could match. However, more digits need to be analysed. So the call will be blocked at this point and the relay will wait for the user to dial further digits. As soon as the user has dialled 0043, the first map will be tried. Also, as soon as the user dials a digit that is not in 0043, the first 2 maps are skipped and the third map is tried.

While this already works fine, there is one problem with it. When the user dials 0, he certainly expects to hear a dial-tone from the carrier. However, as the call is stuck in the routing engine waiting for more digits, the user will hear nothing and probably assume that something is wrong. The solution is to insert a screenshot.png map which routes all calls to the TONE interface (fish-help.png Gateway/Interfaces). It will play a tone until the next digit is received and then report a local failure. The routing engine will try the next maps then.

We have seen how to modify the called party number on a call. We can do this with the calling party number too. Assume we have a help desk number 400 in the PBX and there are a number of agents serving the help desks whose extensions are in the range 401 to 409. To make sure these extensions will not be visible to external customers, we replace the calling party numbers to 400 for those agents (so customers would call back the help desk number instead of the individual agent). This can be done by defining fish-help.png CGPN-Maps to the relevant maps which screenshot.png modify the calling party number.

Please note that each CGPN-Map applies to a single map only. You may need to duplicate into all maps (like in this example). Please note the exclamation mark in 40!->400. This is wildcard matching any remaining digits. There are various wild cards available for fish-help.png maps and fish-help.png CGPN-Maps.

There are a number of further flags available as described in Wiki. However, one is of particular interest: the screenshot.png Verify CGPN in the map configuration. If this is set, then a map will only be used if one of the CGPN-Maps matches. Normally, CGPN-Maps do not need to match and are used for calling party number modifications only.

Emergency Calls

An important new feature introduced with firmware version 9 is the possibility to prioritize calls over existing ones. This allows the PBX to grant access to a certain interface to those calls passing through a specifc route configured with the fish-help.png Emergency flag.

In screenshot.png this example, an outgoing call to the emergency number 911 will be allowed to break out through ISDN1 interface even if all the channels are already taken by previous calls. The PBX will simply disconnect one of those calls and let the emergency call out.

Another useful implementation of this feature could be, if combined with Verify CGPN, prioritize company's boss calls over employees ones so that he or she will always have access to the PSTN line.

Emergency Calls and SIP Trunk

In several countries, SIP providers have implemented a scheme where for emergency calls, the dialled number (e.g. 112) must be called by a location-specific prefix. This allows the provider to route the call to the emergency centre next to the calling customer. This prefix however is usually not numeric, instead it starts e.g. with a capital letter E followed by some numeric code. A call to 112 may thus for example be carried out as call to destination E2147112 with E2147 being the location code.

Such a called number can be created by using the Name Out property in a route as described in fish-help.png Gateway/Routes/Map. You would create a map matching the CDPN 112 and map it to a called name E2147°. This will remove the called party number from the call and add a called party name where the character ° is replaced by the original called party number.

This number is used to create the called party URI when interworked to SIP (something like E2147112@sample.provider.tld). It is sent as called name when interworked to H.323 or QSIG.


Call switching is controlled by the gateway's routing table (in the Routes tab).The routing table is searched top down for a matching map in a route. If a matching map is found,

  • whose route has specified the source interface of the current call as a permitted interface in the enable calls from interfaces list and
  • whose dial prefix specified in the Number -in field matches the called number of the current call, and whose Verify CGPN box is not checked or whose Verify CGPN box is checked and the calling number of the current call matches the calling Number-in field

then, the current call will be switched to the interface specified in the Interface to field in the map. In the process, the called number is modified in such a way that the dial prefix in the Number in field is replaced by the sequence of digits in the Number out field. The calling number is modified accordingly using the Number in and Number out fields if the CGPN maps, whose number in field matches the dial prefix of the calling number of the current call. If it is not possible to switch the call to the identified interface however, the routing table is searched for the next map entry that meets the requirements specified above.

Sample: Handling CLIR to Extern

Here is a little sample on what you can do with the routing table.

Some customers have the requirement to hide individual extension on external calls. That is, when a user calls another extension, the called phone shall show the calling number. However, when this user calls out through the trunk to an external number, then it shall hide the calling number (i.e. use CLIR). Now, setting CLIR is easily done screenshot.png using the Hide own number check-markn in the fish-help.png Phone/User/Preferences tab of the calling phone. Also, if CLIR shall not be applied internally, then this policy is enforced by screenshot.png setting the No CLIR on internal calls check-mark in the fish-help.png PBX/Config/General tab.

However, nowadays many countries enforce a valid calling number for business calls, so setting CLIR is not an option (and even if not forced by law, showing no calling number is considered offensive by many customers). The better option then is to send the companies switchboard extension (often -0) instead of the individual extension. We can do that for all external calls by just specifying an screenshot.png unconditional CGPN replacement. If it is to be done only for those calls which have the CLIR property set (that is, calls from those users who have the Hide own Number check-mark set), then the configuration is slightly more tricky though.

First of all, keep in mind that a call with CLIR set is not a call without a calling number. It still carries the original calling number, it is just accompanied by a flag saying "do not show this number". That is, if the CLIR bit is removed, the call will show its original calling number again. To remove the calling number from an outgoing call in the routing table, you must both clear the Presentation Restricted flag and remove the entire calling number.

There is another pitfall. If only the calling number and the CLIR flag are removed, then the interface maps will modify the calling number to the trunk's subscriber number followed by nothing. In most countries of the world, you will not be able to call back to this number (as the extension is missing). So you could be tempted to screenshot.png replace the entire calling number with a 0 (as suggested above). However, the screenshot.png standard interface maps (e.g. on a BRI interface) will remove this zero and insert a National Number property instead (as it is assumed that a call with a calling number starting with 0 must be an external call rerouted back by a CFx). The solution is to use the extension number you would route incoming calls to, which call back to the trunk number. In other words, the extension you screenshot.png specify for the Loopback property in the fish-help.png PBX trunk object. If you don't want external users to see this extension as a calling number, then you must specify an explicit interface map for this extension, mapping it back to 0.

screenshot.png Selective CGPN Map on CLIR

Here is a syslog capture from a call from extension 100 to an external destination 05111234:

20110503-114129 CALL 1 Alloc
20110503-114129 CALL 1 A:Call -> / RB1::->*::
20110503-114129 ROUTE 1 INTERFACE MAP if=RB1 CGPN-In
R100->R100, CDPN-In 05111234->05111234, DGPN-In ->
-------------------------------------------- call comes in from pbx with calling number 100 restricted
20110503-114129 ROUTE 1 EVAL ROUTE route=RT2
20110503-114129 ROUTE 1 EVAL MAP route=RT2 map=1 dest='BRI1' in=''->out=''
20110503-114129 ROUTE 1 MAP(CDPN-MATCH OK) route=RT2 map=1 dest='BRI1' in=''->out=''
20110503-114129 ROUTE 1 EVAL CGPN-MAP cgpn=R100 verify=false in=''->out='200'
20110503-114129 ROUTE 1 EVAL CGPN-MAP SUCCESS in=''->out='200'
20110503-114129 ROUTE 1 APPLY CGPN-MAP
-------------------------------------- calling party number map is applied, restricted 100 is mapped to 200 unrestricted
20110503-114129 ROUTE 1 EVAL DGPN-MAP(FAILED) in=''->out='200'
20110503-114129 ROUTE 1 APPLY CDPN-MAP in='05111234'->out='05111234'
20110503-114129 ROUTE 1 SUCCESS route=RT2 map=1 dest='BRI1' in=''->out=''
20110503-114129 ROUTE 1 INTERFACE MAP if=BRI1
CGPN-Out 200->S730090, CDPN-Out 05111234->05111234, DGPN-Out ->S73009
--------------------------------------------- special extension 200 is mapped back to type subscriber, 7300920
20110503-114129 CALL 1 B:Call>05111234 / RB1:R100:Trunk->BRI1:05111234:


Everytime when a call passes the RELAY a fish-help.png CDR will be generated.

The gateway will not store the CDRs but can transmit them to a remote target. They can then be evaluated with the appropriate software. There are several methods of transmitting CDR data which can be configured in the fish-help.png Gateway/CDR tab. Also, 2 target destinations can be configured in the CDR0 and CDR1 tab. This way, the same data can, for instance, be sent to the administrator via SYSLOG and, for instance, to the book-keeping department via HTTP. This also provides redundancy if CDR data is mission critical.

CDRs are either generated for each single call event (such as Setup, Alert. Connect, ...) or summarized at the end of a call depending on the Write CDRs dropdown in the fish-help.png Gateway/General tab. By default, no CDRs are sent at all.

When one of the involved interfaces is an ISDN interface, Advice of Charge records may be received from the carrier. The innovaphone gateway will include the AOC-E type information into the final CDR for a call then.

AOC information elements are passed transparently through the routing engine and via H.323. This way, the information can be passed to remote PBX systems. However, when a call is routed through the PBX, fish-help.png AOC information is lost unfortunately.


The PBX can also write CDRs. This happens if the Generate CDRs check-mark is ticked in fish-help.png PBX/Config/General. These CDRs have a different format (xml based). In most cases, the PBX CDRs are more useful than the older Gateway CDRs. See fish-help.png Concept Call Detail Record CDR PBX for details.

Gateway Calls

In the gateway fish-help.png Calls overview page, all calls actively being made can be monitored. Here you see what codec is used on what call and the current round trip, jitter and packet loss values.
Also it shows what protocol (H.323 or SIP) is used, and if media relay is in use or not.

fish-help.png Information about reading the call screen is described in our wiki.

The used codec is also seen, so you know what codec is used for that call like G.711,T.38, G.729,... also there is one codec called XPARENT.
The codec XPARENT is chosen when the bearer capability is not audio or speech, that means if the B-channel has 'Unrestricted Digital Information’ means data will be sent via the B-channel - then the codec XPARENT will be in use.


In the fish-help.png syslog you can see when calls are passing the RELAY. This helps you find configuration errors in the routing table. In the syslog you see calls in realtime. The messages are constantly automatically updated and are scrolled upwards, out of the window.

To see the gateway calls, tick on Gateway Calls in the fish-help.png Maintenance/Diagnostics/Logging tab.

Syslog Example

the BRI interface is registered at a trunk object in the PBX (automatic routes). The trunk object is called Trunk, and via this trunk object a user (phone ,extension 10) dials a number in the ISDN world (0511987).

20090721-164159 CALL 0 Alloc
|----------|--------|-------|------ Date h/m/sec CallID Event
The CallID is very useful.If you have more than one call in a syslog then you can relate all messages relating to a single call with the CallID.

20090721-164159 CALL 0 A:Call -> / RB1::->*::
A:Call means that the calling party initiates a call. The "/" shows the used codecs (so no codecs are negotiated yet). So this log entry says that a call is initiated via the trunk object because we know that RB1:: is used as the automatic registration of BRI1 to the Trunk object..

20090721-164159 CALL 0 B:Call 10:phone->0511987 / RB1:10:Trunk->BRI1:0511987:
Here B:Call means that now the called party is called. You see B:Call 10:phone->0511987, which means that the extension 10 user phone is calling 0511987. "/" has still no values, so no coder is negotiated yet. RB1:10:Trunk means that the automatic registration RB1 is calling number 10 via the Trunk object (the name configured at the ISDN interface to register at the PBX trunk object). Finally, ->BRI1:0511987 means that the call setup is sent via BRI1 and the number 0511987 is called via BRI1.

20090721-164159 CALL 0 Media 10:phone->0511987 G729AB,30(0,0,0)/G729AB,30(0,0,0) RB1:10:Trunk->BRI1:0511987:
Media means that a media channel has been established and codecs are negotiated as G729AB,30(0,0,0)/G729AB,30(0,0,0) (so we have same codecs in both directions). In this case codec G.729AB is used. The values in the brackets show call quality statistics so far (round-trip,jitter,packet loss). NOTE: If only one side has a codec (left or right side of the "/" ) then the media negotiation did not work and there is only one way audio.

20090721-164159 CALL 0 B:Proceed 10:phone->0511987 G729AB,30(1,0,0)/G729AB,30(0,0,0) RB1:10:Trunk->BRI1:0511987:
B:Proceed - call proceeding on the B-side of the call.

20090721-164159 CALL 0 B:Alert 10:phone->0511987 G729AB,30(1,0,0)/G729AB,30(0,0,0) RB1:10:Trunk->BRI1:0511987:
B:Alert - The B-side of the call (called party 0511987) is ringing.

20090721-164201 CALL 0 B:Connect 10:phone->0511987 G729AB,30(1,0,0)/G729AB,30(0,0,0) RB1:10:Trunk->BRI1:0511987:
B:Connect - the called party is connected.

20090721-164205 CALL 0 B:Disc 10:phone->0511987 G729AB,30(1,0,0)/G729AB,30(0,0,0) RB1:10:Trunk->BRI1:0511987: Cause: Normal call clearing
B:Disc - the called side has disconnected the call (hung up the phone). If a cause code was received (e.g. with the disconnect from the other side), it is shown here. Here it is Cause: Normal call clearing. fish-help.png ISDN Cause Codes are listed in Wiki.

20090721-164207 CALL 0 A:Rel 10:phone->0511987 G729AB,30(1,0,0)/G729AB,30(0,0,0) RB1:10:Trunk->BRI1:0511987: Cause: Normal call clearing
A:Rel - calling party releases the call.

20090721-164207 CALL 0 B:Rel 10:phone->0511987 G729AB,30(1,0,0)/G729AB,30(0,0,0) RB1:10:Trunk->BRI1:0511987: Cause: Normal call clearing
B:REL - the called party releases the call.

20090721-164207 CALL 0 Free
Free - the call ID 0 is free now for another call.

To summarize a list of all the possible events :

A:Call The calling party initiates a call.
B:Call The called party is called.
B:Proceed A call proceeding is received from the calling parties network (or a transit).
Media A media channel has been established.
B:Alert The called party is alerted.
B:Connect The called party is connected.
A:X The calling party transfers the call. Following events will display a different calling party.
B:X The called party transfers the call. Following events will display a different called party.
A:Disc The calling party disconnects the call.
B:Disc The called party disconnects the call.
A:Rel The calling party releases the call.
B:Rel The called party releases the call.
No-Route The gateway routing process has no route for the call.
Personal tools