Explaining Dial Plan

From Asterisk Australia

Q. What is a Dial Plan and how to configure it?

The SPA syntax for the dial plan closely resembles the corresponding syntax specified by MGCP and MEGACO.  Some extensions are added that are useful in an end-point.

The dial plan functionality is regulated by the following configurable parameters:

• Interdigit_Long_Timer
• Interdigit_Short_Timer
• Dial_Plan ([1] and [2])

Other timers are configurable via parameters, but do not directly pertain to the dial plan itself. They are discussed elsewhere in this document.

Getting to Know Interdigit Long Timer

The Interdigit_Long Timer specifies the default maximum time (in seconds) allowed between dialed digits, when no candidate digit sequence is as yet complete (see discussion of Dial_Plan parameter for an explanation of candidate digit sequences).

Getting to Know Interdigit Short Timer

The Interdigit_Short_Timer specifies the default maximum time (in seconds) allowed between dialed digits, when at least one candidate digit sequence is complete as dialed (see discussion of Dial_Plan parameter for an explanation of candidate digit sequences).

Getting to know Dial Plan[1] and Dial Plan[2]

The Dial_Plan parameters contain the actual dial plan scripts for each of lines 1 and 2.

Getting to Know Dial Plan Digit Sequences

The plans contain a series of digit sequences, separated by the | character.  The collection of sequences is enclosed in parentheses, (' and ').

When a user dials a series of digits, each sequence in the dial plan is tested as a possible match.  The matching sequences form a set of candidate digit sequences.  As more digits are entered by the user, the set of candidates diminishes until only one or none are valid.

Any one of a set of terminating events triggers the SPA to either accept the user-dialed sequence, or transmit it to initiate a call, or else reject it as invalid.  The terminating events are:

• No candidate sequences remain 
  The number is rejected.
• Only one candidate sequence remains, and it has been matched completely
  The number is accepted and transmitted after any transformations indicated by the dial plan, unless the sequence is barred by the dial plan (barring is discussed later), in which case the number is rejected.

o  A timeout occurs: the digit sequence is accepted and transmitted as dialed if incomplete, or transformed as per the dial plan if complete.

o  An explicit 'send' (user presses the '#' key): the digit sequence is accepted and transmitted as dialed if incomplete, or transformed as per the dial plan if complete.

The timeout duration depends on the matching state.  If no candidate sequences are as yet complete (as dialed), the Interdigit_Long_Timeout applies.  If a candidate sequence is complete, but there exists one or more incomplete candidates, then the Interdigit_Short_Timeout applies.

White space is ignored, and may be used for readability.

Getting to Know Digit Sequence Syntax

Each digit sequence within the dial plan consists of a series of elements, which are individually matched to the keys pressed by the user. Elements can be one of the following:

• Individual keys '0', '1', '2' . . . '9', '*', '#'.
• The letter 'x' matches any one numeric digit ('0' .. '9')
• A subset of keys within brackets (allows ranges): '[' set ']' (e.g. [389] means '3' or '8' or '9')
  o Numeric ranges are allowed within the brackets: digit '-' digit (e.g. [2-9] means '2' or '3' or ... or '9')
  o Ranges can be combined with other keys: e.g. [235-8*] means '2' or '3' or '5' or '6' or '7' or '8' or '*'.

Getting to Know Element Repetition

Any element can be repeated zero or more times by appending a period ('.' character) to the element. Hence, "01." matches "0", "01", "011",  "0111", ... etc.

Getting to Know Subsequence Substitution

A subsequence of keys (possibly empty) can be automatically replaced with a different subsequence using an angle bracket notation: '