Invocación de web services externos¶

Definición¶

Al editar un registro, SIP+ puede invocar web services que envíen datos del registro a otros sistemas y/o obtenga datos de dicho sistema. Por ejemplo: al comenzar el primer registro de una madre, SIP+ puede pasar la identificación de la madre a otro sistema y obtener de éste datos patronímicos, dirección, historial de consultas prenatalas, etc.

Es posible invocar web services externos en las siguientes instancias:

manual: Se invocan por el usuario al presionar el botón correspondiente durante la edición de formularios.
onNewMother: Se invocan automáticamente cuando se da de alta una nueva madre al sistema.
onNewPregnancy: Se invocan automáticamente cuando se da de alta una nueva gesta al sistema. También se invocan cuando se da de alta una nueva madre ya que con ella se le da de alta a su primer gesta.
onFieldChange: Se invocan cuando se modifican los valores de los campos. Es necesario definir cuáles campos disparan la invocación de cada web service.

Es posible definir más de un web service para cada instancia. Cada instancia contiene un array JSON con la definición de los web services de dicha instancia.

La invocación a dichos web services se configura en sip-plus.conf mediante una sección con el siguiente formato:

webservices {
  manual = [
    {
      url = URL
      input = ["CAMPO1", "CAMPO2", "CAMPO3", ...]
    },
    ...
  ]

  onNewMother = [
    {
      url = URL
      input = ["CAMPO1", "CAMPO2", "CAMPO3", ...]
    },
    ...
  ]

  onNewPregnancy = [
    {
      url = URL
      input = ["CAMPO1", "CAMPO2", "CAMPO3", ...]
    },
    ...
  ]

  onFieldChange = [
    {
      triggers = ["CAMPO1", "CAMPO2", "CAMPO3", ...]
      url = URL
      input = ["CAMPO1", "CAMPO2", "CAMPO3", ...]
    },
    ...
  ]
}

Para cada web service es necesario especificar:

Requerido:

url: URL a invocar. Las invocaciones se realizan desde el servidor, así que el servidor debe tener acceso a esta URL.
input: Array en formato JSON con los nombres de las variables a enviar al web service. Ver diccionario de variables.
triggers: (Sólo para web services de onFieldChange): Array en formato JSON con los nombres de las variables que disparan la invocación al web service. Ver diccionario de variables.

Opcional:

username: Nombre de usuario a utilizar en caso de que la invocación al web service requiera autenticación.
password: Contraseña a utilizar en caso de que la invocación al web service requiera autenticación.
headers: Headers adicionales a agregar a la invocación al web service. Es un objeto especificando cada header y su valor. Por ejemplo: headers {x-domain: "sip-plus"}.

Ejemplo:

  onNewMother = [
    {
      url = http://sipplus.org:9000/webservices-demo/basicInfo
      input = ["1018", "1019", "0019"]'
    }
  ]

Este web service invocará a http://sipplus.org:9000/webservices-demo/basicInfo de forma automática cada vez que se ingrese una nueva madre al sistema. Se le pasarán los 3 campos que identifican a la madre: país del documento ("1018"), tipo de documento ("1019") y número de documento ("0019").

Invocación¶

El SIP+ invocará a los web services mediante HTTP POST, enviando en el body un objeto JSON conteniendo como atributos las variables declaradas, y el valor de cada atributo será su valor en el registro.

Ejemplo de invocación:

{
  "1018": "UY",
  "1019": "CI",
  "0019": "12345678"
}

La respuesta debe incluir el header Content-Type: application/json y contener en el body un objeto JSON con el mismo formato que la invocación.

Ejemplo de respuesta:

{
  "0001": "María",
  "0002": "Pérez",
  "0006": "31/12/99"
}

Sobre la declaración de variables¶

Niveles¶

Las variables del diccionario tienen 3 posibles niveles. Existen variables a nivel de madre, de gesta , o de recién nacido.

Las variables deben aparecer siempre de la siguiente forma:

Las variables de nivel de madre deben ser declaradas simplemente con su nombre.
Ejemplo: "0019" para pasar el número de documento de la madre.
Las variables de nivel de gesta deben incluir el prefijo "pregnancy/".
Ejemplo: "pregnancy/0040" para pasar la cantidad de gestas previas.
Las variables de nivel de recién nacido deben incluir el prefijo "pregnancy/child".
Ejemplo: "pregnancy/child/0310" para pasar el sexo del recién nacido.

