English

The Dialplan is one of the most important functions to set up during the configuration of a beroNet Gateway. It defines how calls are being routed in certain circumstances. Here are two important information to know about this tool:

• It is based on regular expressions ('Howto RegEx'.)
• It works from top to bottom: if a call matches the parameters of a rule, then the rule will apply. Therefore general rules should be placed under more precised ones. 

In the above example, the calls coming from our SIP account will be routed to the first ISDN port only when the number "03025938919" is called. In any other case, the calls will be routed to the ISDN port number 2. If we had put the precise rule in a second position, calls would never be routed to ISDN port 1.

As this tool is a major part of the beroNet Gateway, it is important to exactly understand how it works. Let's take a closer look at the different possible options:

1. Direction (From and to ID)
2. Destination and New destination
3. Source and New source
4. Position

1) Direction (From ID and To ID)

Here we choose the technology (SIP, Analog, ISDN or GSM) the call has to come from in order for the rule to apply. Of course, we also choose to which technology the call will be routed to. 

When we choose ISDN, Analog or GSM as "from" or "to", we have the possibility to choose either a group of ports or one port within a certain group.  

On the other hand, when SIP is set as "From", it is possible to choose the "Match type". Different possibilities are then offered: we can match via the IP address, via the from or to user, via a manual address or in a default way. The matchtype will be coded in the configuration file "isgw.dialplan" as a prefix before the name of the SIP Account. The following prefixes exist: 

• 'p:' - Match Type IP Address only
• 'd:' - Match Type IP Address and From User
• 't:' - Match Type To User only 
• 'a:' - Match Type Automatic, the Matchtype configured in the SIP account will be used.

Usually, Dialplan rules work as pair of two rules: when the gateway routes the call from a SIP account to ISDN lines, it is often necessary to route the calls in the other way i.e. from ISDN to SIP. Therefore two rules are necessary: one from SIP to ISDN and the other from ISDN to SIP.

2) Destination and New destination

The "Destination" field enables a user to make a rule apply when a certain number is being dialed. This field is also known as "CalledID" or "DAD": If the field is left empty, then "(.*)" is automatically added. This means that the rule will apply whichever the called number is. In our first example, we explained that the first rule would apply when the number "03025938919" is called. Therefore we added this number in the destination field.

The field "new destination" enables the gateway to modify the DAD.The default "\1" sends to the "To" technology the variables that are set between brackets in the "Destination" field. 

In the example above, the gateway is transparent, meaning that it sends the dialed number the way it received it.

In this example, the rule will apply when the number "1234" is dialed and the gateway will rewrite this number and send "6789" to the "to" technology.

As we said in the beginning, the beroNet Dialplan uses regular expressions. It enables our partners to create flexible rules without having to make a long list of possible numbers that can be dialed. It is also a good way to only send a certain number of digits. When a gateway is used to connect a traditionnal PBX to SIP for example, it is sometimes necessary to send only 4 digits to the PBX. 

Here, the rule applies when a 10 digit number starting with 014661 is being dialed. Then the gateway sends only the 4 digits that are between brackets and leaves the 6 first ones. For more example, see below.

3) Source and New Source

The "Source" field enables beroNet gateway users to make a Dialplan rule apply only when the call comes from a certain number. This field is also known as "CallerID" or "OAD". The same regular expressions are used. The default parameters are the same as for the "Destination" and "New Destination" fields. Here is a default rule:

 

The "New Source" field enables beroNet users to modify the CallerID with which they call. To call anonymously, we just have to write "Anonymous" in this field. Providers usually do not allow end-users to call with a complete different CallerID but calling anonymously is almost always an option. 

If nothing is changed in both fields, then the gateway does a transparent job: it sends the CallerID it receives in source to ISDN / Analog or SIP depending on the direction of the rule. 

4) Position

The positions of Dialplan rules are very important. As we already explained at the beginning of this blog post: the Dialplan "works from top to bottom: if a call matches the parameters of a rule, then the rule will apply. Therefore general rules should be placed under more precised ones."

Let's take a look at a few example to understand this better:

In this example, according to the first rule, all calls coming from the "SIP_Account" will be routed to the ISDN ports no matter what the CallerID (OAD) or the the CalledID (DAD) is. This means that each and every call coming from this SIP account will be routed to ISDN.

