Domain dial-plans
From Pbxnsip Wiki
Contents |
Dial Plan
The dial plan consists of four components:
- The preference is a number that used to sort the dial plan entries. When the PBX searches a matching entry in the dial plan, it process the entries of the dial plan from the lowest preference value to the highest preference value. You may use the same preference value for several entries; however in this case the PBX will randomly pick one of the entries for you.
- The Trunk setting defines which trunk is used for the call. In this drop down menu you will find the available trunks in this domain by their name. If you select a trunk then, if the dial plan entry matches a number, the PBX will send the call to the selected trunk. In addition to the list of available trunks the PBX offers more choices:
- If you select "Not Allowed" and the pattern matches the input, then the PBX just denies the call. This mode is used to stop processing the dial plan. This makes it easier to define exceptions of calls that should not be sent out (e.g. 0800 numbers).
- The mode "Call Extension" sends a call to a registered extension. In this mode, the replacement must contain an extension number. In most cases, you can just "hard code" that extension (e.g. set it to "123"). But you can also use the rules for generating a replacement pattern including the \1...\9 replacement strings.
- The mode "Try Loopback" is useful when you have several domains on the same PBX and you want to send a call from one domain to another without the need of an external SIP proxy. In this mode, the PBX will first check if there is a match of the pattern, and then calculate the destination using the replacement pattern. If the destination matches a telephone number (starting with "+") on the local system, then the PBX will send the call back to the system. Note: You must turn "Loopback detection" off (see Overall System Settings) and you must have at least one UDP socket (not bound to any specific address or bound to the loopback address 127.0.0.1 or [::1]).
- The pattern setting is matched against the destination of the call. See below for the description of the matching algorithm.
- The replacement is used in the To-header as well as in the Request-URI. See the description below.
Simple Dial Plan
In most of the cases, you can use simple patterns.
- Literals. If you want to match a specific number (e.g. 911), just put that number there. The literal will be the first match in the expression.
- Prefixes. If you want to match a specific prefix, put that prefix there with a star behind it. For example, "9*" would match all numbers that start with a 9. The prefix will not be part of the match, only the string matched by the * will be the match of the first expression.
- Fixed patterns. If you use a "x" in a pattern, the PBX will treat it as a wildcard for 0-9. For example, 978xxxxxxx will match any number with the area code 978.
If you use the simplified expression, you don't have to specify a replacement. The PBX will automatically put a "sip:\1@\r;user=phone" as the replacement. There is also a simplified replacement. If you put a prefix in front of a star, the PBX will insert that prefix before the match. For example, "1*" will put a "1" in front of the match.
Examples:
- Pattern "91*" and replacement "1*": If the input is "919781234567@domain.com", the output will be "19781234567@domain.com"
- Pattern "978xxxxxxx" and no replacement: If the input is "9781234567@domain.com", the output will be "9781234567@domain.com"
- Pattern "911|411" and no replacement: This will match input "911@domain.com" and "411@domain.com".
- Pattern "xxxxxxx" and a replacement of "234xxxxxxx" will insert the area code of 234 to the 7 digit number and input "234xxxxxxx@domain.com"
Regular Expression Matching
The regular expression matching algorithm is a very flexible algorithm that follows the NAPTR algorithm of RFC 2915. For an exact description, please refer to this document.
The pattern string of the dial plan is surrounded by a "^" and a "$" (to make sure that the whole string is matched". The PBX uses the username and the hostname. The port number, parameters and the scheme are not included for the comparison.
If there is a match, the PBX will generate the resulting destination from the replacement string. The string may include references to matching groups in the pattern string. These matches are referred by the group number (starting with 1). Additionally, the matching string 'r' may be used to insert the registrar name.
Technically, that is the description of the algorithms. The example in the next section will make the algorithms more understandable.
To delete a dial plan entry, just clear the pattern and the replacement and press the Edit button.
For more on Regular Expressions see http://en.wikipedia.org/wiki/Regular_expression
Examples
Typical dial plan
A typical example is the string ([0-9]*)@.* as pattern and sip:\1@\r;user=phone as the replacement. The pattern string has one group [0-9]*, which is referred in the replacement string as \1. That means, if the pattern is matched against the value 2121234567@test.com, it will store 2121234567 in the first group and the result will be sip:2121234567@test.com;user=phone (the user=phone indicates the recipient that the number is a telephone number).
A very simple dial plan
In many cases, you just want to route all numbers that start with a “9” to an outside trunk. This can be done easily just by using the pattern “9*”; you don’t need to fill anything into the replacement field (the PBX does that automatically).
Dial plan with prefix in front of the number
If you use a pattern like “1*” in the replacement field, the PBX will automatically put a “1” in front of the match which it found in the pattern field. In the case when you use the pattern “9*” and dial the number 92121234567, the PBX will automatically convert that into a 12121234567.
A dial plan example for North America
If you use the PBX in the fixed-length dial pal of North America, you may use a dial plan like the one below.
The first pattern matches the emergency number and the service number explicitly and sends it to the local gateway. It is a good idea to have an entry for these important numbers, so that they don’t accidentally get routed to the wrong gateway.
The second pattern matches all international numbers and sends them to a special trunk, which is supposed to save you costs for international calls.
The third pattern deals with all domestic calls. We use the fixed-length pattern here, to that the PBX can actually tell when this number is complete.
You could add another pattern like 91978xxxxxxx and send those calls to another trunk if you have negotiated a flat rate with your local PSTN service provider.
Sending star codes on a trunk
In this case you need to fall back to the good old extended regular expressions:
The pattern matches pattern that start with a star symbol followed by any number of digits. The replacement then inserts the star again and puts the dialled number behind the star. Alternatively, you could include the star symbol in the match group of the pattern and then you would not have to put the star in the replacement.
Dial Plan List
Purpose
Each domain may have zero, one or more dial plans. Dial plan are used when an extension dials a number that is not available on the local PBX. You can assign the dial plan per extension. This gives you the possibility to assign different permissions to the extensions. For example, you might want to have a "Local" dial plan that handles only local calls and an "International" dial plan with permission to make international calls.
Dial plans are not used to control the PBX. For this purpose, each domain has a list of star codes.
Create Dial Plan
To create a dial plan, just enter the name in the creation box in the "Show List" link for the dial plans. The name may be any descriptive name; you may include spaces and capital letters.
The list shows the available dial plans. If you want to delete a dial plan, click on the delete symbol and all dial plan data will be lost. If you click on the edit button, you can set up the details of the dial plan. The wildcard patterns are a simple way to match a pattern in the PBX. This pattern matching scheme is pretty simple and not as powerful as the extended regular expression (ERE) pattern matching. However, it solves most of the problems.
Wildcard Patterns
The wildcard pattern matching is used for example in the following places:
- Checking the permission who is allowed to page a Paging.
- The Dialog Permissions in every account use it.
- The permission to record a message in the Agent Group, IVR Node or Auto Attendant.
- The permission to change the status of a Service Flag.
The following wildcards are available:
- A '*' matches any string (with any length).
- A '?' matches any character (length one).
- A '$' matches a single digit (length one).
- A '%' matches any number (multiple digits or empty string)
- A range enclosed in '[' and ']' matches that range.
- A '\' matches the following character.
Examples. The following examples show typical usages of the wildcard patterns.
- The pattern "9*" matches any thing starting with a 9.
- The pattern "*9" matches anything ending with a 9.
- The pattern "11[02]" matches the patterns 110 and 112.
