Dial Plans

Dial plans are used to route (and optionally modify) specific dialed numbers to specific trunks. Dial plans are used when an internal destination could not be found.

Basically, it first compares a pattern with the dialed number according to matching rules. If it matches, it replaces the dialed number according to the replacement rules (if replacement field is not empty) and sends the call to the trunk set for that rule (pattern). If it doesn’t match, it moves on to the next rule, and so on.

The rules are defined in separate lines and each contains at least:

• A trunk to which the call is sent if the pattern matches.
• A pattern which the dialed number must match for the rule to trigger. For example a pattern 9* would mean any dialed number starting with 9 would be sent to the trunk set in this rule.
• Optionally, a replacement field which replaces the dialed number (according to replacement rules) before sending it to the set trunk. So, for example, if the pattern is 9* and the replacement rule is 1*, then the number 92121234567 will be replaced with 12121234567 . If the replacement field is empty, then the dialed number is not touched as it is sent to the set trunk.

The dial plan is sorted by the priorities before execution. Lower numbers will be matched first. If the numbers are the same and the dial plan entry is resumed later (e.g. because of a trunk failover), it will continue with the next higher number.

Dial plans can be global. This means that all domains can use this dial plan. This makes sense in multi-tenant environments where all domains can share the same dial plan and the same trunks.

The PBX can check if a number is on a do-not-call list. This uses the address book of the user and domain—if the entry has the do-not-call flag set it will not call the number.

The numbers that are put into the dial plan are usually in the readable format. This means the number is presented in the way that a user would read it. This means that in North America, domestic numbers are 10-digits (without the leading 1) and international numbers start with 011. For the rest of the world, domestic numbers start with a single 0, and international numbers start with a 00. If an area code is present, the PBX will use the local presentation if the call is within the area code. You can change this behavior in the dial plan, for example if you prefer the E164 format in the dial plan.

Creating a Dial Plan

• Go to your selected domain in the Vodia PBX web interface.
• Click on Dial Plans under Features as shown above.
• Give a Name for the new dial plan you want to create.
• Press Create .

The new dial plan will appear in the list above. You can now click it in order to configure it. You can also enter any other dial plan in the list, for modification, by clicking it.

Configuring a Dial Plan

Go to your selected domain in the Vodia PBX web interface.

• Click on Dial Plans under Features as shown above.
• Click on the dial plan on the list that you want to configure.
• Here you can modify the fields for the different rules of the dial plan.
• Here you can also create new rules or remove rules or enable or disable them.
• To create a new rule, simply enter all its fields, like the pref number, selecting the rule's trunk from the dropdown, the pattern to match, and the replacement (which should be left blank if you don't want to touch the dialed number before passing it to the trunk). You can also enter a service flag for the dial plan to be active or not, depending on the timings given in the service flag.
• Press Save.

The new rule will appear on a separate line on the list of rules.

Dial plans have a few parameters that control how the system processes the dial plan:

Name: This is the human readable name for the dial plan. Global: If this flag is turned on, the dial plan will be available to all tenants of the system. Number presentation in dial plan: This parameter determines how numbers are fed into the dial plan. By default, the system reformats the number that a user has entered into a unique presentation, for example it does not make a different if a user dials 16173998147, 6173998147 or +16173998147. Check if number is on do-not-call list: When this flag is enabled the system will first check if a number is on the do-not-call list in the tenant before processing the number. Star codes that are handled in dial plan: This setting lists the star codes that are handled by this dial plan. Star codes must start with *. If the list is empty, the dial plan will not handle star codes. Otherwise, the list contains the star codes that are handled by this dial plan, for example when the list is *54 *55 this dial plan will handle *54 and *55, all other star codes will be processsed internally by the system. If a star code ends with a *, the system will match only the beginning. For example when the entry is *54* the system will match *54, *541 and *54123. If the pattern is *, all star codes will be handled by the dial plan. Route internal calls: When this flag is enabled, the system will check if the dialed number is an internal resource of the tenant and send the call there without processing the dial plan.

