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

2. Configure Email Notifier

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

Important

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

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

Attention

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.

Note

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

Important

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

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

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

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

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

Note

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.

4. Additional Information

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

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

4.3. 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_01@griaule.com",
                "email_02@griaule.com"
            ],
            "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"
        },
        ...
    }
}