1 Introduction
1.1 Introduction
SAFR Email Sender provides a solution to send customized rich text email notifications triggered from SAFR Events. Email templates are highly customizable, and conditions can be specified to generate event notifications for different conditions such as id class (threat, concern, stranger), person type or many other event attributes.
This guide describes how to install and configure SAFR Email Sender. For SAFR documentation please visit http://docs.real.com.
1.2 Downloads
Download the following files required by SAFR – Genetec API Integration.
1.3 Requirements
Email sender requires a single factor authentication email account using username and password authentication. Many email services require specific configuration to allow this mode. This guide provides guidance for how to enable single factor authentication for some email services.
This guide assumes you have SAFR Software installed and configured and you are familiar with how to generate watchlist alarms through SAFR Actions. For more information about SAFR and SAFR Actions, see http://docs.real.com.
1.4 Overview
SAFR Email Sender is triggered by SAFR Actions. Email is created using a template defined in the configuration file. Pre-defined templates are available, or a custom template can be created. The template defines the layout and content of the email message. Tokens inside the template allow for dynamic content that is passed from the SAFR event. Dynamic information can include recognized person name, picture or other data such as location and person properties.
Notifications can be customized based on the type of event. For example, stranger alerts can go to one group and threat alerts can be sent to a different group. The content of the email can be varied for each, containing different information or layout.
2 Email Templates
2.1 Email Templates
Email templates allow the message layout and content to be specified. The following pre-made templates are available or custom templates can be created.
|
Notification |
Visitor |
|
|
|
2.2 Creating Custom Email Templates
The two included email templates can be used without making any customizations. This section descrxibes how to create your own email templates if desired.
Email templates are generated using JinJa templating engine. This section will describe how to create the most common email elements. More advanced template syntax rules can be found in the following link.
2.2.1 Including event attributes
To include an event attribute in the email, include one of the known attribute names into double curly braces as in following example:
Person Name: {{ personName }}
Leading or trailing spaces are ignored. So {{personName}} is the same as {{ personName }}. The end result will have the persons full name "John Doe" inserted into the email at the desired location. The token may be inserted at any place within the email template.
2.2.2 Conditional elements
You can include or omit a portion of the email depending on the value of one of the event attributes. For example, the following will include a row in the output for person name, only if event includes such a field.
{% if personName %}
<li>Name : {{personName}}</li>
{% endif %}
The first line checks if the event has a personName attribute and if that attribute has a value. If so, then the next line is included in the output, where {{personName}} is replaced with the actual name as described in previous section. Everything between the {% if %} and {% endif %} is inserted into the email if the condition is true. But the 1st and last lines are not themselves included in the output.
2.2.3 Inserting Images
One of three possible images can be inserted into the email for each event.
- reference_image - Face image for enrolled person
- detected_image - Event face image (just the face cropped from the video frame)
- scene_image - Event scene image (full frame of video)
- logo - Image specified in email_logo_file of configuration file
Each of the images are attached to the email and then can be inserted into the body of the email as shown below:
<img src="cid:reference_image" width="240" style="display:block;width:100%;max-width:240px">
The image is identified with the following:
cid:NAME
where NAME is either reference_image, detected_image or scene_image.
3 SAFR Configuration
3.1 Install Files
- Place following files in C:\Program Files\RealNetworks\SAFR\scripts
- email_sender.exe
- email_sender.config
- templates (unpack templates.zip and ensure folder is named 'templates' with the html files in this folder)
Your unpacked structure should look like this:
- Edit email_sender.config. Set the SAFR Account credentials and any other properties you wish the customize. See comments in configuration file for instructions.
3.2 SAFR Actions
SAFR Actions should be set as following for the script best performance.
Here is the SAFR Actions action command
scripts\email_sender.exe -i "#I" -s "#S" -e "#v" -t "#s" -p "#D" -S "#l" -T "#t" -pfn "#" -pln "#U" -pn "#N" -pa "#A" -pg "#G" -ps "#M" -id "#a" -pt "#T" -at "#C" -aid "#c" -pp "#p" -pe "#e" -hl "#H" -pm "#m" -po "#O" -g "#g" -r "recipient_email_addresses" -et "email_template"
Only the last 2 options can be customized. Remaining options can be used in template. The table below describes the all options and provides the token that can be added to the template in order to insert its value.
|
Command Option |
Value |
Template Token |
Description |
|
-i |
#I |
site |
Site value assigned to the SAFR feed where detection occurred. |
|
-s |
#S |
source |
Source value assigned to the SAFR feed where detection occurred. |
|
-e |
#v |
eventId |
SAFR Event ID |
|
-t |
#s |
eventTime |
SAFR Event start time |
|
-p |
#D |
personId |
SAFR Person ID |
|
-S |
#l |
similarityScore |
SAFR Similarity Score |
|
-T |
#t |
tags |
Person Tags for the recognized person |
|
-pfn |
#F |
personFirstName |
Person First Name |
|
-pln |
#U |
personLastName |
Person Last Name |
|
-pn |
#N |
personName |
Person Name |
|
-pa |
#A |
age |
age (###) |
|
-pg |
#G |
gender |
gender |
|
-ps |
#M |
sentiment |
sentiment avgSentiment (#.##) |
|
-id |
#a |
idClass |
idClass Values of Threat, Concern, No-Concern |
|
-pt |
#T |
personType |
person type |
|
-at |
#C |
actionType |
action type |
|
-aid |
#c |
actionId |
action id |
|
-pp |
#p |
phone |
Person phone |
|
-pe |
#e |
|
Person email |
|
-hl |
#H |
homeLocation |
home location |
|
-pm |
#m |
moniker |
moniker |
|
-po |
#O |
organization |
Organization |
|
-g |
#g |
groups |
groups (comma separate list of groups) |
|
N/A |
N/A |
emailTitle |
Value of email_title from configuration file. Maybe be augmented with name, ID class and Person type if email_title_attribute is True. |
|
N/A |
N/A |
personNotes |
Notes from person record. (this may be up to 1000 characters). |
|
N/A |
N/A |
personAddDate |
Date person record was created. |
|
N/A |
N/A |
personAddSite |
Site (camera or workstation) where person was added. |
|
N/A |
N/A |
personAddSource |
Source (camera or workstation) where person was added. |
|
N/A |
N/A |
siteUrl |
Value of email_site_url from configuration file. |
|
N/A |
NA |
footerText |
Value of email_footer_text from configuration file |
|
-re |
See note |
Comma separated list of email addresses. This will override the default email recipients specified in the configuration file. If excluded or "recipient_email_addresses", email addresses from configuration file will be used. |
|
|
-et |
See note |
Email template. This will override the default email template specified in the configuration file. If excluded or "email_template", template from configuration file will be used. Available templates are:
Custom templates can be created as described above. Custom templates should be placed in the 'templates' folder in same directory as application. |
4 Application Behavior
Application will create following two directories in the same directory where the executable is located:
- logs - stores log files. Logs are rolled daily. No automatic log removal is performed. Customer should take this action though logs are typically very small and should not take significant disk space.
- people - stores cache of recent persons to allow suppression of repeat emails within configurable time. This directory should be cleaned up occasionally (automated or manually). Anything older than the suppression duration can be deleted safely.
5 Testing
Test the script using a sample command line. You will need a valid event and person Id. You can get these from an existing event (Right click and chose "copy event details" and paste this into a text file.
python scripts\EmailSender2.py -i "My Site" -s "My Camera Name" -e "EVENT_ID" -t "1741568807413" -p "PERSON_ID" -S "1.1831" -T "tag1, tag2" -pfn "John" -pln "Doe" -pn "John Doe" -pa "34" -pg "male" -ps "0.16" -id "concern" -pt "shoplifter" -at "" -aid "" -pp "" -pe "" -hl "Barton Store" -pm "" -po "" -g "region2,region3" -r "manager@acme.com" -et "notification-template.html"
- Get EVENT_ID and PERSON_ID from SAFR Actions log file located in C:\ProgramData\RealNetworks\SAFR\ares\logs\ares.log.They will be 32 character strings with hypens like this: 9049ff81-1f3d-46f5-a5e6-2a87bfe52793.
6 Troubleshooting
See Troubleshooting section in "Running a Script with SAFR Actions" in Common > Actions under http://docs.real.com
1