Sesión Embebida

Invocación

Si se invoca al SIP+ con parámetros de URL embedSystem y embedToken , el SIP+ buscará en su configuración una sección embed.<embedSystem> y, de encontrarla, invocará a URL especificada en la propiedad getSession.url de esa sección, sustituyendo $token por el valor recibido en embedToken.

Ejemplo:

Si se invoca al SIP+ a:

http://sipplus.org:9000?embedSystem=DEMO&embedToken=4ce0d29c-ba74-4060-9018-a72beb599d51

y se tiene en sip-plus.conf la siguiente sección:

embed {
  demo {
    getSession {
      url = "http://sipplus.org:9000/embed-demo/session/$token"
    }
  }
}

Entonces el SIP+ invocará (mediante HTTP GET ) a:

http://sipplus.org:9000/embed-demo/session/4ce0d29c-ba74-4060-9018-a72beb599d51

para obtener los datos de la sesión. Esta URL es la especificada en embed.demo.getSession.url , sustituyendo $token por el valor pasado en embedToken en la URL, mientras que demo corresponde al valor pasado en embedSystem (En la configuración el nombre del sistema debe estar con minúsculas. En la URL es indiferente).

Importante: El sistema externo debe generar un nuevo token único para cada nueva sesión embebida. Adicionalmente, debe implementar un mecanismo de expiración de dichos tokens. De no seguir con estos lineamientos se está incurriendo en una falla de seguidad.

Formato de respuesta

La respuesta debe incluir el header Content-Type: application/json y contener la información de sesión en el body en formato JSON con la siguiente estructura:

{
  "user": {
    "id": <STRING>(1),
    "userName": <STRING>,
    "fullName": <STRING>,
    "countryId": <STRING>(2),
    "roles": <ARRAY:ROLE>,
    "institutions": <ARRAY:INSTITUTION>(3),
    "readableInstitutions": <ARRAY:INSTITUTION>(4)
  },
  "institution": <INSTITUTION>(5),
  "embedCoordinates": <EMBED_COORDINATES>(6)
}

Con los siguientes formatos para los elementos:

<ROLE>:
{
  "id": <STRING>(7),
  "name": <STRING>,
  "permissions": <ARRAY:STRING>(8)
}

<INSTITUTION>:
{
  "id": {
    "countryId": <STRING>,
    "divisionId": <STRING>,
    "subdivisionId": <STRING>,
    "code": <STRING>
  },
  "name": <STRING>
}

<EMBED_COORDINATES>:
{
  "form": <STRING>,
  "section": <NUMBER>(9),
  "embedId": <STRING>(10),
  "motherIdentification": {
    "countryCode": <STRING>(11),
    "typeCode": <STRING>(12),
    "number": <STRING>
  },
  "pregnancy": <NUMBER>(13),
  "child": <NUMBER>,
  "ignoreLocks": <BOOLEAN>(14)
}

Comentarios :

