Interaction Manager
Introduction
A key part of many systems is the ability to generate notifications to platform, particularly over SMS and email. The JSLEE interaction manager service allows for centralised creation and routing of such events.
Configuration Parameters
The interaction manager service has several configuration sections, as well as core elements, that must be configured before use.
A sample interaction manager service configuration might be:
"interaction": {
"handler": "nz.co.nsquared.slee.interactionmanager.InteractionManagerVerticle",
"configuration": {
"sms-address": "smpp",
"email-address": "email",
"template-paths": "/path/to/templates/notifications",
"friendly-hours": {
"start-hour": 9,
"end-hour": 22,
"storage-service": "redis",
"storage-service-type": "redis",
"storage-name": "fh-notifications"
},
"templates": [
{
"name": "Welcome SMS",
"selector": "notification.type == \"welcome\"",
"type": "sms",
"template-file": "sms/notification.welcome.1.ftl",
"friendly-hours": false
},
{
"name": "Expiry Warning SMS",
"selector": "notification.type == \"expiry_3d\"",
"type": "sms",
"template-file": "sms/notification.expiry-3d.1.ftl",
"friendly-hours": true
}
]
}
}
Core Configuration
At the root level, several configuration options are available:
Parameter | Type | Required? | Default | Description |
---|---|---|---|---|
email-address |
String | No | - | The JSLEE service name to send email notifications to for delivery. If not provided, email notifications will be unavailable. |
sms-address |
String | No | - | The JSLEE service name to send SMS notifications to for delivery. If not provided, SMS notifications will be unavailable. |
sms-source-default |
String | No | 123 |
The source designation to use when sending SMS notifications, if one is not provided in the notification request. |
template-paths |
String | No | templates |
The directory under which all notification templates are stored. |
templates |
Array | No | - | The templates that are available for procesing by the interaction manager. The possible values for items in this array are explained below. If not supplied, no notifications will be sent. |
friendly-hours |
Object | No | - | The configuration for friendly hours handling of notifications, as set out below. If not provided, friendly hours support will not be enabled and notifications will be sent for delivery as soon as they arrive. |
Template Configuration
Each template that the interaction manager uses has a text file base and associated metadata used for selection and processing of any notifications generated for that template.
Each text file base used for templates must be in the Apache FreeMarker template engine language. This allows for high levels of control in the processing of notifications generated by the platform.
The following template configuration items are available:
Parameter | Type | Required? | Default | Description |
---|---|---|---|---|
name |
String | Yes | - | The free text name of this notification. |
type |
String | Yes | - | The type of notification to be constructed, either sms or email . |
selector |
String | No | - | A JSLEE expression which must return true or false to determine whether the template applies for a notification. for If not supplied, the notification will be disabled. |
template-file |
String | Yes | - | The relative path from the template-paths value to the FreeMarker template file for this notification. |
friendly-hours |
Boolean | No | false |
Whether friendly hours should be honoured for this notification. |
Selectors
Template selectors are written as JSLEE expressions. For a detailed breakdown of how JSLEE expressions can be written, see the core expressions documentation. Within the interaction manager the following variables and methods can be referenced from within an expression:
Variable | Type | Description |
---|---|---|
notification |
JsonObject | A JSON Object representing the entirety of the notification event provided by the event source. |
The notification
object provided can be accessed with the identifier notification
within expressions. Each notification
will be different, however the following fields can be expected to exist:
Field | Type | Description |
---|---|---|
type |
String | A string determining the type of notification. The value of this field will be determined by the source of the notification event. |
subtype |
String | A string determining the sub-type of notification. The value of this field will be determined by the source of the notification event. |
source |
String | A string determining the source of the notification. The value of this field will be determined the setup of the JSLEE. |
Friendly Hours Configuration
The interaction manager can hold selected notifications if they are received outside of a given time range. Notifications that are generated within this time range will be sent in the order they were received once the next friendly hours period begins. If no friendly hours configuration section is supplied, all notifications will be sent as they are received with no delay.
The following friendly hours configuration items are available:
Parameter | Type | Required? | Default | Description |
---|---|---|---|---|
start-hour |
Integer, 0..23 | Yes | - | The starting hour number to begin sending friendly hours notifications. Notifications requiring friendly hours handling will be sent in the period where the current hour is greater than or equal to this value and the end-hour value is not reached. |
end-hour |
Integer, 0..23 | Yes | - | The ending hour number to stop sending friendly hours notifications. Notifications requiring friendly hours handling will stop being sent once this hour value is reached. |
timezone |
String | No | Etc/UTC |
The IANA timezone to use when getting the current time. |
storage-service |
String | No | redis |
The JSLEE service name to send notifications to for storage until friendly hours begins. |
storage-service-type |
String | No | redis |
The JSLEE service type that is being used for service. Only Redis storage is supported. |
storage-name |
String | No | fh-notifications |
The name of the location to store notifications until friendly hours. For Redis storage, this is the name of the holding list. |
storage-poll-milliseconds |
Long | No | 60000 |
The number of milliseconds to either poll the storage for new notifications (inside friendly hours) or check if friendly hours has started (outside friendly hours). |
Friendly Hours Redis Configuration
If Redis storage is being used for friendly hours, additional configuration options are available:
Parameter | Type | Required? | Default | Description |
---|---|---|---|---|
processing-list |
String | No | fh-processing |
The holding list to use for notifications that are being sent as part of friendly hours. Notifications are moved here from the list defined in storage-name and then either deleted or moved to the list defined under success-list or error-list , as applicable. |
success-list |
String | No | - | The success list to use for notifications that have been successfully sent during friendly hours after being stored. If not defined, notifications will be deleted after a successful send. |
error-list |
String | No | - | The error list to use for notifications that have not been successfully sent during friendly hours after being stored. If not defined, notifications will be deleted after an unsuccessful send. |