/
Communication Manager

Communication Manager

Owned by Francisco Javier López Acevedo
20/03/25
7 min read

Available since version 7.0.0

Introduction

A communications management module has been implemented in Onesait Platform that will allow communications to be defined and subsequently send notifications of various types linked to them.

thumbnail_Gráfico_pegado-1-20250307-112846.png

This module allows the definition of communication types, as well as the sending of different types of notifications and subscriptions to them: notifications between services, e-mails, chats and PUSH. Notifications can be scheduled to be sent at a specific time or even repeated over time, using cron expressions.

The module is built on Spring Boot making use of Quartz Scheduler for scheduling the sending of notifications, and Azure Notification Hub for sending PUSH notifications to mobile devices.

Types of notifications

The different types of notifications available include:

  • Back End Notifications between Services: The purpose of this type of notification is to send messages between different modules or services of the system. These services will be responsible for subscribing to ‘topics’ and will receive the notifications linked to these topics. A diagram of this type of notifications is shown below.

image-20250307-114733.png

  • Device Type Notifications: These notifications work in the same way as Backend type notifications but are designed so that, once the notification is received, a second native notification is triggered to iOS and Android devices. A diagram of this type of notification is shown below:

image-20250307-115048.png

  • Email Type Notifications: These notifications make use of an SMTP mail server to send emails to recipients.

  • Chat Type Notifications: This type of notifications is designed for the use case of chat between two parties, with a source and a destination. A diagram of this type of notification is shown below:

image-20250307-115101.png

  • Native Notifications to Devices (PUSH): PUSH notifications that will be sent through the Azure Notification Hub to native iOS and Android devices.

Types of subscriptions

For subscriptions, two types are distinguished:

  • Subscriptions from iOS and Android Devices: This type of subscriptions will be made by registering the device and informing of the ‘tags’ to which they are going to be subscribed. It only applies to native device type notifications.

  • Subscriptions to the remaining of Notifications: These subscriptions will apply to the rest of notifications, you will have to inform the subscriber identifier (e.g. Service21) and the ‘topics’ to which you are going to subscribe.

How to Manage Communications

Registering a Type of Communication

To send notifications, you must first define the type of communication. This will be done through an endpoint of the REST API exposed by the communication manager, which will have the following format:

image-20250307-115838.png

In a communication, the type (name) of the communication, the type of notifications that will be associated with this communication and the fields that these notifications will contain are defined, so that subscribers can know in advance the fields to which they can subscribe.

These fields, together with their value, will be called ‘topics’ in the notifications in this notification system.

Sending Notifications

Once the communication to be used to send certain types of communications has been defined, these notifications can be sent.

To send BACKEND, DEVICE, MAIL, CHAT type Notifications, the same endpoint will be used, while to send native notifications to devices, a different endpoint and payload will be used.

General Notifications

These notifications, which can be of the following types: BACKEND, DEVICE, MAIL, CHAT, can be sent in JSON format, or in multipart format if attachments are to be sent, such as MAIL or POST.

A couple of examples of a DEVICE type are shown below:

image-20250307-120503.png
image-20250307-120512.png

Regarding the JSON object, it has the following general fields:

  • Title: Title of the notification.

  • Message: Body of the notification.

  • Type: BACKEND, DEVICE, MAIL, CHAT.

  • Origin: Unique identifier of the service sending the notification.

  • Communication Type: Name of the previously registered communication.

  • Cron expression: CRON expression in case you want to schedule the sending of the notification.

  • Categories: Categories associated to the notification.

For BACKEND and DEVICE types, the following specific field is available:

  • Target Subscription Fields: key-value map containing the fields and values for which this notification is intended. Regular expressions are allowed in the values in order to reach several ‘topics’ in mass mailings or other use cases.

image-20250307-121212.png

In the case of the MAIL type, it would have the following specific fields:

  • To: To whom the mail is addressed, it admits a list separated by ‘;’.

  • Cc: with copy, admits list separated by ‘;’.

  • Html: Boolean to indicate if the message has HTML content.

  • Attachments: Attached files in the mail, it forces to use multipart format in the request.

image-20250307-121254.png

For the CHAT type, there are two specific fields:

  • Chat ID: This is only necessary if it is to continue a conversation. If a new conversation is opened, it is auto-generated.

  • Destination: To which service or destination it is addressed.

image-20250307-121532.png

PUSH notifications to devices

For this type of notifications another endpoint shall be used, and requests shall always be made in JSON format (no multipart).

image-20250307-121634.png

In this case, the JSON fields shall be the following:

  • Message: Body of the notification.

  • Title: Title of the notification.

  • Extra Template Props: Key-Value map to add extra properties if a template has been registered in the device that is not the default one.

  • Tag Expression: logical expression of tags to address the notification, such as: barcelona && deportes It takes precedence over the tags attribute.

  • Tags: tags to which the notification is addressed, such as: ["minsait", "madrid"].

  • Categories: categories associated with this notification.

Subscribe to Receive Notifications

Since there are two forms of notifications, there are also two forms of subscription.

General notification subscriptions

Subscriptions for BACKEND, DEVICE, MAIL, CHAT type notifications will use the endpoint that will accept the following format:

image-20250307-122509.png

The body of the call will be a JSON with the following fields:

  • Notification Endpoint: REST callback endpoint to receive notifications.

  • Subscriber ID: unique identifier of the subscribing service.

  • Subscription Fields: Key-Value map indicating the field name and value. The value can be a wildcard * to subscribe to any value or even a regular expression, such as: ‘chatId’: ‘1|2|3’.

The subscriber is responsible for subscribing to all the fields of interest, even if it is with a wildcard as value, because if for example a notification comes in with the fields ‘company’ and “company_group” and the subscriber wants to receive that notification, but has only indicated in the subscription the field company: ‘*’, he/she will not receive the notification.

Below are some examples of JSON files:

image-20250310-085222.png
image-20250310-085058.png
image-20250310-085355.png

PUSH Notification Subscriptions

Registration shall be done from the native iOS and Android applications from the devices. The same endpoint will be used both for first time registration and for updating the tags to which is subscribed.

image-20250307-131751.png

In this case, the JSON fields will be as follows:

  • Registration ID: Registration ID in case of a registration update, for this reason the mobile application shall store the registration ID in some way to avoid continuous registration of the same device.

  • Device Token ID: Token programmatically extracted from the device. The iOS and Android APIs can retrieve it. If help is needed to retrieve it, contact a C1 manager.

  • Template: basic templates are used by default for Azure Notification Hub. If you would like to customise a template, please indicate it here. The format of the templates can be found at Azure Notification Hub documentation and the default templates used are the following:

    • Platform: IOS, ANDROID.

    • Tags: tags that the device subscribes to.

image-20250307-132001.png
image-20250307-132023.png

An example of such a subscription would be:

image-20250307-132148.png

Additional operations

In addition to the operation of notifications and subscriptions, there are other operations such as confirmation of receipt of a notification, consultation of notification history, etc.

For more details, consult the Open API descriptor of the Communication Manager.

Open API specification and Java library of DTOs

The Communication Manager has an Open API descriptor to be able to query the endpoints and the data exchange model (DTOs).

The Open API descriptor can be found at the following URL:

https://<instance_url>/communication-manager/swagger-ui/index.html

In addition, a library is available for Maven/Java projects that contains the necessary DTOs for requests and responses to the communication manager, so if a Java application is used for integration, its use is recommended.

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

Related content