Guía de integración de Interoperabilidad

Esta guía ayudará a los equipos de desarrollo a conocer cuál es el procedimiento de solicitud de integración de servicios de interoperabilidad; o de solicitud de nuevos servicios no existentes. Adicionalmente, se detalla la estructura y contenido de los manuales de integración de los servicios.

Esta guía va dirigida a los equipos de desarrollo de proyectos que, por sus necesidades de negocio, requieren de la integración con servicios del catálogo público de interoperabilidad o del catálogo completo.

Integración con servicios de interoperabilidad

El primer paso a realizar será revisar el catálogo y ver si está disponible el servicio que se necesita. Se pueden dar tres casuísticas:

• El servicio existe y responde a las necesidades. Se tiene que solicitar a la OTI el alta en dicho servicio para que compartan el manual de integración y las credenciales en caso de ser necesarias.
• El servicio existe y NO responde a las necesidades. Se tiene que poner en contacto con la OTI (oti.ada@juntadeandalucia.es) para que informe si existe la posibilidad de ampliar la funcionalidad de dicho servicio. Esto no solo depende de la OTI ya que el proveedor del servicio es quien realmente puede o no proporcionar la funcionalidad.
• No existe un servicio de interoperabilidad que responda a las necesidades. Se tiene que poner en contacto con la OTI (oti.ada@juntadeandalucia.es) y explicarles con el mayor detalle posible con quién necesita integrarse, qué tipos de operativas se necesitan y, si ya se tiene información para realizar dicha integración, facilitarla para que puedan ponerse en contacto con el proveedor.

Respecto a las dos últimas posibilidades, no significa que la integración se vaya a llevar a cabo o que exista esa funcionalidad adicional dentro del servicio que ya existe. Una vez recibido el correo electrónico, la OT-I tendrá que evaluar la necesidad, si necesita aclaraciones, se pondrá en contacto con el remitente y, hablará con el proveedor de servicios para ver si es posible llevar a cabo la integración.

Si finalmente se aprueba la creación o modificación del servicio, una vez desarrollado, se añadirá al catálogo correspondiente. Una vez aquí, podrá continuar con la sección Alta de una integración como consumidor.

Prerrequisitos

Antes de comenzar a ver los pasos necesarios para poder integrarse con un servicio de interoperabilidad, es bueno conocer algunas normativas y políticas que se han aplicado en la construcción de estos servicios. De esta forma, podrá resultar más fácil su entendimiento y resolverá algunas dudas que puedan surgir, tanto durante la lectura de esta guía como a la hora de desarrollar las integraciones con los servicios:

• Normas de referencia 
  • Arquitectura de referencia de interoperabilidad y pila tecnológica
• Políticas 
  • De seguridad: describe las políticas de seguridad que se aplican en el uso y en la generación de los servicios de interoperabilidad.
  • De gestión de errores: define los comportamientos estándar ante errores durante la ejecución de los servicios de interoperabilidad.
  • Ciclo de vida de servicios y gestión de obsoletos: define la política de gestión de obsoletos de la OT-I en el Catálogo de Servicios. Muy útil de cara a saber y poder adaptarse a las nuevas versiones de los servicios así como para saber qué ocurre si no nos actualizamos a las nuevas versiones.
• Catálogo de activos 
  • El catálogo público de activos de interoperabilidad está publicado en el portal.
  • Existe también un catálogo completo de activos, que incluye también aquellos con visibilidad restringida a la Junta de Andalucía y solo puede ser consultado iniciando sesión en el portal con un usuario del LDAP.
  • Antes de seguir con la guía, es recomendable revisarlos para saber si hay que pasar por la sección de Solicitud de desarrollo de nueva integración o ir directamente a Alta de una integración como consumidor. 
• Soporte 
  • La principal vía de comunicación de los equipos de desarrollo y responsables de los sistemas de información con la OT-I es la herramienta NAOS, siendo necesario disponer de cuenta de usuario en el LDAP de la Junta de Andalucía.

Herramientas

En esta sección, se van a presentar dos herramientas de uso muy común entre los desarrolladores que sirven para realizar pruebas con servicios RESTful y servicios SOAP, ya que, en la gran mayoría de los casos, los servicios con los que integrarse serán APIs REST o Servicios Web SOAP.

Actualmente, ambas permiten realizar pruebas tanto con servicios REST como SOAP, pero cada una de ellas nació y sigue estando más dirigida a un tipo concreto:

• Postman: permite crear colecciones de pruebas de APIs agrupadas y bien organizadas y permite realizar configuraciones por entornos, de modo que una simple selección en un desplegable permite cambiar de host, credenciales, configuraciones varias, etc.

  Además, algo muy interesante, es que permite compartir colecciones con otros usuarios sin necesidad de exportar e importar, haciendo que cualquier cambio que se haga, sea visible por el resto de los usuarios compartidos.

