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
Adding attachments			See Notification generation

Examples

1. Contact from a static list

2. Using a collection

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 certificate

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

• Connection with OAuth2

• Gmail authentication

Sending notification

Concept

A notification is sent through a transmission vector. This transmission vector describes which 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
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
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. Default value is [3]
	type	integer
	default	3
retryDelay	The delay between each retry. Default value is [{“unit”:”SECONDS”,”value”:10}]
	default	unit	SECONDS
		value	10
	#/definitions/DurationConfigurationEntity
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):

1. provider 1 -> provider 3 -> provider 2 -> provider 4

2. 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):

1. Using a manual configuration

2. From keycloak

3. From a collection

Examples

1. Contact from a static list

2. Using a collection

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	An informative field at the destination of the integrator of OnSphere
	type	string
email	Use to send a email. 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
number	Use to send a sms. If empty or invalid the contact will be ignored.
	type	string
additionalProperties	False

ENTERPRISE

type	object
properties
type	type	string
	enum	ENTERPRISE
	default	ENTERPRISE
description	An informative field at the destination of the integrator of OnSphere
	type	string
email	Use to send a email. If empty or invalid the contact will be ignored.
	type	string
name	The firstname to use during the generation of notification
	type	string
number	Use to send a sms. If empty or invalid the contact will be ignored.
	type	string
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

1. Using message formatter

Adding attachments

Notification can have attachments sends with them.

Warning

Currently, only email notifications that are triggered from a script can have attachments given to them.

Attachments must be feed to the notification request manually. An attachment is an object that is composed of:

• content: content of the file as a base64 string. File is created in a temporary directory when the notification is processed

• name: name of the attachment. Also used as the name for the file

• format: format of the attachment. Used as the extension for the file

Look at the communication script API to see how to pass attachments when making a notification. You can also take a look at the following example.