Safora Fence Event Types

These are the three event types the Safora integration needs. Set up the integration itself first; this article covers only the event types it writes to.

Supported event types

EarthRanger event type Display title Priority What raises it
safora_fence_tamper Tamper Detected Red The controller detects interference with the fence line.
safora_low_fence_voltage Low Fence Voltage Amber Fence voltage drops below the controller's threshold.
safora_low_battery Low Battery Amber The controller's battery charge runs low.

All three live in an event category called Safora Fence (safora_fence).

Important

Create these event types before connecting Safora. Until they exist, EarthRanger turns the events away with “You do not have permission to perform this action.”, and the Route Activity Logs show that message.

Fields

Field Label Type On which event types What it holds
fence Fence Text All three The fence controller that reported, e.g. HIP-SAF-FENCE-01.
voltage Voltage Text Low Fence Voltage Fence voltage at the time of the alarm.
charge Charge (%) Text Low Battery Battery charge as a percentage, e.g. 6.
note Note Text All three The message Safora sends with the event — used on resolution events, e.g. Fence voltage restored – auto-resolved.

Why voltage and charge are text, not numbers. Safora does not always send a reading. Resolution events arrive with 0 or N/A in place of a measurement, and a number field silently rejects N/A, leaving the value off the form. Text accepts whatever arrives, so nothing is lost.

How to create these event types

1. Install the command-line tool and sign in

You need a terminal with Python 3.11 or newer and pipx installed, and an EarthRanger account on the target site. 

pipx install earthranger-cli                         # install the tool; this gives you the 'er' command

er profile add sitename --server sitename --username you   # save the site as a profile ('sitename' is the site's subdomain, e.g. 'borana' for borana.pamdas.org)
export ER_PROFILE=sitename                                 # tell 'er' to use that profile in this terminal
er auth login                                              # asks for your EarthRanger password and signs you in

Important: the account you log in with must have permissions on the Event Category that will host these event types.

2. Save this spec as safora-fence.yaml

The spec below creates the Safora Fence category as well as the three event types. To put them in a category the site already uses instead, change the category block at the top. 

category:
  value: safora_fence
  display: Safora Fence
event_types:
- value: safora_fence_tamper
  display: Tamper Detected
  icon_id: threats_rep
  default_priority: red
  auto_resolve: true
  resolve_time: 186
  ordernum: 3
  layout:
    label: ''
    columns: 1
  fields:
  - key: fence
    label: Fence
    type: string
  - key: note
    label: Note
    type: string
- value: safora_low_fence_voltage
  display: Low Fence Voltage
  icon_id: fence_voltage_rep
  default_priority: amber
  auto_resolve: true
  resolve_time: 168
  ordernum: 7
  layout:
    label: ''
    columns: 1
  fields:
  - key: fence
    label: Fence
    type: string
  - key: voltage
    label: Voltage
    type: string
  - key: note
    label: Note
    type: string
- value: safora_low_battery
  display: Low Battery
  icon_id: low_battery_rep
  default_priority: amber
  auto_resolve: true
  resolve_time: 186
  ordernum: 50
  layout:
    label: ''
    columns: 1
  fields:
  - key: fence
    label: Fence
    type: string
  - key: charge
    label: Charge (%)
    type: string
  - key: note
    label: Note
    type: string

resolve_time is in hours, and ordernum sets where each type appears in the reporting menu — both can be changed to suit the site.

3. Preview, then apply

er events apply safora-fence.yaml --dry-run   # shows what will be created or changed
er events apply safora-fence.yaml             # actually does it

Applying is safe to repeat: it creates what is missing and patches only what differs. Nothing is ever deleted.

4. Verify

er events list event-types --category safora_fence
er events show event-type safora_low_battery

CLI tool and full spec documentation: https://github.com/PADAS/earthranger-cli