(1) "id": El id de usuario debe ser un UUID en formato 8-4-4-4-12 que lo identifique de forma única. Si no se dispone de un id en este formato, ver sección «Sobre UUIDs» más adelante.
(2) "countryId": Código ISO-3166-1 alpha-2 del país (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
(3) "institutions": Son todas las instituciones a las que el usuario pertenece. Puede ser una lista vacía si el usuario tiene el permiso AccessAllInstitutions.
(4) "readableInstitutions": Son todas las instituciones que el usuario puede consultar.
Para los combos de selección de institución, cada control especifica si se toma la lista de posibles valores de "institution" o "readableInstitutions". (Si el usuario tiene el permiso AccessAllInstitutions y la lista «instituions» está vacía, se utilizará siembre «readableInstitutions».)
(5) "institution": Es la institución a la que está logueado el usuario. Se guarda junto con los datos del usuario en las trazas de auditoría. Si el usuario tiene el permiso AccessAllInstitutions , se puede omitir este elemento.
(6) "embedCoordinates": Si está presente, el SIP+ embebido quedará cautivo en el registro especificado, y en el formulario y sección especificadas. Si esta sección se omite, el SIP+ se comportará normalmente, comenzando por la pantalla de búsqueda de registros.
(7) "id": El id de rol debe ser un UUID en formato 8-4-4-4-12. Si no se dispone de un id en este formato, ver sección «Sobre UUIDs» más adelante.
(8) "permissions": La lista de posibles permisos se incluye más adelante.
Si el sistema externo no utiliza un mecanismo de agrupación de permisos en roles, simplemente pasar un rol ficticio y poner allí todos los permisos.
(9) "section": De omitirse la sección, se podrá navegar entre las secciones del formulario a las que se tenga acceso.
(10) "embedId": Identifiación única de la gesta en el sistema externo.
(11) "countryCode": ver (2).
(12) "typeCode": La lista de posibles tipos de documento se incluye más adelante.
(13) "pregnancy": El número de gesta se puede omitir. Si se omite, y aún no hay una gesta del SIP+ asociada a»embedId», se mostrará una pantalla previa de selección de gesta.
(14) "ignoreLocks": En caso de ser true, se ignorarán los bloqueos de campos de las firmas del registro. Se puede omitir, en cuyo caso tendrá valor false.

Sobre UUIDs

Los "id" de usuario y roles sirven para identificar estas entidades de forma única. Es importante que haya una correspondencia única entre el "id" y la entidad. En particular, el "id" de usuario se guarda en la traza de auditoría.

En caso de no disponer de identificadores únicos en formato UUID, es posible convertir otros formatos a UUID:

  • String → UUID : Es posible convertir cualquier string a un UUID de forma determinista utilizando la variante 3 o 5 de UUID. Estas variantes permiten combinar un UUID al azar (de tipo 1 o 4, el cual el sistema externo debería generar una única vez y guardar) con un string arbitrario para generar un nuevo UUID: https://en.wikipedia.org/wiki/Universally_unique_identifier#Versions_3_and_5_(namespace_name-based)
  • Entero → UUID : Es posible convertir un entero a un UUID simplemente agregando ceros a la izquierda hasta tener un número de 32 dígitos, y luego forzando el formato 8-4-4-4-12. Alternativamente, se puede convetir el entero a un string y aplicar el método anterior.

Como última alternativa, si no se dispone de un identificador único de ningún tipo, se puede pasar el valor 00000000-0000-0000-0000-000000000000. En particular, si el sistema externo no maneja el concepto de roles, se puede pasar un único rol con este "id". Se recomienda no utilizar este método para el "id" de usuario: es mejor utilizar el método descripto para convertir string a UUID, aplicándolo al valor que se pasa en "userName".

Configuración adicional

En la configuración del sistema embebido en el archivo sip-plus.conf es posible definir más de un sistema embebido. Para cada sistema embebidor, además de especificar getSession.url , es posible definir:

  • language: Determina el lenguaje en que se mostrará el SIP+. Los posibles valores son Spanish , English , Portuguese , French y Dutch. Si este parámetro se omite, por defecto tendrá valor Spanish.
  • getSession.method: Método HTTP a utilizar en la invocación a getSession.url. Puede ser GET o POST. En caso de usar POST, los parámetros se enviarán en el cuerpo de la invocación, en un objeto JSON con propiedades "embedSystem" y"embedToken". Si este parámetro se omite, por defecto tendrá valor GET.
  • getSession.username: Nombre de usuario a utilizar en caso de que la invocación a getSession.url requiera autenticación.
  • getSession.password: Contraseña a utilizar en caso de que la invocación a getSession.url requiera autenticación.
  • getSession.headers: Headers adicionales a agregar a la invocación a getSession.url. Es un objeto especificando cada header y su valor. Por ejemplo: getSession.headers {x-domain: "sip-plus"}.
  • shadowEdit: Si tiene valor true, entonces todas las modificaciones realizadas a los registros con el SIP+ en este modo embebido (para este embedId específico) se mantendrán en un registro «sombra» y no serán visibles cuando se utilice el SIP+ en modo normal (o en otros sistemas embebidos) hasta que el registro sea firmado. Nótese que los cambios realizados en SIP+ en modo normal (o en otros sistemas embebidos con shadowEdit = false), SÍ se verán cuando se utilice SIP+ en este sistema embebido. Al momento de firmar el registro, los cambios del registro «sombra» se impactarán sobre el registro principal. Si este parámetro se omite, por defecto tendrá valor false.
  • lockOnSign: Si tiene valor true, entonces cuando un registro sea firmado, los campos firmados pasarán a ser de sólo lectura. Si este parámetro se omite, por defecto tendrá valor false.
  • services.username: Si se especifica, las operaciones adicionales de modo cautivo requerirán de autenticación básica HTTP con este nombre de usuario. Si este parámetro se omite, o se omite services.password , no se protegerán con autenticación los servicios adicionales de modo cautivo.
  • services.password: Si se especifica, las operaciones adicionales en modo cautivo requerirán de autenticación básica HTTP con esta contraseña. Si este parámetro se omite, o se omite services.username , no se protegerán con autenticación los servicios adicionales de modo cautivo.

Ejemplo:

embed {
  demo {
    language = Spanish
    getSession {
      url = "http://sipplus.org:9000/embed-demo/session/$token"
      method = POST
    }
    shadowEdit = true
    lockOnSign = false
  }

  test {
    language = English
    getSession.url = "http://sipplus-english.org:9000/embed-demo/session/$token"
    shadowEdit = false
    lockOnSign = true
    services {
      username = "user"
      password = "password"
    }
  }
}

Lista de posibles permisos

  • AccessFormSection(formulario, sección)
  • EditForms
  • PrintForms
  • DeleteForms
  • CloseForms
  • VerifyForms
  • ShowStatistics
  • ShowReports
  • ManageUsers
  • ManageSessions
  • ShowDBStatistics
  • ImportDB
  • ExportDB
  • ExportLocalDBToFile
  • ImportLocalDBFromFile
  • ExportRemoteDBToFile
  • ImportRemoteDBFromFile
  • DestroyLocalDB
  • AccessAllInstitutions
  • NavigatePregnancies
  • ShowFormHistories

Lista de posibles tipos de documento

  • PSP : Pasaporte
  • CI : Cédula de Identidad (UY, BO, BR, CL, CR, EC, NI, PA, PY, VE)
  • CIE : Cédula de Identidad y Electoral (DO)
  • DNI : Documento Nacional de Identidad (AR, PE)
  • DUI : Documento Único de Identidad (SV)
  • DPI : Documento Personal de Identificación (GT)
  • TDI : Tarjeta de Identidad (HN)
  • CPF : Registro de Personas Físicas (BR)
  • RG : Registro General (BR)
  • CC : Cédula de Ciudadanía (CO)
  • CURP : Clave Única de Registro de Población (MX)
  • CRED : Credencial Cívica
  • DRV : Licencia de Conducir
  • EXP : Número de Expediente
  • OTR : Otro

Lista de posibles formularios

  • SIPNM (33 secciones): Historia Clínica Perinatal con Near Miss con secciones pequeñas.
  • SIPNM2 (9 secciones): Historia Clínica Perinatal con Near Miss con secciones grandes.
  • SIPNMArg (33 secciones): Historia Clínica Perinatal con Near Miss de Argentina con secciones pequeñas.
  • SIPNM2Arg (9 secciones): Historia Clínica Perinatal con Near Miss de Argentina con secciones grandes.
  • SIPNMUy (33 secciones): Historia Clínica Perinatal con Near Miss de Uruguay con secciones pequeñas.
  • SIPNM2Uy (9 secciones): Historia Clínica Perinatal con Near Miss de Uruguay con secciones grandes.
  • Aborto (15 secciones).
  • Neonatal (11 secciones).
  • Comunitario (6 secciones).
  • Zika (1 sección).
  • CNVUY (2 secciones): Certificado de Nacido Vivo de Uruguay.
  • SIPNMBol (10 secciones): Historia Clínica Perinatal con Near Miss de Bolivia.
  • SIPCar (6 secciones): Historia Clínica Perinatal del Caribe.
  • SIPStK (6 secciones): Historia Clínica Perinatal de St Kitts & Navis.
  • SIPBah (6 secciones): Historia Clínica Perinatal de Bahamas.
  • SIPTYT (6 secciones): Historia Clínica Perinatal de Trinidad & Tobago.
  • SIPMalf (2 secciones): Anomalías congénitas.
  • SIPNotas (1 sección): Anotaciones.

En general los formularios con secciones pequeñas se ajustan bien a dispositivos móviles, mientras lo que tienen secciones grandes pueden mostrar más información a la vez en clientes web.

Ejemplo

La instalación del SIP+ incluye un web service de ejemplo donde se puede ver una respuesta esperada válida para la resolución de un token en parámetros de sesión embebida.

Dicho ejemplo está accesible en

http://sipplus.org:9000/embed-demo/session/$token

Esta demo se comporta de tal forma de que simula resolver el token dependiendo de sus últimos 11 dígitos de la siguiente forma:

Si los últimos 11 dígitos son AAAAABBBXYZ , entonces:

  • Si Z == 0, SIP+ se ejecuta en modo embebido normal, con todas sus funcionalidades. Se utiliza un usuario ficticio, permiso para acceder a todas las instituciones y edición de todas las secciones de SIPNM2 (únicamente este formulario).
  • Si Z >= 1 y Z <= 9, SIP+ se ejeuta en modo cautivo (sólo se puede ver una sección de un formulario en un registro dado). En este caso, el formulario será SIPNM2 y además:
    • Z será el número de sección.
    • Si Y == 0 , no se especificará gesta y SIP+ preguntará cuál se debe utilizar.
    • Si Y >= 1 y Y <= 9 , será el número de gesta.
    • X será el número de recién nacido.
    • AAAAA será el número de cédula de identidad uruguaya de la madre.
    • BBB será el identificador externo de la gesta.

Importante: Cabe mencionar que toda esta lógica es utilizada solamente a modo de simulación por el web service de ejemplo. En una integración real, el sistema externo deberá generar un UUID único al azar como forma de token y guardar su propia base de datos el vínculo entre dicho token y los parámetros de sesión.

Ejemplos:

  • Con el token 00000000-0000-0000-0000-044762129211:
    • El número de cédula será 44762.
    • El identificador externo será 129.
    • La gesta será 2.
    • El recién nacido será 1.
    • Se mostrará el SIP+ cautivo con esos datos en la primera sección de SIPNM2.
  • Con el token 00000000-0000-0000-0000-000000000000:
    • SIP+ se ejecuta en modo normal (con usuario ficticio y permisos determinados como se explica arriba).
    • Al ser el último dígito 0 se ignoran el resto de los dígitos.

Nota: Es posible habilitar el modo embebido de demo si se descomenta la sección específica en sip-plus.conf. Esto puede ser útil para ver en funcionamiento el ciclo completo pero bajo ninguna circunstancia se debe poner en producción un sistema con esta sección descomentada, ya que sería una severa falla de seguridad.