The second rule says: "calls coming from "SIP_Account" with  "0156638515" as a DAD, will be routed to the analog port number 1". However, this second rule is more precise than the first one. It will not apply as long as it is placed under it. In order for it to apply, we need to put it in the first row as below:

In this example, we can send some calls to the analog port when the number 0156638515 is being dialed and the rest is sent to ISDN.

5) Understanding the regular expressions

Regular expressions enable beroNet users to create clever Dialplan rules. Depending on the information set in the "Destination / New Destination" or "Source / New Source" fields, the Dialplan will make a transparent job or change the CID or DAD of a call. 

Let's take a look at some examples:

Example 1: 

Destination:       “0176(.*)”    matches if calledID is starting with 0176
New Destination:   “0049176\1”   will cut 0176 from calledID and add 0049176 to the calledID, followed by reference to parameter 1 
Source:            “(..)”        matches callerIDs with exact 2 digits.
New Source:        “25938912”    CallerID will be overwritten by 25938912

Example 2:

Destination:       ”259389([0-8][0-9])”  matches all numbers starting with 259389 followed by 2 digits in the range from [00-89]
New Destination:   “\1”                  will cut 259389 from calledID and add the 2 digits referenced by parameter 1
Source             “(.*)”                matches any callerID
New Source:        “\1 “                 \1 is the value in the first parenthesize of 'Source'

Example 3:

Destination:       ”0([2-9])(.*))”    matches all numbers starting with 0. The second digit has to be in range[2-9] followed by the any digits.
New Destination:   “\1\2”             will cut 0 from calledID and add the parameter 1 followed by parameter 2 
Source             “(.*)”             will match any callerID
New Source:        “\1 “              \1 is the value in the first parenthesize of 'Source' field

German

Der Dialplan ist das Herzstück der Konfiguration eines beroNet VoIP Gateways. Hier wird die Zu- und Verteilung der Rufe definiert. Es ist wichtig zu wissen, dass: 

• er auf „Regular Expressions“ ('Howto RegEx'.) basiert
• er von oben nach unten abgearbeitet wird. Sobald eine Regel auf einen Ruf zutrifft, wird diese angewendet, so dass es sich empfiehlt, dass präzisere Regeln über allgemeineren platziert werden. 

Im obigen Beispiel gehen Rufe über einen SIP Account ein und werden über den ersten ISDN Port weitergeleitet, sofern die gewählte Rufnummer "03025938919" entspricht. In jedem anderen Fall wird das Gespräch über ISDN Port 2 weitergeleitet. Wäre nun Regel 2 über Regel 1, so würde nie ein Ruf über ISDN Port 1 weitergeleitet werden, da die allgemeinere Regel alle Rufe abfängt.

Es ist von größter Wichtigkeit den Aufbau und die Funktionsweise des Dialplans zu verstehen, da dieser ein wesentlicher Bestandteil der Funktionsweise des Gateways ist. Die einzelnen Felder im Detail sind:

1. Direction (From und to ID)
2. Destination und New destination
3. Source und New source
4. Position
5. Erläuterung der „Regular Expressions“

1) Direction (From ID und To ID)

Hier wählen wir die Technologie (SIP, Analog, ISDN oder GSM) über die der Ruf eingehen soll, damit die Regel auf ihn angewendet wird. Hier wird auch bereits festgelegt über welche Technologie der Ruf dann weitergeleitet werden soll.

Wählen wir ISDN, Analog oder GSM als "From direction" oder "To direction", erhalten wir die Möglichkeit aus den bereits vorher definierten Portgruppen zu wählen. Wählen wir SIP als „From direction“ aus, so definieren wir über die Option „Match type“, ob über die IP-Adresse, dem „From oder To User“, einer manuellen Adresse oder einem „Default SIP account“ gematcht werden soll.

Für gewöhnlich funktionieren die Regeln des Dialplans paarweise, da die Weiterleitung von beispielsweise SIP zu ISDN auch in die entgegengesetzte Richtung ISDN zu SIP gewünscht ist. In diesem Fall müsste die zweite Regel separat angelegt werden.

2) Destination und New destination

