Tabla de Contenidos
Introducción a SmartWebDoc
SmartWebDoc es un servicio web que permite a páginas web o aplicaciones web acceder a los datos de Smart.
Instalación
Se instala preferiblemente en la misma red donde está instalada la base de datos de Smart, para que la lectura de los datos sea lo más rápido.
SmartWebDoc se puede instalar tanto en un servidor Windows como en uno con el sistema operativo Linux. Por lo tanto es posible instalarlo en el mismo servidor de la base de datos, aunque esto no es recomendable por motivos de seguridad.
Para Windows se puede usar el programa de instalación smartwebdocsetup.exe, que solamente pide el número del puerto (por defecto 8000) y la carpeta de instalación.
Una vez terminada la instalación hay que revisar el fichero de configuración, que se encuentra en la carpeta de instalación. Si el puerto de comunicación es 8000, entonces la configuración la podemos cambiar en C:\Program Files (x86)\SmartWebDoc\smartwebdoc_8000.xml
.
<?xml version="1.0"?> <smartwebdoc> <debug>2</debug> <servidor> <ip>0.0.0.0</ip> <puerto>8000</puerto> <mensajeservidor>SmartWebDoc server</mensajeservidor> <rawpermitido>S</rawpermitido> <ssl>N</ssl> <protocolo>http</protocolo> <ficherocertca>cacert.pem</ficherocertca> <ficherocertificado>smartwebdoc.pem</ficherocertificado> <ficheroclaveprivada>smartwebdoc.key</ficheroclaveprivada> <clavecontrasena>...</clavecontrasena> <verificarcert>S</verificarcert> </servidor> <bd> <nombre>192.168.x.x:/carpeta/de/basededatos.gdb</nombre> <usuario>SYSDBA</usuario> <grupo></grupo> <clave>...</clave> <maxcon>5</maxcon> <msespera>5000</msespera> <msdesconectar>10000</msdesconectar> <msmaxejec>30000</msmaxejec> <procpermitido>XGOM_WEB</procpermitido> </bd> </smartwebdoc>
Lo principal es cambiar el acceso a la base de datos y el usuario y la contraseña de la base de datos. Luego hay que reiniciar el servicio Servicio SmartWebDoc puerto 8000 desde el panel de control de todos los servicios, para que el programa lea de nuevo la configuración.
Comunicación
Se puede configurar SmartWebDoc para que use el protocolo http o https, con el puerto que se desea. Por defecto se usa el puerto 8000.
Se accede al servicio con el método POST, pasando los datos en formato JSON.
Method: POST URL: /smartwebdoc/select/?format=json Query: format=json HeaderLine: POST /smartwebdoc/select/?format=json HTTP/1.1 Content: { "version" : "1.1", "method" : "Select", "params" : ["PROC_LEER_OBRAS", ["2016-03-01", "2016-03-31", "CL", "000999"]] }
El servicio web contesta con otro JSON:
FirstHeaderLine: HTTP/1.1 200 OK Content: { "version" : "1.1", "result" : [["16-00001", "OB000001", "Obra XYZ", "2016-03-31 00:00:00","99.99000", "ESP", "2016-09-27 00:00:00"], ["16-00002", "OB000002", "", "2016-03-31 00:00:00","1500.12000", "ESP", "2016-09-27 00:00:00"]] }
Existen dos URLs para acceder al servicio web, que son intercambiables:
Se recomienda utilizar siempres la segunda URL, es posible que la primera en un futuro deja de funcionar.
El query format=json
es opcional y dice al servicio que se quiere recibir el resultado en el formato JSON, que de momento es el único formato soportado por SmartWebDoc.
HTTPS en un entorno de pruebas
Los certificados usados por SmartWebDoc funcionando con https suelen ser self-signed y por lo tanto hay problemas de confianza al acceder el servicio desde los exploradores de web habituales.
A continuación se explica como configurar el explorador Firefox para que funcione bien con SmartWebDoc.
En primer lugar tenemos que importar el certificado de la autoridad de certificación de raíz. Este certificado nos lo puede facilitar Smart y suele llamarse cacert.pem.
Vamos a la configuración de Firefox como se muestra a continuación:
Dentro del Administrador de certificados vamos a la pestaña Autoridades y damos en el botón Importar
para importar el certificado cacert.pem.
Luego vamos a la pestaña Servidores y damos en Añadir excepción
. Ponemos la dirección del servidor donde está instalado SmartWebDoc y damos en Obtener certificado
:
Cuando se muestre el certificado podemos dar en Confirmar excepción de seguridad
. Si nos pone algo como “el certificado no es válido” lo podemos ignorar y confirmar de todos modos.
Protócolo JSON
Existen dos tipos de interfaz, Select y Raw. Ambos usan el formato JSON para pasar los datos.
JSON tipo "Select"
(ver ejemplo en el párrafo anterior)
En este caso, los datos JSON que recibe el servicio web tienen que llevar siempre el campo params
. El valor de este campo es una matriz que contiene el nombre de un procedimiento de la base de datos (PROC_LEER_OBRAS
) y los parámetros que se quiere pasar a este procedimiento (“2016-03-01”, “2016-03-31”, “CL”, “000999”
).
El JSON de vuelta contiene una matriz de dos dimensiones con los registros que devuelve el procedimiento.
Esta manera de intercambio de datos permite total flexibilidad a la hora de acceder a la base de datos. Por el otro lado, quien accede al servico web necesita conocer la definición de los procedimientos que pretende utilizar.
Documentos, imagenes etc. que devuelve el servicio se codifican en base 64.
JSON tipo "Raw"
A continuación se muestra un ejemplo de una petición Raw al servicio SmartWebDoc:
{ "version" : "1.2", "metodo" : "Raw", "opciones" : { "metaData":true }, "comandos" : [ { "sql":"select codigo, nombre from producto where upper(nombre) like :filtro rows 50", "params": { "filtro" : "PAN DE LECHE PACK%" } }, { "sql":"update USUARIO set NOMBRE = :nombre where CODIGO = :codigo", "params": { "nombre" : "Smart", "codigo" : "SMART" } } ] }
Se puede enviar una serie de comando, que se ejecutan dentro de una misma transacción. El resultado contiene un bloque por cada comando con el correspondiente resultado:
{ "version": "1.2", "resultados": [ { "estado": "OK", "metaData": { "CODIGO": { "tipo": "ftString", "etiqueta": "Código" }, "NOMBRE": { "tipo": "ftString", "etiqueta": "Nombre" } }, "datos": [ { "CODIGO": "2003990", "NOMBRE": "PAN DE LECHE PACK-4" }, { "CODIGO": "2009781", "NOMBRE": "PAN DE LECHE PACK-6" } ] }, { "estado": "OK", "datos": [] } ] }
También es posible enviar imagenes u otros datos binarios (documentos de office etc.) al serivico web, pero entonces hay que codificar el parámetro en base64 y añadir al nombre del parámetro el anexo B64
, como se muestra en el siguiente ejemplo:
{ "version" : "1.2", "metodo" : "Raw", "opciones" : { "metaData":true }, "comandos" : [ { "sql":"execute procedure INSERTA_IMAGEN :id, :imagenB64", "params": { "id" : 1000, "imagenB64" : "A3G1BGI_8KWilO" } } ] }
El formato Raw permite cualquier interacción con los datos, siempre dentro de los límites de seguridad que se explican a continuación.
Seguridad
El servicio web se conecta a la base de datos con un usuario con privilegios restringidos. Solo va a tener acceso a los datos imprescindibles para la aplicación web.