Email Notification Service

Introduction

The GBDS Email Notification Service provides a feature for auditorship. Through this service, it is possible to configure an email list that will be notified whenever a 1:N face search is requested.

It is possible to use this feature with any SMTP Server, configuring the service as described in Configure Email Notifier section. When no SMTP Server is available, the user should create it and install the service dependencies.

Configure Email Notifier

Properties

The Email Notification Service configuration file is located at etc/griaule/conf/email-notifier/config.properties and contains the following parameters:

# GBS Email Notifier

jdbc.driverClassName=com.mysql.jdbc.Driver
jdbc.url=jdbc:mysql://<mysql/mariadb ip>:<port>/enotifier?useSSL=false
jdbc.username=<username>
jdbc.password=<encrypted password>
jdbc.dialect=org.hibernate.dialect.MySQLDialect
jdbc.showSql=false

locale=en_US

gbds.url=http://<gbds api host>:<port>
gbds.user=<gbds user>
gbds.key=<gbds password>
gbds.logLevel=INFO
gbds.timeout=300 # seconds

The parameter values between “<>” must be edited according to the environment information.

Database

The database table enotifier.settings contains the email template and subject, and all the information for SMTP connection:

Key
Description

mail.smtp.auth

SMTP mail authorization: NONE, TLS, SSL

mail.smtp.from.email

SMTP mail from email

mail.smtp.from.name

SMTP mail from name

mail.smtp.host

SMTP mail host

mail.smtp.password

SMTP mail password for TLS and SSL encrypted using an already known key

mail.smtp.port

SMTP mail port: NONE=25; TLS=587; SSL=465

mail.identify.request.single.subject

Email subject; email-notifier will concatenate id hash for thread separation

mail.identify.request.single.template

Email body template; Fields: <username>: username <timestam:date/time pattern>: if no date time pattern is provided, MM/dd/YYYY HH:mm:ss is used <biographics>: iterate over biographics; inside iteration: <biographic:key> and <biographic:value> provides key/value image will be sent as an attachment

mail.identify.result.subject

Search Result email notification subject

mail.identify.result.template

Search Result email notification template

mail.identify.request.multiple

Turns on/off multiple email sending with face identify search request notifications

mail.identify.request.multiple.period

Period to consolidate email notifications

mail.identify.request.multiple.subject

Subject for multiple notifications email

mail.identify.request.multiple.template

Body template for multiple notifications email The emails packs a zip file with all images listed.

Image list zip file attached can contain a maximum of 24MB. Above that, the listing is broken down into more than one e-mail.

To create the table, run the required database dump file.

If no dump file was provided, contact Griaule Support Team.

Any changes applied to this table will reflect in the next email sent.

Operation

The service binaries will be placed at /var/lib/griaule/email-notifier/gbs-email-notifier-xxx.jar and /var/lib/griaule/email-notifier/lib.

Starting and Stoping Email Notifier

To start the Email Notification service, run:

/var/lib/griaule/email-notifier/scripts/start-email-notifier.sh

And to stop it:

/var/lib/griaule/email-notifier/scripts/kill-email-notifier.sh

Logs

Email notifier uses the log4j configuration file at /etc/griaule/conf/email-notifier/email-notifier-log4j.xml.

All logs will be placed under /var/logs/griaule/email-notifier/.

Shutdown log will be generated on /var/log/griaule/email-notifier/email-notifier.log

Actions

The email service can hold a list of interests through GBDS for some people. Some actions can be made when a search is required and these people appear on search results. The actions are:

  • Hide person from the search result;

  • Hide person information on the search result if user authorized does not have access to see it;

  • Notify through email the search result with the person.

To configure it, it is needed to access the tables gbds.people_transparency and gbds.people_transparency_group to inform if some person must be removed, hidden, or notified on each identify search made.

The table holds PGUID for some person, action, flag to enable this person transparency. Group table hold email groups for notification

With inserted PGUID action must be: REMOVE, CLASSIFIED, or NOTIFY:

  • On remove (REMOVE), get result endpoint will not return the person;

  • On classify/hidden information (CLASSIFIED), get search result will return person but fields pguid/tguid will be with text classified, all your matches with the score, query and reference index as -1. If the user authenticated has permission transparency_show_classified_people all person data is shown again.

  • On notify (NOTIFY), table gbds.people_transparency_group holds email groups informing which emails must be notified with the person search result.

On table gbds.people_transparency, a pguid can appear on more than one row, so more than one action can be made for this pguid, for ex: remove and notify or classify and notify.

Additional Information

API and Database Settings

This service is activated by some configurations at gbdsapi.properties or the gbds.settings table in the database. Those are:

  • gbds.transparency.search.identify.send-email.enabled

    Enable or disable this service

  • gbds.transparency.email-notifier.log-level

    Set the log level.

  • gbds.transparency.email-notifier.timeout

    Define timeout.

  • gbds.transparency.email-notifier.url

    Define notification URL

More information about those settings can be seen in GBDS API Configuration Manual.

Email Notifier GBDS Endpoints

GBDS provides a simple API for storing and retrieving users/emails to send. The full documentation API can be seen at GBDS API

  • Insert or updated groups and emails: POST Email Notify Group This call inserts/updates groups and emails relative to these groups.

  • Retrieve Group: Get Email Group This call returns the group and the emails in the group.

  • Insert or update user and its groups: POST Email Notify User This call inserts/updates an individual user and associates it with groups.

  • Retrieve user: Get Email User This call returns the user and its associated groups.

Notifier Get List Endpoint

The email notifier has an endpoint to list email requests notified:

  • GET http://host:port/gbs-email-notifier/notify/list (port usually is 8086)

    Query filters:

    • status: one or more of: PENDING, PROCESSING, ERROR, DONE

    • ini-date: initial date on format: YYYY-MM-dd-HH-mm-ss

    • end-date: End date on format: YYYY-MM-dd-HH-mm-ss

    • username

    • email

    • pageIndex, default 0, minimum 0

    • pageSize, default 20, minimum 1, maximum 100

The example response is:

{
    "notifications": [
        {
            "tguid": "86A2BA4A-822C-4F1F-9017-46E0144F274C",
            "timestamp": "2021-08-24-10-52-07",
            "status": "DONE",
            "username": "rgiolo",
            "emails": [
                "[email protected]",
                "[email protected]"
            ],
            "biographics": {
                "information": "some value",
                "ip-address": "192.168.0.62",
                "face-score-threshold": "30",
                "big-text": "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum ..."
            },
            "message": "Email sent"
        },
        ...
    ]
}

Last updated