...

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

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

   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 file 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 set of fields. Users have to specify only the fields that they wants to use as filters. destination is a mandatory field and it is associated to one or more destinations which are linked to the user's ECMWF account. Only the notifications complying with all the fields defined will execute the trigger. 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

   Code Block
   language bash theme DJango
   user@local aviso listen

   Once in execution this command will create a process waiting for notifications. Users can terminate the application by typing CTRL+C .

   Note that the configuration file is read-only at start time, therefore every time users make changes to it they need to restart the listening process.

   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.

Testing my listener

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

...

Aviso configuration file allows the definition of multiple listeners. Alternatively, the listeners configuration can be indicated as an independent file or multiple files:

user@local aviso listen listener1.yaml listener2.yaml 

 Regardless where is defined, each listener is composed of:

...

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 ...

Dealing with historical  notifications

Before listening to new notifications, Aviso checks what was the last notification received and it will then return all the notifications that have been missed since. It will then carry on by listening to new ones. The first ever time the application runs however no previous notification will be returned. This behaviour allows users not to miss any notifications in case of machine reboots.

Aviso can also replay past notifications. The user can retrieve notifications from the ECMWF server of several days before. This can also be used to test the listener configuration with real notifications.​

Here an example, launch Aviso with the following options:​

user@local aviso listen --from 2020-01-20T00:00:00.0Z --to 2020-01-21T00:00:00.0Z

It will replay all the notifications sent from 20 January to 21 January and the ones complying with the listener request will execute the triggers.

Note that the dates must be in the past and --to can only be defined together with --from. The dates are defined in ISO format and they are in UTC.

In absence of --to, the system after having retrieved the past notifications, it ​will continue listening to future notifications. If --to is defined Aviso will terminate once retrieved all the past notifications.

Running as a service

Aviso can be executed as a system service. This helps automating its restart in case of machine reboots. The following steps help to configure Aviso to run as a service:

1. Identify the location of the Aviso executable:

   Code Block
   language bash theme DJango
   user@local whereis aviso

   
   

2. Create a system service unit, by creating the following file in /etc/systemd/system/aviso.service:

   Code Block
   language yml
   [Unit]​ Description=Aviso​ [Service]​ User = <username> (if omitted it will run as root) Group= <groupname> WorkingDirectory= <home_directory> (optional) ExecStart=<aviso_location> listen​ [Install]​ WantedBy=multi-user.target​

3. Reload systemd:

   Code Block
   language bash theme DJango
   user@local sudo systemctl daemon-reload​

4. Start the service:

   Code Block
   language bash theme DJango
   user@local sudo systemctl start aviso.service

   
   Note that if the user changes the Aviso configuration the Aviso service must be restarted otherwise the change will be ineffective.