Gestor de comunicaciones
- Francisco Javier López Acevedo
- doc_enterprise
- Onesait Platform
Disponible desde la versión 7.0.0
Introducción
Se ha implementado en Onesait Platform un módulo para la gestión de comunicaciones que va a permitir la definición de comunicaciones para posteriormente enviar notificaciones de diversos tipos vinculadas a las mismas.
Este módulo permite definir tipologías de comunicaciones, así como el envío de diferentes tipos de notificaciones y suscripción a las mismas: notificaciones entre servicios, correos electrónicos, chats y PUSH. Las notificaciones pueden ser programadas para ser enviadas en un momento concreto o incluso repetidas en el tiempo, mediante expresiones cron.
El módulo está construido sobre Spring Boot haciendo uso de Quartz Scheduler para la programación de envío de notificaciones, y de Azure Notification Hub para el envío de notificaciones PUSH a dispositivos móviles.
Tipos de notificaciones
Entre los distintos tipos de notificaciones disponibles, se encuentran:
Notificaciones back end entre servicios: el objetivo de este tipo de notificaciones es enviar mensajes entre diferentes módulos o servicios del sistema. Dichos servicios serán encargados de suscribirse a unos «tópicos» y recibirán las notificaciones vinculadas a dichos tópicos. A continuación, se representa un esquema de este tipo de notificaciones.
Notificaciones de tipo device: estas notificaciones funcionan igual que las de tipo Backend pero están destinadas a que, una vez recibida la notificación, se desencadene una segunda notificación nativa a dispositivos iOS y Android. A continuación, se representa un esquema de este tipo de notificaciones:
Notificaciones de tipo correo electrónico: estas notificaciones hacen uso de un servidor de correo SMTP para enviar correos a destinatarios.
Notificaciones de tipo chat: este tipo de notificaciones está pensando para el caso de uso de chat entre dos partes, con un origen y un destino. A continuación, se representa un esquema de este tipo de notificaciones:
Notificaciones nativas a dispositivos (PUSH): notificaciones PUSH que serán enviadas a través del Azure Notification Hub a dispositivos nativos iOS y Android.
Tipos de suscripciones
Para las suscripciones, se distinguen dos tipos:
Suscripciones de dispositivos iOS y Android: este tipo de suscripciones se harán registrando el dispositivo e informando de los «tags» a los que se van a suscribir. Solo aplica a notificaciones de tipo nativas a dispositivos.
Suscripciones al resto de notificaciones: estas suscripciones aplicarán al resto de tipo de notificaciones, se tendrá que informar del identificador de suscriptor (p.e. Servicio21) y de los «tópicos» a los que se va a suscribir.
Cómo gestionar las comunicaciones
Registro de un tipo de comunicación
Para enviar notificaciones, en primer lugar se deberá definir el tipo de la comunicación. Esto se hará a través de un endpoint de la API REST expuesta por el gestor de comunicaciones, el cual que tendrá el siguiente formato:
En una comunicación se define el tipo (nombre) de la comunicación, la tipología de notificaciones que van a asociarse a esta comunicación y los campos que van a llevar estas notificaciones, de tal forma que los suscriptores puedan conocer de antemano los campos a los que pueden suscribirse.
Estos campos, en conjunto con su valor, serán los denominados en las notificaciones como «tópicos» en este sistema de notificaciones.
Envío de notificaciones
Una vez definida la comunicación que se va a utilizar para enviar cierto tipo de comunicaciones, se podrá enviar dichas notificaciones.
Para enviar notificaciones de tipo BACKEND, DEVICE, MAIL, CHAT, se utilizará un mismo endpoint,
mientras que, para enviar notificaciones nativas a dispositivos, se utilizará un endpoint y payload
diferentes.
Notificaciones generales
Estas notificaciones, que podrán ser de tipo: BACKEND, DEVICE, MAIL, CHAT, podrán enviarse en formato JSON, o en formato multipart si se van a enviar archivos adjuntos como es el caso de tipo MAIL oPOST.
A continuación se muestra un par de ejemplos de un tipo DEVICE:
Respecto al objeto JSON, éste cuenta con los siguientes campos generales:
Title: título de la notificación.
Message: cuerpo de la notificación.
Type:
BACKEND,DEVICE,MAIL,CHAT.Origin: Identificador único del servicio que envía la notificación.
Communication Type: nombre de la comunicación previamente dada de alta.
Cron expression: expresión CRON en caso de que se quiera programar el envío de la
notificación.Categories: categorías asociadas a la notificación.
Para los tipos de BACKEND y DEVICE se cuenta con el siguiente campo específico:
Target subscription fields: mapa de clave-valor que contiene los campos y valores a los que va
destinada esta notificación. En los valores se admiten expresiones regulares para poder
alcanzar a varios «tópicos» en envíos masivos u otros casos de uso.
En caso del tipo MAIL, contaría con los siguientes campos específicos:
To: a quien va dirigido el correo, admite lista separada por «;».
Cc: con copia, admite lista separada por «;».
Html: booleano para indicar si el message tiene contenido HTML.
Adjuntos: archivos adjuntos en el correo, obliga a usar formato multipart en la petición.
Para el tipo CHAT, cuenta con dos campos específicos:
Chat ID: solo será necesario si es para continuar una conversación. Si se abre una nueva conversación, se autogenera.
Destination: a que servicio o destino va dirigido.
Notificaciones PUSH a dispositivos
Para este tipo de notificaciones se utilizará otro endpoint, y las peticiones se harán siempre en formato
JSON (no multipart).
En este caso, los campos del JSON serán los siguientes:
Message: cuerpo de la notificación.
Title: título de la notificación.
Extra template props: mapa clave-valor para añadir propiedades extra si se ha registrado una
plantilla en el dispositivo que no es la de por defecto.Tag expression: expresión lógica de tags para dirigir la notificación, como por ejemplo:
barcelona && deportes. Tiene prioridad sobre el atributo tags.Tags: etiquetas a las que va dirigida la notificación, como por ejemplo:
["minsait”,”madrid”].Categories: categorías asociadas a esta notificación.
Suscribirse para recibir notificaciones
Puesto que hay dos formas de notificaciones, también se cuenta con dos formas de suscripción.
Suscripciones a notificaciones generales
En las suscripciones para notificaciones de tipo BACKEND, DEVICE, MAIL, CHAT se hará uso del endpoint que aceptará el siguiente formato:
El cuerpo de la llamada será un JSON con los siguientes campos:
Notification endpoint: endpoint de callback REST para recibir las notificaciones.
Subscriber ID: identificador único del servicio que se suscribe.
Subscription fields: mapa de clave-valor indicando el nombre del campo y el valor. El valor
podrá ser un wildcard*para suscribirse a cualquier valor o incluso una expresión regular,
como por ejemplo:“chatId”: “1|2|3”.
El suscriptor es responsable de suscribirse a los todos los campos de interés, aunque sea con un wildcard como valor, ya que si por ejemplo entra una notificación con los campos «empresa» y
«grupo_empresa» y el suscriptor quiere recibir esa notificación, pero solo ha indicado en la suscripción el campo empresa: “*”, no recibirá la notificación.
A continuación mostramos algunos ejemplos de los archivos JSON:
Suscripciones a notificaciones PUSH
El registro se hará desde las aplicaciones nativas iOS y Android desde los dispositivos. Se utilizará el
mismo endpoint tanto para el registro por primera vez, como para la actualización de los tags a los que
está suscrito.
En este caso, los campos del JSON serán los siguientes:
Registration ID: ID de registro en caso de que sea una actualización del registro, por esta razón
la aplicación móvil deberá almacenar el ID de registro de alguna forma y así evitar el registro
continuo del mismo dispositivo.Device Token ID: token extraído programáticamente del dispositivo. Las APIs de iOS y Android
permiten obtenerlo. Si se necesitase ayuda para recuperarlo, contactar con algún responsable
del C1.Template: por defecto se utilizan plantillas básicas para Azure Notificación Hub. Si se quisiera
personalizar una plantilla, se indicaría aquí. El formato de las plantillas se puede encontrar en la
documentación de Azure Notification Hub y las plantillas por defecto que se utilizan son las
siguientes:Platform:
IOS,ANDROID.Tags: etiquetas a las que se subscribe el dispositivo
Un ejemplo de este tipo de suscripción sería:
Operaciones adicionales
Además de la operativa de notificaciones y suscripciones, existen otras operaciones como la de confirmación de recepción de una notificación, consulta de histórico de notificaciones, etc.
Para más detalles, consultar el descriptor Open API del Gestor de Comunicaciones.
Especificación Open API y librería Java de DTOs
El gestor de comunicaciones cuenta con un descriptor Open API para poder consultar los endpoints y el modelo de intercambio de datos (DTOs).
El descriptor Open API se puede encontrar en la siguiente URL:
https://<instance_url>/communication-manager/swagger-ui/index.htmlAdemás, se dispone de una librería para proyectos Maven/Java que contiene los DTOs necesarios para las peticiones y respuestas al gestor de comunicaciones, por lo que si se usa una aplicación Java para la integración se recomienda su uso.
<dependency>
<groupId>com.minsait.onesait</groupId>
<artifactId>notification-dtos</artifactId>
<version>1.0.0</version>
</dependency>
<repositories>
<repository>
<id>osp releases</id>
<url>https://nexus.onesaitplatform.com/nexus/repository/releases/</url>
</repository>
</repositories>