Integrar una aplicación en Asterisk no resulta dificil si tenemos unos conocimientos básicos del dialplan y sabemos como realizar consultas a bases de datos. En esta ocasión y a modo de sencillo ejemplo relizaremos una sencilla modificación en nuestro dialplan para enlazar asterisk con Mantis.

¿Que es Mantis?

Para aquellos que no lo conozcais, Mantis es un completo sistema de seguimiento de incidencias, libre y funciona sobre php+mysql. No llevo mucho tiempo trabajando con Mantis, pero hasta ahora he descubierto bastantes posibilidades:

• Las incidencias pueden pasar por diversos estados (abierta, asignada al ténico, cerrada…) facilmente reconocibles por colores, así como organizarlas por proyectos.
• Permite la creación crear varios perfiles de usuario (técnico, desarrollador, coordinador…),
• Es posible definir un flujo de trabajo (p. ej: el perfil X puede abrir incidencias, pero solo el perfil Y puede resolverlas y cerrarlas)
• También nos permite mantener una comunicación directa via email con el cliente afectado, de forma que cada vez que editemos una incidencia le llegue un mensaje al usuario con los cambios realizados.

Captura de Mantis.

Un caso práctico.

Bien, supongamos que la joven empresa Pepe Consulting S.L. se dedica a la reparación y mantenimiento de equipos informáticos.

Esta empresa tiene una central en la que reciben los pedidos de los clientes, llevan un registro de las incidencias y a coordinan a los técnicos que estan en la calle.

Resulta que Godofredo Cascajosa, uno de los técnicos de campo, se ha desplazado a un pueblo cercano, Villacabreros del Trabuco, para hacer una reparación y ahora necesita llamar a la central para saber cual es su próximo encargo.

Pues bien, ahí es donde entra Asterisk en acción, ¿por que tener a una operadora ocupada cuando el propio Asterisk puede darle esa información? Con el siguiente ejemplo veremos como Asterisk realiza una consulta a la base de datos de Mantis y facilita la información requerida al técnico.

Lo primero de todo es tener un buen plan, en nuestro caso hemos diseñado el diagrama de flujo que va a seguir nuestra aplicación:

Al turróoooon!!!

Para que esto funcione tenemos que saber dónde almacena mantis la información sobre las incidencias dentro de la base de datos. En nuestro caso las incidencias son almacenadas en la tabla mantis_bug_table y los campos que nos interesan son:

• id: número de incidencia
• summary: titulo de la incidencia
• status: estado de la incidencia (nos interesa el estado 10, incidencias abiertas

En la tabla mantis_bug_text_table encontraremos el campo description donde se almacenan la descripciones de las incidencias.
Comenzaremos creando la extension mantis, que se corresponderá con el número 101.

[mantis]
exten => 101,1,Answer()
 
;Conexion inicial a la base de datos
exten => 101,n,MYSQL(Connect CONNID host user pass dabase)
exten => 101,n,GotoIf($["${CONNID}" = ""]?errMysql)
 
exten => 101,n,NoOp(Menu inicial)
exten => 101,n(menu),Wait(1)
 
;Leemos las opciones del menu y esperamos la respuesta
exten => 101,n,Festival(Pulse UNO para listar las incidencias.)
exten => 101,n,Festival(Pulse DOS para ver detalles.)
exten => 101,n,Read(MENU,,1)  ;Recogemos la opcion pulsada
exten => 101,n,GotoIf($["${MENU}" = "1"]?opcion1)
exten => 101,n,GotoIf($["${MENU}" = "2"]?opcion2)
exten => 101,n,Goto(menu)

Con esto ya hemos conseguido crear la conexión a la base de datos y el menú inicial. Vamos con el primer apartado del menu:

; ==================================
; Opcion 1 (Listado de incidencias)
; ==================================
exten => 101,n(opcion1),NoOp(Opcion 1 seleccionada)
 
; Cuenta el número de incidencias abiertas
exten => 101,n,MYSQL(Query QCOUNT ${CONNID} SELECT\ COUNT(id)\ from\ mantis_bug_table\ WHERE\ status=10)
exten => 101,n,MYSQL(Fetch foundRow ${QCOUNT} BUG_COUNT) ; fetch row
 
; Si no existen incidencias salimos
exten => 101,n,GotoIf($["${BUG_COUNT}" = "0"]?infoNoHayBugs)
 
; Si existen incidencias indicamos el numero
exten => 101,n,Festival(Hay ${BUG_COUNT} incidencias abiertas:)
 
; Consultamos las incidencias abiertas
exten => 101,n,MYSQL(Query QBUGS ${CONNID} SELECT\ CONCAT(\'Incidencia número\ \'\,id\,\'\: \ \'\,summary)\ from\ mantis_bug_table\ WHERE\ status=10)
exten => 101,n(fetchrow),MYSQL(Fetch foundRow ${QBUGS} BUG_DESC) ; fetch row
exten => 101,n,GotoIf($["${foundRow}" = "0"]?done) ; Si no existen incidencias salimos
exten => 101,n,Wait(1)
exten => 101,n,Festival(${BUG_DESC})
exten => 101,n,Goto(fetchrow)
 
exten => 101,n,Goto(menu) ; Volvemos al menú

Fijaos que al construir la consulta debemos introducir el caracter de espacio debemos hacerlo con una barra invertida delante “\ “.
Ahora con el segundo:

; =================================
; Opcion 2 (Detalle de incidencias)
; =================================
exten => 101,n(opcion2),NoOp(Opcion 2 seleccionada)
exten => 101,n,Wait(1)
exten => 101,n,Festival(Introduzca el número de incidencia con 4 dígitos)
 
;Lectura del numero de incidencia
exten => 101,n,Read(ID,,4)
 
;Buscamos la incidencia introducida
exten => 101,n,MYSQL(Query QDESCRIPTION ${CONNID} SELECT\ description\ from\ mantis_bug_text_table\ WHERE\ id=${ID})
exten => 101,n,MYSQL(Fetch foundRow ${QDESCRIPTION} DESCRIPTION) ; fetch row
 
;Si no existe la incidencia avisamos saltamos a la subrutina que informa que la incidencia no existe
exten => 101,n,GotoIf($["${foundRow}" = "0"]?infoBugInexistente)
 
;Si existe la incidencia se lee su numero y su descripcion
exten => 101,n,Wait(1)
exten => 101,n,Festival(Incidencia numero ${ID}. Descripcion:)
exten => 101,n,Festival(${DESCRIPTION})
 
exten => 101,n,Goto(menu) ;Volvemos al menú

Y el código donde manejamos los mensajes de error:

; =======
; Errores
; =======
exten => 101,n(infoNoHayBugs),Festival(No hay incidencias abiertas.)
exten => 101,n,Goto(menu)
 
exten => 101,n(infoBugInexistente),Festival(La incidencia indicada no existe.)
exten => 101,n,Goto(menu)
 
exten => 101,n(errMysql),Festival(Se ha producido un error de conexión.)
exten => 101,n,Hangup

Un vez guardado este código en el archivo mantis.dialplan en /etc/asterisk/dialplan, tenemos que asegurarnos que lo estamos incluyendo en nuestro dialplan mediante la línea:

#include dialplan/mantis.dialplan

También nos aseguraremos de que la extension [mantis] esté habilitada para las llamadas entrantes poniendo esta linea en nuestro contexto de llamadas entrantes:

include => mantis

Reiniciamos nuestro Asterisk, y voilá! Cuando nuestro técnico llame a la central solo tendrá que marcar el 101 para acceder al menú de consulta de incidencias de Mantis.

“Me gusta que los planes salgan bien…”

A la hora de pensar en una aplicación telefónica real en Asterisk, lo primero que como programador se me viene a la cabeza, es la forma en que se va a comunicar con el usuario. Esto es, la forma en que va a introducir los datos y va a obtener la información deseada.

En una aplicación informática estándar, tenemos a disposición del usuario la pantalla del ordenador para mostrar información y un teclado y ratón con el que introducir los datos, sin embargo tenemos que tener en cuenta, que por muy potente que sea el programa que hemos desarrollado en asterisk, el usuario solo va a disponer de un pequeño auricular y un teclado numérico de 10 teclas (y en el peor de los casos, con los antiguos teléfonos analógicos, ni siquiera eso).

Actualmente, con el uso de los teléfonos móviles (y algunos fijos) tenemos la posibilidad de interactuar mediante mensajes SMS, lo cual ofrece una vía adicional de comunicación entre nuestra aplicación y el usuario, pero en este artículo nos centraremos mas en la comunicación basada en la telefonía tradicional.

La salida

El canal de salida estándar en nuestro caso el auricular del teléfono, mediante el cual podremos reproducir sonidos, grabaciones o incluso generar voces sintéticas mediante TTS (text to speech).

Una opción económica a la hora de elegir un motor TTS es Festival Speech Synthesis System (Festival para los amigos) una alternativa libre para generar voz sintética. Actualmente se encuentra en su versión 2.0 beta y soporta muchos idiomas y cuando digo muchos me refiero a bastantes. En cuanto a la calidad de la voz, no os voy a engañar, suena a máquina, os parecerá estar hablando con el ordenador de Juegos de Guerra (Que también tiene su encanto, oye!) pero las alternativas son aplicaciones comerciales de pago no asequibles a cualquier bolsillo. Entre las mas conocidas, Verbio y el famoso Loquendo.

La entrada

En cuanto al canal de entrada, la introducción de datos, la fórmula mas sencilla es la utilización del propio teclado del teléfono para introducir dígitos, esto nos limita a usar solo números y los caracteres especiales # y *. Por lo que nos vemos siempre obligados a utilizar códigos de usuario numéricos, contraseñas numéricas y menús organizados por números.

También existen actualmente sistemas de reconocimiento de voz aunque la mayoría aun no están muy depurados. Probablemente ya lo habréis sufrido alguna vez llamando al servicio técnico de alguna compañía (“Por favor, diga claramente el motivo de su llamada…”). El principal problema de estos sistemas es que no son fiables, requieren que el usuario hable claramente, vocalizando y sin ningún ruido de fondo, algo complicado si tenemos en cuenta la gran riqueza dialéctica de nuestro país.

Mas adelante ya veremos como montar una aplicación básica en Asterisk usando Festival y el teclado numérico como entrada de datos. Así como la instalación y configuración del servicio Festival.

Recientemente hemos descubierto las ventajas de la programación AGI en el dialplan de Asterisk, y nos preguntabamos si sería posible integrar una libreta de direcciones con asterisk de forma que se pudiera mostrar en el caller id el nombre del usuario que estaba llamando. De esta forma podremos ver en la ventana emergente de nuestro softphone (o en el display del teléfono IP) el nombre del contacto, en lugar del número desde el que está llamando.

En nuestro caso trabajamos con la libreta de direcciones de eGroupWare, y una vez localizada la base de datos y la tabla en la que se almacenan los contactos, el resto no supone mucho trabajo.

Empezaremos por editar el dialplan de nuestro Asterisk, e indicarle que todas las llamadas entrantes deben ser pasadas a nuestro script para comprobar si están en la libreta de contactos.

[entrantes]
exten => s,1,AGI(callerid.agi)  ;Reconocimiento del callerID
exten => s,2,Goto(horarios,s,1)  ;Comprobación del horario de oficina

A continuación crearemos nuestro script de reconocimiento de callerid. Para ello vamos a utilizar Python, pero igualmente lo podríamos haber hecho en Perl, Ruby o Php. La ventaja de la programación AGI es que es independiente del lenguaje que utilicemos, ya que la comunicación entre el dialplan y el AGI se realiza mediante la salida/entrada estándar.

Previamente hemos instalado en nuestro servidor la librería MySQLdb para Python que nos permitirá hacer consultas SQL a la base de datos de eGroupWare.

#!/usr/bin/python
#FILE: callerid.agi
 
import sys
import MySQLdb
 
# datos de la conexion SQL
host = 'avefenix'
user = 'USER'
password = 'PASS'
database = 'egroupware'

Recogemos todos los datos introducidos por la entrada estándar, aunque el unico que nos interesa es el campo ‘agi_callerid’ que es el que contiene el número teléfono entrante.

callerid = "Oculto" # por defecto
while 1:
        line = sys.stdin.readline().strip()
        if line =='':
                break
        key,data = line.split (':')
        if key  == 'agi_callerid':     #Extraemos la variable de entorno "agi_callerid"
                callerid=data.strip()	# Lo guardamos en la variable callerid
                break

Una vez obtenido el callerId conectamos con la base de datos, y le dejamos todo el peso de la operación de búsqueda a la consulta SQL. En nuestro caso vamos a buscar el teléfono en los campos de teléfono de trabajo, de casa, móvil y fax.

#Conectamos con la base de datos de Avefenix
db=MySQLdb.connect(host,user,password,database)
 
#Creamos un cursor para ejecutar la consulta
cursor = db.cursor()
 
#Hacemos la consulta SQL
cursor.execute('select n_fn,org_name from egw_addressbook where tel_work=' + callerid + ' or tel_cell=' + callerid + ' or tel_home=' + callerid + ' or tel_fax=' + callerid)

Una vez tenemos el resultado de la consulta, construimos un callerid con el nombre del contacto y la empresa a la que pertenece y se lo pasamos al dialplan mediante SET CALLERID, en caso de no encontrar ninguna coincidencia simplemente salimos y dejamos que el dialplan muestre el número de teléfono entrante.

# Cogemos el primer resultado
registro = cursor.fetchone()
 
# Si hemos encontrado al menos un resultado
if (registro != None):
        #Ponemos el nuevo callerId con el formato nombre(empresa)
        callerid = ''
        if (registro[0] != None): #Nombre del contacto
        		callerid = callerid + registro[0]
        if (registro[1] != None): #Empresa del contacto
        		callerid = callerid + '(' + registro[1] + ')'
 
        callerid = callerid.replace (' ','\ ') #Sustituimos los espacios por ‘\ ‘
 
        sys.stdout.write ("SET CALLERID " + callerid + "\n")
        sys.stdout.write ("VERBOSE El\ nuevo\ callerid\ de\ entrada\ es\ " + callerid + "\n")
        sys.stdout.flush ()
else:
        # si no hemos encotnrado el contacto en la BD
        sys.stdout.write ("VERBOSE No\ se\ ha\ encontrado\ el\ contacto\n")
        sys.stdout.flush ()

A continuación salvamos el script, en nuestro caso lo guardaremos en /var/lib/asterisk/agi-bin/callerid.agi, que será donde lo buscará nuestro dialplan. Reiniciamos Asterisk y vemos que funciona correctamente.

Aún nos quedan algunos problemas por resolver como puede ser la duplicidad de números en la agenda, o la visualización incorrecta de caracteres especiales como acentos y eñes, pero como una primera aproximación es una solución muy válida.

A modo de diario de a bordo, en parte para compartir libremente nuestro conocimiento y en parte para utilizarlo como una base de conocimiento propia, los integrantes de la empresa sevillana eNe Soluciones hemos dado el paso y nos hemos lanzado a la creación de este blog.

En eNe Soluciones estamos solidamente comprometidos con la filosofía del software libre, y a través de este blog queremos poner nuestro pequeño granito de arena en el mundo del conocimiento libre y devolver así en lo posible toda la ayuda prestada por parte de la comunidad.

Sean bienvenidos!