• SoapUI: principalmente dirigida a WS SOAP, es capaz de crear un proyecto completo de pruebas a partir del fichero WSDL de un Servicio Web, generando estructuras de las peticiones para todas las operaciones existentes.

  Algo a destacar es la facilidad para mockear servicios ya que es capaz de levantar un servidor en el que se pueden añadir, de forma manual, respuestas de todas las operaciones.

  La propia aplicación genera la estructura tanto de las peticiones como de las respuestas, indicando obligatoriedades de campos y otras características como cardinalidades, para que solo haya que indicar el valor que tomará el campo.

  También permite compartir los proyectos de testing pero lo hace a través de un plugin subiendo a un repositorio Git el proyecto.

Explicadas las herramientas, sabiendo que ambas permiten probar tanto REST como SOAP y que se recomienda seguir los pasos que se indiquen en la sección de introducción de los manuales de integración para realizar las pruebas con algunas de estas herramientas, se deja en manos del desarrollador el usar una u otra herramienta, según se sienta más cómodo y que le pueda resultar más sencillo validar la integración con el servicio, así como generar una colección de pruebas más amplia para validar los distintos casos de uso.

Alta de una integración como consumidor

En esta sección de la guía se va a explicar cómo solicitar el alta para el consumo de un servicio de interoperabilidad existente en los catálogos de activos interoperables de la Junta de Andalucía.

Hay que recordar que una integración habilita la comunicación entre dos o más sistemas haciendo uso de los activos de interoperabilidad existentes en el catálogo público o en el completo, de acuerdo con las interacciones que se definieran cuando se desarrolló.

En el portal de desarrollo, la OT-I proporciona una guía rápida con las posibilidades de integración mediante activos de interoperabilidad. En dicha guía rápida, se pone a disposición una lista de servicios prestados para guiar y facilitar el proceso de integración. Aquí el foco lo tiene el servicio INT01 Solicitar o modificar una integración. 

Las posibles opciones disponibles en este servicio son: alta, actualización, baja y promoción de entorno (tras haber realizado la integración en entornos inferiores). En este caso, la opción a usar es NUEVA ALTA.

Para realizar esta solicitud, será necesario rellenar varios documentos, en función del tipo de servicio. Para facilitar esta labor, se proporciona el manual de solicitud de integración, que proporciona ayuda para rellenar los formularios necesarios para la gestión de la solicitud de integración con los servicios de interoperabilidad.

Como cabe esperar, antes de solicitar la promoción de entorno (para poder acceder al entorno productivo), es necesario solicitar el alta en el entorno no productivo.

La solicitud se realizará generando un tique en NAOS con las opciones indicadas en la siguiente captura, adjuntando los documentos necesarios, cumplimentados y firmados. En elemento hay que indicar Solicitar o modificar una integración  (consumidor) - Nueva alta.

Los documentos que hay que rellenar son los siguientes:

• Formulario de solicitud de integración: formulario para la solicitud de integraciones con activos de los catálogos de activos de interoperabilidad de la Junta de Andalucía.

  Principalmente se indica con qué servicios se quiere integrar, el motivo, una estimación de la carga de trabajo, el entorno y qué mecanismo de interoperabilidad se solicita (servicio web o descarga de datos)

  Este documento corresponde a un único sistema de información que va a ser consumidor de los servicios que el catálogo de activos de interoperabilidad ofrece. No se aceptan solicitudes con más de un Sistema Consumidor de servicios.

• Formulario anexo para solicitud de Servicios Web: este es el formulario que hay que rellenar para el caso en el que el mecanismo de interoperabilidad incluya el uso de Servicios Web.

  En él se indicarán cada uno de los servicios web que se van a solicitar su consumo, indicando el código y nombre del servicio y el volumen y frecuencia de consumo previstos.

• Formulario anexo para la solicitud de descarga de datos: este es el formulario que hay que rellenar para el caso en el que el mecanismo de interoperabilidad incluya la descarga de datos.

  En él se indicará el código del activo y su nombre, la frecuencia de consumo prevista y el uso que se va a hacer de los datos solicitados.

Los documentos que se hayan cumplimentado deben adjuntarse al tique firmados según se indica en el apartado criterio de firma del manual de solicitud de integración.

Manual de integración

En esta sección se explicarán las distintas partes de las que consta un manual de integración de los que se proporcionan tras solicitar el alta de una integración como consumidores.

Introducción

Este apartado introductorio consta de dos subapartados: propósito y condiciones para integrarse.

