Notification Handler

Notification Handler

The notification handler is a Lua object that is used to handle all notification sending via pluggable modules.

As N2IWF action rules are encountered, rules may choose to send a notification as part of rule processing.

Attributes

The notification handler should only be accessed using its methods. Direct access to its attributes is not recommended.

Methods

The notification handler is a globally-cached object that does not have instances, so its methods should be accessed using the period operator, e.g.:

notification_handler.maybe_send_notification ()

maybe_send_notification

This function sends the applicable notification for the action rule currently being processed based on either configuration or hook functions.

This function takes two positional parameters:

This function returns the notification name that the action rule contained (if any), regardless of whether the notification was successfully sent or not.

Custom Notifications

Custom notification protocols may be used and will be automatically made available as per the N2SVCD Lua service caching configuration.

All notification text processing remains within the core N2IWF notification handler, and the text to be sent is provided to the custom protocol implementation along with any other parameters configured.

Custom Notification Protocol Configuration

Custom notification protocols must be defined in a file called notification.lua that is placed in a directory that matches the notification type name used in configuration and/or hooks. For example, the XML configuration for a custom notification protocol called custom1 might be:

<global name="NOTIFICATIONS" type="array">
  <notification name="custom_notf" protocol="custom1">
    <to from_var="logical"/>
    <parameter1>456</parameter1>
    <text>I am a custom notification protocol.</text>
  </notification>
</global>

<global name="PRE_RATING" type="array">
  <rule ... notification="custom_notf" />
</global>

This could then exist in the filesystem as:

/path/to/custom1/notification.lua

This would then be looked up by the notification handler as (in order):

• n2.notification.custom1.notification
• custom1.notification

The custom notification location must be accessible to the Lua service via the configured library path - for example, the Lua service configuration for this case could include /path/to/?.lua in its lua_lib_path.

Custom Notification Parameters

When configuring a custom notification protocol, some common parameters are automatically checked for:

• protocol, which should always be the custom value.
• to is required for all protocols.
• route may be specified for all protocols. This will be passed to the protocol handler to be used as required.
• text may be specified for all protocols (including when specified in XML node body). Note that the runtime value will be processed as usual before being passed to the handler.

Parameter defaults will also be checked for any custom notification parameters.

Custom Notification Specification

All custom notifications must support the following features.

parameters

The parameters object of a custom notification must be a table that contains a key for each possible configuration parameter.

Each key’s value must also be a table with 0 or more of the following key/value pairs:

• required: true if the parameter is required to be populated for the notification to be sent.
• default: the value to use if the parameter is not populated.

send_notification

This method is called to send a notification.

This function takes a single parameter, a table of the parameter names and values to be used when sending the notification. This table will be filled out by the IWF notification handler and contain only scalar values that can be sent directly.

The return value from this method is ignored. Errors may be thrown if the notification cannot be sent.

Example

An example of a custom notification might be:

local notification = {
    parameters = {
        parameter1 = { required = true }, -- Required parameter, so no default.
        parameter2 = { default = 'foo' }  -- Optional parameter with default.
    }
}

notification.send_notification = function (parameters)
    local to = parameters.to
    if not to then error ("Missing 'to' parameter") end
    local text = parameters.text
    local route = parameters.route
    
    local p1 = parameters.parameter1
    local p2 = parameters.parameter2
    
    -- Do something with received parameters here.
end

return notification