Este formato aplica tanto en la declaración del web service en el archivo sip-plus.conf, como al JSON de respuesta al invocar a un web service.

Renombrar variables¶

Es posible declarar una variable de forma tal que en la invocación al web service se la pase con otro nombre. Esto se puede lograr de la siguiente forma:

En el array de variables (propiedad "input" de la declaración del web service), en vez de declarar la variable como un string, declarla como un objeto JSON con único atributo, correspondiente al nombre de la variable, y en el valor indicar el nuevo nombre.

Por ejemplo, en vez de declarar:

  ["1018", "1019", "0019"]

se puede declarar:

  [{"1018": "PaisId"}, {"1019": "TipoId"}, {"0019": "NroId"}]

Al estar así declarado, el web service se invocará de la siguiente forma (adaptando el ejemplo anterior):

{
  "PaisId": "UY",
  "TipoId": "CI",
  "NroId": "12345678"
}

Adicionalmente, en el nuevo nombre se puede especificar una ruta, separando los componentes de la ruta con la barra / , y así crear estructuras.

Por ejemplo, si se declara:

  [{"1018": "id/pais"}, {"1019": "id/tipo"}, {"0019": "id/numero"}]

Entonces la invocación será de la siguiente forma:

{
  "id": {
    "pais": "UY",
    "tipo": "CI",
    "numero": "12345678"
  }
}

Variables especiales¶

Existen dos variables que no forman parte del diccionario pero que es posible pasar a un web service. Estas variables son:

"pregnancy" : Contiene el número de gesta que está siendo editada al momento de invocación.
"child" : Contiene el número de recién nacido que está siendo editado al momento de invocación.

Formato de valores¶

Al invocar a un web service, las variables declaradas pero que no tengan un valor ingresado en el registro se omitirán en la invocación.

Los valores, tanto en la invocación al web service como en su respuesta, deben cumplir con el siguiente formato, de acuerdo a su tipo definido en el diccionario de variables:

`TEXT`¶

El valor es un string de JSON, o sea el valor rodeado de comillas dobles. No debe superar el largo especificado en properties/length.

Ejemplo:

  "0001": "María"

`NUMERIC`¶

El valor es un numérico de JSON.

Ejemplo:

  "pregnancy/0009": 25

`DATE`¶

El valor es un string de JSON, con la fecha en formato "DD/MM/AA". Al utilizarse 2 cifras para el año, se considera a 1950 como año de corte: el valor 49 corresponde a 2049, mientras que el valor 50 corresponde a 1950.

Ejemplo:

  "0006": "31/12/99"

`TIME`¶

El valor es un string de JSON, con la hora en formato "HH:MM". Se utiliza formato de 24 horas para la hora.

Ejemplo:

  "pregnancy/child/0283": "23:59"

`PERIOD`¶

Este tipo se utiliza para representar una período de tiempo expresado en días y horas. El valor es un string de JSON, con el período en formato "DDdHHh".

Ejemplo:

  "pregnancy/child/6108": "01d15h"

`BOOLEAN`¶

El valor es un booleano de JSON (o sea, true o false ). Sin embargo, SIP+ nunca guarda un valor false en el registro, su ausencia indica que el valor es false. Por lo tanto, si el web service espera una variable de este tipo y el SIP+ no la incluye en la invocación, debe asumirse que su valor es false.

En la respuesta del web service sin embargo, es válido responder con un valor de false, lo cual indicará al SIP+ que el valor debe eliminarse en caso de estar previamente en true. Si la respuesta omite el valor, SIP+ simplemente dejará ese valor sin modificar.

Ejemplo:

  "pregnancy/0010": true

`ENUMERATION`¶

El valor es un numérico de JSON, indicando el índice de la opción seleccionada, con base 0. Por lo tanto debe de ser un valor mayor o igual a 0 y menor estricto a properties/options. (properties/names indica el nombre de cada opción en los distintos idiomas).

Ejemplo:

 "0011": 0

`LONGTEXT`¶

Es igual que un TEXT , pero un LONGTEXT puede incluir saltos de línea en su valor (\n), ya que será mostrado en múltipes líneas (un TEXT no debe tener saltos de línea). Dichos saltos de línea deben estar correctamente escapeados en el JSON (deben aparecer como \\n).

Ejemplo:

  "pregnancy/0555": "Nota 1\\nNota 2"

`CODE`¶

