path: root/doc/tex/cel-doc.tex

\section{Design Goals}

CEL, or Channel Event Logging, has been written with the hopes that it will help
solve some of the problems that were difficult to address in CDR records. Some
difficulties in CDR generation are the fact that the CDR record stores three
events: the "Start" time, the "Answer" time, and the "End" time. Billing time is
usually the difference between "Answer" and "End", and total call duration was
the difference in time from "Start" to "End".  The trouble with this direct and
simple approach is the fact that calls can be transferred, put on hold,
conferenced, forwarded, etc. In general, those doing billing applications in
Asterisk find they have to do all sorts of very creative things to overcome the
shortcomings of CDR records, often supplementing the CDR records with AGI
scripts and manager event filters.

The fundamental assumption is that the Channel is the fundamental communication
object in asterisk, which basically provides a communication channel between two
communication ports. It makes sense to have an event system aimed at recording
important events on channels. Each event is attached to a channel, like ANSWER
or HANGUP. Some events are meant to connect two or more channels, like the
BRIDGE\_START event. Some events, like BLINDTRANSFER, are initiated by one
channel, but affect two others. These events use the Peer field, like BRIDGE
would, to point to the target channel.

The design philosophy of CEL is to generate event data that can grouped together
to form a billing record. This may not be a simple task, but we hope to provide
a few different examples that could be used as a basis for those involved in
this effort.

There are definite parallels between Manager events and CEL events, but there
are some differences.  Some events that are generated by CEL are not generated
by the Manager interface (yet). CEL is optimized for databases, and Manager
events are not. The focus of CEL is billing. The Manager interface is targeted
to real-time monitoring and control of asterisk.

To give the reader a feel for the complexities involved in billing, please take
note of the following sequence of events:

Remember that 150, 151, and 152 are all Zap extension numbers, and their
respective devices are Zap/50, Zap/51, and Zap/52.

152 dials 151; 151 answers.  152 parks 151; 152 hangs up.  150 picks up the park
(dials 701).  150 and 151 converse.  151 flashes hook; dials 152, talks to 152,
then 151 flashes hook again for 3-way conference. 151 converses with the other
two for a while, then hangs up. 150 and 152 keep conversing, then hang up. 150
hangs up first.(not that it matters).

This sequence of actions will generate the following annotated list of 42 CEL
events:

{\it Note that the actual CEL events below are in CSV format and do not include
     the ;;; and text after that which gives a description of what the event
     represents.}

\begin{astlisting}
"EV\_CHAN\_START","2007-05-09 12:46:16","fxs.52","152","","","","s","extension","Zap/52-1","","","DOCUMENTATION","","1178736376.3","",""                                   ;;; 152 takes the phone off-hook

"EV\_APP\_START","2007-05-09 12:46:18","fxs.52","152","152","","","151","extension","Zap/52-1","Dial","Zap/51|30|TtWw","DOCUMENTATION","","1178736376.3"                   ;;; 152 finishes dialing 151

"EV\_CHAN\_START","2007-05-09 12:46:18","fxs.51","151","","","","s","extension","Zap/51-1","","","DOCUMENTATION","","1178736378.4","",""                                   ;;; 151 channel created, starts ringing

{\it (151 is ringing)}

"EV\_ANSWER","2007-05-09 12:46:19","","151","152","","","151","extension","Zap/51-1","AppDial","(Outgoing Line)","DOCUMENTATION","","1178736378.4","",""                  ;;; 151 answers

"EV\_ANSWER","2007-05-09 12:46:19","fxs.52","152","152","","","151","extension","Zap/52-1","Dial","Zap/51|30|TtWw","DOCUMENTATION","","1178736376.3","",""                ;;; so does 152 (???)

"EV\_BRIDGE\_START","2007-05-09 12:46:20","fxs.52","152","152","","","151","extension","Zap/52-1","Dial","Zap/51|30|TtWw","DOCUMENTATION","","1178736376.3","","Zap/51-1"  ;;; 152 and 151 are bridged

{\it (151 and 152 are conversing)}

