[Asterisk-doc] Updating my time situation, please read!
Jared Smith
asterisk-doc@lists.digium.com
Thu, 15 Jan 2004 07:26:56 -0700
This is a MIME-formatted message. If you see this text it means that your
E-mail software does not support MIME-formatted messages.
--=_daytona-9495-1074176852-0001-2
Content-Type: text/plain; charset=iso-8859-1
Content-Transfer-Encoding: 7bit
On Wed, 2004-01-14 at 12:37, Steven Critchfield wrote:
>
> hmm, I thought I had started simple and built on the previous example as
> I went.
Don't get me wrong, I really appreciate the writing you've done. I'm
just trying to make it *PAINFULLY* simple in order to help out the
absolutely clueless newbie. For someone with previous programming
experience, you're examples work well. But I don't think they're simple
enough for the majority of the people trying out Asterisk these days.
Hopefully the attached file will be clearer on what I'm trying to
accomplish... It's by no means done, but it's as far as I got last night
before I fell asleep. It's mostly just a fleshed-out outline with some
examples, because I was too lazy to actually write out paragraphs. I
copied and pasted the text right out of your file when there was a good
fit.
Again, I'm not trying to offend anyone (especially not Steven) by
changing what's already been written... I'm just trying to make this
particular chapter as newbie-friendly as possible. After all, this
chapter is *the vital* chapter of the whole book. If readers get lost
in this chapter, they'll probably never use Asterisk or read any further
chapters in the book.
(Not only that, but maybe this will help reduce the signal to noise
ratio on the -users list, so that I can actually enjoy reading it
again.)
Jared
--=_daytona-9495-1074176852-0001-2
Content-Type: text/xml; name="extensions2.xml"; charset=utf-8
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename=extensions2.xml
<chapter>
<!-- Chapter outline and examples written by Jared Smith -->
<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>
</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>
</sect2>
<sect2>
<title>Priorities</title>
<para/>
</sect2>
</sect1>
<sect1>
<title>A simple example</title>
<para/>
<sect2>
<title>A simple 1FXOx1FXS setup</title>
<para/>
</sect2>
<sect2>
<title>The special 's' extension</title>
<para/>
</sect2>
<sect2>
<title>The <function>Playback()</function> and <function>Dial()</function> functions</title>
<para/>
</sect2>
<sect2>
<title>Handling Incoming Calls</title>
<informalexample>
<programlisting>
[incoming]
exten=>s,1,Answer()<lineannotation> ; Answer the line</lineannotation>
exten=>s,2,Playback(welcome)<lineannotation> ; Play back the 'welcome' sound file</lineannotation>
exten=>s,3,Dial(Zap/2)<lineannotation> ; Dial the receptionist at channel Zap/2</lineannotation>
</programlisting>
</informalexample>
</sect2>
</sect1>
<sect1>
<title>Adding Additional Functionality</title>
<para/>
<sect2>
<title>Adding another FXS port</title>
<informalexample>
<programlisting>
[incoming]
exten=>s,1,Answer()<lineannotation> ; Answer the line</lineannotation>
exten=>s,2,Playback(welcome)<lineannotation> ; Play back the 'welcome' sound file</lineannotation>
exten=>s,3,Dial(Zap/2&Zap/3)<lineannotation> ; Dial both channels Zap/2 and Zap/3</lineannotation>
</programlisting>
</informalexample>
</sect2>
<sect2>
<title>Creating Voice Menus</title>
<para>
[Explain what IVR is, and why we want it in our dial plan]
[The <filename>menu</filename> file is a voice recording saying
"Press 1 for the Operator or 2 to speak with John"]
</para>
</sect2>
<sect2>
<title>Accepting User Input with the <function>Background()</function> Function</title>
<para>
[Explain the Background() application, and how it's different than Playback()]
</para>
</sect2>
<sect2>
<title>Adding a Voice Menu</title>
<para>
[Now that we understand IVR and the Background() app,
let's use them in our example.]
</para>
<informalexample>
<programlisting>
[incoming]
exten=>s,1,Answer()<lineannotation> ; Answer the line</lineannotation>
exten=>s,2,Playback(welcome)<lineannotation> ; Play back the 'welcome' sound file</lineannotation>
exten=>s,3,Background(menu)<lineannotation> ; Play 'menu' file and accept input from caller</lineannotation>
exten=>1,1,Dial(Zap/2)<lineannotation> ; Dial channels Zap/2 if the user dials 1</lineannotation>
exten=>2,1,Dial(Zap/3)<lineannotation> ; Dial channels Zap/3 if the user dials 2</lineannotation>
</programlisting>
</informalexample>
</sect2>
<sect2>
<title>Handling Calls Between Internal Users</title>
<para>
[Explain that we're going to add a second context,
and use it for calling between internal extensions.]
</para>
<informalexample>
<programlisting>
[incoming]
exten=>s,1,Answer()<lineannotation> ; Answer the line</lineannotation>
exten=>s,2,Playback(welcome)<lineannotation> ; Play back the 'welcome' sound file</lineannotation>
exten=>s,3,Background(menu)<lineannotation> ; Play 'menu' file and accept input from caller</lineannotation>
exten=>1,1,Dial(Zap/2)<lineannotation> ; Dial channels Zap/2 if the user dials 1</lineannotation>
exten=>2,1,Dial(Zap/3)<lineannotation> ; Dial channels Zap/3 if the user dials 2</lineannotation>
[internal]
exten=>>1001,1,Dial(Zap/2)<lineannotation> ; Dialing extension 1001 calls channel Zap/2</lineannotation>
exten=>>1002,1,Dial(Zap/3)<lineannotation> ; Dialing extension 1002 calls channel Zap/3</lineannotation>
</programlisting>
</informalexample>
</sect2>
</sect1>
<sect1>
<title>Variables</title>
<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>
<para>
There are two types of variables, namely global variables and
call variables. As their names imply, global variables apply
to all extensions, while call variables only apply to the
current call in progress.
</para>
<sect2>
<title>Global Variables</title>
<para>
</para>
</sect2>
<sect2>
<title>Call Variables</title>
<para>
</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, or division.
</para>
<para>
[example of some simple variable expressions]
</para>
<para>
For more information on using expressions with variables, see
the <filename>README.variables</filename> file that comes with
the Asterisk source code.
</para>
</sect2>
<sect2>
<title>Adding Variables</title>
<para>
[Take our Widgets Inc. example and add variables for
${RECEPTIONIST}, etc.]
</para>
<informalexample>
<programlisting>
[global]
RECEPTIONIST=Zap/2<lineannotation> ; Assign 'Zap/2' to the global variable ${RECEPTIONIST}</lineannotation>
JOHN=Zap/3<lineannotation> ; Assign 'Zap/3' to the global variable ${JOHN}</lineannotation>
[incoming]
exten=>s,1,Answer()
exten=>s,2,Playback(welcome)
exten=>s,3,Background(menu)
exten=>1,1,Dial(${RECEPTIONIST})<lineannotation> ; Dial the channel assigned to ${RECEPTIONIST}</lineannotation>
exten=>2,1,Dial(${JOHN})<lineannotation> ; Dial channel assigned to ${JOHN}</lineannotation>
[internal]
exten=>>1001,1,Dial(Zap/2)<lineannotation> ; Dialing extension 1001 calls channel Zap/2</lineannotation>
exten=>>1002,1,Dial(Zap/3)<lineannotation> ; Dialing extension 1002 calls channel Zap/3</lineannotation>
</programlisting>
</informalexample>
<sidebar>
<title>A Useful Debugging Tip</title>
<para>
[As a sidebar, explain how you can use the NoOp() application to debug variables]
</para>
</sidebar>
</sect2>
</sect1>
<sect1>
<title>Macros</title>
<para/>
<sect2>
<title>What are Macros?</title>
<para/>
</sect2>
<sect2>
<title>Attributes of Macros</title>
<para>
[Macros start with "macro-"]
[Macros are expanded in place]
[Macros use the "s" extension]
[Variables are passed in as <replaceable>ARG1</replaceable>, <replaceable>ARG2</replaceable>, etc.]
</para>
</sect2>
<sect2>
<title>Adding Macros to our Dial Plan</title>
<para/>
</sect2>
</sect1>
<sect1>
<title>Call Flow</title>
<para/>
<sect2>
<title>Pattern Matching</title>
<para>
[Patterns start with "_"]
[More specific patterns take priority, don't they?]
[Explain the ${EXTEN} variable, along with the ${EXTEN:i:j} syntax]
[Example of a simple "outbound" context]
</para>
</sect2>
<sect2>
<title>Linking Contexts with Includes</title>
<para>
[How to do it]
[Order of includes count! Explain why...]
[Time-sensitive includes]
[OK, now let's "include" the "outbound" context inside of the "internal" context]
</para>
</sect2>
<sect2>
<title>The other special extensions (i,t,o,h,fax,???)</title>
<simplelist>
<member>'s' - start</member>
<member>'i' - invalid</member>
<member>'t' - timeout</member>
<member>'h' - hangup</member>
<member>'T' - Absolute Timeout</member>
</simplelist>
<para>
The start extension is for most calls that are initiated with no
other known information.
</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>
<warning>
<para>
There are currently some problems to be aware of when
using the 'h' extension. Specifically, the
variables about the call are lost as the information is
destroyed with the channel.
</para>
</warning>
<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>
<para>
Absolute Timeout is a used when a call is being terminated for
exceeding a Absolute Timeout variable set. Be aware of the case
difference from the normal timeout. This can be used to warn
a user that they exceeded some allowable limit. Or it could be used
to request someone to try calling back later if they waited in a
queue too long. Essentially it should notify the caller that they
are being disconnected so as not to leave them with the impression
they had been cut off unintendedly.
</para>
</sect2>
<sect2>
<title>Using Goto and GotoIf</title>
<para/>
</sect2>
</sect1>
</chapter>
--=_daytona-9495-1074176852-0001-2--