un service flag con Asterisk

Area Culturale
Esempio di integrazione con XML
definitions: un service flag con Asterisk
Questo articolo è un primo pezzo introduttivo su di una feature molto potente: le XML definitions, vedremo
come creare un service flag con notifica in stile BLF ma completamente personalizzato.
I BLF (Busy Lamp Field) sono spesso sotto-utilizzati: vengono generalmente impiegati per monitorare altri
interni, come speed dial, o al più per effettuare il pickup di una chiamata, in questo articolo vedremo come
possiamo utilizzare il meccanismo alla base dei BLF per scopi diversi.
Il sistema su cui si basa il funzionamento dei BLF è definito dall’RFC 4235, questa specifica descrive un
meccanismo di notifiche legate a sessioni SIP iniziate con una richiesta INVITE. I telefoni implementano i
BLF associando i vari stati al comportamento del led luminoso corrispondente: in genere un led
lampeggiante significa che l’interno sta squillando, acceso fisso significa che l’interno è occupato.
Ora, un BLF può anche essere utilizzato per monitorare qualcosa di più generico, come ad esempio un
service flag detto anche servizio notte.
Un “servizio notte” è un servizio che modifica delle regole di call routing su base oraria oppure può essere
attivato o disattivato manualmente, per fare un esempio pratico le chiamate dirette al numero principale
devono dovranno essere destinate ad un interno nel caso in cui il servizio notte è disattivo, mentre saranno
inviate ad una casella di posta se il servizio è attivo.
Area Culturale
Esempio con Asterisk
Il seguente stralcio di dialplan implementa il feature code *500 il quale fa in modo di abilitare o disabilitare
un servizio notte chiamato “main_flag”:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
;Feature code: *500
exten => *500,1,Answer()
; check the main_flag/enable DB value:
same => n,GotoIf($["${DB(main_flag/enabled)}" = "1"]?disable:enable)
;
; the flag is disabled: enable it
same => n(enable),Verbose(Enabling the flag main_flag)
same => n,Set(DB(main_flag/enabled)=1)
; set the hint to BUSY state
same => n,Set(DEVICE_STATE(Custom:main_flag)=BUSY)
same => n,Playback(enabled)
same => n,Hangup()
;
; the flag is enabled, disable it
same => n(disable),Verbose(Disabling the flag main_flag)
same => n,Set(DB(main_flag/enabled)=0)
; set the hint to NOT_INUSE
same => n,Set(DEVICE_STATE(Custom:main_flag)=NOT_INUSE)
same => n,Playback(disabled)
same => n,Hangup()
; Main receptionist routing
exten => 500,1,Verbose(Inbound call to main number - checking if night mode or normal)
same => n,Set(NIGHTMODE=${DB(main_flag/enabled)})
same => n,GotoIf($["${NIGHTMODE}" = "1"]?nightmode)
same => n,Verbose(main_flag is enabled)
same => n,Dial(SIP/150)
same => n(nightmode),Verbose(main_flag is disabled)
same => n,Voicemail(150,su)
same => n,Hangup()
include => hints
[hints]
; BLF for main_flag
exten => *500,hint,Custom:main_flag
Area Culturale
Descrizione dettagliata
Il PBX quando riceve una chiamata destinata all’interno *500 per prima cosa verifica il valore della chiave di
database main_flag/enabled: se il valore è “1” (il servizio notte è abilitato) viene eseguito il dialplan
alla priority n(disable), altrimenti il flusso continua da n(enable). Nel caso in cui il servizio notte è
disabilitato il servizio viene abilitato impostando la chiave main_flag/enabled a 1, viene invece impostata a
0 nel caso in cui il servizio risulta abilitato.
Inoltre viene sincronizzato un custom device state di nome main_flag: viene impostato a BUSY se il servizio
notte è attivo e NOT_INUSE se il servizio è disattivo.
Il dialplan che gestisce l’extension 500 fa in modo di ruotare la chiamata al peer SIP/150 se il servizio notte
è disabilitato oppure ad una voicemail se il servizio è abilitato.
Il context hints invece gestisce le subscriptions per il feature code.
Funzionamento
Una volta caricato il dialplan possiamo testarne il funzionamento: chiamando l’interno *500 potremo
abilitare o disabilitare il servizio notte. Chiamando invece l’interno 500 la telefonata verrà gestita a seconda
dello stato del servizio: se attivo verremo rediretti alla Voicemail, altrimenti l’interno 150 verrà fatto
squillare.
NB: i file audio enabled e disabled dovranno essere caricati nel sistema altrimenti non sarà possibile udire il
messaggio di conferma
Monitoraggio tramite BLF
In queste applicazioni risulta fondamentale avere uno stato “visualizzabile” del servizio: i BLF in questa
situazione fanno al caso nostro:
Configuriamo sul telefono un tasto funzione BLF con number *500:
BLF feature key
Area Culturale
Configurato questo il telefono invierà una SUBSCRIBE per il SIP URI sip:*[email protected], se non ci sono
problemi la SUBSRCIBE verrà accettata con un 200 OK e verrà notificato lo stato dello user agent
monitorato:
Qui di seguito la SIP trace dopo aver configurato il BLF:
BLF SIP trace
Area Culturale
E’ possibile anche visualizzare lo stato della subscription tramite il menu Subscriptions:
Outgoing Subscriptions
Configurato il BLF il telefono accenderà o spegnerà il LED del tasto funzione a seconda dello stato del
servizio notte: acceso se il servizio è attivo, spento se il servizio è disattivo, premendo il tasto sarà possibile
cambiare lo stato del servizio.
Di seguito come appare lo schermo di uno snom821 con il tasto 1 configurato come BLF per il servizio
notte:
Servizio disattivo (il tasto è spento):
Servizio attivo (il tasto è acceso di rosso fisso):
Un BLF personalizzato
Questo tasto si comporta a tutti gli effetti come un normale BLF, ora vorremmo però avere un
comportamento più specifico per questo BLF “particolare”, ad esempio vorremmo che il tasto fosse verde
se il servizio notte è disattivato e che l’info di stato nel line info layer non fosse talking o idle ma notte e
giorno.
Per implementare questo comportamento personalizzato non basta un semplice BLF ma occorrono delle
regole sul telefono in grado di creare degli stati personalizzati (nel nostro caso notte e giorno) a cui
associare dei led behaviors.
Queste regole possono essere definite tramite XML Definitions, queste regole possono creare delle
subscriptions di vario tipo, “parsare” il contenuto delle NOTIFY e definire degli stati in base al contenuto e
delle azioni.
Area Culturale
L’XML definition
Per prima cosa occorre preparare in un file di testo l’XML definition da applicare al tasto funzione, questa
definition farà in modo di:
1. effettuare una subscription di tipo dialog-info per il feature code (*500)
2. definire lo stato notte quando la NOTIFY definisce uno stato confirmed (corrispondente all’Asterisk
device state BUSY)
3. definire lo stato giorno in tutti gli altri casi
4. alla pressione del tasto il telefono deve chiamare il SIP URI associato al feature code
Qui di seguito l’XML definition, nei commenti la spiegazione dei vari tag (eventualmente le variabili
service_code e domain vanno modificate).
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
<!-- XML definition start: the name and the identity is defined here: -->
<general type="Servizio Notte" identity="1"/>
<initialization>
<!-- define the initial status -->
<state value="initial"/>
<!-- The service code -->
<variable name="service_code" value="*500"/>
<!-- The domain -->
<variable name="domain" value="172.16.18.21"/>
<variable name="subscr_uri" value="sip:$(service_code)@$(domain)"/>
</initialization>
<!-- create the dialog type subscription
-->
<subscription type="dialog" to="&lt;$(subscr_uri)&gt;" for="$(subscr_uri)"/>
<!-- first parsing rules: apply this definition -->
<!-- to the well related NOTIFY
-->
<NotifyParsingRules type="applies">
<level1 translates_to='OK'>/dialog-info[@entity="$(subscr_uri)"]</level1>
</NotifyParsingRules>
<NotifyParsingRules type="state">
<!-- define the state "notte" if dialog state is confirmed -->
<level1 translates_to="notte">/dialog-info/dialog/state[.="confirmed"]</level1>
<!-- go to "giorno" state in all others states -->
<level2 translates_to="giorno"/>
</NotifyParsingRules>
<action>
<!-- dial the URI when pressed -->
<dial target="$(subscr_uri)" when="on press"/>
</action>
L’XML definition può essere applicata tramite provisioning oppure via interfaccia web,:
Area Culturale
Via interfaccia web occorre selezionare XML definition come tipo tasto e incollare l’XML nel campo number:
XML definition via WUI
Via provisioning occorre invece definire il tasto nella seguente sintassi:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<functionKeys e="2">
<fkey idx="0" context="1" label="Segreteria" perm="">
<general type="Servizio Notte" identity="1"/>
<initialization>
<variable name='service_code' value='*500'/>
<variable name='domain' value='172.16.18.21'/>
<variable name='service_name' value='Servizio Notte'/>
<variable name='subscr_uri' value='sip:$(service_code)@$(domain)'/>
<state value="initial"/>
</initialization>
<subscription type="dialog" to="&lt;$(subscr_uri)&gt;" for="$(subscr_uri)"/>
<NotifyParsingRules type="applies">
<level1 translates_to="OK">/dialog-info[@entity="$(subscr_uri)"]</level1>
</NotifyParsingRules>
<NotifyParsingRules type="state">
<level1 translates_to="notte">/dialog-info/dialog/state[.="confirmed"]</level1>
<level2 translates_to="giorno"/>
</NotifyParsingRules>
<action>
<dial target="$(subscr_uri)" when="on press"/>
</action>
</fkey>
</functionKeys>
Area Culturale
Definizione del LED behavior
Ora occorre fare in modo che il tasto sia verde nello stato giorno e rosso nello stato notte, per fare questo
abbiamo a disposizioni i settings che definiscono il led behavior e nello specifico ci interessano i prametri:
led_on, led_green e led_red.
Aggiungendo gli stati giorno e notte attiveremo i led con i colori voluti nei relativi stati:
led_on=giorno notte ON BUSY IN_A_CALL CALLING IN_A_MEETING URGENT_INTERRUPTIONS_ONLY
HOLDING DND ACTIVE INACTIVE BE_RIGHT_BACK AWAY UNAVAILABLE AVAILABLE PhoneHasCall
CurrentIdentityHasVoiceMessages PhoneHasVoiceMessages
led_green=giorno AVAILABLE Wrap-Up
led_red=notte BUSY IN_A_CALL CALLING IN_A_MEETING URGENT_INTERRUPTIONS_ONLY HOLDING DND
PS: i parametri led_on, led_green, led_red non sono gestibili tramite interfaccia web, vanno quindi
configurati
tramite
provisioning
oppure
tramite
richiesta
HTTP a
http://phone_IP/settings.htm?settings=save&led_on=giorno notte ON BUSY …. …. …
Ora il tasto associato al servizio notte è completamente integrato con il servizio:
Quando il servizio notte non è attivo (il LED è verde):
Quando il servizio notte è attivo (il LED è rosso):
Chiaramente questa feature può essere impiegata per qualsiasi tipo di notifica (ricezione email, consegna
merci, ecc..).
Grazie alla potenza delle XML definitions i snom possono implementare features molto specifiche e
totalmente personalizzate utilizzando dei protocolli standard, garantendo così la totale interoperabilità e
compatibilità.