[Asterisk-doc] docs extensions.xml,1.1,1.2
websmith
asterisk-doc@lists.digium.com
Sun, 11 Jan 2004 08:43:34 +0000
- Previous message: [Asterisk-doc] docs voip-providers.xml,1.1,1.2 chapter02.xml,1.8,NONE chapter03.xml,1.5,NONE chapter05.xml,1.5,NONE chapter06.xml,1.8,NONE chapter07.xml,1.11,NONE chapter08.xml,1.1,NONE
- Next message: [Asterisk-doc] Changes
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
Comments:
Update of /cvsroot/asterisk/docs
In directory sc8-pr-cvs1:/tmp/cvs-serv27005
Modified Files:
extensions.xml
Log Message:
Check in the extension.conf stuff that Steven Critchfield wrote...
Index: extensions.xml
===================================================================
RCS file: /cvsroot/asterisk/docs/extensions.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** extensions.xml 11 Jan 2004 07:48:26 -0000 1.1
--- extensions.xml 11 Jan 2004 08:43:28 -0000 1.2
***************
*** 1,5 ****
<chapter>
<title>Creating Dialplans</title>
! <para/>
! </chapter>
--- 1,391 ----
<chapter>
<title>Creating Dialplans</title>
! <sect1>
! <title>Introduction to <filename>extensions.conf</filename></title>
! <para>
! You will spend many hours in this file. It is the basis for how
! every call made is dealt with. The concepts covered in this section
! will be used the entire time you use asterisk.
! </para>
! <sect2>
! <title>Contexts</title>
! <para>
! The first bit of information to learn about is contexts. Contexts
! have a couple of functions within asterisk dial plan. Contexts
! define scope. All calls that enter asterisk will begin in a
! defined context. What is defined in this context will determine
! what is possible for the call to do. Contexts can also help build
! an IVR menu where you reuse extension numbers as options on you
! menu.
! </para>
! <para>
! Contexts are capable of including other contexts into themselves.
! The include functionality is even possible on a time of day,
! day of week, or day of month basis. The normal use for this
! conditional include is for an automatic transition from business
! hours to after hours prompts to direct a caller.
! </para>
! <para>
! Contexts are denoted by their name inside of square brackets.
! Contexts may contain extension definitions, and includes of other
! contexts.
! </para>
! <programlisting>
! [incoming_calls]
! <lineannotation>; We always want callers to be able to get to the extensions.</lineannotation>
! include => worker_extensions
!
! <lineannotation>; Normal IVR menu</lineannotation>
! include => day_menu|08:00-17:00|Mon-Fri|*|*
!
! <lineannotation>; Tue-Fri mornings are normal after hours</lineannotation>
! <lineannotation>; Mon-Thu nights are normal after hours</lineannotation>
! include => night_menu|00:00-08:00|Tue-Fri|*|*
! include => night_menu|17:00-24:00|Mon-Thu|*|*
!
! <lineannotation>; Mon morning is part of a weekend menu.</lineannotation>
! include => weekend_menu|00:00-08:00|Mon|*|*
! <lineannotation>; Fri evening starts the weekend</lineannotation>
! include => weekend_menu|17:00-24:00|Fri|*|*
! <lineannotation>; and Sat-Sun are weekend times also.</lineannotation>
! include => weekend_menu|*|sat-sun|*|*
!
! [internal_restricted_callers]
! <lineannotation>; our employees should be able to contact our other employees</lineannotation>
! include => worker_extensions
!
! <lineannotation>; only internal callers can call out, and this is restricted to</lineannotation>
! <lineannotation>; local calls</lineannotation>
! include => outbound_local_context
!
! [internal_unrestricted_callers]
! <lineannotation>; our employees should be able to contact our other employees</lineannotation>
! include => worker_extensions
!
! <lineannotation>; only internal callers can call out</lineannotation>
! include => outbound_local_context
! include => outbound_toll_context
! </programlisting>
! <para>
! From this example you should be able to notice that contexts can be
! used to reduce retyping sections as in the worker_extensions being
! included in all the example contexts.
! </para>
! <para>
! Also demonstrated here is the ability to separate privileges. Calls
! coming from outside of our system are not given the ability to call
! out to other phone numbers. Also you will notice the ability to
! separate your internal users from having the same abilities to call
! out. You may not want anyone but your executives to be able to call
! long distance or even international.
! </para>
! </sect2>
! <sect2>
! <title>Extensions</title>
! <para>
! The extension definitions are very much like subroutines in
! programming. You will define them as the steps a call will take as
! it progresses though your dial plan. A single extension line will
! contain the extension number or special letter you are defining, a
! priority number that is very much like old basic programming,
! the function you need to be applied, and any of the arguments to be
! passed to the function. The priority numbers must be consecutive for
! the call to progress from one to the next. Here is an example of a
! extension definition.
! </para>
! <programlisting>
! [sample_context]
! exten => s,1,Wait(1)
! exten => s,2,Answer()
! exten => s,3,Background(hello_prompt)
! </programlisting>
! <para>
! There are 4 special extensions to know about.
! </para>
! <simplelist>
! <member>'s' - start</member>
! <member>'i' - invalid</member>
! <member>'t' - timeout</member>
! <member>'h' - hangup</member>
! </simplelist>
! <para>
! The start extension is for most calls that are initiated with no
! other known information. This is true for calls on normal home
! lines, or non digital lines.
! </para>
! <para>
! Hangup is where calls will go to when hangup is detected, or where
! you can send calls that you want to hangup on.
! </para>
! <para>
! Timeout is for when a user is presented with a menu and they do not
! respond. In the timeout extension you will want to decide if you
! wish to repeat your menu, or just send the call to a hangup so as
! to free up the line.
! </para>
! <para>
! Invalid is for when Asterisk has determined that the input from the
! call is not valid for the current context. You may wish to play a
! prompt explaining the extension was invalid, and then send the call
! back to the extension that contains the menu prompts.
! </para>
! <programlisting>
! [My_home_incoming_context]
! include => my_extensions
!
! <lineannotation>; Make sure we wait long enough for the CallerID to be received.</lineannotation>
! exten => s,1,wait(1)
! <lineannotation>; Answer the line so that the line is available to play audio on.</lineannotation>
! exten => s,2,Answer()
! exten => s,3,DigitTimeout(15)
! exten => s,4,ResponseTimeout(10)
! <lineannotation>; Announce who we are, and what to do.</lineannotation>
! exten => s,5,Background(Hello_prompt)
! <lineannotation>; Here is where a caller is expected to enter an extension</lineannotation>
!
! exten => i,1,Background(invalid_extension)
! exten => i,2,Goto(s,5)
!
! exten => t,1,Background(slow_user)
! exten => t,2,Goto(s,5)
!
! exten => h,1,hangup()
!
!
! [my_extensions]
! <lineannotation>; ring my extension for 25 seconds only</lineannotation>
! exten => 1,1,Dial(Zap/2,25)
! <lineannotation>; if dial falls through, I didn't answer, so play unavailable message</lineannotation>
! exten => 1,2,Voicemail(u1)
! <lineannotation>; If they left a message, hangup
! now.</lineannotation>
! exten => 1,3,hangup()
!
! <lineannotation>; Now if dial failed due to the line being busy, play the busy message</lineannotation>
! exten => 1,102,Voicemail(b1)
! <lineannotation>; again, if the message is left,
! hangup.</lineannotation>
! exten => 1,103,hangup()
!
! <lineannotation>; This wouldn't be a PBX without many more, but they look the same as above.</lineannotation>
! </programlisting>
! <para>
! Here you should see the exception of the priority numbers just
! incrementing by 1. Dial will jump to the next priority + 100 if the
! dial failed.
! </para>
! </sect2>
! </sect1>
! <sect1>
! <title>Variables</title>
! <para>
! There are 2 types of variables in Asterisk. The first kind is a
! per call variable. They are either during call set up, or by
! functions in extension definitions such as SetVar. The Second kind of
! variables are global, and are defined either in the global
! section of the extensions.conf file, or by the function
! SetGlobalVar encountered in a extension definition.
! </para>
! <para>
! Variables can be used for many things. They can be used to help
! reduce typing, or they can be used to limit looping in an error
! condition too long. When using the value of a variable, you
! denote it with a dollar sign and the variable name surrounded
! by curly braces.
! </para>
! <programlisting>
! [global]
! Lief=Zap/3
! Critch=Zap/4
! Wassim=Zap/5
! ALL=${Lief}&${Critch}&${Wassim}
+ [extensions]
+ exten => 1,1,Dial(${Lief})
+ exten => 2,1,Dial(${Critch})
+ exten => 3,1,Dial(${Wassim})
+
+ [incoming]
+ include => extensions
+
+ exten => s,1,Wait(1)
+ exten => s,2,Answer()
+ exten => s,3,Background(hello)
+
+ <lineannotation>; This is where the user can't decide who to call, so we ring everyone</lineannotation>
+ exten => t,1,Dial(${ALL)
+ </programlisting>
+ <para>
+ In this pretty simple example, You can see how it would be
+ easy to change how to dial to someone and have it propagate to
+ the ALL variable. You should also note that it was possible to
+ concatenate the variables just by placing them next to each
+ other.
+ </para>
+ <para>
+ It is also possible to do simple expressions. These expressions
+ are evaluated when placed within square brackets. Expressions
+ are used to either combine values together via addition,
+ subtraction, multiplication, division, or to evaluate truth for
+ use with a GotoIf function for call flow.
+ </para>
+ </sect1>
+ <sect1>
+ <title>Macros</title>
+ <para>
+ When you combine variables with a special form of contexts, you
+ get macros. Macros, like in C, are expanded in the place they
+ are called. Macros are defined much like a normal context except
+ the name is prepended by "marcro-". The arguments you send to
+ this macro will be in variables such as ARG1 and ARG2. There is
+ also a special variable called MACRO_EXTEN so you know where
+ you are being called from.
+ </para>
+ <programlisting>
+ [globals]
+ Lief=Zap/3
+ Critch=Zap/4
+ Wassim=Zap/5
+ ALL=${Lief}&${Critch}&${Wassim}
+
+ [macro-stdexten]
+ exten => s,1,Dial(${ARG1},20)
+ exten => s,2,Voicemail(u${MACRO_EXTEN})
+ exten => s,3,Hangup()
+ exten => s,102,Voicemail(b${MACRO_EXTEN})
+ exten => s,103,Hangup()
+
+ [extensions]
+ <lineannotation>; Let the first to answer the phone be the operator</lineannotation>
+ exten => 0,1,Macro(stdexten,${ALL}
+ exten => 1,1,Macro(stdexten,${Lief}
+ exten => 2,1,Macro(stdexten,${Critch}
+ exten => 3,1,Macro(stdexten,${Wassim}
+ </programlisting>
+ <para>
+ It should come as no surprise that this is yet another way of
+ reducing typing. We defined the 5 steps that we want taken for
+ each of the extensions in one place only. This helps also in
+ reducing typing mistakes.
+ </para>
+ </sect1>
+ <sect1>
+ <title>Call flow</title>
+ <para>
+ This is where we put a few more pieces together to pull some of
+ these concepts into a more interesting example. We also need to
+ cover how to create menus.
+ </para>
+ <para>
+ Dial plans take time to develop due to the need to think about
+ how it affects other sections. Key presses will attempt to be
+ matched to an extension as long as there is a possibility for
+ the current pattern to be further matched. Any time you have
+ ambiguous matches where the digits type can match one extension
+ exactly and another partially, you will have to wait for the
+ timeout to go to the shorter extension match. So it is usually
+ important to designate certain digit ranges for certain
+ functions.
+ </para>
+ <para>
+ You may be used to noticing that 9 is associated with dialing
+ an outside line. This is due to the fact that in a local
+ calling area, the exchanges could over lap other sections of
+ your dialplan. Similarly you may have noticed that with in
+ certain companies, all the extensions will start with a
+ specific number. Like the 9, the specific number will denote
+ the type of function you are about to match against.
+ </para>
+ <para>
+ When you are choosing some of your dial plan, you should keep an
+ eye on expandability. Going through a change in dial plan can
+ cause a major headache to the users on your system. Something
+ as simple as choosing the range used for extensions, will
+ determine the maximum number of extensions you can expand to
+ before having to change things around.
+ </para>
+ <para>
+ For example, if you choose single digit extensions, there will
+ only be up to 9 options when you consider 1 entry will be used
+ for selecting an outgoing line. It isn't uncommon for a
+ moderately sized company to choose 4 digit extensions all
+ starting with the same digit. This will allow them 1000
+ extensions with only using a single leading digit.
+ </para>
+ <para>
+ Another part that makes the extensions file so versatile is the
+ pattern matching ability. Patterns are defined by placing an
+ underscore as the first character of the extension definition.
+ Exact matches can be typed as is, the letter 'X' matches all
+ digits, and the letter 'N' matches 2-9. This is especially
+ useful when defining outside phone number availability.
+ </para>
+ <programlisting>
+ [global]
+ Lief=Zap/2
+ Critch=Zap/3
+ Wassim=Zap/4
+ Jared=Zap/5
+ Brian=Zap/6
+ Support=${Wassim}&${Critch}&${Brian}
+ Sales=${Lief}&${Jared}
+ ALL=${Sales}&${Support}
+
+ [macro-stdexten]
+ exten => s,1,Dial(${ARG1},20)
+ exten => s,2,Voicemail(u${MACRO_EXTEN})
+ exten => s,3,Hangup()
+ exten => s,102,Voicemail(b${MACRO_EXTEN})
+ exten => s,103,Hangup()
+
+ [extensions]
+ <lineannotation>; Let the first to answer the phone be the operator</lineannotation>
+ exten => 0,1,Macro(stdexten,${ALL}
+ exten => 5001,1,Macro(stdexten,${Lief}
+ exten => 5002,1,Macro(stdexten,${Critch}
+ exten => 5003,1,Macro(stdexten,${Wassim}
+ exten => 5004,1,Macro(stdexten,${Jared}
+ exten => 5005,1,Macro(stdexten,${Brian}
+
+ [incoming]
+ include => extensions
+
+ exten => s,1,Wait(1)
+ exten => s,2,Answer()
+ exten => s,3,Background(hello)
+
+ exten => 1,1,Goto(Sales,s,1)
+ exten => 2,1,Goto(Support,s,1)
+
+ <lineannotation>; This is where the user can't decide who to call, so we ring everyone</lineannotation>
+ exten => t,1,Dial(${ALL)
+
+ [Sales]
+ include => extensions
+
+ exten => s,1,Background(Sales_blurb)
+
+ exten => 1,1,Macro(stdexten,${Lief})
+ exten => 2,1,Macro(stdexten,${Jared})
+
+ exten => t,1,Hangup()
+
+ [Support]
+ include => extensions
+
+ exten => s,1,Background(Support_blurb)
+
+ exten => 1,1,Macro(stdexten,${Wassim})
+ exten => 2,1,Macro(stdexten,${Critch})
+ exten => 2,1,Macro(stdexten,${Brian})
+
+ exten => t,1,Hangup()
+
+ [internal]
+ include => extensions
+
+ exten => _9NXXXXXX,1,Dial(${Trunk}/${EXTEN})
+ exten => _91NXXNXXXXXX,1,Dial(${Trunk}/${EXTEN})
+ </programlisting>
+ </sect1>
+ </chapter>
- Previous message: [Asterisk-doc] docs voip-providers.xml,1.1,1.2 chapter02.xml,1.8,NONE chapter03.xml,1.5,NONE chapter05.xml,1.5,NONE chapter06.xml,1.8,NONE chapter07.xml,1.11,NONE chapter08.xml,1.1,NONE
- Next message: [Asterisk-doc] Changes
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]