1 About SAFR Actions

SAFR Actions is SAFR's Event to Action rules engine designed to trigger an action based on different event conditions. SAFR Actions runs as a Windows Service or Linux command line. It registers itself as an event listener with SAFR and monitors for events matching a specific condition. When a matching event is encountered it triggers one or more actions. SAFR Actions has pre-defined actions such as send an email or SMS message, or it can invoke a script or executable file to trigger. This document describes how to use SAFR Actions to run a script. It is equally applicable to trigger any program that runs from the command line.

This document assumes you have prepared your SAFR system for matching faces and generating the events of interest. For example, you may have configured SAFR on one or more cameras to identify persons from a watchlist and generate an action when a person from the Watchlist is matched. If needed, refer to SAFR Documentation at http://docs.real.com for more information on setting up.

1.1 Applications

This section describes different applications for running commands in SAFR Actions.

Create CSV Output Log

Send data about selected events to a log file in CSV Format. This file can be ingested into an external application on a scheduled basis or loaded into Excel for analysis or reporting. Scripts can rotate the file automatically by writing to a date formatted filename or manually rotated. If manually rotating, the safest method would be to rename the file. The next log record written will use the old filename and the renamed file will not be touched.

Make HTTP POST Request

Collect data about selected events and submit to an external web service using HTTP POST or PUT commands. You can use curl or a scripting language capable of making HTTP REST API calls to submit your data to a 3rd party systems such as an Incident Management Software (IMS).

Create Alert Sound

Create an audible alert on a PC if a high priority event occurs such as a person classified as Threat appears. Because Windows does not allow a background Windows Service to interact with IO devices such as sound, attempting to play a sound file will not work when using SAFR Actions as Windows Service. Instead, run SAFR Actions command line to play sounds on the PC.

Trigger a Light Tower

Devices such as Patlite Signal Tower allow remote API control to activate a light to different colors. SAFR Actions can send signals for different conditions such as Red for Threat, Yellow for Concern and Green for Person Type 'VIP'.

On-Screen Feedback for Enrollment

Scripts can return custom codes which can then display customized information back to a user such as "Welcome <Name>" for a known person, or "Please see receptionist" for a stranger.

1.2 Required Hardware and Software

1.2.1 Required Hardware

  • One or more video feeds. This can be a SAFR Camera, a 3rd party camera, or SAFR SCAN.
  • A PC to run SAFR Actions. This PC should operate 24x7 to monitor for new events.
    • If using SAFR On-Premises server, then SAFR Actions is installed with SAFR Platform installer and can be run on the same machine as SAFR Server.
    • If using SAFR Cloud, then a separate PC is required to run SAFR Actions.

1.2.2 System Requirements

Following are the minimum system requirement to run SAFR Actions

  • Intel i5 CPU or equivalent
  • 8 GB RAM
  • 100 GB HD

If running SAFR Actions on same PC as SAFR Server, no additional resources required for SAFR Actions.

1.2.3 Required Software

SAFR Actions is installed with SAFR Desktop or SAFR Server. Only run SAFR Actions on a single PC or actions will be duplicated.

1.3 Install SAFR Desktop Client and SAFR Actions

Download and install the SAFR Desktop for Windows from the SAFR Download Portal . The SAFR Desktop installer includes both the SAFR Desktop Client and SAFR Actions.

If you have many 3rd party cameras, you may need to install multiple Desktop Clients on different machines.

1.4 Prepare your Script

1.4.1 About SAFR Actions Script

SAFR Actions can invoke one or more command line applications. A command line application can be a binary executable, a DOS batch file, a python script, CURL or any other command that can be invoked. SAFR Actions can pass dynamic arguments (tokens) so that actions can be customized.

Below is an example of an action that invokes a python script and passes a single argument (event id).

A screenshot of a computer Description automatically generated

Tokens are specified with a # followed by a single character. A list of available tokens can be found in SAFR Actions at http://docs.real.com.

1.4.2 Script Folder

Scripts are placed in the Scripts Folder located in the following locations:

  • Windows: C:\Program Files\RealNetworks\SAFR\ares\Scripts
  • Linux: /opt/RealNetworks/SAFR/ares/scripts

Scripts should be placed in this directory.

When SAFR Actions scripts are run, the current working directory is the same directory as the Scripts folder. Any log files or other output is relative to this path unless a fully qualified path is supplied. If writing or reading files outside of this folder, ensure the system user has permissions to do so or the command will silently fail.

1.5 SAFR Actions Configuration File

This section describes the basics of the SAFR Actions configuration file. For complete information about SAFR Actions configuration files, refer to SAFR Actions at http://docs.real.com.