"EV\_BRIDGE\_END","2007-05-09 12:46:25","fxs.52","152","152","","","151","extension","Zap/52-1","Dial","Zap/51|30|TtWw","DOCUMENTATION","","1178736376.3","",""            ;;; after 5 seconds, the bridge ends (152 dials \#700?)

"EV\_BRIDGE\_START","2007-05-09 12:46:25","fxs.52","152","152","","","151","extension","Zap/52-1","Dial","Zap/51|30|TtWw","DOCUMENTATION","","1178736376.3","","Zap/51-1"  ;;; extraneous 0-second bridge?

"EV\_BRIDGE\_END","2007-05-09 12:46:25","fxs.52","152","152","","","151","extension","Zap/52-1","Dial","Zap/51|30|TtWw","DOCUMENTATION","","1178736376.3","",""            ;;;

"EV\_PARK\_START","2007-05-09 12:46:27","","151","152","","","","extension","Zap/51-1","Parked Call","","DOCUMENTATION","","1178736378.4","",""                            ;;; 151 is parked

"EV\_HANGUP","2007-05-09 12:46:29","fxs.52","152","152","","","h","extension","Zap/52-1","","","DOCUMENTATION","","1178736376.3" ,"",""                                   ;;; 152 hangs up 2 sec later

"EV\_CHAN\_END","2007-05-09 12:46:29","fxs.52","152","152","","","h","extension","Zap/52-1","","","DOCUMENTATION","","1178736376.3","",""                                  ;;; 152's channel goes away

{\it (151 is parked and listening to MOH! now, 150 picks up, and dials 701)}

"EV\_CHAN\_START","2007-05-09 12:47:08","fxs.50","150","","","","s","extension","Zap/50-1","","","DOCUMENTATION","","1178736428.5","",""                                   ;;; 150 picks up the phone, dials 701

"EV\_PARK\_END","2007-05-09 12:47:11","","151","152","","","","extension","Zap/51-1","Parked Call","","DOCUMENTATION","","1178736378.4","",""                              ;;; 151's park comes to end

"EV\_ANSWER","2007-05-09 12:47:11","fxs.50","150","150","","","701","extension","Zap/50-1","ParkedCall","701","DOCUMENTATION","","1178736428.5","",""                     ;;; 150 gets answer (twice)

"EV\_ANSWER","2007-05-09 12:47:12","fxs.50","150","150","","","701","extension","Zap/50-1","ParkedCall","701","DOCUMENTATION","","1178736428.5","",""                     ;;;

"EV\_BRIDGE\_START","2007-05-09 12:47:12","fxs.50","150","150","","","701","extension","Zap/50-1","ParkedCall","701","DOCUMENTATION","","1178736428.5","","Zap/51-1"       ;;; bridge begins between 150 and recently parked 151

{\it (150 and 151 are conversing, then 151 hits flash)}

"EV\_CHAN\_START","2007-05-09 12:47:51","fxs.51","151","","","","s","extension","Zap/51-2","","","DOCUMENTATION","","1178736471.6","",""                                   ;;; 39 seconds later, 51-2 channel is created. (151 flashes hook)

"EV\_HOOKFLASH","2007-05-09 12:47:51","","151","152","","","","extension","Zap/51-1","Bridged Call","Zap/50-1","DOCUMENTATION","","1178736378.4","","Zap/51-2"            ;;; a marker to record that 151 flashed the hook

"EV\_BRIDGE\_END","2007-05-09 12:47:51","fxs.50","150","150","","","701","extension","Zap/50-1","ParkedCall","701","DOCUMENTATION","","1178736428.5","","Zap/51-1"         ;;; bridge ends between 150 and 151

"EV\_BRIDGE\_START","2007-05-09 12:47:51","fxs.50","150","150","","","701","extension","Zap/50-1","ParkedCall","701","DOCUMENTATION","","1178736428.5","","Zap/51-1"       ;;; 0-second bridge from 150 to ?  150 gets no sound at all

"EV\_BRIDGE\_END","2007-05-09 12:47:51","fxs.50","150","150","","","701","extension","Zap/50-1","ParkedCall","701","DOCUMENTATION","","1178736428.5","","Zap/51-1"         ;;;

"EV\_BRIDGE\_START","2007-05-09 12:47:51","fxs.50","150","150","","","701","extension","Zap/50-1","ParkedCall","701","DOCUMENTATION","","1178736428.5","","Zap/51-1"       ;;; bridge start on 150

{\it (151 has dialtone after hitting flash; dials 152)}

"EV\_APP\_START","2007-05-09 12:47:55","fxs.51","151","151","","","152","extension","Zap/51-2","Dial","Zap/52|30|TtWw","DOCUMENTATION","","1178736471.6","",""             ;;; 151-2 dials 152 after 4 seconds

"EV\_CHAN\_START","2007-05-09 12:47:55","fxs.52","152","","","","s","extension","Zap/52-1","","","DOCUMENTATION","","1178736475.7" ,"",""                                  ;;; 152 channel created to ring 152.

{\it (152 ringing)}

"EV\_ANSWER","2007-05-09 12:47:58","","152","151","","","152","extension","Zap/52-1","AppDial","(Outgoing Line)","DOCUMENTATION","","1178736475.7","",""                  ;;; 3 seconds later, 152 answers

"EV\_ANSWER","2007-05-09 12:47:58","fxs.51","151","151","","","152","extension","Zap/51-2","Dial","Zap/52|30|TtWw","DOCUMENTATION","","1178736471.6","",""                ;;;   ... and 151-2 also answers

"EV\_BRIDGE\_START","2007-05-09 12:47:59","fxs.51","151","151","","","152","extension","Zap/51-2","Dial","Zap/52|30|TtWw","DOCUMENTATION","","1178736471.6","","Zap/51-1"  ;;; 1 second later, bridge formed betw. 151-2 and 151

{\it (152 answers, 151 and 152 convering; 150 is listening to silence; 151 hits flash again... to start a 3way)}

"EV\_3WAY\_START","2007-05-09 12:48:58","","151","152","","","","extension","Zap/51-1","Bridged Call","Zap/50-1","DOCUMENTATION","","1178736378.4","","Zap/51-2"           ;;; another hook-flash to begin a 3-way conference

"EV\_BRIDGE\_END","2007-05-09 12:48:58","fxs.50","150","150","","","701","extension","Zap/50-1","ParkedCall","701","DOCUMENTATION","","1178736428.5","","Zap/51-1"         ;;; -- almost 1 minute later, the bridge ends (151 flashes hook again)

"EV\_BRIDGE\_START","2007-05-09 12:48:58","fxs.50","150","150","","","701","extension","Zap/50-1","ParkedCall","701","DOCUMENTATION","","1178736428.5","","Zap/51-1"       ;;; 0-second bridge at 150. (3 way conf formed)

"EV\_BRIDGE\_END","2007-05-09 12:48:58","fxs.50","150","150","","","701","extension","Zap/50-1","ParkedCall","701","DOCUMENTATION","","1178736428.5","","Zap/51-1"         ;;;

"EV\_BRIDGE\_START","2007-05-09 12:48:58","fxs.50","150","150","","","701","extension","Zap/50-1","ParkedCall","701","DOCUMENTATION","","1178736428.5","","Zap/51-1"       ;;; bridge starts for 150

{\it (3way now, then 151 hangs up.)}

"EV\_BRIDGE\_END","2007-05-09 12:49:26","fxs.50","150","150","","","701","extension","Zap/50-1","ParkedCall","701","DOCUMENTATION","","1178736428.5","","Zap/51-1"         ;;; 28 seconds later, bridge ends

"EV\_HANGUP","2007-05-09 12:49:26","","151","152","","","","extension","Zap/51-1","Bridged Call","Zap/50-1","DOCUMENTATION","","1178736378.4","",""                       ;;; 151 hangs up, leaves 150 and 152 connected

"EV\_CHAN\_END","2007-05-09 12:49:26","","151","152","","","","extension","Zap/51-1","Bridged Call","Zap/50-1","DOCUMENTATION","","1178736378.4","",""                     ;;; 151 channel ends

"EV\_CHAN\_END","2007-05-09 12:49:26","fxs.51","151","151","","","h","extension","Zap/51-2$<$ZOMBIE$>$","","","DOCUMENTATION","","1178736428.5","",""                          ;;; 152-2 channel ends (zombie)

{\it (just 150 and 152 now)}

"EV\_BRIDGE\_END","2007-05-09 12:50:13","fxs.50","150","150","","","152","extension","Zap/50-1","Dial","Zap/52|30|TtWw","DOCUMENTATION","","1178736471.6","",""            ;;; 47 sec later, the bridge from 150 to 152 ends

"EV\_HANGUP","2007-05-09 12:50:13","","152","151","","","","extension","Zap/52-1","Bridged Call","Zap/50-1","DOCUMENTATION","","1178736475.7","",""                       ;;; 152 hangs up

"EV\_CHAN\_END","2007-05-09 12:50:13","","152","151","","","","extension","Zap/52-1","Bridged Call","Zap/50-1","DOCUMENTATION","","1178736475.7","",""                     ;;; 152 channel ends

"EV\_HANGUP","2007-05-09 12:50:13","fxs.50","150","150","","","h","extension","Zap/50-1","","","DOCUMENTATION","","1178736471.6","",""                                    ;;; 150 hangs up

"EV\_CHAN\_END","2007-05-09 12:50:13","fxs.50","150","150","","","h","extension","Zap/50-1","","","DOCUMENTATION","","1178736471.6","",""                                  ;;; 150 ends
\end{astlisting}

In terms of Manager events, the above Events correspond to the following 80
Manager events:

\begin{astlisting}
\begin{verbatim}
Event: Newchannel
Privilege: call,all
Channel: Zap/52-1
State: Rsrvd
CallerIDNum: 152
CallerIDName: fxs.52
Uniqueid: 1178801102.5

Event: Newcallerid
Privilege: call,all
Channel: Zap/52-1
CallerIDNum: 152
CallerIDName: fxs.52
Uniqueid: 1178801102.5
CID-CallingPres: 0 (Presentation Allowed, Not Screened)

Event: Newcallerid
Privilege: call,all
Channel: Zap/52-1
CallerIDNum: 152
CallerIDName: fxs.52
Uniqueid: 1178801102.5
CID-CallingPres: 0 (Presentation Allowed, Not Screened)

Event: Newstate
Privilege: call,all
Channel: Zap/52-1
State: Ring
CallerIDNum: 152
CallerIDName: fxs.52
Uniqueid: 1178801102.5

Event: Newexten
Privilege: call,all
Channel: Zap/52-1
Context: extension
Extension: 151
Priority: 1
Application: Set
AppData: CDR(myvar)=zingo
Uniqueid: 1178801102.5

Event: Newexten
Privilege: call,all
Channel: Zap/52-1
Context: extension
Extension: 151
Priority: 2
Application: Dial
AppData: Zap/51|30|TtWw
Uniqueid: 1178801102.5

Event: Newchannel
Privilege: call,all
Channel: Zap/51-1
State: Rsrvd
CallerIDNum: 151
CallerIDName: fxs.51
Uniqueid: 1178801108.6

Event: Newstate
Privilege: call,all
Channel: Zap/51-1
State: Ringing
CallerIDNum: 152
CallerIDName: fxs.52
Uniqueid: 1178801108.6

Event: Dial
Privilege: call,all
SubEvent: Begin
Source: Zap/52-1
Destination: Zap/51-1
CallerIDNum: 152
CallerIDName: fxs.52
SrcUniqueID: 1178801102.5
DestUniqueID: 1178801108.6

Event: Newcallerid
Privilege: call,all
Channel: Zap/51-1
CallerIDNum: 151
CallerIDName: <Unknown>
Uniqueid: 1178801108.6
CID-CallingPres: 0 (Presentation Allowed, Not Screened)

Event: Newstate
Privilege: call,all
Channel: Zap/52-1
State: Ringing
CallerIDNum: 152
CallerIDName: fxs.52
Uniqueid: 1178801102.5

Event: Newstate
Privilege: call,all
Channel: Zap/51-1
State: Up
CallerIDNum: 151
CallerIDName: <unknown>
Uniqueid: 1178801108.6

Event: Newstate
Privilege: call,all
Channel: Zap/52-1
State: Up
CallerIDNum: 152
CallerIDName: fxs.52
Uniqueid: 1178801102.5

Event: Link
Privilege: call,all
Channel1: Zap/52-1
Channel2: Zap/51-1
Uniqueid1: 1178801102.5
Uniqueid2: 1178801108.6
CallerID1: 152
CallerID2: 151

Event: Unlink
Privilege: call,all
Channel1: Zap/52-1
Channel2: Zap/51-1
Uniqueid1: 1178801102.5
Uniqueid2: 1178801108.6
CallerID1: 152
CallerID2: 151

Event: Link
Privilege: call,all
Channel1: Zap/52-1
Channel2: Zap/51-1
Uniqueid1: 1178801102.5
Uniqueid2: 1178801108.6
CallerID1: 152
CallerID2: 151

Event: Unlink
Privilege: call,all
Channel1: Zap/52-1
Channel2: Zap/51-1
Uniqueid1: 1178801102.5
Uniqueid2: 1178801108.6
CallerID1: 152
CallerID2: 151

Event: ParkedCall
Privilege: call,all
Exten: 701
Channel: Zap/51-1
From: Zap/52-1
Timeout: 45
CallerIDNum: 151
CallerIDName: <unknown>

Event: Dial
Privilege: call,all
SubEvent: End
Channel: Zap/52-1
DialStatus: ANSWER

Event: Newexten
Privilege: call,all
Channel: Zap/52-1
Context: extension
Extension: h
Priority: 1
Application: Goto
AppData: label1
Uniqueid: 1178801102.5

Event: Newexten
Privilege: call,all
Channel: Zap/52-1
Context: extension
Extension: h
Priority: 4
Application: Goto
AppData: label2
Uniqueid: 1178801102.5

Event: Newexten
Privilege: call,all
Channel: Zap/52-1
Context: extension
Extension: h
Priority: 2
Application: NoOp
AppData: In Hangup! myvar is zingo and accountcode is  billsec is 26 and duration is 40 and end is 2007-05-10 06:45:42.
Uniqueid: 1178801102.5

Event: Newexten
Privilege: call,all
Channel: Zap/52-1
Context: extension
Extension: h
Priority: 3
Application: Goto
AppData: label3
Uniqueid: 1178801102.5

Event: Newexten
Privilege: call,all
Channel: Zap/52-1
Context: extension
Extension: h
Priority: 5
Application: NoOp
AppData: More Hangup message after hopping around"
Uniqueid: 1178801102.5

Event: Hangup
Privilege: call,all
Channel: Zap/52-1
Uniqueid: 1178801102.5
Cause: 16
Cause-txt: Normal Clearing

Event: Newchannel
Privilege: call,all
Channel: Zap/50-1
State: Rsrvd
CallerIDNum: 150
CallerIDName: fxs.50
Uniqueid: 1178801162.7

Event: Newcallerid
Privilege: call,all
Channel: Zap/50-1
CallerIDNum: 150
CallerIDName: fxs.50
Uniqueid: 1178801162.7
CID-CallingPres: 0 (Presentation Allowed, Not Screened)

Event: Newcallerid
Privilege: call,all
Channel: Zap/50-1
CallerIDNum: 150
CallerIDName: fxs.50
Uniqueid: 1178801162.7
CID-CallingPres: 0 (Presentation Allowed, Not Screened)

Event: Newstate
Privilege: call,all
Channel: Zap/50-1
State: Ring
CallerIDNum: 150
CallerIDName: fxs.50
Uniqueid: 1178801162.7

Event: Newexten
Privilege: call,all
Channel: Zap/50-1
Context: extension
Extension: 701
Priority: 1
Application: ParkedCall
AppData: 701
Uniqueid: 1178801162.7

Event: UnParkedCall
Privilege: call,all
Exten: 701
Channel: Zap/51-1
From: Zap/50-1
CallerIDNum: 151
CallerIDName: <unknown>

Event: Newstate
Privilege: call,all
Channel: Zap/50-1
State: Up
CallerIDNum: 150
CallerIDName: fxs.50
Uniqueid: 1178801162.7

Event: Link
Privilege: call,all
Channel1: Zap/50-1
Channel2: Zap/51-1
Uniqueid1: 1178801162.7
Uniqueid2: 1178801108.6
CallerID1: 150
CallerID2: 151

Event: Newchannel
Privilege: call,all
Channel: Zap/51-2
State: Rsrvd
CallerIDNum: 151
CallerIDName: fxs.51
Uniqueid: 1178801218.8

Event: Unlink
Privilege: call,all
Channel1: Zap/50-1
Channel2: Zap/51-1
Uniqueid1: 1178801162.7
Uniqueid2: 1178801108.6
CallerID1: 150
CallerID2: 151

Event: Link
Privilege: call,all
Channel1: Zap/50-1
Channel2: Zap/51-1
Uniqueid1: 1178801162.7
Uniqueid2: 1178801108.6
CallerID1: 150
CallerID2: 151

Event: Unlink
Privilege: call,all
Channel1: Zap/50-1
Channel2: Zap/51-1
Uniqueid1: 1178801162.7
Uniqueid2: 1178801108.6
CallerID1: 150
CallerID2: 151

Event: Link
Privilege: call,all
Channel1: Zap/50-1
Channel2: Zap/51-1
Uniqueid1: 1178801162.7
Uniqueid2: 1178801108.6
CallerID1: 150
CallerID2: 151

Event: Newcallerid
Privilege: call,all
Channel: Zap/51-2
CallerIDNum: 151
CallerIDName: fxs.51
Uniqueid: 1178801218.8
CID-CallingPres: 0 (Presentation Allowed, Not Screened)

Event: Newcallerid
Privilege: call,all
Channel: Zap/51-2
CallerIDNum: 151
CallerIDName: fxs.51
Uniqueid: 1178801218.8
CID-CallingPres: 0 (Presentation Allowed, Not Screened)

Event: Newstate
Privilege: call,all
Channel: Zap/51-2
State: Ring
CallerIDNum: 151
CallerIDName: fxs.51
Uniqueid: 1178801218.8

Event: Newexten
Privilege: call,all
Channel: Zap/51-2
Context: extension
Extension: 152
Priority: 1
Application: Set
AppData: CDR(myvar)=zingo
Uniqueid: 1178801218.8

Event: Newexten
Privilege: call,all
Channel: Zap/51-2
Context: extension
Extension: 152
Priority: 2
Application: Dial
AppData: Zap/52|30|TtWw
Uniqueid: 1178801218.8

Event: Newchannel
Privilege: call,all
Channel: Zap/52-1
State: Rsrvd
CallerIDNum: 152
CallerIDName: fxs.52
Uniqueid: 1178801223.9

Event: Newstate
Privilege: call,all
Channel: Zap/52-1
State: Ringing
CallerIDNum: 151
CallerIDName: fxs.51
Uniqueid: 1178801223.9

Event: Dial
Privilege: call,all
SubEvent: Begin
Source: Zap/51-2
Destination: Zap/52-1
CallerIDNum: 151
CallerIDName: fxs.51
SrcUniqueID: 1178801218.8
DestUniqueID: 1178801223.9

Event: Newcallerid
Privilege: call,all
Channel: Zap/52-1
CallerIDNum: 152
CallerIDName: <Unknown>
Uniqueid: 1178801223.9
CID-CallingPres: 0 (Presentation Allowed, Not Screened)

Event: Newstate
Privilege: call,all
Channel: Zap/51-2
State: Ringing
CallerIDNum: 151
CallerIDName: fxs.51
Uniqueid: 1178801218.8

Event: Newstate
Privilege: call,all
Channel: Zap/52-1
State: Up
CallerIDNum: 152
CallerIDName: <unknown>
Uniqueid: 1178801223.9

Event: Newstate
Privilege: call,all
Channel: Zap/51-2
State: Up
CallerIDNum: 151
CallerIDName: fxs.51
Uniqueid: 1178801218.8

Event: Link
Privilege: call,all
Channel1: Zap/51-2
Channel2: Zap/52-1
Uniqueid1: 1178801218.8
Uniqueid2: 1178801223.9
CallerID1: 151
CallerID2: 152

Event: Unlink
Privilege: call,all
Channel1: Zap/50-1
Channel2: Zap/51-1
Uniqueid1: 1178801162.7
Uniqueid2: 1178801108.6
CallerID1: 150
CallerID2: 151

Event: Link
Privilege: call,all
Channel1: Zap/50-1
Channel2: Zap/51-1
Uniqueid1: 1178801162.7
Uniqueid2: 1178801108.6
CallerID1: 150
CallerID2: 151

Event: Unlink
Privilege: call,all
Channel1: Zap/50-1
Channel2: Zap/51-1
Uniqueid1: 1178801162.7
Uniqueid2: 1178801108.6
CallerID1: 150
CallerID2: 151

Event: Link
Privilege: call,all
Channel1: Zap/50-1
Channel2: Zap/51-1
Uniqueid1: 1178801162.7
Uniqueid2: 1178801108.6
CallerID1: 150
CallerID2: 151

Event: Unlink
Privilege: call,all
Channel1: Zap/50-1
Channel2: Zap/51-1
Uniqueid1: 1178801162.7
Uniqueid2: 1178801108.6
CallerID1: 150
CallerID2: 151

Event: Hangup
Privilege: call,all
Channel: Zap/51-1
Uniqueid: 1178801108.6
Cause: 16
Cause-txt: Normal Clearing

Event: Newexten
Privilege: call,all
Channel: Zap/50-1
Context: extension
Extension: h
Priority: 1
Application: Goto
AppData: label1
Uniqueid: 1178801162.7

Event: Newexten
Privilege: call,all
Channel: Zap/50-1
Context: extension
Extension: h
Priority: 4
Application: Goto
AppData: label2
Uniqueid: 1178801162.7

Event: Newexten
Privilege: call,all
Channel: Zap/50-1
Context: extension
Extension: h
Priority: 2
Application: NoOp
AppData: In Hangup! myvar is  and accountcode is  billsec is 0 and duration is 0 and end is 2007-05-10 06:48:37.
Uniqueid: 1178801162.7

Event: Newexten
Privilege: call,all
Channel: Zap/50-1
Context: extension
Extension: h
Priority: 3
Application: Goto
AppData: label3
Uniqueid: 1178801162.7

Event: Newexten
Privilege: call,all
Channel: Zap/50-1
Context: extension
Extension: h
Priority: 5
Application: NoOp
AppData: More Hangup message after hopping around"
Uniqueid: 1178801162.7

Event: Masquerade
Privilege: call,all
Clone: Zap/50-1
CloneState: Up
Original: Zap/51-2
OriginalState: Up

Event: Rename
Privilege: call,all
Oldname: Zap/50-1
Newname: Zap/50-1<MASQ>
Uniqueid: 1178801162.7

Event: Rename
Privilege: call,all
Oldname: Zap/51-2
Newname: Zap/50-1
Uniqueid: 1178801218.8

Event: Rename
Privilege: call,all
Oldname: Zap/50-1<MASQ>
Newname: Zap/51-2<ZOMBIE>
Uniqueid: 1178801162.7

Event: Hangup
Privilege: call,all
Channel: Zap/51-2<ZOMBIE>
Uniqueid: 1178801162.7
Cause: 0
Cause-txt: Unknown

Event: Unlink
Privilege: call,all
Channel1: Zap/50-1
Channel2: Zap/52-1
Uniqueid1: 1178801218.8
Uniqueid2: 1178801223.9
CallerID1: 150
CallerID2: 152

Event: Hangup
Privilege: call,all
Channel: Zap/52-1
Uniqueid: 1178801223.9
Cause: 16
Cause-txt: Normal Clearing

Event: Dial
Privilege: call,all
SubEvent: End
Channel: Zap/50-1
DialStatus: ANSWER

Event: Newexten
Privilege: call,all
Channel: Zap/50-1
Context: extension
Extension: h
Priority: 1
Application: Goto
AppData: label1
Uniqueid: 1178801218.8

Event: Newexten
Privilege: call,all
Channel: Zap/50-1
Context: extension
Extension: h
Priority: 4
Application: Goto
AppData: label2
Uniqueid: 1178801218.8

Event: Newexten
Privilege: call,all
Channel: Zap/50-1
Context: extension
Extension: h
Priority: 2
Application: NoOp
AppData: In Hangup! myvar is  and accountcode is  billsec is 90 and duration is 94 and end is 2007-05-10 06:48:37.
Uniqueid: 1178801218.8

Event: Newexten
Privilege: call,all
Channel: Zap/50-1
Context: extension
Extension: h
Priority: 3
Application: Goto
AppData: label3
Uniqueid: 1178801218.8

Event: Newexten
Privilege: call,all
Channel: Zap/50-1
Context: extension
Extension: h
Priority: 5
Application: NoOp
AppData: More Hangup message after hopping around"
Uniqueid: 1178801218.8

Event: Hangup
Privilege: call,all
Channel: Zap/50-1
Uniqueid: 1178801218.8
Cause: 16
Cause-txt: Normal Clearing
\end{verbatim}
\end{astlisting}

And, humorously enough, the above 80 manager events, or 42 CEL events,
correspond to the following two CDR records (at the moment!):

\begin{astlisting}
""fxs.52" $<$152$>$","152","h","extension","Zap/52-1","Zap/51-1","NoOp","More Hangup message after hopping around"","2007-05-09 17:35:56","2007-05-09 17:36:20","2007-05-09 17:36:36","40","16","ANSWERED","DOCUMENTATION","","1178753756.0",""

""fxs.50" $<$150$>$","150","152","extension","Zap/50-1","Zap/51-1","NoOp","More Hangup message after hopping around"","2007-05-09 17:37:59","2007-05-09 17:38:06","2007-05-09 17:39:11","72","65","ANSWERED","DOCUMENTATION","","1178753871.3",""
\end{astlisting}


\section{Events \& Fields}

While CDRs and the Manager are basically both event tracking mechanisms, CEL
tries to track only those events that might pertain to billing issues.

See table~\ref{event_table} for a list of events raised by CEL and
table~\ref{field_table} for the list of fields passed for each CEL event.

\begin{table}[h]
  \begin{tabular}{ | l | p{10cm} | }
    \hline
    Event            & Description                                                               \\ \hline \hline
    CHAN\_START      & The time a channel was created                                            \\ \hline
    CHAN\_END        & The time a channel was terminated                                         \\ \hline
    ANSWER           & The time a channel was answered (ie, phone taken off-hook, etc)           \\ \hline
    HANGUP           & The time at which a hangup occurred.                                      \\ \hline
    CONF\_ENTER      & The time a channel was connected into a conference room                   \\ \hline
    CONF\_EXIT       & The time a channel was removed from a conference room                     \\ \hline
    CONF\_START      & The time the first person enters a conference                             \\ \hline
    CONF\_END        & The time the last person left a conf (and turned out the lights?)         \\ \hline
    APP\_START       & The time a tracked application was started                                \\ \hline
    APP\_END         & the time a tracked application ended                                      \\ \hline
    PARK\_START      & The time a call was parked                                                \\ \hline
    PARK\_END        & unpark event                                                              \\ \hline
    BRIDGE\_START    & The time a bridge is started                                              \\ \hline
    BRIDGE\_END      & The time a bridge is ended                                                \\ \hline
    3WAY\_START      & When a 3-way conf starts (usually via attended xfer)                      \\ \hline
    3WAY\_END        & When one or all exit a 3-way conf                                         \\ \hline
    BLINDTRANSFER    & When a blind transfer is initiated                                        \\ \hline
    ATTENDEDTRANSFER & When an attended transfer is initiated                                    \\ \hline
    TRANSFER         & Generic transfer initiated; not used yet...?                              \\ \hline
    HOOKFLASH        & So far, when a hookflash event occurs on a Zap interface                  \\ \hline
    USER\_EVENT      & these are triggered from the dialplan, and have a name given by the user. \\
    \hline
  \end{tabular}
  \caption{List of CEL Events}
  \label{event_table}
\end{table}

\begin{table}[h]
  \begin{tabular}{ | l | p{10cm} | }
    \hline
    Field         & Description                                                                \\ \hline \hline
    eventtype     & The name of the event; see the above list; each is prefixed with "EV\_".   \\ \hline
    eventtime     & The time the event happened                                                \\ \hline
    cidname       & CID name field                                                             \\ \hline
    cidnum        & CID number field                                                           \\ \hline
    cidani        & CID ANI field                                                              \\ \hline
    cidrdnis      & CID RDNIS field                                                            \\ \hline
    ciddnid       & CID DNID field                                                             \\ \hline
    exten         & The extension in the dialplan                                              \\ \hline
    context       & The context in the dialplan                                                \\ \hline
    channame      & The name assigned to the channel in which the event took place             \\ \hline
    appname       & The name of the current application                                        \\ \hline
    appdata       & The arguments that will be handed to that application                      \\ \hline
    amaflags      & The AMA flags associated with the event; user assignable.                  \\ \hline
    accountcode   & A user assigned datum (string)                                             \\ \hline
    uniqueid      & Each Channel instance gets a unique ID associated with it.                 \\ \hline
    userfield     & A user assigned datum (string)                                             \\ \hline
    linkedid      & the per-call id, spans several events, possibly.                           \\ \hline
    peer          & For bridge or other 2-channel events, this would be the other channel name \\
    \hline
  \end{tabular}
  \caption{List of CEL Event Fields}
  \label{field_table}
\end{table}

\section{Applications \& Functions}

\subsection{CEL Function}

**** THIS IS NO LONGER TRUE.  REWRITE. ****

The CEL function parallels the CDR function, for fetching values from the
channel or event.  It has some notable notable differences, though! For
instance, CEL data is not stored on the channel. Well, not much of it, anyway!
You can use the CEL function to set the amaflags, accountcode, and userfield,
which are stored on the channel.

Channel variables are not available for reading from the CEL function, nor can
any variable name other than what's in the list, be set. CDRs have a structure
attached to the channel, where the CDR function could access the values stored
there, or set the values there. CDRs could store their own variable lists, but
CEL has no such storage. There is no reason to store any event information, as
they are immediately output to the various backends at the time they are
generated.

See the description for the CEL function from the CLI: core show function CEL

Here is a list of all the available channel field names:
\begin{verbatim}
  cidname       userfield
  cidnum        amaflags
  cidani        cidrdnis
  ciddnid       appdata
  exten         accountcode
  context       uniqueid
  channame      appname
  peer          eventtime
  eventtype
\end{verbatim}

\subsection{CELGenUserEvent Application}

This application allows the dialplan to insert custom events into the event
stream.

For more information, in the CLI, type: core show application CELGenUserEvent

Its arguments take this format:

\begin{verbatim}
  CELGenUserEvent(eventname)
\end{verbatim}

Please note that there is no restrictions on the name supplied. If it happens to
match a standard CEL event name, it will look like that event was
generated. This could be a blessing or a curse!

\section{Configuration Files}

\begin{itemize}
\item cel.conf
\end{itemize}

\section{Generating Billing Information}

*** This is the Next Big Task ***