Dial Plan Entries

There are several fields in the dial plan:

Preference. The preference is used to tell the system how to sort the dial plan. Trunk. The trunk drop down field contains the trunk that should be used. There are some special fields that are explained below. C. This fields stands for CMC, or client matter code. When checked, the PBX will attempt to collect the client matter code from the user before placing an outbound call. This can be useful for accounting purposes. P. When this field is turned on, the PBX will ask the user to enter the PIN code. The pin code can be set under each extension level > Account Profile > PIN setting. This can be useful to protect expensive dial plan entries from abuse, e.g. employees walking into office calling international destinations. Pattern. The pattern field defines when the entry matches. This field is described below. Replacement. When the pattern matches, the PBX may transform the user input, for example put numbers in front of the dialed number. This is also explained in more detail below. Service Flag. Each dial plan entry may be enabled or disabled with a service flag. That makes it possible to enable certain entries based on time or based on manually set flags. Status. In addition to the service flag, each entry may be manually enabled or disabled.

In the trunk drop down, there are additional options available:

• Not Allowed: When this entry is selected, the PBX will stop processing the dial plan and reject the call. Starting with version 68, if you enter a text in the replacement field, the system will use that text as annoucement to the user why the call was rejected (in the audio language of the tenant).
• Call Extension: This will send a call not to trunk, but to an extension. The extension must be in the replacement field. This option can be useful when using PSTN gateways behind NAT that must register with the PBX as an extension in order to be accessible through the firewall.
• Try Loopback: When there are multiple domains, the PBX may try to send the call into another domain through a "loopback trunk". The replacement must contain a telephone number (starting with +) or a SIP URL with a username and a domain that exists on the system (since version 5.4). If that account can be located on the local system, the call will be sent there. This makes it easy to use multiple domains on the same system without an external SIP proxy.

Pattern Matching

Simplified pattern matching.

There are two ways to match the dialed number, simplified and extended regular expression. Before feeding a number into the pattern matching the system represents the number in the local domain country code format. For example, in the US with the country code 1 a number 1617123123 would be reformatted to 6171231234 and +493055578992 would be formatted into 011493055578992 (unless a different presentation was selected). This makes it easy to match patterns, no matter how the user has dialed the number.

Simplified expressions are based on the following rules:

• Patterns can be separated by the | symbol. In this case the pattern matches if one of the pattern matches. For example 911|411 would match either number 911 or 411.
• A literal matches if the input is equal to the parameter. For example the pattern 911 matches only if the dialed number was 911.
• The symbol x in a pattern matches any character. For example, the pattern x11 matches 911, 411, and any other 3-digit number that ends in 11.
• The symbol * matches an arbitrary long number of digits. When using this pattern, the replacement will use only the digits matched by the symbol.
• Symbols in angle brackets match the characters in the bracket. For example pattern [0-7] matches characters 0 to 7, [134] matches characters 1, 3 or 4.
• Area codes can be matches by using a area codes pattern. For example [usa] matches the domestic USA area codes (more below). This makes sure that the rule applies only to a list of codes that are hard to express in a pattern. For example the pattern [usa]xxxxxxx would match only domestic USA destinations.

Currently the following area codes are defined:

• [usa] domestic USA (3 digits)
• [can] Canada area codes (3 digits)
• [ala] Alaska area codes (3 digits, currently 907)
• [haw] Hawaii area codes (3 digits, currently 808)
• [fre] Toll Free USA area codes (3 digits, currently 800 888 877 866 855 844 833)
• [pre] Premium USA (3 digits, currently 900)
• [pue] Puerto Rico area codes (3 digits, currently 787 939)
• [dom] Dominican Republic area codes (3 digits, currently 809 829 849)
• [vir] United States Virgin Islands area codes (3 digits, currently 340)
• [eur] European Union country codes

