...

1. Prepare the python3 environment needed

   Code Block
   language bash theme DJango
   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

   Code Block
   language bash theme DJango
   user@local sudo pip3 install -e git+https://git.ecmwf.int/scm/lex/aviso.git@master#egg=aviso

   
   

...

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

   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 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 list set of attributesfields. The users Users have to specify only the attributes fields that they wants to use as filters. destination is a mandatory attribute field and it needs is associated to have as value one or more destinations which are associated linked to the user's ECMWF account. Only the notifications complying with all the attributes fields defined will execute the triggerstrigger. 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. The user 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 needs 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 by the user to test the listener configuration.

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

   notification_engine:
     type: test 
   

   This setting in test mode. This 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.

   Launch again the aviso application.

   $

   Code Block
   language bash theme DJango
   user@local aviso listen

   --test

   The console should display a Test Mode message.

2. Send notificationsa test notification. From another terminal run the notifiy notify command. Here an example:

   $

   , matching the example configuration presented above:

   Code Block
   language bash theme DJango
   user@local aviso notify event=dissemination,class=od,date=20190810,destination=

   FOO

   <user_destination>,domain=g,expver=1,step=1,stream=enfo,time=0,location=

   xxxxxxxx

   xxxx --test

   Note the list of parameters required, the order is not important, but the command requires all of them.The console output should display the notification. The destination has to match the one of the listener configuration.

3. After a few seconds, the console output should display the notification, as the trigger is set to echo.

Define my listener

Aviso configuration file allows the definition of multiple listeners, each listener is compose or a event type, a request block and a triggers block.

Event

Aviso offers notifications for the following types of events:

• The dissemination event is submitted by the product generation. The related listener configuration must define the destination field. Note that a notification received by a dissemination listener will contain the field location containing the URL to the product notified.

• The mars event is designed for real-time data from the model output. The related listener configuration does not have the destination field and has no mandatory fields. Moreover the notification received by this listeners will not contain the location field because the users will be able to access to it by the conventional MARS API.

Request

The table below shows the full list of fields accepted in request block.

Triggers

The triggers block accepts a sequence of triggers. Each trigger will result in an independent process executed every time a notification is received. This sections shows the type of triggers currently available.

Echo

This is the simplest trigger as it prints the notification to the console output. It does not accept any extra parameters.

triggers:
  - type: echo

Log

This trigger logs the event to the log file specified. Please note that it will fail if the directory does not exist.

triggers:
  - type: log
    path: testLog.log

Command

This trigger allows the user to define a shell command.

triggers:
  - type: command
    working_dir: $HOME/aviso/examples
    command: ./script.sh --date ${request.date} -s ${request.stream}
    environment:
      STEP: ${request.step}
      TIME: "The time is ${request.time}"

• command is the command that will be executed for each notification received. This is a mandatory field.
• environment is a user defined list of local variables that will be passed to the command shell. This is an optional field.
• working_dir defines the working directory that will be set before executing the command. This is an optional field.

Moreover, the system performs a parameter substitution for every sequence of the patterns ${name} in the command and environment fields. Each sequence is substituted with the value associated to the corresponding key found in the notification received.

A notification is a dictionary whose keys can be used in the parameter substitution mechanism described above. Here an example of a notification:

{
    "event": "dissemination",
    "request": {
        "class": "od",
        "date": "20191112",
        "destination": "FOO",
        "domain": "g",
        "expver": "0001",
        "step": "001",
        "stream": "enfo",
        "time": "18"
    },
    "location": "https://xxx.ecmwf.int/xxx/xxx.xx"
}    

The full notification can be passed in the command by using the keyword ${json} that will translate the structure in a JSON inline string. Finally, the trigger can save the notification to a JSON file whose file name can be retrieved using the keyword ${jsonpath}.

Using Aviso as a Python API

...