Introducción Dialplan

El Plan de Marcación, llamando Dialplan en Asterisk, podría considerarse la columna vertebral del sistema. Como caracteristica principal, podriamos decir que es algo parecido a un lenguaje de script, en el que funciones, aplicacicones y recursos se van intercalando para formar algo parecido a "procedimientos" y "programas" dentro de lo que pudiera considerarse.

Este paradigma de programación orientado a los canales de telefonía es exclusivo en el mundo y aporta todo el potencial y flexibilidad, que las PBX tradicionales no pueden ofrecer, o lo hacen mediante mecanismos de licenciamiento y estructuras en ocasiones demasiado complejas.

Algo tan sencillo como crear un calendario de disponibilidad, suele ser una función que las centrales más nuevas y sofisticadas del mercado solo consiguen aplicando estrategias que en la mayor parte de los casos quedan limitadas a una serie de plantillas que no cubren la totalidad de la posible intención que requiera el cliente. Por ejemplo cuando hablamos de horarios por departamentos, se considera un proceso clásico en Asterisk, que en cambio, en algunas PBX, puede convertirse en un mundo.

Conceptos Esenciales

Para empezar a desarrollar un posible Dialplan, vamos a ver algunos conceptos básicos en los que se fundamenta todo el potencial.

El Dialplan se fundamenta principalmente en un fichero, aunque se pueden incluir ficheros auxiliares adicionales, llamado extensions.conf, dentro del directorio de configuraciones generales /etc/asterisk.

Concepto de Marcación

Cuando hablamos de Plan de Marcación, hacemos referencia literalmente a esto: La Marcación en un teléfono, o dispositivo de cualquier tipo (no tiene que ser necesariamente los clásicos 10 números (del 0 al 9), sino también empezamos a incluir el concepto de carácter alfanumérico). Una vez realizado el marcado, este, entraría como una "entrada" dentro de nuestro plan de marcación por el contexto que corresponda, en función de como hayamos definido nuestro el canal al que hace referencia nuestro dispositivo SIP, IAX, etc. Dentro de este contexto, la entrada (la marcación que hicimos), empieza a recorrer el script secuencialmente y a partir de ahí pueden surgir una serie de eventos asociados a esa entrada que en cualquier caso siempre suelen tener algo que ver con el mundo de la comunicación, aunque no necesariamente, ya que por ejemplo, podría darse un caso curioso de una aplicación concreta, como es la de al Marcar los números 1-1-1 en nuestro teléfono, y que se encendiera la luz de nuestro despacho.

A cada posibilidad concreta, de un conjunto de marcaciones o marcación individidual se le denomina extensión. Ejemplo, la marcación 1-1-1 sería la extensión 111.

Contextos

Los contextos son la forma de categorizar o englobar , una serie de procedimientos en función de la marcación a la que hacemos referencia desde el dispositivo que la hacemos. La sintaxis típica seria un nombre de contexto englobado entre corchetes, algo asi: [contexto].

Por ejemplo si nuestro dispositivo, que opera a traves del protocolo SIP, le indicamos que al realizar su Marcación, la envíe al contexto [general] dentro de nuestro Dialplan, definiremos que hace una posible marcación realizada en forma de extensión.

Hay que considerar que en caso que un dispositivo no tenga especificado un contexto en concreto, todas sus marcaciones se redirigiran directamente a un contexto genérico llamado [default]

Extensiones

Dentro de los contextos, se van definiendo las posibilidades concretas para un conjunto de marcaciones o como dijimos antes, extensiones.

Para definir una extensión se hace poniendo la palabra "exten =>" delante de la marcación a la que queremos hacer referencia (ejemplo exten => 111). Como comentabamos antes, hay que recordar que el concepto de marcación gracias a Asterisk no solo se limita a caracteres númericos, sino que se expande a los alfanumericos, por tanto la extensión, exten => doe también se podría considerar una extensión valida.

La sintaxis correcta sería: exten => <marcación_de_la_extensión>,<prioridad>,<aplicación>

Las Prioridades las veremos en adelante, las Aplicaciones se ven todo alrededor de este Wiki ya que realmente estas son el verdadero mundo de Asterisk.

Prioridades

Una Extensión, al ser de alguna forma como un lenguaje de script, puede tener varias funciones, o aplicaciones de forma secuencial. Al marcar la extensión 111, si la intención es que prepare la comida del horno, en primer lugar, podríamos requerir que programara la temperatura, en segundo lugar, que programara el tiempo de horneado, y en tercer lugar que lanzara la orden de calentado. Como queremos que este "algoritmo" siga un orden establecido, esto lo hacemos a través de las prioridades, que se conforman en orden secuencial numerico (el 1, el 2, el 3), aunque también podemos hacer una llamada recursiva a un contador interno para que vaya aumentando de forma "automática" (el 1, el 2, el n+1 (3), el n+1 (4) etc). La n viene de next, y es importante recalcar que la primera prioridad siempre ha de ser la número 1.