Das Feld "Destination" ermöglicht es die Regel anhand einer bestimmten gewählten Rufnummer greifen zu lassen. Dieses Feld ist auch als "CalledID" oder "DAD" bekannt. Sobald das Feld leer gelassen wird, wird automatisch "(.*)" gesetzt, was die Regel bei jeder Rufnummer greifen lässt. In unserem ersten Beispiel griff die Regel sobald die Nummer "03025938919" gewählt wurde. Diese Nummer wurde über das Feld „Destination“ gesetzt.

Das Feld "New destination" ermöglicht es die „DAD“ zu ändern. Die standardmäßige Option "\1" übergibt die im Feld „Destination“ innerhalb der Klammern gesetzten Parameter an die unter „To ID“ gewählte Technologie. 

Im obigen Beispiel arbeitet das Gateway transparent und leitet die gewählte Nummer so weiter, wie sie eingeht.

Im obigen Beispiel greift die Regel sobald die Rufnummer „1234“ gewählt wurde. Das Gateway überschreibt nun diese Nummer und übergibt „6789“.

Wie anfangs genannt basiert der beroNet Dialplan auf „Regular Expressions“. Dies ermöglicht die Erstellung von flexiblen Regeln ohne eine Liste aller möglichen Rufnummern anlegen zu müssen.

So ist es auch möglich nur eine bestimmte Anzahl an Stellen einer Rufnummer zu übermitteln.

Hier greift die Regel wenn eine 10stellige Rufnummer beginnend mit 041661 gewählt wird. Das Gateway übergibt dann lediglich die 4 Stellen die innerhalb der Klammern sind.

3) Source und New Source

Das Feld "Source" ermöglicht eine Regel abhängig von der Absendernummer greifen zu lassen. Dieses Feld ist auch als "CallerID" oder "OAD" bekannt. Hier werden die gleichen „Regular Expressions“ genutzt, so dass die Standardparameter die gleichen wie bei den Feldern „Destination“ und „New destination“ sind. 

Das Feld "New Source" ermöglicht die Änderung der Absendernummer. Um beispielsweise mit unterdrückter Rufnummer anzurufen trägt man "Anonymous" in das Feld ein. Normalerweise gestatten Provider End-Usern nicht mit einer komplett unterschiedlichen Rufnummer einen Ruf abzusetzen, aber das Unterdrücken der Rufnummer hingegen schon.

Ist kein Parameter gesetzt, arbeitet das Gateway auch hier transparent und leitet alles so weiter, wie es eingeht.

4) Position

Die Position der Regeln im Dialplan ist wie anfangs erwähnt von hoher Bedeutung. Da er die Regeln von oben nach unten abarbeitet, sollten präzise Regeln vor allgemeineren Regeln kommen in der Reihenfolge.

In diesem Beispiel greift die erste Regel alle Anrufe die von einem SIP_Account kommen und leitet diese an ISDN weiter.

Die zweite Regel hingegen greift nur die Anrufe ab, die von einem SIP_Account kommen und die Rufnummer  "0156638515" als DAD haben, und will diese an den Analogport 1 weiterleiten. Nun ist die zweite Regel präziser und wird solange nicht greifen, solange sie im Dialplan unter der ersten und allgemeineren Regel steht:

Nun greift die Regel wie beabsichtigt und alle anderen Anrufe werden an ISDN weitergeleitet.

5) Erläuterung der „Regular Expressions“

„Regular Expressions“ ermöglichen eine individuelle Erstellung von Dialplanregeln. Abhängig von den gesetzten Parametern in den Feldern  "Destination / New destination" oderr "Source / New source", arbeitet das Gateway entweder transparent oder aber editiert die CID oder DAD eines Anrufes. 

Ein paar Beispiele zur Verdeutlichung:

Beispiel 1: 

Destination:       “0176(.*)”    greift sobald die calledID mit 0176 beginnt

New destination:   “0049176\1”   0176 wird bei der calledID durch 0049176 ersetzt, gefolgt vom Inhalt der Klammer referenziert durch die 1 

Source:            “(..)”        greift bei callerIDs mit genau 2 Stellen

New Source:        “25938912”    CallerID wird durch 25938912 ersetzt

Beispiel 2:

Destination:       ”259389([0-8][0-9])”  greift bei allen Nummern die mit 259389 beginnen gefolgt von zwei Stellen im Bereich [00-89]

New Destination:   “\1”                  259389 der called ID wird gelöscht und lediglich die 2 Stellen referenziert durch Parameter 1 übernommen

Source             “(.*)”                greift bei jeder callerID

