V1 NOV 2005 (c) 2000-2005 Michele Gobbi e Alessandro Bissoli(info@callware.it). This software is licensed using LGPL.

# VoiceOne

## Cos'è VoiceOne

VoiceOne è un'applicazione web che ha lo scopo di configurare e gestire un server Asterisk. L'intenzione è di fornire uno strumento semplice e completo per gestire in piena autonomia un centralino telefonico.

## Requisiti

### Hardware

- whatever PC running Linux...
- 256 MB RAM or above recommanded

### Software

- Linux Kernel 2.6.9 or above
- MySQL 4.1 or above (v5 not tested yet)
- Apache 2 or above
- PHP 4.3 or above (v5 not tested yet)
- Asterisk 1.2 or above with addons
- mISDN drivers
- chan_mISDN 0.2.1 or above

mISDN drivers and the latest version of chan_mISDN should be installed through the misdn-install script provided by beroNet.com at http://www.beronet.com/download/install-misdn.tar.gz

## Installazione

Per configurare VoiceOne è necessario seguire i seguenti passi:

1. Editare il file /etc/sudoers aggiungendo le seguenti righe:

       www-data ALL=NOPASSWD: /sbin/shutdown
       www-data ALL=NOPASSWD: /etc/init.d/asterisk
       www-data ALL=NOPASSWD: /usr/sbin/safe_asterisk
       www-data ALL=NOPASSWD: /etc/init.d/misdn-init
       www-data ALL=NOPASSWD: /usr/sbin/astgenkey
       www-data ALL=NOPASSWD: /var/www/voiceone_webservices/config/script/install.sh
       www-data ALL=NOPASSWD: /var/www/voiceone_webservices/config/script/inkey.sh
       www-data ALL=NOPASSWD: /var/www/voiceone_webservices/config/script/misdn-conf.sh
       www-data ALL=NOPASSWD: /var/www/voiceone_webservices/config/script/set-lan.sh
       www-data ALL=NOPASSWD: /var/www/voiceone/admin/public/script/convert_and_move.sh

2. Scaricare e copiare nella document root del vostro webserver il modulo `voiceone/` e il modulo `voiceone_webservice/`.
3. Modificare inserendo i parametri corretti, il file `DOCUMENT_ROOT/voiceone/admin/config/cfg.php`
4. Modificare inserendo i parametri corretti, il file `DOCUMENT_ROOT/voiceone_webservice/config/cfg.php`
5. Controllare i percorsi impostati negli script nelle cartelle `DOCUMENT_ROOT/voiceone/admin/public/script/*` e `DOCUMENT_ROOT/voiceone_webservice/config/script/*`
6. Lanciare dal browser la pagina `http://vostrodominio/voiceone/setup.php` e seguire le istruzioni

ATTENZIONE: lo script set-lan.sh sovrascrive in modo brutale alcuni files del vostro sistema. Quindi controllate i file che va a modificare e, se serve, commentate le parti che non vi interessano.
Questo script viene lanciato nel momento in cui premete salva nel VoiceOne Configurator nel pannello di configurazione della rete. Ha lo scopo di modificare alcuni parametri di configurazione di rete della macchina e riscrive il file sudoers in modo da aggiungere permessi di root ad alcuni script di VoiceOne. Per poter funzionare deve avere a sua volta i permessi di root; è necessario quindi, aggiungere nel file `/etc/sudoers` la seguente riga:

    apache	yourhostname=NOPASSWD:/var/www/html/voiceone_webservices/config/script/set-lan.sh

dove yourhostname va sostituito con l'hostname della macchina.

## Concetti di Base

Si è cercato di semplificare i complicati concetti che stanno alla base del funzionamento di Asterisk. In particolare VoiceOne cerca di modellare le strutture di Asterisk in forme più comprensibili all'utente. Di seguito vengono elencati alcuni concetti di cui faremo uso più avanti:

Entità
  Con questo termine, VoiceOne identifica quattro elementi: i client, i provider, i numeri di telefono e le sedi.
Entità::Client
  L'entità più semplice è il client. Banalmente può essere visto come il telefono collegato al centralino, ma può essere anche un client software. Può essere sia SIP che IAX.