Siguiendo la sintaxis de las extensiones para ejecutar la orden de horneado seria algo así:

exten => 111,1,Programa_Temperatura()
exten => 111,2,Programa_Tiempo()
exten => 111,3,Encender_Horno()

Pero podemos mejorar esta estructura con si aplicamos el contador que hablábamos antes:

exten => 111,1,Programa_Temperatura()
exten => 111,n,Programa_Tiempo()
exten => 111,n,Encender_Horno()

Con la última versión de Asterisk, la 1.8, para no andar repitiendo constantemente lo de "exten => extension" se introduce una sintaxis nueva que simplifica mucho la vida, con same => (significa algo asi como, "lo mismo que antes").

exten => 111,1,Programa_Temperatura()
same => n,Programa_Tiempo()
same => n,Encender_Horno()

Esta última forma será la que seguiremos en todos los ejemplos al ser la más escueta y correcta a día de hoy.

Etiquetas

Dado que podemos empezar a utilizar los contadores en las prioridades, que ya no asignan un número especifico, puede ser difícil referenciarnos a una prioridad de una extensión en cuestión. Por esto surge el concepto de etiquetas, que junto a las prioridades, podemos darle un nombre a las mismas, y así poder hacer una referencia directa si nos surgiera la necesidad.

Por ejemplo, si tenemos una extensión con muchas prioridades:

exten => 111,1,...
exten => 111,n,...
...
exten => 111,n,...
exten => 111,n,...

Y por cualquier circunstancia quisiéramos ir justamente a la penúltima prioridad de la extensión, añadiendo la etiqueta (penúltima) a esa prioridad, ya tendríamos esa referencia penúltima para darle el uso a conveniencia en un futuro. Esto es especialmente útil para los saltos condicionales que veremos más adelante.

exten => 111,1,...
exten => 111,n,...
...
exten => 111,n(penultima),...
exten => 111,n,...

Extensiones Especiales

Existen cuatro tipo de extensiones estándar, que sirven para encuadrar distintos escenarios en los cuales, no es suficiente con definir una extensión especifica.

• La extensión start (s), inicio, suele ser una extensión creada de forma voluntaria a la cual la llamada suele ir, si la enviamos a un contexto especifico.
• La extensión invalid (i), inválida, hace referencia al hecho de marcar una extensión que no existe en el contexto que nos encontramos. Sirve para manejar estas excepciones, y por ejemplo poder lanzar un mensaje tipo "La extensión que ha marcado no existe".
• La extensión relative timeout (t), fin de tiempo relativo, salta cuando cumple el tiempo establecido para una Aplicación que este condicionada a un intervalo (controlado por la Función TIMEOUT). Gracias a esta extensión podriamos hacer que la llamanda no se pierda cuando cumpla el plazo, lanzando algun mensaje y reencaminandola.
• La extensión absolute timeout (T), fin de tiempo absoluto, también asociada a la función TIMEOUT, salta cuando el tiempo "global" de la llamada acaba si es que esta establecido, independientemente del punto en que nos encontremos.
• La extensión hangup (h), colgado, salta cuando nos cuelgan una llamada (obviamente si colgamos nosotros no podremos escuchar nada), suele utilizarse para reproducir un mensaje tipo "Gracias por contactar con nosotros, Hasta Pronto".

Hay otras menos populares, pero eventualmente estas son las que más haremos uso en nuestros Planes de Marcación.

Gestión de Variables

Como en todo buen lenguaje de programación o en este caso, de script, es fundamental que exista un mecanismo para almacenar Variables. Las variables pueden almacenar múltiples tipos de información pero no tan extendido como en otros lenguajes. Principalmente se usan para simplificar el código o hacerlo más legible.

Existen cuatro tipos de variables:

• Variables de Canales
• Variables Globales
• Variables de Entorno
• Variables Compartidas

Variables de Canales

Como veremos en Aplicaciones Básicas existe una Aplicación llamada Set que sirve para crear una variable y asignarle un valor especifico durante la ejecución de un canal en concreto. Podrían asemejarse a las variables locales de una función si lo comparáramos a cualquier otro lenguaje de programación. Por ejemplo si queremos asignar a la variable CONTADOR el numero 5 seria: Set(CONTADOR=5). Si luego quisiéramos acceder a esta variable, la sintaxis seria: ${<nombre_variable} en este caso sería: ${CONTADOR}.

