Elastix Web Services (WSDL)

 Elastix Web Services (WSDL)
Manual de Usuario
Elaborado por: Departamento de Desarrollo de Elastix
Versión: Elastix 2.0.4-Beta 2
VERSIONAMIENTO
Versión Versión de
Elastix
1
2.0.4-2beta
Fecha
Editado por
Aprobado Por
Detalles
06-Abr-2011
Ing. Alberto Santos
Ing. Bruno Macias
Documentación Inicial
Elastix Web Services en Elastix 2.0.4-*
Los Elastix Web Services nos permiten obtener cierta información o realizar alguna acción
sobre un servidor elastix.
Para probar los Elastix Web Services se debe seguir los siguientes pasos:
1. Elastix 2.0.4 >= beta1
2. Tener habilitado los repositorios beta.
3. Ejecutar en una consola de linux el comando:
yum update elastix-*
Para ver ejemplos de
http://elx.ec/ewsexample
como
usarlos
descargue
el
siguiente
archivo:
ESCENARIOS
Básicamente se han planteado dos escenarios para el uso de los Elastix Web Services: en
PHP y en Javascript.
Escenario PHP
Lo primero que se debe hacer es crear un arreglo con con las opciones SOAP. Estas
opciones debe tener el usuario para el login y su password, ya que la información
adquirida o modificación son sólo para el usuario que se envía. Un ejemplo del arreglo
con las opciones SOAP sería el siguiente:
Figura 1. Ejemplo de arreglo con opciones SOAP
Como se puede observar en la Figura 1 la autenticación SOAP que se está utilizando es
para el usuario admin, por lo tanto la información o cambios se verán reflejados sólo para
este usuario.
Luego de esto debemos crear un objeto de tipo SoapClient para ello haremos uso de la
clase existente de PHP SoapClient la cual recibe como parámetro la url donde se
encuentra el Elastix Web Service y el arreglo con las opciones de SOAP que ya
previamente lo hemos definido.
Figura 2. Creando objeto SoapClient
En la figura 2 hemos inicializado un objeto tipo SoapClient, donde ipServer es la dirección
ip del Elastix Web Service y su ubicación es:
modules/calendar/escenarios/soap_voicemail.php. (dirección a partir de la raiz de
apache). Al final se debe agregar ?WSDL porque de esa forma se obtiene el WSDL.
Una vez inicializado el objeto SoapClient debemos crear un objeto tipo SoapParam el cual
recibe un arreglo con los parámetros de entrada que recive el Elastix Web Service que
vamos a invocar, este arreglo debe tener como clave el nombre del parámetro, y como
segundo parámetro el nombre del método que vamos a invocar.
Figura 3 . Creando objeto SoapParam
En la Figura 3. de ejemplo se va invocar al método downloadVoicemail, este recibe como
parámetro de entrada file que es el nombre del archivo a descargar.
Ahora se obtiene los datos utilizando el objeto SoapClient creado previamente, invocando
a su método.
Figura 4. Obtener los datos del Elastix Web Service
En la Figura 4 la variable $resultado es un objeto que tiene como atributo los valores de
los parámetros de salida que fueron devueltos por el método invocado, en este ejemplo
sería downloadVoicemail, por lo tanto si queremos hacer uso de algún parámetro de
salida simplemente hacemos $resultado->atributo.
De esta forma obtenemos los datos que nos proporciona el Elastix Web Service, o se
ejecuta el método deseado.
Hay que tener una consideración con un método de Elastix Web Services que es
justamente el mostrado anteriormente (downloadVoicemail) ya que si queremos que nos
aparezca el diálogo para descarga debemos hacer lo siguiente:
Figura 5. Crear diálogo de descarga para método downloadVoicemail
Finalmente debemos encerrar todo dentro de un try catch, ya que el Elastix Web Service
nos puede devolver una excepción tipo SoapFault en caso de que hubiese cualquier tipo
de error, y si queremos que nos imprima una descripción del mensaje podemos hacer lo
siguiente:
Figura 6. Script Final de como usar un método de un Elastix Web Service en PHP
Escenario Javascript
Lo primero que hay que tener en cuenta, al querer hacer uso de un Elastix Web Service
usando javascript son las restricciones que tienen los browsers para realizar peticiones
(requests hacia un servidor). La principal de todas es “same origin policy” la cual nos
indica que los browser solo pueden hacer peticiones a un servidor que se encuentre en su
mismo dominio y al mismo puerto (80 para Apache). Por lo tanto si queremos que
nuestras peticiones funcionen sin necesidad de usar un Proxy, debemos tener el archivo
javascript en el mismo servidor al cual se le hará la petición.
Teniendo en cuenta esa consideración, ahora necesitamos un Soap Client, para lo cual
existen muchos plug in ya sea javascript o jquery, pero la que se utilizó fue la siguiente de
jquery: http://plugins.jquery.com/files/jquery.soapclient.js.txt
Una vez descargado e incluido el jQuery.SOAPClient, procedemos a hacer uso del
mismo. Para ello crearemos una función que se llamará cuando se desee invocar a ese
Elastix Web Service. Dentro de esta función instanciamos a jQuery.SOAPClient el cual
recibe un objeto con una serie de datos, se describirá sólo los más importantes:
•
url: url donde se encuentra el Elastix Web Service (cuidado con “same origin
•
•
•
•
•
•
policy”).
methode: nombre del método que se va a invocar.
username: nombre de usuario para autenticación SOAP.
password: password de username para autenticación SOAP.
error: función que se ejecutará en caso de haber un error en jQuery.SOAPClient.
data: parámetros de entrada que recibe el método del Elastix Web Service. Estos
son recibidos como objetos.
success: función que se ejecutará si es que la petición en jQuery.SOAPClient fue
exitosa. Esta función recibe el xml de respuesta como objeto y como string.
Luego de haber instanciado a jQuery.SOAPClient llamamos a la función exec.
Figura 7. Ejemplo de uso de jQuery.SOAPClient
El objeto XML que nos da como respuesta en caso de success luce de la siguiente forma:
Figura 8. Ejemplo de respuesta XML obtenida por Elastix Web Service
Teniendo este objeto XML necesitamos parsearlo para obtener los datos que nos
interesan. Como se puede observar en la figura 8 los parámetros de salida del Elastix
Web Service se encuentran dentro de tags, pero estos tienen un prefijo que para este
caso es ns1:, este prefijo en ocasiones puede variar dependiendo del browser o del tipo
de programación realizada para crear el WSDL. Por lo tanto para ser lo más genéricos
posible se crea una expresión regular para obtener ese prefijo.
Ya con el prefijo podemos empezar a parsear el XML y crear un arreglo con los datos. En
este caso los datos de cada extensión se encuentran dentro del tag extension el cual es
un parámetro de salida por lo que lo podemos identificar siempre sin ningún problema.
El resto es cuestión de empezar a jugar con los demás parámetros de salida.
[Figura 9. en la siguiente página]
Figura 9. Ejemplo de parseo de objeto XML obtenido como respuesta del Elastix Web Service