Entità::Sedi
  Una sede corrisponde ad un altro VoiceOne installato in modo remoto (in un'altra sede aziendale) che comunica con il centralino. Le sedi sono utili per effettuare chiamate a costo zero via IAX.
Entità::Provider
  I provider che il centralino può utilizzare. Sono previsti provider telefonici tradizionali oppure provider SIP.
Entità::Numeri Telefonici
  Queste entità comprendono insieme di numeri telefonici che l'utente può chiamare.
Entità::Code
  Rappresentano code di utenti
Gruppi
  Sono insiemi di entità omogenei. Possiamo trovare quindi gruppi di client, gruppi di sedi, gruppi di numeri di telefono e gruppi di provider.
Diritti
  Ogni entità ha la possibilità di intraprendere alcune determinate azioni. Un diritto indica cosa un'entità può fare. Ogni diritto contempla tre parti: i gruppi di entità che si possono chiamare, le applicazioni che sono abilitate e le azioni che vengono scatenate se si entra in questo diritto.

## Architettura del sistema

L'applicazione è basata su web service. VoiceOne è quindi formato da due parti:

1. Web Service: è il server vero e proprio che mette a disposizione un set di metodi per gestire la configurazione e i dati di Asterisk. Il protocollo di comunicazione è XML-SOAP.
2. Client: si tratta di un client SOAP che si interfaccia al webservice. Questo modulo contiene l'interfaccia grafica per l'utente. Si è scelto di utilizzare una GUI web per ovvi motivi di portabilità e diffusione.

### 1. Web Service

Questo modulo si trova nella cartella `voiceone_webservices`. Il server è contenuto nel file `server.php`. I metodi che vengono messi a disposizione saranno descritti nei paragrafi successivi; per ora, potete consultare la lista completa all'indirizzo:

    http://www.tuodominio/voiceone_webservices/server.php

mentre il file xml-soap è raggiungibile attraverso questo url:

    http://www.tuodominio/voiceone_webservices/server.php?wsdl

Il file server.php per poter funzionare fa uso di tre librerie opensource che troviamo nella cartella `lib`:

1. NuSoap (SOAP Toolkit for PHP): La libreria in questione mette a disposizione metodi per la creazione di server e client per la comunicazione attraverso webservice. Il sito ufficiale del progetto è http://sourceforge.net/projects/nusoap/
2. ADOdb (Database Abstraction Library for PHP and Python for MySql): La libreria crea un layer che si interpone tra il core dell'applicazione e i database. L'estrema utilità di questo modulo è l'eventuale portabilità su diversi database dell'applicazione. Il sito del progetto è: http://adodb.sourceforge.net/
3. floAPI (Interface to control Asterisk PABX program): Con questo modulo il server riesce a impartire comandi direttamente ad Asterisk. Viene utilizzato per ricaricare i nuovi parametri o per estrarre informazioni sullo stato corrente del centralino. Il sito del progetto è: http://www.phpclasses.org/browse/package/2521.html

Cosa succede quando viene invocato un metodo sul server? Ad ogni metodo pubblico corrisponde una funzione php contenuta in server.php che viene eseguita (NuSoap). Solitamente in queste funzioni php vengono elaborati dei dati sul database in lettura o scrittura (ADOdb). Come ultime operazioni, poi, si impartiscono comandi ad Asterisk in modo che ricarichi i dati appena scritti sul database (floAPI). Il risultato della funzione viene poi restituito al client sottoforma di risposta Xml SOAP.

VoiceOne sfrutta l'importante funzionalità di Asterisk che permette di scrivere su database (e non su file) i propri dati di configurazione. Per questo motivo si fa uso di un database Mysql che si chiama `asterisk`. Le tabelle che Asterisk usa sono:

- ast_config: Contiene la configurazione statica di Asterisk. Questo vuol dire che in questa tabella vengono riportati esattamente i dati che normalmente si troverebbero sui file .ini nella cartella di configurazione di Asterisk. Attualmente contiene extensions.conf, sip.conf, iax.conf e misdn.conf
- cdr: dati statistici su chiamate effettuate e ricevute
- country: (List Cost Routing) lista delle nazioni mondiali
- countryprefix: (List Cost Routing) lista dei prefissi internazionali
- extensions_table: Tabella che contiene in maniera dinamica alcuni dati di configurazione. La modifica di queste righe comporta un immediato aggiornamento del centralino
- iax_buddies: Lista dei client IAX
- provider: (List Cost Routing)
- providerdestination: (List Cost Routing) Associazione tra nazione e provider
- providerrate: (List Cost Routing) Costo orario dei provider
- sip_buddies: Lista dei provider SIP
- voicemail_users: Lista delle VoiceMail attive

Sullo stesso database `asterisk`, VoiceOne aggiunge alcune tabelle di appoggio che completano e integrano i dati del centralino. Le tabelle aggiunte sono:

- cw_action: Lista delle azioni che si possono intraprendere in un contesto (p.e. chiamare un gruppo di utenti, redirigere la chiamata verso un ivr o una coda, ecc...)
- cw_application: Lista delle applicazioni che è possibile associare ad un contesto
- cw_client: Dettaglio dei client sip e iax
- cw_department: Dettaglio delle sedi (più asterisk si possono collegare per effettuare chiamate tramite IAX in modo trasparente all'utente)
- cw_entity: Client, Sedi, Risorse e Numeri Telefonici sono definite ad alto livello Entità. Questa tabella ne contiene i dati comuni.
- cw_entity_extensions: le estensioni presenti su extensions_table legate a ciascuna entità
- cw_extension_type: tipi di estensione. Possono essere tasti veloci, oppure numeri telefonici, interni, ecc...
- cw_group: Lista dei gruppi di entità
- cw_group_entity: Associazione tra gruppi ed entità
- cw_isdn_card: Lista delle schede isdn disponibili
- cw_isdn_group: Lista dei gruppo di porte isdn
- cw_isdn_option: Opzioni personalizzate isdn sui singoli gruppi di porte isdn
- cw_isdn_phonenumber: Numeri telefonici in ascolto su porte isdn
- cw_isdn_port: Lista delle porte isdn disponibili
- cw_isdn_portgroup: Associazione tra gruppi di porte e porte isdn
- cw_ivr: Lista degli IVR creati
- cw_ivr_node: Nodi di ciascun IVR
- cw_number: Dettaglio dei numeri telefonici
- cw_option: Opzioni tabellate generiche. In questa tabella è presente uno schema generale per opzioni di vario genere. Si possono creare con cw_option delle categorie di opzioni e generare form html per la loro compilazione.
- cw_queue: Dettaglio delle code
- cw_queue_member: Membri che sono associati alle code
- cw_resource: Lista dei provider SIP e tradizionali attivi su questo centralino
- cw_right: Lista dei diritti.
- cw_right_application: Associziazione tra diritti e applicazioni
- cw_right_group: Associazione tra gruppi e diritti
- cw_technology: Tecnologie supportate (deprecato)
- cw_user: Lista degli utenti che hanno accesso a VoiceOne

### 2. Web Client

La GUI è gestita dal client web che si trova nella cartella `voiceone`. Questo modulo ha il compito di interfacciarsi con l'utente e di mandare evenutali comandi ad Asterisk usando i metodi esposti dal webservice.

L'interfaccia è concettualmente divisa in due grosse sezioni: la sezione personale e la sezione di configurazione. La prima permette di leggere la rubrica, vedere chi è in linea e modificare i propri parametri personali, la seconda permette di modificare le impostazioni del centralino.

#### Utenti

Sono stati studiati 3 tipi di utenti che possono accedere all'interfaccia web:

- Gli utenti standard, che dispongono solo del pannello utente (Personal VoiceOne)
- I configuratori, che hanno la possibilità di accedere ad alcune voci del VoiceOne Configurator
- Gli installatori, che hanno pieno accesso a tutte le funzionalità del VoiceOne Configurator

Inoltre, tutti gli interni hanno associato di default un utente di tipo standard. E' comunque possibile creare nuovi utenti non associati a client. Per entrambi i casi, si può scegliere il tipo di utenza (standard, configuratore, installatore).

#### Personal VoiceOne

La prima parte dell'interfaccia utente è

#### VoiceOne Configurator

xxx