Además existen una serie de Variables especificas asociadas a los canales y predefinidas por el sistema, las más comunes son:

• ${DIALSTATUS}: Sirve para saber el estado de la llamada, posibles valores ANSWER (respondido), BUSY (ocupado), NOANSWER (sin respuesta), CANCEL (llamada cancelada), DONTCALL (llamadas bloqueadas, el destinatario esta en estado no disponible), etc.
• ${CONTEXT}: Devuelve el nombre del contexto.
• ${EXTEN}: Devuelve el número de la extensión completa dentro del contexto en cuestión.
• ${PRIORITY}: Devuelve el número de la prioridad dentro de la extensión en cuestión.
• ${CALLERID}: Muestra el identificador del llamante, puede ser un número o cadena de texto.
• ${CHANNEL}: Devuelve el nombre del canal en cuestión.

Subcadenas de Variables

Es posible que en determinados casos, solo nos interese una subcadena de una variable. Por ejemplo, si agregamos a una extensión un número especifico a marcar, para algo en concreto (por ejemplo, las llamadas a la Central de Córdoba se realizan marcando el número 4 delante). Al crear la extensión haríamos una extensión como esta: _41XX (más adelante podemos ver patrones).

Luego al recoger la variable predefinida del canal, ${EXTEN} recogeriamos una extensión asi: 4114, pero la extensión que realmente nos interesa enviar a la central de Córdoba es la 114. Por tanto necesitamos recortar en una subcadena.

Existen tres posibilidades:

• Recortar a partir de N posiciones: ${EXTEN:1}, en este caso es lo que vamos buscando
• Recortar las últimas N posiciones, con un número negativo: ${EXTEN:-3} también conseguiríamos lo que vamos buscando.
• Recortar posiciones especificas, considerando que la primera posición es el 0: ${EXTEN:1:3} , es la tercera forma de conseguir lo que buscamos.

Esto es aplicable a todo tipo de Variables, pero especialmente útil para las Variables de Canal justamente por los supuestos casos parecidos al del ejemplo.

Variables Globales

Son aquellas variables accesibles e iguales desde cualquier contexto, canal o instancia durante la ejecución del plan de marcación.

Se definen debajo de un contexto especial llamado [globals] que suele posicionarse justo al principio del fichero extensions.conf.

El clásico uso de estas variables, es para conceptualizar los distintos pares con un nombre mas "accesible". Por ejemplo, en vez de usar SIP/ext11 para llamar a la extensión ext1 conectada por el protocolo SIP, podríamos definir dentro de "globals" una variable global así:

[globals]
EXT11 = SIP/ext11

Y desde ese momento llamar a la variable ${EXT11} cuando queramos hacer referencia a ese canal. De hecho podríamos agrupar varios canales, por ejemplo para un uso concreto como es el de llamada a múltiples extensiones simultáneamente, con una sola variable global:

[globals]
VENTAS = SIP/ext11&SIP/ext12&SIP/ext13&SIP/ext14

Luego utilizando la función Dial podríamos llamar a todas esas extensiones a la vez solo utilizando la variable ventas:

exten => 111,1,Dial(${VENTAS})

Variables de Entorno

Son un tipo de variables muy poco utilizadas por el sistema Asterisk ya que sirven para acceder a las variables de entorno de nuestro sistema *NIX. La sintaxis es muy sencilla: ${ENV(<nombre_variable>)}. Por ejemplo la variable de entorno HOME, que indica la ruta al directorio principal del usuario que ejecuta el sistema en ese momento podria obtenerse (si por ejemplo quisiéramos escribir un fichero de audio especifico dentro de ese directorio a través de una combinación de aplicaciones en una extensión).

Variables Compartidas

De reciente incorporación, podrían considerarse un subconjunto de variables locales o de canal, ya que de alguna forma, tienen la misma naturaleza, pero sirven para ser compartidas específicamente por dos o mas canales. Realmente se introdujo para poder ofrecer esta funcionalidad especifica, de poder extender el uso de una variable de canal, a otros por necesidades muy concretas.

