Navigation :

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.