New Source:        “\1 “                 \1 ist der Wert in den Klammern der „Source“

Beispiel 3:

Destination:       ”0([2-9])(.*))”    greift bei allen Nummern beginnend mit 0. Die zweite Stelle muss im Bereich zwischen [2-9] sein gefolgt von beliebigen Stellen

New Destination:   “\1\2”             die 0 wird abgeschnitten von der calledID und Parameter 1 gefolgt von Parameter 2 angehängt 

Source             “(.*)”             greift bei jeder callerID

New Source:        “\1 “              \1 entspricht dem Wert in den Klammern des „Source“ Feldes

French

Le Dialplan (plan de numérotation) des Passerelles VoIP beroNet définit la manière dont les appels sont routés à travers la passerelle beroNet. Deux règles gouvernent le fonctionnement de cet outil: 

• Le dialplan utilise des expressions régulières (‘Howto RegEx’.)
• Le dialplan fonctionne de haut en bas : les règles spécifiques doivent être placées au-dessus des règles générales.

Dans l’exemple ci-dessus, les appels provenant du compte SIP seront uniquement routés vers le premier port ISDN si le numéro « 02025938919 » est appelé. Tous les autres appels seront routés vers le second port ISDN. Si nous avions placé la règle spécifique en seconde position, les appels n'auraient jamais été routés vers le premier port ISDN.

Le plan de numérotation est une étape-clé de la configuration et du bon fonctionnement des passerelles beroNet, c’est pourquoi il est important de bien comprendre ce dernier. Jetons un coup d’œil aux différentes fonctions du Dialplan.

1. "Direction" (From ID and To ID)

2. "Destination" et "New destination"

3. "Source" et "New Source"

4. "Position"

1. Direction ("From ID" et "To ID")

Afin que la règle s’applique, Il faut choisir la technologie d’où provient l’appel et la technologie vers laquelle l’appel doit être routé.

Lorsque l’on choisit ISDN, Analog ou GSM, dans un sens comme dans l’autre, il est possible de choisir soit un groupe de ports, soit un port spécifique situé dans un groupe de ports.

Si on choisit l’option SIP dans "From", il est possible de choisir l’option « match type » qui offre la possibilité de matcher par défaut, via l’adresse IP, via le "from" ou "to user", ou encore via une adresse IP entrée manuellement.

En général, les règles créées dans le plan de numérotation vont par paires : lorsqu’un appel est routé d’un compte SIP vers des lignes RNIS/ISDN, il est alors souvent nécessaire de router les appels dans le sens inverse (ISDN vers SIP par exemple).  Dans ce cas, il est nécessaire de créer deux règles : l’une du SIP vers ISDN, la seconde ISDN vers SIP. À partir du firmware 16.x, une option "reverse rule" permet de créer deux règles d'un coup.

2. "Destination" et "New destination"

Le champ « Destination » permet à l’utilisateur d’appliquer une règle à un numéro appelé spécifique. Ce champ est aussi appelé « CalledID » ou « DAD ». Si le champ est laissé vide, la passerelle insère par défaut « (.*) ». Cela signifie que la règle s’appliquera pour n’importe quel numéro appelé. Dans notre premier exemple, nous souhaitions que la règle s’applique lorsque le numéro « 03025938919 » est appelé. C’est pourquoi nous avons ajouté ce numéro dans le champ destination.

Le champ New destination permet de modifier le numéro appelé / DAD. L’expression par défaut «\1 » contenue dans le champ reprend les variables situées entre la première pair de parenthèse du champ destination. "\2" reprend ainsi les variables situées dans la seconde pair de parenthèses du champ destination.

Dans l’exemple ci-dessus, la règle est transparente: la passerelle enverra le numéro appelé par la technologie "from" vers la technologie "to" tel qu'elle le reçoit. 

Dans cet exemple, la règle s’appliquera lorsque le numéro « 1234 » est appelé. La passerelle réécrira ce numéro et enverra « 6789 » à la technologie vers laquelle les appels sont routés.

Comme indiqué précédemment, le Dialplan beroNet utilise des expressions régulières, vous permettant de créer des règles flexibles sans avoir à rédiger une liste interminable de numéros pouvant être appelés. C’est également un bon moyen de pouvoir envoyer un certain nombre de digits. Lorsqu’une passerelle sert à convertir un PABX traditionnel en SIP par exemple, il est parfois nécessaire d’envoyer seulement 4 digits.

