PBX GUI - Preparando PBXact para su integración con utile h+ (middleware de PBX-PMS)

Utile h+ es un middleware que tiene como objetivo integrar plataformas IP-PBX con Property Management Systems (PMS). Esta guía describe las configuraciones necesarias en el servidor PBXact para que se establezca la integración.

Servicios que se implementarán

Servicios compatibles con PBXact:

• Clase de servicio (permisos para las llamadas salientes según si la habitación esté libre u ocupada)

• Estado de la habitación (estado de limpieza de la habitación; para que los empleados de limpieza del hotel registren en el PMS que la habitación ha sido limpiada)

• Minibar (IVR de minibar para ordenar fácilmente)

• Gestión de alarmas (llamadas de despertador)

• Facturación (facturación de llamadas externas realizadas)

Consideraciones previas en el servidor PBXact

1. El software SAMBA para compartir archivos debe estar instalado para poder intercambiar información entre utile h+ y PBXact.

2. Dentro de la configuración de las extensiones en PBXact, se debe definir la variable HABITACION, con el número de habitación.

3. Las troncales para realizar llamadas externas deben tener el parámetro "Outbound CallerID" configurado correctamente con el DID de esa troncal, cumpliendo con lo que el Operador espera. Es posible que tenga que colocarlo con el formato:
   "Nombre del Hotel" <#######>
   (donde: ####### es el DID del Hotel)

4. Todas y cada una de las extensiones de habitación de hotel deben crearse con un único controlador de canal SIP, ya sea PJSIP (predeterminado para la integración utile h+) o CHAN_SIP, esto para todas las habitaciones.

Configuraremos los puntos 1 y 2 a continuación.

Esquema de integración

Open

Estructura de directorios

Para el intercambio de información entre PBXact y utile h+, se utilizará un directorio dentro del sistema PBXact, por ejemplo, /opt/CHAR . Este directorio debe ser escribible desde el servidor Windows donde está instalado el utile h+.

Por eso, es necesario instalar el servicio SAMBA:

Una vez instalado, coloque la siguiente configuración mínima en su archivo de configuración ( /etc/samba/smb.conf ):

Una vez que se ha establecido la configuración de SAMBA, es necesario crear la siguiente estructura de directorios dentro de la ruta  /opt/CHAR :

• Directorio

 /opt/CHAR/checking → Directorio donde se encontrarán los archivos AGI de cada habitación

• Directorio 

/opt/CHAR/despertador → Enlace simbólico a /var/spool/asterisk/outgoing para el Servicio de alarma

• Directorio 

/opt/CHAR/tarificacion → Enlace simbólico a /var/log/asterisk/cdr-csv

• Archivo 

/opt/CHAR/codigos.txt → Los códigos de los empleados para que sean validados al llamar para registrar la habitación como limpia y también para registrar en los archivos de registro qué empleado limpió la habitación

NOTA: recuerde asignar el propietario correcto y otorgar los permisos apropiados, simplemente ejecute lo siguiente:

También tendrá que copiar el agi predeterminado:

Reinicie el servicio SAMBA para aplicar los cambios realizados anteriormente en su archivo de configuración:

Habilítelo para que se ejecute automáticamente cada vez que se inicie el servidor:

Los siguientes contextos mínimos se pueden definir dentro del archivo de asterisk /etc/asterisk/extensions_custom.conf donde especificamos ciertos parámetros de configuración para las extensiones de habitaciones del hotel:

• [habitaciones] → Contexto saliente para extensiones de habitaciones del hotel.

• [hab-libre] → Contexto saliente cuando la habitación está vacía (checked-out).

• [hab-ocupada] → Contexto saliente cuando la habitación está ocupada (checked-in).

• [servicios] → Contexto para los servicios del hotel.

• [extensiones] → Contexto saliente para llamadas internas de una habitación a otra.

• [internacionales] → Contexto saliente para llamadas externas fuera del hotel (para sean facturadas).

• [roomservice] → Contexto saliente para el estado del servicio de limpieza (para que la persona de limpieza pueda registrarlo una vez que haya limpiado la habitación).

• [minibar] → Contexto saliente para llamadas al servicio de minibar.

• [despertador] → Contexto entrante para las llamadas de alarma.

Los configuraremos a continuación, dentro de las siguientes secciones:

Estado: Checked-in / Checked-out

Este servicio se utiliza cuando una habitación está ocupada (Checked-In) o vacía (Checked-Out).

Se hace necesario controlar el tipo de llamadas salientes que se permitirán en cada uno de estos estados. Para hacerlo, en el directorio /opt/CHAR/checking , la aplicación utile h+ modificará la secuencia de comandos AGI que seleccionará el contexto donde debe buscar el número al que llamar.

Todas las extensiones de habitación de hotel deben pertenecer al contexto "habitaciones" y tener definida una variable con el Número de habitación ("HABITACION"), de la siguiente manera:

[101]
type=friend
secret=clave
defaultuser=101
canreinvite=no
nat=no
context=habitaciones
setvar=HABITACION=101 

Como se indicó, las dos últimas líneas (context y setvar) son las que permiten la integración de PBXact con utile h+. Para que estas líneas se agreguen correctamente a las extensiones de habitación de hotel, el archivo /etc/asterisk/pjsip.endpoint_custom_post.conf (o /etc/asterisk/sip_custom_post.conf  si es que las extensiones de habitación de hotel utilizan el controlador de canal CHAN_SIP) debe editarse de la siguiente manera (ejemplo):

NOTA: para las extensiones CHAN_SIP la nomenclatura correcta es setvar (y no set_var que es para las extensiones PJSIP)

Y así sucesivamente para todas las extensiones de habitación de hotel.

El contexto [habitaciones] define, en el plan de marcado de asterisk, desde donde comenzará el plan de marcado ejecutarse para cada llamada realizada por las extensiones de habitación del hotel, debe ser como sigue (coloque estas líneas en el archivo /etc/asterisk/extensions_custom.conf):

Una vez configuradas, las extensiones de habitación podrán llamar a los servicios del hotel o cualquier número, dependiendo del resultado de la secuencia de comandos AGI ejecutada, ya que establecerá una llamada con el contexto [hab-ocupada] o con el contexto [hab-libre] , según sea el caso, que se puede configurar de la siguiente manera:

• [hab-libre] → solo debe permitir realizar llamadas de servicios de hotel y llamadas a otras extensiones de habitación, configurado de la siguiente manera (coloque estas líneas en el archivo 

/etc/asterisk/extensions_custom.conf ):

• [hab-ocupada] → debe permitir realizar cualquier llamada, configurado de la siguiente manera (coloque estas líneas en el archivo 

/etc/asterisk/extensions_custom.conf ):

Para poder marcar a otras habitaciones y realizar llamadas externas, los contextos [extensiones] e [internacionales] deben agregarse al archivo /etc/asterisk/extensions_custom.conf respectivamente:

NOTA 1: ZXX  permitirá marcar cualquier extensión desde 100 hasta 999 (ver DIAL PATTERN INFO). Si las extensiones de habitación de hotel siguen un patrón bastante diferente (quizás números de cuatro dígitos por ejemplo), esto debe ajustarse acordemente.
NOTA 2: PJSIP/${EXTEN} es posible que deba cambiarse a SIP/${EXTEN} si las extensiones de habitación de hotel se crearon más bien con el controlador de canal CHAN_SIP.

NOTA: los AGI son generados por el utile h+ directamente. 

Estado de limpieza de la Habitación

Este servicio será utilizado por el empleado del hotel para indicar si la habitación está limpia o sucia. Para hacerlo, utile h+ leerá la información del archivo "/opt/CHAR/roomservice.log".

Para acceder al servicio, es necesario agregar un código en el contexto del servicio, de la siguiente manera (coloque estas líneas en el archivo /etc/asterisk/extensions_custom.conf ):

Con esta configuración, podremos acceder al contexto de servicio de habitaciones, donde se configurarán las llamadas de servicio. Se recomienda generar al menos 1 archivo de audio  (ver System Recordings Module User Guide):

• room-cleaning-service.gsm → “Servicio de limpieza de habitaciones. Presione 0 si la habitación está limpia, o presione 1 si no está limpia”

El archivo “/opt/CHAR/codigos.txt” se usará para validar el código ingresado por el empleado y poder registrarlo para el PMS (fecha, hora, empleado limpiando qué habitación). Se puede usar el siguiente contexto (coloque estas líneas en el archivo /etc/asterisk/extensions_custom.conf ): 

NOTA: el formato para cada una de las líneas que se almacenarán en el registro que se transferirá al PMS (roomservice.log) es el siguiente:

Identificador de Room Service (RS), Fecha y Hora del evento, Número de la Habitación, Estado de la Habitación (0 - limpia, 1 - sucia), Código del Empleado

Servicio de Minibar

Este servicio se utiliza para indicar los cargos del minibar. Para hacerlo, utile h+ leerá la información del archivo /opt/CHAR/roomservice.log

Para acceder al servicio es necesario agregar un código en el contexto [servicios], de la siguiente manera (agregue las líneas mostradas en negrita dentro del archivo /etc/asterisk/extensions_custom.conf a continuación de las líneas ya agregadas anteriormente al contexto [servicios]): 

[servicios]
exten=>*01,1,NoOP(-- Servicio de Habitaciones --)
exten=>*01,n,Goto(roomservice,s,1)

exten=>*02,1,NoOP(-- Servicio de MiniBAR --)
exten=>*02,n,Goto(minibar,s,1) 

Con esta configuración podremos acceder al contexto del minibar donde se configurará su servicio. Se recomienda generar al menos 7 archivos de audio para ello:

• minibar.gsm → "Bienvenido al servicio de Minibar"

• intro_cantidad.gsm → "Introduzca la cantidad"

• intro_articulo,gsm → "Introduzca el código del artículo"

• cantidad.gsm → "Cantidad introducida…"

• articulo.gsm → "Artpiculo introducido…"

• menuarticulo.gsm → "Presione 1 para confirmar y continuar, presione 2 para cancelar, presione 3 para confirmar y finalizar y * para acceder a la lista de artículos."

• listacodigos → "Siempre que desee dejar de escuchar la lista de artículos, presione una tecla. La lista de artículos es la siguiente: ..."

Se puede usar el siguiente contexto (coloque estas líneas en el archivo /etc/asterisk/extensions_custom.conf):

Servicio de Alarma (llamadas de despertador)

Este servicio se utiliza cuando el huésped pide que lo despierten a una hora determinada en la mañana. Se basa en los archivos de llamadas de Asterisk que se generarán mediante utile h+ y se guardarán en el directorio /opt/CHAR/despertador . El cual no es más que un enlace simbólico con /var/spool/asterisk/outgoing

El contexto para el servicio de despertador es el "[despertador]" y puede ser de la siguiente manera (coloque estas líneas en el archivo /etc/asterisk/extensions_custom.conf):

NOTA: puede ser necesario modificar el archivo de plantilla para generar las llamadas de despertador de acuerdo con el controlador del canal SIP con el que se crearon las extensiones de habitación de hotel (CHAN_SIP o PJSIP). Esto se hace editando el achivo reminder_template.call dentro del servidor Windows corriendo el utile h+, ubicado específicamente en: C:\CHARWIN\asterisk\hlink\reminder_template.call  Simplemente cambie en la primera línea de PJSIP a SIP si las extensiones de habitación de hotel usan el controlador de canal CHAN_SIP y no el controlador PJSIP:

Channel: PJSIP/%EXTENSION% → Channel: SIP/%EXTENSION%

Permitir las llamadas desde extensiones administrativas (Recepción y demás) hacia las habitaciones

Agregar las siguientes líneas en final del archivo /etc/asterisk/extensions_custom.conf

Facturación

Cada llamada externa realizada desde una extensión de habitación de hotel se contabiliza y transfiere apropiadamente al utile h+ , el cual a su vez envía la información al PMS. Para esta integración, se debe incluir lo siguiente en el archivo /etc/asterisk/cdr.conf :

El último paso es asegurarse de que se apliquen los cambios de Asterisk, solo ejecute:

APÉNDICE A

Scripts bash opcionales para automatizaciones por lotes

Rellenar el archivo SIP custom_post.conf

Para completar automáticamente el archivo /etc/asterisk/pjsip.endpoint_custom_post.conf (o /etc/asterisk/sip_custom_post.conf si las extensiones de habitación de hotel usan el driver CHAN_SIP y no PJSIP), el script bash opcional podría utilizarse:

Simplemente ejecútelo desde cualquier PC o servidor Linux (podría ejecutarse desde el propio PBXact) de la siguiente manera:

1. Haga ejecutable el script:
   chmod +x populate_custom_post_file_for_utileh.sh

2. Ejecútelo:
   sh populate_custom_post_file_for_utileh.sh

El script le preguntará en pantalla (consola Linux) la cantidad total de habitaciones y luego el número de la primera habitación, en base a esta información genera un archivo llamado "custom_post.conf" que luego debe colocarse con el nombre correcto (ya sea pjsip.endpoint_custom_post.conf o sip_custom_post.conf), dependiendo de si usa PJSIP o CHAN_SIP para las extensiones de creadas para las Habitaciones y, por supuesto, ubicado en la ruta correcta (/etc/asterisk/) con el propietario y los permisos correctos (revise el APÉNDICE B abajo).

Generación por primera vez de los archivos checkinout###.php

La primera vez que el estado de una habitación se establece como Checked-In o Checked-out a través de utile h+ (o a través del propio PMS), utile h+ genera un archivo checkinout###.php correspondiente y lo coloca dentro del PBX bajo /opt/CHAR/checking/ como se mencionó anteriormente; si se considera, el script bash opcional  en conjunto con el archivo podría utilizarse para generar automáticamente esos archivos de checkinout###.php para cada habitación de una sola vez:

1. Coloque ambos archivos en la central, en: /opt/CHAR/Checking/
   
   

2. Otorgue permisos de ejecución al script:
   chmod +x /opt/CHAR/checking/generate_chekinout_files_for_utileh.sh
   
   

3. Cambie el propietario de ambos archivos a asterisk:
   chown asterisk: /opt/CHAR/checking/checkinout_BASE_FILE.php /opt/CHAR/checking/generate_chekinout_files_for_utileh.sh
   
   

4. Ejecute el script como usuario asterisk:
   sudo -u asterisk sh /opt/CHAR/checking/generate_chekinout_files_for_utileh.sh

El script le preguntará en pantalla (consola Linux) la cantidad total de habitaciones y luego el número de la primera habitación, en base a esta información, genera todos los archivos de checkinout###.php

Eliminar archivos de buzón de voz después de que el estado de la habitación haya cambiado a checked-out

Para eliminar automáticamente todos los archivos de buzón de voz de todas las Habitaciones cuyo estado haya cambiado a checked-out, se puede usar el script bash opcional :

1. Coloque el script en el PBX, en: /opt/

2. Hágalo ejecutable:
   chmod +x /opt/delete_vm_files.sh

3. Edite el crontab (crontab -e) y agregue la línea cronjob que hará que el script se ejecute automáticamente de manera periódica. Ejemplos:
   a) Si desea que el script se ejecute todos los días a las 13h30: 30 13 * * * /usr/bin/sh /opt/delete_vm_files.sh
   b) Si desea que el script se ejecute cada 10 minutos: */10 * * * * /usr/bin/sh /opt/delete_vm_files.sh

APÉNDICE B

Archivos .conf de ejemplo

Aquí hay archivos de configuración de muestra (.conf) de la integración descrita anteriormente. En lugar de agregar/editar los archivos mencionados anteriormente directamente desde el servidor PBXact, puede considerar descargar los archivos siguientes y cargarlos en el servidor PBXact bajo sus rutas correctas (asegúrese de ajustar el dueño y los permisos de estos archivos acordemente después de haberlos cargado manualmente):

(root 644) /etc/samba/ : 
(asterisk 777) /opt/CHAR/ : 
(asterisk 664) /etc/asterisk/ :   o  /etc/asterisk/ : 
(asterisk 664) /etc/asterisk/ : 
(asterisk 664) /etc/asterisk/ : 

Los servicios profesionales de Sangoma pueden proporcionar soporte de configuración de PBXact y se limitan a la configuración de PBXact. utile h+ no tiene ninguna garantía de Sangoma ya que se trata de una integración de terceros. Los usuarios finales son responsables de obtener su propio soporte h+ útil.