====== 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.

{{ :usu:smartweb:smartwebdoc.png?600 |SmartWebDoc arquitectura}}

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''.

<code 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>
</code>

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:
  - http://127.0.0.1:8000/smartwebdoc/select/?format=json
  - http://127.0.0.1:8000/services/ismartwebdoc/?format=json
**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:
{{  :usu:smartweb:pegado:20180522-093611.png?600  |Opciones certificados Firefox}}

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'':
{{  :usu:smartweb:pegado:20180522-094802.png?600  |Obtener certificado Firefox}}

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:
<code>
{
  "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" }
    }
  ]
}
</code>
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:
<code>
{
  "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": []
    }
  ]
}
</code>
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:
<code>
{
  "version"  : "1.2",
  "metodo"   : "Raw",
  "opciones" : { "metaData":true },
  "comandos" :
  [
    {
      "sql":"execute procedure INSERTA_IMAGEN :id, :imagenB64",
      "params": { "id" : 1000, "imagenB64" : "A3G1BGI_8KWilO" }
    }
  ]
}
</code>

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.