Skip to content

Notifications

Introduction#

The Piveau Metrics Notifications is part of the Metadata Quality Assurance (MQA) of Piveau. It notifies a publisher per email when their catalogues score is decreasing.

How to change the mail sending interval#

The time and interval the checks are done can be configured via these three environment variables:

  • NOTIFICATIONS_TIMER_UNIT: this should either be WEEK or MONTH and sets the context for the interval calculation. If the unit is WEEK, the check will run each week on the same day(s) (eg. on mondays and thursdays). If this is set to MONTH, the calculation will result in days of a month this check should run (eg. on the 1st, 5th and 20th of each month). This could result in different weekdays for consecutive weeks.

  • NOTIFICATIONS_TIMER_COUNT: A comma separated list of numbers, specifying the days of the unit set in NOTIFICATIONS_TIMER_UNIT.
    That is, if the Unit is WEEK, the days will refer to the days of a week (Monday, Tuesday,..), where Monday is 1 and Sunday is 7. In this case, any number greater than 7 will be ignored. If the Unit is Month, the numbers will refer to the days of a Month (1st,2nd,3rd...). The maximal value for a day will depend on the number of days in this month. This means that a 31 is valid, but only for months with 31 days. On a month with only 30 days, the 31 will be ignored.

  • NOTIFICATIONS_TIMER_HOUR: the full hour of the day, the check will run, default is 9am. Depends on the server time.

The time of the next run will be calculated either on startup or directly after a scheduled run. Alternatively a check can be triggered manually via the API at /notification/check/now.

What triggers a mail?#

When the score of a catalogue drops by a certain threshold, 5 Points by default, a notification mail to the publisher will be triggered. The catalogue to be checked has to be defined in an environment variable called NOTIFICATIONS_ACTIVE_CATALOGUES.

The service is caching a version of the quality report from the last time, a notification was sent. If it detects on startup that an enabled catalogue is not cached, it will cache that one during startup.

If the service discovers during a check, that the most current quality report has a lower score than the one that was cached, a notification is sent.

There exists a threshold for which a difference is ignored. This threshold can be configured via the NOTIFICATIONS_SCORE_DELTA environment variable and is set to 5 as default.

After a notification is sent, the old cached version will be replaced with the most current quality report. This ensures that eventually a notification will be triggered, even when the difference during two checks is lower than the threshold for mutliple consecutive checks.

How to subscribe a new user#

The Notification will be sent to the publisher of the catalogue. The publisher is specified in the Linked Data Database. However, not every catalogue is checked initially. If the catalogue is already enabled, another notification recipient can be added, by adding them to the publisher list in the metadata.

If the user is already a publisher for a catalogue, but the catalogue is not yet active, the catalogue has to be added to the list of active catalogues in an environment variable called NOTIFICATIONS_ACTIVE_CATALOGUES.

How to unsubscribe a user#

If a user is a publisher of an enabled catalogue, but does not want to receive notifications, they can be set on a blacklist. To do that, an API PUT request can be created on this endpoint: /user/{mail}/blacklist/{catalogue} where {mail} has to be replaced with the users mail address and {catalogue} has to be replaced with the name of the catalogue. This API endpoint is protected with an API key.

To remove the user from this blacklist, the same endpoint has to be called with an DELETE request.

Key Technologies#