[Asterisk-doc] Asterisk db example

[Randolph Resnick]

Hi,

I realize this may not be the easiest way to do things (sorry, I don't 
have time to put this in the doc format), but attached is a text about 
the Asterisk DB with a follow me example. Up to you to decide if this is 
worthy of including. I think it is a good idea to make sure the book 
ends with some directions and ideas.

rr
-------------- next part --------------
The Asterisk database

The astdb offers persistent variables that are available from anywhere in the dialplan. By persistent, we mean that they remain after a reboot of the system or a even reinstall of asterisk, unless you specifically erase the entire asterisk file structure. Global variables are read when the dialplan is loaded. They can be changed using the SetGlobalVar application, but if asterisk is restarted or the dialplan is reloaded, they go back to what is written in the decalartions in the glocal section of extensions.cof.

The astdb allows you to have one or more "families" of data where you store keys and values. Within each family, keys are unique. This lets us build useful data structures like this:

; based on an extension number
/MyStuff/2000/flags
/MyStuff/2002/flags

; based on a task like forwarding
/MyStuff/forward/2000

; based on users
/MyStuff/Fred/email
/MyStuff/Wendy/email

The use of MyStuff makes it easy to look at only "my stuff" in the db.
The CLI has the necessary commands to manipulate the astdb by hand for debugging:

*CLI> database put MyFamily MyKey "My Value"
Updated database successfully

*CLI> database show myfamily
/MyFamily/MyKey                                   : My Value                 

*CLI> database del MyFamily MyKey
Database entry removed.

*CLI> database show myfamily


In the dialplan, the DB applications manipulate these data and keys. DBPut, DBGet and DBDel are used to create a key and set (or change) its value, fetch the value of a key and delete the key, respectively.

There are many interesting things that can be done with the astdb key/value system.

Users that move around in an office or outside it are not linked to a single phone. We need a mechanism to find them when a call comes in. We can do this by making a "follow me" forwarding system for each user. To simplify this example, no authentication is done, so anyone who dials the codes can forward anyone else's number. In real life this may not bring happy results. It would be simple to add a code using the Authenticate application mentioned elsewhere in this guide. The extension below is "hard wired" to the value of MYNUMBER. It would be trivial to change this to allow a range of two digit numbers.

; We have arbitrarily created a family call "MyStuff" in the astdb.
; It is created upon first reference to it. We also use global variables.
; In that family we are using "follow" as a persistent variable
; to hold the extension to forward calls to. When a call comes in for
; MYNUMBER we will look in the DB for the MYNUMBER key in the follow group. 
; If there is no such key, our dialplan will send the call to a default extension
; given as MYDEFAULTEXT. Finally the context of these calls is given in MYCONTEXT

MYNUMBER=80 ; this is the one person's "follow me" extension 
MYDEFAULTEXT=2005 ; this is the extension it will go to if there is no forward
MYCONTEXT=inhouse-extensions ; this is the context for this person

; this is the forwarded extension
exten => ${MYNUMBER},1,DBGet(follow=MyStuff/follow/${EXTEN}) ; is there a forward instruction?
exten => ${MYNUMBER},2,GotoIf($[X${follow} !=  X]?${MYCONTEXT},${follow},1)
exten => ${MYNUMBER},3,GoTo(${MYCONTEXT},${MYDEFAULTEXT},1) ; send to a default number
exten => ${MYNUMBER},4,Hangup

; dialing * says "send calls to (value of MYNUMBER) to the extension I am calling from"
exten => *${MYNUMBER},1,Macro(callback-login)

; dialing ** says "Stop forwarding (value of MYNUMBER), send to default"
exten => **${MYNUMBER},1,Macro(callback-logout)

; save a callerid in the forwarding table
[macro-callback-login]
exten => s,1,Answer
exten => s,2,DBPut(MyStuff/follow/${MACRO_EXTEN:1}=${CALLERIDNUM}) ;strip '*' and store forward number
exten => s,3,SayDigits(${CALLERIDNUM}) ; verify the number
exten => s,4,Wait(5) ; Allow caller to hang up first
exten => s,5,Hangup

; ERASE a callerid in the forwarding table
[macro-callback-logout]
exten => s,1,Answer
exten => s,2,DBDel(MyStuff/follow/${MACRO_EXTEN:2}) ; strip the '**', remove the db key and data
exten => s,3,Wait(5) ; allow caller to hang up first
exten => s,4,Hangup

After a login from a phone showing callerid as 2002, 
show dialplan MyStuff/forward should look like this:

/MyStuff/forward/80                 : 2002