Actions Overview
In SAFR an action is essentially a script or macro that communicates a desired action in a language or protocol the receiving device or system understands. It can be written in any language supported by the computer where Actions Relay Event Service (ARES) is installed. It only needs to be invocable as an executable directly or through the use of another executable (usually a script interpreter such as Python).
These are the principle components involved with actions:
- Actions Relay Event Service (ARES): ARES is a cross-platform Java application that acts as an event listener that dispatches configured actions in response to events, as defined in the SAFRActions.config file. ARES can provide replies on any event to be handled by the client originating the event and is normally installed as a service by either the SAFR Platform or SAFR Desktop installers. It is constantly active and is automatically started by the operating system on power-up.
- SAFRActions.config: The SAFRActions.config file defines which events will trigger specified actions. It also can specify additional condition constraints before the action(s) will trigger.
- SAFR Actions: Only available on macOS and Windows. SAFR Actions is a GUI tool that makes editing the SAFRActions.config file much easier. It presents the JSON information of the config file in a visual and easy to understand manner and offers drop-down menus so you can quickly and easily see what values are available and valid. SAFR Actions makes the JSON element hierarchies easy to understand, and ensures that your changes will validate against the SAFRActions.config JSON schema.
<name: value connection attributes>
rules: [
{
event: { },
triggers: [
<time of day and week properties>
actions: [ ],
reply: { },
conditionalReply: { },
],
excludeDates: [ ]
}
]
noTriggerReply: { }
nFactorDef: [ { }, { }, ... ]
emailDef: [ { }, { }, ... ]
smsDef: [ { }, { }, ... ]
- rules:
- 1 or more rules can be defined.
- When an event occurs each rule is checked to see if any of its events match.
- A rule's event matches an occurring event when:
- All attributes rules[i].events match the event.
- Each rule has 1 or more triggers.
- Each trigger inside a matching rule is fired as long as the time of day conditions match. Exception: If 2 triggerIds are identical only the first trigger is fired.
- Each trigger has one or more actions.
- Actions are either:
- A shell command or a batch/shell script to be executed.
- A send email command that has the syntax of:
@emailSend <emailDef.label>
- A send SMS message command that has the syntax of:
@smsSend <smsDef.label>
- All actions are run asynchronously unless a conditionalReply is specified in which case the first rule is run synchronously (and the return code of that rule is used for the conditionalReply) while all other rules are run asynchronously.
- noTriggerReply is used to perform a reply if none of the triggers are fired.
- nFactorDef can define 2 or more conditions that must occur within the specified time window.
- emailDef defines one or more email message attributes (subject, from, message, etc).
- smsDef defines one or more Short Message Service (SMS) messages.
- Send email when visitor arrives during work hours
- rules
- Rule 1
- event (hasPersonId=false)
- trigger (day/hours: 8-5, M-F)
- action: @emailSend visitorEmail
- emailDef
- label=visitorEmail
- subject="Visitor Arrived"
- message="A visitor has arrived at #I - #S."
- …
- Log all events to a CSV and send one type of email for a known person event and another for a threat event.
- rules
- Rule1 (known person email)
- event ( hasPersonId=true, idClass=No-Concern )
- trigger
- action: @emailSend knownEmail
- Rule 2 (threat email)
- event (hasPersonId=true, idClass=[Threat, Concern])
- trigger
- action: @emailSend threatEmail
- Rule 3 (log)
- trigger
- action: ".\scripts\log_event.bat "#D" "#N" "#F" …"
- If editing config file, escape backslash or quotes with another backslash. (In SAFR Actions no escaping is needed.)
- The file ‘log_event.bat' should be placed in
C:\Program Files\RealNetworks\SAFR\ares\scripts
(for Windows) or /Library/RealNetworks/SAFR/ares/scripts
(for macOS).
- emailDef
- 1 (label=knownEmail, subject, message, etc)
- 2 (label=threatEmail, subject, message, etc)
When using long file names for actions on Windows machines, the file names need to be escaped correctly:
"actions": [
"python \"c:\\Program Files\\RealNetworks\\SAFR\\ares\\test.py\""
]
Within the SAFR Actions GUI the same entry appears as follows: