Email Notification Service

Introduction

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

You can use this feature with any SMTP server by configuring the service as described in the section Configuring the Email Notifier. When no SMTP server is available, the user must create it and install the service dependencies.

Configuring the Email Notifier

Properties

The configuration file for the Email Notification Service 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.

Database

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

Key	Description
mail.smtp.auth	SMTP authorization: NONE, TLS, SSL
mail.smtp.from.email	SMTP sender email
mail.smtp.from.name	SMTP sender name
mail.smtp.host	SMTP host
mail.smtp.password	SMTP password for TLS and SSL
mail.smtp.port	SMTP port: NONE=25; TLS=587; SSL=465
mail.identify.request.single.subject	Email subject; the notifier will concatenate the hash id to separate threads.
mail.identify.request.single.template	Email body template: Fields: <username>: user name <timestamp:date/time pattern>: if no pattern is provided, MM/dd/YYYY HH:mm:ss will be used <biographics>: iterates over biographics; inside the iteration: <biographic:key> and <biographic:value> provide key/value images will be sent as attachment.
mail.identify.result.subject	Subject of the email notification for the search result
mail.identify.result.template	Template of the email notification for the search result
mail.identify.request.multiple	Enables/disables sending multiple emails with notifications of face identification search requests
mail.identify.request.multiple.period	Period to consolidate email notifications
mail.identify.request.multiple.subject	Subject for multiple email notifications
mail.identify.request.multiple.template	Email body template for multiple notifications. The emails package a zip file with all listed images.

The zip file of the attached image list can have at most 24 MB. Above that, the listing is split into more than one email.

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 be reflected in the next sent email.

Operation

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

Starting and stopping the 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

The email notifier uses the log4j configuration file at /etc/griaule/conf/email-notifier/email-notifier-log4j.xml. All logs will be in /var/logs/griaule/email-notifier/.

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

Actions

The email service can contain an interest list via GBDS for some people. Some actions can be taken when a search is required and those people appear in the search results. The actions are:

• Hide person from the search result;

• Hide the person's information in the search result if the authorized user does not have access to view it;

• Notify by email the search result with the person.

To configure the action, it is necessary to access the tables gbds.people_transparency and gbds.people_transparency_group to inform if any person should be removed, hidden or notified at each identification search performed.

The table contains PGUID, action and flag to enable the transparency of that person. The groups table holds email groups for notification.

With the PGUID entered, the actions must be: REMOVE, CLASSIFIED, or NOTIFY:

• When removing (REMOVE), the get result endpoint will not return the person;

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

• In the notification (NOTIFY), the table gbds.people_transparency_group contains email groups stating which emails should be notified with the person's search result.

In the table gbds.people_transparency, a pguid may appear more than once, so more than one action can be taken for this pguid, for example: remove and notify or classify and notify.

Additional Information

API and Database Settings

This service is enabled by some settings in gbdsapi.properties or in the table gbds.settings in the database. These are:

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

  Enable or disable this service

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

  Sets the log level

• gbds.transparency.email-notifier.timeout

  Sets the timeout.

• gbds.transparency.email-notifier.url

  Sets the notification URL

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

GBDS Endpoints for the Email Notification Service

GBDS provides a simple API to store and retrieve users/emails to send. The full documentation can be seen at the GBDS API

• Insert or update groups and emails: POST Email Notify Group

  This call inserts/updates groups and emails related to those groups.

• Retrieve Group: Get Email Group

  This call returns the group and the emails in the group.

• Insert or update the user and their groups: POST Email Notify User

  This call inserts/updates an individual user and associates them with groups.

• Retrieve user: Get Email User

  This call returns the user and their associated groups.

Notifier Get List Endpoints

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

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

  Query filters:

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

  • ini-date: start date in the format: YYYY-MM-dd-HH-mm-ss

  • end-date: end date in the format: YYYY-MM-dd-HH-mm-ss

  • username (user)

  • email

  • pageIndex, default 0, minimum 0

  • pageSize, default 20, minimum 1, maximum 100

The sample 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"
        },
        ...
	]
}