For simplified patterns, the replacement contains literals and the * symbol to insert the match. For example, 789* would put 789 in front the number that was matched. If there is no replacement pattern, it will automatically insert the matched pattern.

Extended Pattern Matching

Extended pattern matching is more powerful, but it comes at the price of higher complexity. Simple and extended patterns can be mixed in the dial plan per dial plan entry.

The input to extended patterns is in the form number@domain. The patterns are fed into the extended regular pattern matching. The matches can be referenced with the \1, \2 and so on. \r references the domain name.

Dial Plan Samples

Basic Dial Plan

In many cases, you may just want to route all numbers to an outside trunk. This can be done easily by using the pattern * You don’t need to fill anything into the replacement field, the system will automatically use * as replacement.

Dial Plan with Prefix in Front of the Number

If you use a pattern like 1* in the replacement field, the system will automatically put a 1 in front of the match that it found in the pattern field. In the case when you use the pattern 617* and dial the number 6171234567 , the system will automatically convert that into a 16171234567.

(Emergency Numbers)

In the past it was common to use a prefix to tell the system that the call is an outbound call, for example a 9. While this is confusing for most callers, it is dangerous for users in case of emergency when there is no time to figure out how to make an outbound call. In some juristictions including the United States is it now the law that callers must be able to dial emergency numbers without a prefix.

A North American Dial Plan

If you use the Vodia PBX telephone system in the fixed-length dial plan of North America, you may use a dial plan similar to the one that follows:

911|411 The first pattern matches the emergency number and the service number explicitly. 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 or are rejected. If available, these calls can be sent to a seperate trunk which might point to a local gateway. 011* The second pattern matches all international numbers and sends them to a special trunk, which is intended to save costs for international calls. [usa]xxxxxxx The third pattern deals with all domestic calls. The fixed-length pattern was used so that the system can actually tell when this number is complete. The replacement puts a 1 in front of the number, putting it into a 11-digit representation.

Sending Star Codes on a Trunk

Extended regular expressions can be used when sending star codes on a trunk.

When passing a star (*) to the carrier, a backslash is required before the star (e.g., \*67); otherwise, the system will treat the star and the numbers that follow as a star code. In the sample shown above, a backslash has been placed before the Block Caller-ID (*67 ) star code, so when the trunk is used, the system will replace the \*67 with a *67 , causing the caller-ID to be blocked. (The d in the latter part of the string tells the system to replace it with the domain. If an r had been used, the system would replace it with the registrar.)

Important: When using star code patterns in dial plans, you must remove the code from the standard star codes and/or any customized codes. If you’d rather not use star codes in the pattern field but still want to have the dial plan activate a star code, you can use a workaround. You can create a “stand-in” star code that will be used to correlate with the desired star code. In the example shown below, users will need to enter 99 before entering the actual phone number. The system will replace it with the *67 star code. This method allows you to retain the *67 star code as part of the default list of star codes; however, users will need to be informed ahead of time so they that will know to enter 99 before entering the phone number.

Extended regular expressions

If the standard simple dialplan processing does not fit the needs, the system can use extended regular expressions instead. A typical dial plan would include 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 that 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 to the recipient that the number is a telephone number).

The following dial plan illustrates the use of the caret. It’s being used to force the system to begin matching from the start of user input.

Assigning dial plans

You can create several dial plans and give them different names.

You can select any of these dial plans as a default dial plan for a domain. The setting is Default dial plan in the domain general settings .

When the dial plan for accounts, like extensions (see setting Dial plan), or auto attendants etc., is set as Domain Default, which is the default setting, then the above domain default dial plan will be used for that account.

However, any other dial plan (from the list you created) can be set for each account, like extensions, or auto attendants etc.

Text mode

Complex dial plans can be hard to edit. In order to make this easier, there is a text mode in the dial plan web page. This mode converts the dial plan into a CSV text file that can be edited and copied e.g. into other tenants.