Installation

Installation on EWC image Ubuntu 18.04.4 ECMWF built

1. Prepare the python3 environment needed

   user@local sudo apt update
   user@local sudo apt install build-essential
   user@local sudo apt-get install python3-dev
   user@local sudo apt-get install python3-pip
   user@local sudo pip3 install setuptools 
   user@local sudo pip3 install wheel 

2. Install Aviso

   user@local pip3 install -e git+https://git.ecmwf.int/scm/lex/aviso.git@master#egg=aviso 

Quick Start

Aviso can be used as a Python API or as Command-Line Interface (CLI) application. Here a few steps to quickly get a working configuration listening to notifications. 

1. Create a configuration file in the default location /etc/aviso/config.yaml with the following settings:

   username: <user_email>
   listeners:
     - event: dissemination
       request:
         destination: <user_destination>
         stream: enfo
         step: [1,2,3]
       triggers:
         - type: echo

   This file defines the event listeners and the triggers to execute in case of notifications. The first line is required for a correct authentication, the username is the email associated to the user's ECMWF account. This can be checked by logging at https://api.ecmwf.int/v1/key/.

   This example is a basic example of a dissemination event listener. request describes for which dissemination events the user wants to execute the triggers. It is made by a list of attributes. The users have to specify only the attributes that they wants to use as filters. destination is a mandatory attribute and it needs to have as value one or more destinations which are associated to the user's ECMWF account. Only the notifications complying with all the attributes defined will execute the triggers.

   The trigger in this example is echo. This will simply print out the notification to the console output.

2. Save the ECMWF key as a file in /etc/aviso/key. The key can be obtained by logging at https://api.ecmwf.int/v1/key/ . 

3. Launch the aviso application

   user@local aviso listen

   Once in execution this command will create a process waiting for notifications.

   The user can terminate the application by typing CTRL+C

   
   

   Note that before starting to listen for new notifications, the application checks what was the last notification received and it will then return immediately all the notifications that have been missed since. It will then start listening for new ones. The first ever time the application runs however no previous notification will be returned.

Submitting test notifications

Aviso provides the capability of submitting notifications. This functionality can be used by the user to test the listener configuration.

1. Terminate the aviso application and edit the following setting of the configuration file ~/.aviso/config.yaml

   notification_engine:
     type: test 
   

   This setting allows to connect to a local file-based notification server, part of the aviso application, that is able to simulate the notification server behaviour.

   Alternatively, the user can add the --test option to all the commands below.

2. Launch again the aviso application.

   $ aviso listen
   

   The console should display a Test Mode message.

3. Send notifications. From another terminal run the notifiy command. Here an example:

   $ aviso notify event=dissemination,class=od,date=20190810,destination=FOO,domain=g,expver=1,step=1,stream=enfo,time=0,location=xxxxxxxx
   

   Note the list of parameters required, the order is not important, but the command requires all of them.

4. The console output should display the notification.

Using Aviso as a Python API

Aviso can be used as a Python API. This is intended for user that wants to integrate Aviso in a bigger workflow written in Python or that simply have their trigger defined as a Python function. Below an example of a python script that defines a function to be executed once a notification is received, creates a listener that references to this function trigger and finally passes it to aviso to execute.

The listening will happen in a background thread defined as daemon therefore it is responsibility of the user to keep the main thread alive.

Please note that the user configuration has not been defined in this example, the system will automatically read the configuration file defined above.

from pyaviso import NotificationManager

# define function to be called
def do_something(notification):
    # do something with the notification
    ...

# define the trigger
trigger = {"type": "function", "function": do_something}

# create a event listener request that uses that trigger
request = {"destination": "FOO", "stream": "enfo", "date": 20190810, "time": 0}
listener = {"event": "dissemination", "request": request, "triggers": [trigger]}
listeners = {"listeners": [listener]}

# run it
aviso = NotificationManager()
aviso.listen(listeners=listeners)

# wait ...