El valor es un string de JSON, con un valor de que debe pertenecer a la tabla de códigos para el código especificado en properties/type. La lista de tipos de códigos y códigos válidos se encuentra en la tabla aux_codes, pero tener en cuenta que esas definiciones pueden cambiar cuando se utiliza SIP+ en modo embebido.

Ejemplo:

  "pregnancy/0308": "1"

`INSTITUTION`¶

El valor es un objeto JSON con los 4 atributos que identifican a una institución: countryId , divisionId , subdivisionId y code. Todos ellos son strings.

Ejemplo:

  "pregnancy/0018": {
    "countryId": "UY",
    "divisionId": "0",
    "subdivisionId": "10",
    "code": "10009"
  }

Grupos de variables repetidas¶

Algunas variables se encuentran en grillas en el formulario, y por lo tanto dichas variables están repetidas en múltiples líneas. Ejemplos son: controles prenatales, controles postparto, etc. En el diccionario, estas variables se encuentran definidas dentro de un grupo, como es el caso de "prenatal" para los controles prenatales.

Para referenciar estas variables, es necesario incluir el nombre del grupo y el número de línea antes del nombre de la variable, todos ellos separados por una barra /.

Ejemplo:

{
  ...
  "pregnancy/prenatal/1/0116": "01/03/18",
  "pregnancy/prenatal/1/0119": 8,
  ...
  "pregnancy/prenatal/2/0116": "01/04/18",
  "pregnancy/prenatal/2/0119": 12,
  ...
  "pregnancy/prenatal/3/0116": "01/05/18",
  "pregnancy/prenatal/3/0119": 16,
  ...
}

Valores de otras gestas u otros recién nacidos¶

El SIP+ integrará los valores recibidos a la gesta y recién nacido que están activos en el momento de invocar al web service.

Sin embargo, es posible indicar valores de una gesta o recién nacido específicos. Para lograr esto es necesario sustituir en el nombre de la variable el prefijo pregancy por pregnancies/<gesta> y/o child por children/<recién_nacido>, dónde <gesta> y <recién_nacido> son el número de gesta o de recién nacido respectivamente.

Ejemplo, se puede especificar el sexo de 2 gemelares de la gesta actual de la siguiente forma:

{
  ...
  "pregnancy/children/1/0310": 0,
  "pregnancy/children/2/0310": 1,
  ..
}

Formato de respuesta jerárquico¶

El objeto de respuesta puede ser jerárquico en lugar de plano. Cada vez que hay una barra \ en el nombre de una variable, puede sustituirse por un objeto JSON embebido. El SIP+ acepta cualquier combinación de ambos formatos.

Ejemplo:

{
  "0001": "María",
  "0002": "Pérez",
  "0006": "31/12/99",
  "pregnancy": {
    "0009": 25,
    "prenatal": {
      "1": {
        "0116": "01/03/18",
        "0119": 8
      }
    }
  }
}

Ejemplo¶

La instalación del SIP+ incluye 3 web services de ejemplo donde se pueden ver distintos ejemplos de invocaciones. Todos ellos retornan respuestas válidas con datos al azar.

La forma más práctica de ver dichos web services de ejemplo en funcionamiento es utilizando Postman) e importando un conjunto de invocaciones de ejemplo utilizando el siguiente link: https://www.getpostman.com/collections/521a9eb8039854cd7bba.

Nota: Es posible habilitar que el SIP+ invoque a estos web services de demo. En el archivo sip-plus.conf que se distribuye, hay declaraciones comentadas que los invocan. Sin embargo, bajo ninguna circunstancia se debe poner en producción un sistema con estos web services definidos, ya que, de invocarse, alterarían la información ingresada por los usuarios.

Invocación de web services externos¶

Definición¶

Invocación¶

Sobre la declaración de variables¶

Niveles¶

Renombrar variables¶

Variables especiales¶

Formato de valores¶

TEXT¶

NUMERIC¶

DATE¶

TIME¶

PERIOD¶

BOOLEAN¶

ENUMERATION¶

LONGTEXT¶

CODE¶

INSTITUTION¶

Grupos de variables repetidas¶

Valores de otras gestas u otros recién nacidos¶

Formato de respuesta jerárquico¶

Ejemplo¶

`TEXT`¶

`NUMERIC`¶

`DATE`¶

`TIME`¶

`PERIOD`¶

`BOOLEAN`¶

`ENUMERATION`¶

`LONGTEXT`¶

`CODE`¶

`INSTITUTION`¶