A SAFR Actions configuration file is composed of one or more rules. Each rule is made up of an event filter and an action as well as some related behavior. Following outline summarizes a SAFR Actions configuration file.

  • rules
    • Rule1
      • event ( one or more conditions that identify which events apply )
      • trigger(one or more actions)
        • action (an internal action or external program)
    • Rule 2
      • event
      • trigger
        • action
    • Rule 3…

More information about SAFR Actions configuration files can be found in SAFR Actions Guide.

1.6 Creating SAFR Actions Configuration Files

This section describes two ways of creating a SAFR Actions configuration file; GUI Editor or Command Line. If running SAFR Actions on Linux, the configuration file can be created on Windows using the GUI Editor and then used on Linux via command line.

1.6.1 Using Actions GUI Editor

This section describes how to use the GUI Editor to create a SAFR Actions configuration to run two external applications as follows:

  • Make an HTTP POST request to a web service to send information about each event
  • Create a CSV log file with event data

Sample scripts for each are provided below.

On the machine where SAFR Actions is installed:

  1. Open SAFR Actions
  2. Use the “+” and “-“ symbols to add and remove properties to match the following.
    • Clicking "-" deletes that row or entire section
    • Clicking "+" adds a row following current row
    • Some items such as "type" and "personType" allow for one or more items. Click "+" to add each item.
    • To add rules, click "+" next to the rule. Each rule is represented as an "item" and will typically contain an event and a trigger.
      A screenshot of a computer Description automatically generated
    • Set userId and userPwd to your SAFR Account credentials.
    • Above config is for SAFR On-Premise Server. If using SAFR Cloud, change "environment" to "SAFR Cloud".
  3. Choose File > Save to save your changes. Changes take effect immediately.

?After saving, check SAFR Actions Log file (see Troubleshooting below) to ensure configuration is valid and credentials were accepted.

1.6.2 Using SAFR Actions Command Line

SAFR Actions configuration files can be run from command line on Windows or Linux. This is described in this section.

To run SAFR Actions via command line, you will need to create a SAFR Actions configuration file. You can do this using the Windows GUI or a text editor. SAFR Actions configuration files are structured JSON files. The contents of the SAFR Actions configuration file is fully specified in SAFR Actions at http://docs.real.com.

Following is a sample SAFR Actions configuration file for the example given above.

{
"environment": "Custom",
"coviServer": "http:\/\/localhost:8080",
"eventServer": "http:\/\/localhost:8082",
"replyServer": "http:\/\/localhost:8086",
"reportServer": "http:\/\/localhost:8088",
"userId": "stevelocasus",
"userPwd": "***********",
"directory": "main",
"rules": [
{
"event": {
"hasPersonId": true
},
"triggers": [
{
"actions": ["python .\/scripts\/PostEvent.py \"#N\" \"#S\" \"#I\" \"#G\" \"#A\" \"#z\""],
"reply": {
"message": "Script Triggered!"
}
}
]
},
{
"event": {
"personType": [ "Staff", "Visitor" ],
"type": [ "person" ]
},
"triggers": [
{
"actions": [ ".\/scripts\/WriteLog.bat \"#N\" \"#S\" \"#I\" \"#G\" \"#A\" \"#z\"" ]
}
]
}
]
}

Downloadable Files: Scripts-SAFRActions.config, WriteLog.bat, PostEvent.py

1.6.3 Using CURL for HTTP Post

This section provides an alternative means of running an HTTP Post request by using the curl command line application which is available on most Windows and Linux systems.

Below shows the same SAFR Actions configuration file (with only one run) using curl instead of an external Python script.

A screenshot of a computer Description automatically generated

The arguments were kept few for brevity so the full command line can be easily seen. This version also demonstrates a configuration using SAFR Cloud instead of On-Premises server. When using SAFR Cloud and SAFR Camera, only SAFR Actions need be run on Premises, everything else is handled by the camera or in SAFR Cloud.

Following is the text version of the same config file:

{
"environment" : "PROD",
"userId" : "SAFRUSER",
"userPwd" : " **********",
"directory" : "main",
"rules" : [
{
"event" : {
"hasPersonId" : true
},
"triggers" : [
{
"reply" : {
"message" : "Hello #N. You are at #S"
},
"actions" : [
"curl -u USER:PWD -X POST -F 'name=#N' -F \"external_id=#E\" -F \"site=#I\" -F \"source=#S\" -F \"age=#A\" -F \"gender=#G\" http:\/\/ptsv2.com\/t\/YOUR_PTSV2_ID\/post"
]
}
]
}
]
}

Downloadable File: Curl-SAFRActions.config

1.7 Running SAFR Actions via Command Line

