Notifications¶

Concept¶

A notification is an information sent to a user via standard protocol like EMAIL or SMS.

Dedicated glossary¶

Term	Definition
Provider	The connection to use to send notification (like an instance of aspSMS or a connection to GMAIL)
Trigger	The notification trigger. The value when an output is the source of the notification or some free data when it is started by a script (lua or js) or a front-end action.
Transmission vector	Each message can be transmitted with one or more provider. Vectors can be used in sequentially or in parallel.

Capabilities¶

Capability	Support aspSMS	Support EMAIL	Comment
SMTP protocol			See SMTP protocol
SSL/TLS
Authentication by OAuth2 (ROPC flow)			Only with Resource Owner Password Credentials Flow (ROPC flow) Authentication
Outgoing notification			See documentation
Incoming notification			Not available yet
Contact from configuration (static)			See documentation
Contacts from collection			See documentation
Contacts from keycloak			See documentation
Provider connection monitoring			See Provider connection monitoring
Using formatter and values			See Notification generation

Examples¶

Security - user certificates¶

Including certificates for SSL/TLS can be done two different ways :

Using javatruststore option (enable the option in the module configuration file see module.coms)
Using the default method to include external certificates to modules see External resources security

Warning

Using jvmtruststore is a convenient way to use certificate but be aware that the truststore is only updated with new release of OnSphere. And some revocation and/or certificate update may not be present.

Provider aspSMS¶

Requirements¶

To access the aspSMS provider the port TCP/443 must be open to the URL https://json.aspsms.com/

SMTP protocol¶

Requirements¶

Default port

Service	Default port
OAuth2 Azure AD host using Resource Owner Password Credentials Flow	tcp/443 & tcp/587
TLS host	tcp/587
SSL host	tcp/465

Authentication¶

The SMTP provider supports user/password authentication and oAuth2 with ROPC flow.

Note

This feature was only tested with Azure AD.

Examples

Sending notification¶

Concept

A notification is sent through a transmission vector. This transmission vector describes witch providers are used knowing that each can be used in parallel or sequentially.

Usage

A notification is triggered by an output.coms.

Backup provider¶

Using a backup provider provides redundancy in case of failure. This is done inside the output.coms

type	object
properties
providerId	The ID of the provider to use.
	type	string
retry	The number of retry before using the backup as fallback. Be warned that notification are runtime so in case of reboot of themodule notification are lost.
	type	integer
	default	3
retryDelay	The delay between each retry.
	default	value	10
		unit	SECONDS
	#/definitions/DurationConfigurationEntity
backup	When a notification fails on the first provider, this provider is chosen for sending the notification. To prevent an infinite loop, the system ensures that if a provider has already been utilized to send this particular notification, it will not be selected again
	#/definitions/SenderConfiguration
additionalProperties	False

Notification workflow¶

The TargetConfiguration object allows using a list of providers, which can be used with the backup capability to create a flow (sequential or parallel) of notifications, each provider will be used in parallel.

Warning

If a provider is present multiple times on the sender, it will be used only once. For example with the following sender and backup (The row are executed in parallel):

provider 1 -> provider 3 -> provider 2 -> provider 4
provider 2 -> provider 5

When a notification is triggered, the first row will not call the provider 2 again if the provider 1 and 3 fail even if it failed the on the second row.

Contacts¶

There are three ways to define a contacts list (can be mixed):

Using a manual configuration
From keycloak
From a collection

Examples¶

Static contacts¶

Create a list of contacts from the configuration see contacts.coms for complete fields details.

PERSONAL¶

type	object
properties
type	type	string
	enum	PERSONAL
	default	PERSONAL
description
number	Use to send a email. If empty or invalid the contact will be ignored.
	type	string
email	Use to send a sms. If empty or invalid the contact will be ignored.
	type	string
firstname	The firstname to use during the generation of notification
	type	string
lastname	The lastname to use during the generation of notification
	type	string
markdownDescription
additionalProperties	False

ENTERPRISE¶

type	object
properties
type	type	string
	enum	ENTERPRISE
	default	ENTERPRISE
description
number	Use to send a email. If empty or invalid the contact will be ignored.
	type	string
email	Use to send a sms. If empty or invalid the contact will be ignored.
	type	string
name	The firstname to use during the generation of notification
	type	string
markdownDescription
additionalProperties	False

Collection contacts¶

A collections can be used to configure different contacts lists. See feature collections for more information

Extract from keycloak¶

Contacts list used to send a notification can also be extracted from configured users on Keycloak.

Groups are used to search members contact information. For example, a notification can be sent to members of administrator and supervisor groups.

Provider connection monitoring¶

Concept¶

This is the monitoring of the connection with the provider to detect error.

Usage¶

The value.ospp file reflects the state of the connection with a provider :

Note

true mean connected false means disconnected

Notification generation¶

Concept

Messages can be static or dynamic. Usage of dynamic notification needs usage of the osp-reports module. For more details consult the associated documentation.

See the feature reports for details on templates and reports generations.

Following parameters are sent to templates :

trigger : Notification trigger. The value when an output is the source of the notification or some free data when it is started by a script (lua or js) or a front-end action.
values : List of all accessedValue defined on the notification.

Example¶

Using message formatter