Trigger: GPS Zone / Geofence (`geofence_trigger`)¶

This trigger starts an automation when a geolocalizable object (GPS tracker) enters or exits a geographic zone defined in the system. It is ideal for monitoring fleets, guards, vehicles, and mobile assets in facilities or perimeters.

When to use it?¶

When a vehicle or guard leaves the authorized perimeter and you need to trigger an alert.
When a mobile asset (truck, machinery, person with tracker) enters a restricted zone.
When you need to automatically log the arrival or departure of a resource to an operational zone.
When you want to notify the control center that an operator arrived at their round destination.
When you need to activate or deactivate devices upon detecting the presence of a vehicle in a parking lot or loading zone.

If you need to react to an object's state change (not its geographic position), use Trigger: State Change.
If you need to fire the automation at a fixed schedule, use Trigger: Schedule.

How to configure it¶

Most users should use the Form tab. The JSON Editor tab is for advanced users.

Step 0) Open the parameters¶

In the automations canvas, double-click the GPS Zone node.
A modal opens with two tabs: Form and JSON Editor. Stay on Form.

Step 1) Select the geolocalizable objects to monitor¶

This section defines which trackers (GPS objects) will be watched.

There are two selection modes:

Mode	When to use it	Field saved
By ID	When you want to monitor specific trackers by name	`objects_id`
By Domain	When you want to monitor all trackers in a group/domain	`domains`

By Template (Use Template Engine) is currently disabled.

Steps: 1. Choose the mode (By ID or By Domain). 2. Use the multi-select to choose one or more trackers or domains. 3. You can search by typing in the selector. If the list is outdated, use the Refresh button.

Examples: - By ID: Truck-001, North-Guard, Supervisor-Vehicle - By Domain: logistics-fleet, security-personnel

Step 2) Select the geographic zones¶

This section defines in which zones the tracker's position is evaluated.

There are two selection modes:

Mode	When to use it	Field saved
By ID	When you want to monitor specific zones by name	`zones_as_objects`
By Type	When you want to apply the rule to all zones of a given type	`zones_from_tags`

By Template (Use Template Engine) is currently disabled.

Steps: 1. Choose the mode (By ID or By Type). 2. Use the multi-select to choose one or more zones or zone types. 3. You can search by typing in the selector. If the list is outdated, use the Refresh button.

Examples: - By ID: Restricted-Zone-North, Plant-Perimeter-A, Main-Parking - By Type: restricted_zone, operational_zone, outer_perimeter

Step 3) Configure the activation mode¶

The Mode field determines which geographic event fires the automation.

Option	Description	When to use it
On enter (`inside`)	Fires when the tracker enters the zone	Detect unauthorized access, log arrivals
On exit (`outside`)	Fires when the tracker leaves the zone	Detect perimeter breach, log departures
Both (`both`)	Fires both on enter and on exit	Full presence audit, route traceability

Only one mode can be active at a time. If you select one, the others are automatically deselected.

Best practices¶

Define zones with appropriate precision: zones that are too large may generate false positives; zones that are too small may not correctly detect entry/exit based on GPS update frequency.
Use "By Domain" for entire fleets: if you need to monitor all vehicles in a group, it is more maintainable than adding each one by ID.
Combine "By Type" for homogeneous zones: if you have many zones of the same type (e.g.: all restricted zones), it is more efficient than listing them one by one.
Avoid "Both" without downstream logic: if you use both mode, make sure the flow has logic to differentiate entry from exit (the event payload should indicate this).
Test with one tracker and one small zone first before scaling the configuration to multiple trackers and zones.
Consider GPS latency: entry/exit events depend on the tracker's update frequency. A tracker that updates every 30 seconds may take up to 30 seconds to fire the trigger.

Troubleshooting (common issues)¶

The trigger doesn't fire even though the tracker is in the zone
Verify the tracker is actively sending position updates.
Confirm the geographic zone is correctly drawn/defined in the system.
Check that the selected tracker is correct (By ID: verify the exact ID; By Domain: verify the tracker belongs to the domain).
Verify that the activation mode (inside/outside/both) matches the expected event.
The trigger fires repeatedly for the same event
This may occur if the tracker oscillates at the zone boundary (enters and exits multiple times). Check if the zone needs to be enlarged or if the tracker has GPS signal issues.
No trackers appear in the selector
Use the Refresh button to reload the list.
Verify that gps_tracker type objects exist in the system.
Confirm user permissions to view that object type.
No zones appear in the selector
Use the Refresh button to reload the list.
Verify that gps_zone type objects exist in the system.
If using By Type mode, confirm that zone types are configured.
I selected "By Domain" but switching to "By ID" lost my selection
This is expected behavior: when switching modes, the previous selection from the other mode is automatically cleared to avoid inconsistent configurations.