Ici la règle s’applique lorsqu’un numéro à 10 digits commençant par 014661 est appelé. La passerelle envoie uniquement les 4 digits contenus entre les parenthèses et non les 6 premiers digits. Voir ci-dessous pour davantage d’exemples.

3. "Source" et "New Source"

Le champ « Source » permet d'appliquer une règle selon le numéro de l'appelant. Ce champ est aussi appelé « CallerID » ou « OAD ». Les mêmes expressions régulières sont utilisées. Les paramètres par défaut sont les mêmes que ceux utilisés pour les champs "Destination" et "New Destination". Voici une règle par défaut :

Le champ New Source permet de modifier le CallerID avec lequel l’utilisateur appelle. Il suffit alors d’écrire « Anonymous » dans ce champ afin de pouvoir appeler en anonyme. En général, les opérateurs n’autorisent pas les clients finals à appeler avec un CallerID différent de celui qu'il leur a été attribué. Les appels anonymes sont cependant dans presque tous les cas en option.

Si ces champs ne sont pas modifiés, les paramètres par défaut, soit "(.*)" et "\1" seront utilisés et la passerelle agira de manière transparente: le callerID ne sera pas modifié.

4. Position

L’ordre des règles dans le Dialplan est primordial. Comme précisé en début d’article, le Dialplan fonctionne de haut en bas : si les paramètres d'un appel correspondent à ceux d'une règle (technologie source, numéro appelé, numéro appelant), celle-ci s’appliquera. C’est pourquoi les règles générales doivent être placées sous les règles spécifiques.

Regardons quelques exemples pour mieux comprendre :

Dans l'exemple ci-dessus, selon la première règle, tous les appels provenant du "SIP_Account" seront routés vers les ports RNIS quelque soit le numéro appelant (CallerID) ou le numéro appelé (CalledID). Cela signifie que tous les appels provenant du "SIP_Account" seront routés via RNIS.

La seconde règle précise que les appels provenant du SIP_Account avec "0156638515" comme numéro appelé seront routés vers le port analogique 1. Cette règle est plus spécifique que la première, mais elle ne s'appliquera pas tant qu'elle sera positionnée en dessous de celle-ci. Pour que la seconde règle s'applique, il faudra la placer en première position, comme ci-dessous:

Dans l’exemple ci-dessus, certains appels seront envoyés vers le port analogique lorsque le numéro 0156638515 est numéroté. Tous les autres appels seront envoyés vers le port RNIS.

5. Comprendre les expressions régulières

Les expressions régulières permettent aux utilisateurs beroNet  de créer des règles de routage intelligentes. Selon les informations contenues dans les champs « Destination / New Destination » et « Source / New source », le plan de numérotation agira de manière transparente ou changera le CID ou DAD d’un appel.

Regardons quelques exemples :

Exemple 1:

Destination:       “0176(.*)”    s'applique si calledID débute par 0176

New Destination:   “0049176\1”   supprime 0176 du calledID pour ajouter 0049176, suivi par le contenu de la parenthèse du champ "Destination"

Source:            “(..)”        s'applique aux callerIDs à 2 chiffres.

New Source:        “25938912”    le CallerID sera remplacé par 25938912

Exemple 2:

Destination:       ”259389([0-8][0-9])”  s'applique pour tous les numéros commencant par 259389 et dont les deux chiffres suivants se situent dans la fourchette [0-8][0-9]

New Destination:   “\1”                  supprime 259389 du calledID et ajoute les 2 chiffres entre paranthèses du champ destination

Source             “(.*)”                s'applique pour n'importe quel callerID

New Source:        “\1 “                 Reprend la valeur de la parenthèse du champ "source": le callerID ne sera donc pas modifié

Exemple 3:

Destination:       ”0([2-9])(.*))”   s'applique à tous les numéros débutant par 0, dont le second chiffre se situe entre 2 et 9, et suivi pour n'importe quels autres chiffres

New Destination:   “\1\2”            supprime 0 du calledID et ajoute le contenu de la première paranthèse puis celui de la seconde parenthèse du champ Destination

Source             “(.*)”            s'applique pour n'importe quel callerID

New Source:        “\1 “             \1 est la valeur contenue dans la première parenthèse du champ Source