El subapartado de propósito hace alusión al objetivo propio del documento, es decir, servir de manual para la integración del activo.

El subapartado de condiciones para integrarse se desglosa en tres tipos de condiciones: sobre la comunicación, sobre el funcionamiento general y sobre la seguridad.

Sobre la comunicación

Aquí se indica que la comunicación con el servicio solo será posible mediante https, en TLS 1.2 y TLS 1.3.

Sobre el funcionamiento general

Aquí se indica si el servicio es REST o SOAP y cómo se realizará la conexión con el mismo.

Dependiendo del tipo de servicio, indicará cómo montar un proyecto de pruebas del tipo en cuestión, en la herramienta SoapUI.

Sobre la seguridad

Aquí se indicará la configuración que hay que realizar para llevar a cabo del tipo de seguridad configurada en el servicio. Debe coincidir con el apartado seguridad de la tabla del apartado Activo.

Puede contener una guía para llevar a cabo dicha configuración para realizar pruebas, cabeceras que sean necesario incluir en la petición, etc.

Activo

Este apartado contiene toda la información del activo de interoperabilidad.

Operaciones

En este apartado se definen cada una de las operaciones del servicio. Dependiendo de si es un servicio REST o SOAP, habrá campos que apliquen y campos que no.

Cada subapartado corresponde con el nombre de una operación y contiene su tabla explicativa.

SOAP

REST

Tipos de datos

En este apartado se describen los tipos de datos complejos que no son comunes al sistema sino específicos del servicio que se está presentando.

Cada subapartado será un tipo de datos. Si ese tipo de dato incluye otros tipos de datos complejos, se añadirá otro nivel de indización dentro del subapartado.

X.1.1 AltaComunicacionRequest

X.1.1.1 Adjuntos

Ejemplos

En este apartado se incluyen ejemplos de mensajes de entrada y de salida de todas las funcionalidades de cada una de las operaciones. Cada subtítulo dentro de este apartado corresponderá a cada una de las operaciones.

SOAP

X.1 AltaComunicacion

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> 
<soapenv:Header><wsse:Security> …</wsse:Security></soapenv:Header> 
<soapenv:Body><sch:AltaComunicacionRequest> …..</soapenv:Body>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
  <ns2:Response xmlns:ns2="http://ndalucia....”>
    <ns2:resultado>0</ns2:resultado>
...

REST

X.1 continents

https://host_url/nombre_api/continents

https://host_url/nombre_api/continents?type=codelist

{
 "data": [{
  "id": 1,
  "name": "Europa"
}, 
……
]
}

{
 "codes": [{
  "code": "continente_estadistico"
 }]
}

Tablas maestras

En este apartado se muestra la información de las tablas maestras propias del servicio que se han utilizado para la codificación de la información que lo requiera. 

Gestión de errores

En este apartado se definen los errores relativos a mensajes que no hayan podido ser procesados debido a un error de integración. Se indicará el código que devuelve, una descripción del significado del error y una recomendación para evitarlo o a qué operaciones afecta. 

Anexos

En este apartado se profundizará cualquier aspecto que se considere importante sobre la integración del sistema (librerías necesarias, APIs, …) 

Glosario

En este apartado se incluye la definición de términos que se hayan usado en el manual y sea necesario conocer para la comprensión del manual.

 Referencias

En este apartado se incluyen referencias a otras documentaciones/herramientas/webs utilizadas para realizar el manual de integración. 

Actualización de una integración como consumidor

En esta sección de la guía se explica qué hay que hacer para solicitar la actualización en el uso de una integración que ya se está consumiendo.

Al igual que para solicitar el alta en el uso de un servicio de interoperabilidad, para realizar cualquier tipo de cambio en su uso, se tendrá que hacer uso del servicio INT01 Solicitar o modificar una integración, que la OT-I proporciona en el portal del desarrollador. En este caso, la opción a usar será ACTUALIZACIÓN.

Para realizar esta solicitud, aunque no es imprescindible, se recomienda recuperar el documento Formulario de solicitud de integración que se adjuntó al tique NAOS en el momento de la solicitud de alta. De nuevo, será necesario usar el manual de solicitud de integración, que proporciona ayuda para rellenar los formularios necesarios para la actualización en el uso de una integración con los servicios de interoperabilidad.

La solicitud se realizará generando un tique en NAOS con las opciones indicadas en la siguiente captura, adjuntando los documentos necesarios, cumplimentados y firmados. En elemento hay que indicar Solicitar o modificar una integración  (consumidor) - Actualización.

Al ser una actualización, en función del mecanismo de interoperabilidad (servicios web o descarga de datos), habrá que rellenar el formulario correspondiente con las nuevas solicitudes de uso de la integración:

• Formulario anexo para solicitud de Servicios Web: este es el formulario que hay que rellenar para el caso en el que el mecanismo de interoperabilidad incluya el uso de Servicios Web.

  En él se indicarán cada uno de los nuevos servicios web que se van a solicitar su consumo, indicando el código y nombre del servicio y el volumen y frecuencia de consumo previstos.

• Formulario anexo para la solicitud de descarga de datos: este es el formulario que hay que rellenar para el caso en el que el mecanismo de interoperabilidad incluya la descarga de datos.

  En él se indicará el código del activo y su nombre, la frecuencia de consumo prevista y el uso que se va a hacer de los nuevos datos solicitados

El documento que se haya cumplimentado, junto con el formulario de solicitud de integración, deben adjuntarse al tique firmados según se indica en el apartado criterio de firma del manual de solicitud de integración.

Promoción de entorno de uso de una integración

En esta sección de la guía se explica qué hay que hacer para solicitar la promoción de entorno de uso de una integración que ya se está consumiendo.

Al igual que para solicitar el alta o la actualización, se hace uso del servicio INT01 Solicitar o modificar una integración, que la OT-I proporciona en el portal del desarrollador. En este caso, la opción a usar será PROMOCIÓN DE ENTORNO.

De nuevo, se usará el manual de solicitud de integración, que proporciona ayuda para rellenar los formularios necesarios para la actualización en el uso de una integración con los servicios de interoperabilidad.

La solicitud se realizará generando un tique en NAOS con las opciones indicadas en la siguiente captura, adjuntando los documentos necesarios, cumplimentados y firmados. En elemento hay que indicar Solicitar o modificar una integración  (consumidor) - Promoción de entorno.

Los documentos que hay que incluir serán los mismos que se han creado en la solicitud de alta, cambiando el entorno y, si se ha solicitado alguna actualización, se actualizará el Formulario anexo para solicitud de Servicios Web o el Formulario anexo para la solicitud de descarga de datos para que incluya todos los servicios que se han ido solicitando.

La firma realizada en la solicitud es distinta a la que se realiza para la promoción al entorno productivo. Esto se indica en el apartado criterio de firma del manual de solicitud de integración.

Baja del uso de una integración como consumidor

En esta sección de la guía se explica qué hay que hacer para solicitar la baja en el uso de una integración que ya se está consumiendo.

Al igual que para solicitar el alta o la actualización, hay que hacer uso del servicio INT01 Solicitar o modificar una integración, que la OT-I proporciona en el portal del desarrollador. En este caso, la opción a usar será BAJA.

Para realizar esta solicitud, aunque no es imprescindible, se recomienda recuperar el documento Formulario de solicitud de integración que se adjuntó al tique NAOS en el momento de la solicitud de alta y adjuntarlo en esta solicitud. Y, al igual que en la solicitud de alta, se usará el manual de solicitud de integración, que proporciona ayuda para rellenar los formularios necesarios para la actualización en el uso de una integración con los servicios de interoperabilidad.

La solicitud se realizará generando un tique en NAOS con las opciones indicadas en la siguiente captura, adjuntando los documentos necesarios, cumplimentados y firmados. En elemento hay que indicar Solicitar o modificar una integración  (consumidor) - Baja.

Servicios de soporte

Además de las distintas solicitudes de uso como consumidor de las integraciones y del manual proporcionado para llevar a cabo el desarrollo de la integración, se ponen a disposición del equipo de proyecto algunos servicios de soporte de cara al consumo de integraciones. 

Al igual que los servicios de solicitud anteriores, los siguientes servicios de soporte, también se gestionarán mediante tiques en NAOS:

Apoyo sobre el consumo de activos interoperables

En el caso en el que se necesite cualquier tipo de apoyo relacionado con el consumo de servicios interoperables, será necesario abrir un tique con la siguiente información:

• Elemento: Solicitar asesoramiento técnico - Apoyo sobre el consumo de activos interoperables

Notificar incidencias

En el caso de que se necesite notificar una incidencia relacionada con el consumo de servicios interoperables, será necesario abrir un tique con la siguiente información:

• Elemento: (sin determinar)
• Prioridad: se indicará en el cuerpo de la propia petición.

Presentar una queja o sugerencia

Para presentar una queja o una sugerencia relacionada con los servicios de interoperabilidad de la ADA, hay que enviar un correo a la dirección interoperabilidad.ada@juntadeandalucia.es.

Referencias

• Portal del desarrollador – Oficina Técnica de Interoperabilidad
• Catálogo público de activos de interoperabilidad
• Catálogo privado completo de activos de interoperabilidad
• NAOS
• SoapUI
• Postman