Advanced configuration (JSON Editor) — expert users only¶

The JSON Editor tab lets you view and directly edit the internal structure of the node. Useful for:

Copying configurations between flows or instances.
Pasting externally prepared configurations.
Reviewing the exact state of the node.

`input` structure¶

{
  "ruleSet": {
    "zones_as_objects": [{"object_id": "zone-uuid"}],
    "objects_id": ["tracker-uuid"],
    "domains": [],
    "zones_from_tags": [],
    "activation_method": "inside",
    "for": "00:00:00"
  },
  "config": {}
}

Field table¶

Field	Type	Description
`ruleSet.zones_as_objects`	`{ object_id: string }[]`	Zones selected By ID. Exclusive with `zones_from_tags`.
`ruleSet.zones_from_tags`	`{ tag: string }[]`	Zones selected By Type. Exclusive with `zones_as_objects`.
`ruleSet.objects_id`	`string[]`	Tracker IDs selected By ID. Exclusive with `domains`.
`ruleSet.domains`	`string[]`	Tracker domains selected By Domain. Exclusive with `objects_id`.
`ruleSet.activation_method`	`"inside" \\| "outside" \\| "both"`	When it fires: on enter, on exit, or both.
`ruleSet.for`	`"00:00:00"`	Duration (reserved for future use, always `"00:00:00"`).
`config`	`{}`	Always empty (reserved for future use).

Important: zones_as_objects and zones_from_tags are mutually exclusive. The same applies to objects_id and domains. If you fill both at the same time from the JSON Editor, behavior may be unexpected.

JSON examples by use case¶

Specific tracker enters specific zone¶

{
  "ruleSet": {
    "zones_as_objects": [{"object_id": "restricted-zone-north-uuid"}],
    "objects_id": ["truck-001-uuid"],
    "domains": [],
    "zones_from_tags": [],
    "activation_method": "inside",
    "for": "00:00:00"
  },
  "config": {}
}

Any tracker in the security domain exits any zone of type "perimeter"¶

{
  "ruleSet": {
    "zones_as_objects": [],
    "objects_id": [],
    "domains": ["security-personnel"],
    "zones_from_tags": [{"tag": "outer_perimeter"}],
    "activation_method": "outside",
    "for": "00:00:00"
  },
  "config": {}
}

Multiple vehicles and multiple zones — entry and exit¶

{
  "ruleSet": {
    "zones_as_objects": [
      {"object_id": "main-parking-uuid"},
      {"object_id": "loading-zone-uuid"}
    ],
    "objects_id": ["truck-001-uuid", "truck-002-uuid", "supervisor-car-uuid"],
    "domains": [],
    "zones_from_tags": [],
    "activation_method": "both",
    "for": "00:00:00"
  },
  "config": {}
}

Quick guides (recipes)¶

Recipe A — "Alert when a vehicle enters a restricted zone"¶

Trackers: By ID → select the fleet vehicles
Zones: By ID → select the restricted zone
Mode: On enter
Action: Send Telegram notification to supervisor / activate audible alert

Recipe B — "Log guard arrival at round checkpoint"¶

Trackers: By Domain → domain night-shift-guards
Zones: By Type → type round_checkpoint
Mode: On enter
Action: Write to Google Sheets with timestamp / update object state

Recipe C — "Detect when a truck leaves the plant perimeter"¶

Trackers: By Domain → domain logistics-fleet
Zones: By ID → zone main-plant-perimeter
Mode: On exit
Action: Send SMS to control center / start audit log

Recipe D — "Full presence audit in loading zone"¶

Trackers: By ID → vehicles authorized for loading zone
Zones: By ID → zone north-loading-dock
Mode: Both
Action: Log event (entry/exit) in the event log with timestamp

Recipe E — "Activate welcome light when supervisor arrives at headquarters"¶

Trackers: By ID → supervisor's vehicle tracker
Zones: By ID → zone management-parking
Mode: On enter
Action: Send HTTP action to activate lights / notify reception

Recipe F — "Monitor all assets in risk zones"¶

Trackers: By Domain → all mobile asset domains
Zones: By Type → type risk_zone
Mode: On enter
Action: Trigger security protocol / notify brigade

Internal references (to locate it in the editor)¶

Node key: geofence_trigger
Class: trigger
Required fields: at least one tracker (objects_id or domains) and at least one zone (zones_as_objects or zones_from_tags)
Supported activation modes: inside, outside, both
Monitored object types: gps_tracker (trackers) and gps_zone (zones)

Trigger: GPS Zone / Geofence (geofence_trigger)¶