La definición de esta variable al igual que las de canal es a través de la aplicación set: Set(SHARED(CONTADOR,SIP/ext11)). Así "escribimos" la variable CONTADOR en el canal SIP/ext11, y este en su ejecución podría acceder a la misma muy parecido al resto de las variables: ${SHARED(CONTADOR,SIP/ext11}

Asociación de Patrones de Extensiones

Regularmente las extensiones han de definirse literalmente como deben ser marcadas para poder ser alcanzadas en el Plan de Marcación.

Pero excepcionalmente existe un mecanismo para hacer una Asociación, entre un marcado en concreto, y una extensión que define un patrón general, que puede englobar múltiples combinaciones de extensiones.

Para poder crear un patrón, la sintaxis sería simplemente, poner un guión bajo delante de la extensión que va a contener el mismo (ejemplo: exten => _1X,...). En este caso del ejemplo estamos diciendo que todas las marcaciones de dos dígitos, que empiecen por 1, entrarán por este patrón, siempre y cuando no exista una extensión literal que se pueda asociar directamente y sea accesible desde el mismo contexto.

Las posibilidades que nos ofrecen los patrones van en función de su sintaxis:

• X : Cualquier dígito del 0 al 9
• Z : Cualquier dígito del 1 al 9
• N : Cualquier dígito del 2 al 9
• [...] : Cualquier dígito que este entre corchetes, Ej: [126], sería coincidencias del 1, del 2 o del 6.
• [a-b] : Cualquier dígito en ese intervalo siendo el primero "a" y el segundo "b", Ej: [2-4] serían coincidencias del 2, del 3 o del 4
• . : Cualquier dígito(s) en cualquier combinación y cantidad a partir de donde se ponga el punto. Esta opción es una de las que más puede comprometer la seguridad del DialPlan al ser casi totalmente aleatoria, como podremos ver en Seguridad. Es importante que haya al menos 1 dígito más a partir de donde se ponga el punto.
•  ! : Igual que el . pero no es necesario que haya ningún dígito más desde donde se ponga la exclamación.

Ejemplo de diferencia . y ! . Si ponemos "exten => _123.,..." y Marcamos 1-2-3, no entrara por esa extensión ya que hace falta al menos un dígito más para que se cumpla. En cambio si ponemos "exten => _123!,..." y marcamos 1-2-3, si entrará correctamente por esta extensión al cumplirse el patrón correctamente.

Todas estas posibilidades se pueden combinar en cualquier medida, Ej: "exten => _XZN[14][5-9].,..."

Voy a poner un ejemplo muy útil, para la marcación en el territorio Español, que ilustra bien la gran utilidad que puede ofrecer este tipo de asociación por patrones. Supongamos que queremos crear una extensión de marcado, para llamadas salientes a números fijos Españoles, evitando las llamadas a números de tarificación especial, típicamente definidos por contener un 0 en el segundo dígito y aparte Sabemos que todos los fijos nacionales empiezan por 9.

exten => _9ZXXXXXXX,1,Dial(SIP/operador/${EXTEN})

Utilizamos la variable de canal ${EXTEN} para lanzar al dispositivo operador asociado al canal SIP, una llamada utilizando la aplicación Dial para cualquier número fijo nacional cumpliendo las expectativas anteriores.

Coincidencias en la Asociación

¿Que ocurriría si tenemos por ejemplo las dos extensiones siguientes y marcamos la combinación 1-2-3?

1. exten => _1X3,1,NoOp() 2. exten => 123,1,NoOp()

En este caso entraría por la segunda opción, dado que la extensión coincide literalmente con la marcación. Esto quiere decir que existe un orden por el cual van comprobandose las posibilidades que tenemos para realizar una asociación y su descarte en consecuencia. Este orden es:

1. Coincidencia Literal 2. Opciones entre Corchetes [] siempre y cuando haya menos de 7 opciones involucradas, Ej: [3-8], son 6 opciones. 3. La N (8 opciones) 4. La Z (9 opciones) 5. La X (10 opciones) 6. El . (infinitas opciones).

Básicamente podemos observar el patrón, que cuanta mas opciones abiertas existan al elegir una asociación de patrón, mas bajo se encuentra en la escala de selección.

Inclusiones

Include de Contextos

Comúnmente llamados, Includes. Hacen referencia a la acción de incluir algo dentro de un contexto o apartado de nuestro plan de Marcación, sin tener que reescribirlo todo para evitar la redundancia. Son muy parecidos a los Include de la mayoría de los lenguajes de programación existentes.

Existen dos opciones:

• Incluir un contexto.
• Incluir un fichero.

Incluir un Contexto

Este tipo de include es muy práctico, dado que es el mecanismo principal para establecer una jerarquía, o un mecanismo de "herencia" para distintos contextos a los que están asociados varios dispositivos.

La sintaxis es muy parecida a la de las extensiones. Simplemente se define como include => <nombre_del_contexto_a_incluir>

Por ejemplo, según vemos en la imagen supongamos que tenemos tres contextos: [GERENCIA], [MANAGER], [RESTO].

Suponiendo que gerencia tiene acceso a todo lo que tiene acceso los mánager y estos a su vez a todo lo que tiene acceso el resto, la estructura con Include sería la siguiente:

Archivo: /etc/asterisk/extensions.conf

[resto]
exten => 111,1,Dial(SIP/ext111)

[manager]
include => resto

[gerencia]
include => manager

Hay que considerar que a la hora de incluir podemos encontrarnos con la posibilidad de que existan dos extensiones exactamente iguales. En este caso, Asterisk al seguir el orden de lectura del archivo de forma secuencial, se quedará con la primera coincidencia para una extensión en concreto.

El comportamiento de la Aplicación es un poco más complejo cuando se da la redundancia en extensiones a través de los include: Si no especificamos el contexto al que debe dirigirse, por defecto elegirá la extensión desde el contexto que originalmente fue llamada la extensión independientemente que exista en su propio contexto.

Por ejemplo nuestro dispositivo tiene asociado el contexto 1, el cual incluye un segundo contexto, que repite alguna extensión, en caso de realizarse un Goto sin especificar el contexto, y en caso que la extensión sea coincidente en ambos contexto (el original, y el incluido), la llamada irá a la extensión del contexto 1, al cual esta asociado el dispositivo originalmente.

Incluir un Fichero

Sirven principalmente, para poder "modularizar" nuestro Dialplan y así poder evitar el clásico dialplan con miles de lineas, al puro estilo de Programación Monolítica y difícilmente interpretable según el caso.

La sintaxis es también muy parecida al típico include de múltiples lenguajes, "#include fichero.conf".

Por ejemplo si queremos hacer un gran IVR (Interactive Voice Response, clásico sistema de interacción de las centralitas con el llamante) quizá sería una buena idea crear un contexto especifico dentro de un fichero especifico llamando por ejemplo ivr-extensions.conf y dentro de este exclusivamente el contexto [ivr] con todo el proceso que deseemos aportar. Es una buena práctica trabajar siguiendo este concepto.

Switch: Intercambio entre Centrales

Existe un nivel aún mas avanzado de "inclusión" (si es que puede asociarse así), que solo se da entre sistemas Asterisk que interoperan utilizando el protocolo IAX.

No podría considerarse un tipo de inclusión como tal, de alguna forma, podría considerarse mas bien un "intercambio". Una vez el flujo secuencial del Plan de Marcación llega hasta este punto, lanzamos la llamada a un contexto especifico. Este tipo de "inclusión" tiene máxima prioridad, por delante de los otros tipos de inclusión.

Un inconveniente, que no ocurre con los otros "include", ya que queda registro de su uso, y en caso de redundancia son mutuamente excluyentes, es que, en el caso que existan sentencias "switch" a ambos lados (en ambas máquinas), apuntando a dos contextos adyacentes, surgirían bucles infinitos, "peligrosos" potencialmente para la estabilidad de nuestro sistema.

La sintaxis de la sentencia Switch es la siguiente:

• switch => IAX2/<usuario>:<contraseña>@<ip_servidor>/<contexto_destino>

Expresiones y Operadores

Al considerar que el Plan de Marcación es un lenguaje tipo script, debemos establecer por base, que es posible realizar acciones basicas, como manejar bucles, condicionales, y como no estas estructuras de programación, requieren de un elemento para hacerse efectivas: Las expresiones.

Las expresiones eventualmente requieren la aplicación de todo tipo de operadores, sean aritméticos, de comparación y como no, booleanos. Como en la mayoría de los lenguajes estos son:

• Aritméticos: La suma (+), Resta (-), Multiplicación (*), División (/) y Módulo (%)
• Comparación: Igual (=), Distinto (!=), Mayor que (>), Mayor o Igual que (>=), Menor que (<), Menor o Igual que (<=)
• Booleanos: Y (&), O (|)

La sintaxis es muy corriente en este punto: $[<expresion>], ejemplo $[(2+2)>=5] en este caso el resultado sería Booleano (0) y se mostraría exactamente igual que una consulta a una Variable.

Gracias a las expresiones, podríamos alterar las Variables. Vamos a poner un código de ejemplo:

Archivo: /etc/asterisk/extension.conf

[general]
exten => 111,1,Set(contador=1)
same => n,NoOp(Si sumamos uno al contador saldría $[${contador}+1])
same => n,Set(contador=$[${contador}+1])
same => n,NoOp(Ahora si hemos aumentado el contador definitivamente ${contador})

Véase también

• IAX
• SIP
• Seguridad