pl-notification

pl-notification is a ChRIS plugin to send notifications through mail / Slack /Element.

usage: notifcation [-t TITLE] [-c CONTENT] [-s SLACK_URL] [-e ELEMENT_ROOM] [-E ELEMENT_TOKEN] [--element-host ELEMENT_HOST] [-r RCPT] [-S SENDER] [-M MAIL_SERVER] inputdir outputdir

Alternatively, we can create a [inputdir]/.notification.yaml and setup the configuration.

Abstract

Sometimes we would like to be notified in various scenarios in the ChRIS environment. Some typical scenarios are system monitoring and task monitoring. pl-notification is a ChRIS plugin to send notifications through mail / Slack / Element.

Installation

pl-notification is a ChRIS plugin, meaning it can run from either within ChRIS or the command-line.

Local Usage

To get started with local command-line usage, use Apptainer (a.k.a. Singularity) to run pl-notification as a container:

apptainer exec docker://fnndsc/pl-notification notification [--args values...] input/ output/

To print its available options, run:

apptainer exec docker://fnndsc/pl-notification notification --help

Examples

To post some message (optionally with title) to some Slack channel:

notification -t 'the title' -c 'test from pl-notification' -s [slack-url from Slack Incoming Webhooks] inputdir outputdir

To post some message (optionally with title) to some Element room:

notification -t 'the title' -c 'test from pl-notification' -e [full room ID (!something:domain.tld) from Room Info -> Settings -> Advanced -> Internal room ID] -E [access token from Settings -> Help & About -> Advanced -> AccessToken] inputdir outputdir

To send some message with title through Email:

notification -t 'the title' -c 'test from pl-notification' -r [comma separated valid email recipent addresses] [-S [valid email sender address]] [-M [email server]] inputdir outputdir

Different methods can be sent simultaneously with the combined command:

notification -t 'the title' -c 'test from pl-notification' -s [slack-url] -e [room ID] -E [access token] -r [email recipents] [-S [email sender]] [-M [email server]] inputdir outputdir

Development

Building

Build a local container image:

docker build -t localhost/fnndsc/pl-notification .

Running

Mount the source code notification.py into a container to try out changes without rebuild.

docker run --rm -it --userns=host -u $(id -u):$(id -g) \
    -v $PWD/notification.py:/usr/local/lib/python3.11/site-packages/notification.py:ro \
    -v $PWD/in:/incoming:ro -v $PWD/out:/outgoing:rw -w /outgoing \
    localhost/fnndsc/pl-notification notification /incoming /outgoing

Testing

Run unit tests using pytest.

Release

Steps for release can be automated by Github Actions.