Following command runs SAFR Actions on Linux or as a command line in Windows. This is only required if running SAFR Actions command line. If running SAFR Actions on Windows, just saving the configuration from the SAFR Actions GUI will automatically run the configuration as a background Windows Service.

1.7.1 SAFR Actions Command on Windows

"C:\Program Files\RealNetworks\SAFR\jdk\bin\java.exe" -jar “C:\Program Files\RealNetworks\SAFR\ares\ares.jar” "MySAFRActions.config"

Or if run from the SAFR Application Directory:

jdk\bin\java.exe -jar ares\ares.jar "MySAFRActions.config"

1.7.2 SAFR Actions Command on Linux

/opt/RealNetworks/SAFR/jdk/bin/java -jar /opt/RealNetworks/SAFR/ares/ares.jar "MySAFRActions.config"

If the SAFR Actions config file is not in the current directory, a fully qualified path should be provided.

1.8 Test Your Threat Script

Enable on-screen feedback which will make it easier to test if the action is working.

  1. Open SAFR Preferences from the Tools menu.
  2. Go to Events tab.
  3. Scroll down and enable the following Options.
    A screenshot of a computer Description automatically generated
  4. Ensure you have a "message" defined in your SAFR Actions configuration file.

To test the system that you have just set up, do the following:

  1. Register yourself with SAFR and configure yourself as a threat, as described above.
  2. Hide your face from all connected cameras.
  3. Show your face to a connected camera and wait for SAFR to recognize you.
  4. Upon recognition, you should see the following:
    • A red oval should be drawn around your face in SAFR's video feed, indicating that you're a threat.
    • The message "Threat Detected" should flash on the screen.
    • You should see an email appear in your inbox.
    • Your phone should receive an SMS message.

If you don't see the red oval or the on-screen message, review the troubleshooting steps in the next section.

1.9 Troubleshooting

If you the email is not getting generated, try the following.

1.9.1 Check Events are Generated

Open Events from the Tools menu and look for the expected event after a person of type threat appears.

  • If no event
    • Check that enrolled face is of good quality. Open Person record and hold mouse over the face image to see quality metrics. Any metrics with warning icon indicate issues.
      A screenshot of a computer Description automatically generated
    • Connect to the camera with Camera Feed Analyzer and view Recognition details as person walks in view of the camera.
      1. Observe the overlay color, if grey face does not meet minimum quality criteria.
      2. Observe face size, if less than 80 pixels, try to zoom camera or closer to subjects.
      3. Observe the center pose quality (Q). If less than 0.5, try placing camera more in line with direction of travel (though recognition even down to profile pose is possible with good quality enrolled image)

1.9.2 Check SAFR Actions Log File

Open SAFR Actions log (located at C:\ProgramData\RealNetworks\SAFR\ares\logs) to see if there are any clues there.

  • Check for errors with login, ensure that your account information is correct.
  • If you see a "Too Late" message, the machine running the SAFR Desktop Client and the machine running SAFR Actions may not be set to the same time. Correct this and try again.
  • See following helpdesk article for information about SAFR Actions logs:

https://support.safr.com/en/support/solutions/articles/69000208746-interpreting-and-using-safr-actions-ares-logs

1.9.3 Test if Action Triggered

If action appears to be triggered from logs, enable event replies in SAFR Camera Feed Analyzer to verify.

  1. Open Camera Feed Analyzer from the File menu.
  2. Select a camera from the dropdown (see Connect Cameras above)
  3. Open Preferences from Tools menu.
  4. Go to Events tab, scroll down and enable following three checkboxes shown below.

A screenshot of a computer program Description automatically generated

  1. Generate a new event by standing in front of the camera and watch for a message on the video preview window. The message is configured in SAFR Actions config from above:
    A table with text and images Description automatically generated with medium confidence

1.9.4 Troubleshooting Scripts

This section documents how to troubleshoot a SAFR Actions script. This can be even more complex because scripts are run by a background Windows Service so error information is not logged to a file by default.

There are several things that can go wrong with the script run by SAFR Actions such as:

  • Script does not have permission to perform some action such as write or read from a disk location.
  • Script errors that did not appear during testing (i.e. input from SAFR created unexpected conditions).
  • Script is running a different command interpreter than what is used with interactive shell.
    • E.g. Python 3.10 is installed and configured for the logged in user's PATH but when run as a Windows Service, the default Windows Python 3.6 installation is run. This may result in:
      1. Your script may not be compatible with older Python version.
      2. The Windows Python installation may not have the required libraries installed.

See the following article for tips on troubleshooting errors with scripts run by SAFR Actions:

https://support.safr.com/en/support/solutions/articles/69000149289-script-does-not-work-when-run-by-safr-actions

1.10 Downloadable Files

Questions or comments about the documentation? Email us at safr-doc-feedback@realnetworks.com .