Notifications and Messaging

Ferris provides you access to over 40 notification services such as Slack, Email and Telegram.

Ferris FX uses the Apprise Python Libs as an engine for notifiation dispatch. The power of Apprise gives you access to over 40 notification services. A complete list is provided in a table and the end of the document.

In order to send notifications from your package you need is to create and emit a pre-defined event type.

How to send notifications from your package

In order to send notifications from your package you need to send a ‘ferris.notifications.apprise.notification’ event from your package

You can do it like so.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

from fx_ef import context

# Please note that the value for the url_template is the name used within the config 
# For a specifc URL template in configurations.
# Please see configurations sample on how to configure

data = {
"url_template": "slack_1",
"body": "This is the content",
"title": "This is the subject"
}

event_type = "ferris.notifications.apprise.notification"
context.events.send(event_type, data)

How does it Work?

There are 2 approaches to implementing the notifications support.

• Implementation within a Ferris Service
• Implementation in an Exit Gateway

The 2nd option is used in platforms which are behind a firewall and therefore require the gateway to be outside the firewall for accessing external services. In these cases the adapter runs as a separate container.

Irrespective of the infrastructure implementation the service internal API (as illustrated above) does not change.

The following documentation refers to Option 1.

Pre-Requisites

In order to send notifcations

• The Apprise Libs must be present in the Executor Image.

• You must have the Apprise Notifications Packages installed and running. You can find the code base further below in document.

• You must upload a secrets.json file for the Apprise Notifications Package. Please note that you should maintain a separate copy of the configs since this will not be displayed in your configuration manager since it contains credentials.

• A sample configuration file is provided below. Please use the table based on Apprise documentation to understand the URL Template structure.

• Once the Apprise Notifications Package is installed along with the configurations you must link the package to be triggered by the ‘ferris.notifications.apprise.notification’ event.

The Ferris Apprise Package

The following is code for an Ferris executor package to send apprise based notifications.

To send a notification from within your python application, just do the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

import apprise
from fx_ef import context

# Getting the incoming parameters
url_template_name = context.params.get('url_template')

# Create an Apprise instance
apobj = apprise.Apprise()

# Setting up the Apprise object with URLs
# The URL is retreived from the uploaded secrets.json
apobj.add(context.secrets.get(url_template_name))

try: 
  apobj.notify(
    body=get_param('body'),
    title=get_param('title'),
  )
except Exception as ex:
  print(ex)

Configuration

The following is a sample configuration which is uploaded as a secrets.json file for the Ferris Apprise Package.

The configuration consists of a set of named URL templates. With each url_template being based on the Apprise URL schema as shown in the sections further in document.

While you are free to name URL templates as you wish it is preferred to prefix them with an indication of the underlying service being used to send notifications.

1
2
3
4
5
6
7
8

{
  "slack_1": "slack://TokenA/TokenB/TokenC/",
  "slack_2": "slack://TokenA/TokenB/TokenC/Channel",
  "slack_3":"slack://botname@TokenA/TokenB/TokenC/Channel",
  "slack_4": "slack://user@TokenA/TokenB/TokenC/Channel1/Channel2/ChannelN",
  "telegram_1": "tgram://bottoken/ChatID",
  "telegram_2": "tgram://bottoken/ChatID1/ChatID2/ChatIDN"
}

The configurations must be added to a secrets.json file and uploaded as part of the apprise_package.

The apprise package must be configured to be triggered by the ‘ferris.notifications.apprise.notification’ event.

Popular Notification Services

The table below identifies the services this tool supports and some example service urls you need to use in order to take advantage of it.

Click on any of the services listed below to get more details on how you can configure Apprise to access them.

SMS Notification Support

Desktop Notification Support

Email Support

Apprise have some email services built right into it (such as yahoo, fastmail, hotmail, gmail, etc) that greatly simplify the mailto:// service. See more details here.

Custom Notifications