Skip to main content

Rules and workflows

A rule decides which detections raise alerts and what happens next. In the dashboard, rules are called workflows. A workflow has:

  • A trigger: which detections it matches, by event type, camera, severity, object class, zone and time of day.
  • Steps: what to do on a match, such as create an alert, send an email or call a webhook.
  • An enabled switch.

Workflows run after the camera's detection profile. Only detections that pass the profile are checked against your workflows. Every enabled workflow is checked, so one detection can match several workflows.

Create a workflow​

You need the admin role.

  1. Open Workflows and click Create Workflow.
  2. Under General, enter a Workflow Name, for example Person in loading bay after hours. The name appears on each alert this workflow raises.
  3. Under Trigger, set what the workflow matches:
    • Event Type: only events of this type, or Any Event. See Event types.
    • Camera Filter: one camera, or Any Camera.
    • Minimum Severity: only events at or above this severity, or Any Severity.
  4. Under Steps, click Add Step and pick an action. Add as many steps as you need and use the arrows to put them in order.
  5. Click Save Workflow.

New and changed workflows take effect within about 30 seconds.

To filter by object class, zone, schedule or dwell time as well, set those fields of the condition through the workflows API. When you later edit the workflow in the dashboard, those parts of the condition are kept.

Conditions​

A workflow's condition is a JSON object. Every field is optional. A condition of {} matches every detection that passes the camera's profile.

FieldTypeMatches when
camerastringThe detection is from the camera with this name.
classesarray of stringsThe object class is in the list, for example ["car", "truck"]. Use the detector's class names. See Detection classes.
zonestringThe object is inside the camera's zone with this name. See Zones.
scheduleobjectThe detection time is between start and end, written as "HH:MM". A window can wrap past midnight, for example {"start": "22:00", "end": "06:00"}.
min_dwell_secondsnumberThe object has matched the rest of the condition for at least this many seconds. If it stops matching for 10 seconds, the count starts again.
min_severitystringThe event's severity is at least info, medium or high. The dashboard's Minimum Severity sets this.

All the fields you set must match. The workflow's Event Type is stored next to the condition and must match too.

Schedules use the site's local time, set by your administrator with SITE_TIMEZONE, the same clock as detection profile schedules. Without it they use UTC. See Install.

zone can also be an inline polygon of [x, y] points relative to the picture, from 0 to 1. A named zone is easier to keep up to date.

Example conditions​

Any person on any camera:

{ "classes": ["person"] }

A car or truck in the camera's Service Yard zone:

{ "classes": ["car", "truck"], "zone": "Service Yard" }

A person between 22:00 and 06:00 site time:

{
"classes": ["person"],
"schedule": { "start": "22:00", "end": "06:00" }
}

A person who stays in the Loading Dock zone for 2 minutes, at one camera only:

{ "camera": "loading-bay", "classes": ["person"], "zone": "Loading Dock", "min_dwell_seconds": 120 }

Steps​

Steps run in order each time the workflow matches. If a step fails, the next one still runs.

StepWhat it does
Create AlertOpens an alert in the dashboard. Alert Severity sets the alert's severity. Leave it empty to use the detection profile's severity. Message is recorded in the run log.
Send EmailEmails the Recipients you list through an email notification channel, with an optional Subject and Body.
Send SMSTexts the Recipients you list through an SMS notification channel, with an optional message.
Send WebhookSends an HTTP POST with a JSON payload to the Webhook URL you set.
API CallSends an HTTP request with the Method, URL, Headers and payload you set.
Tag EventAdds a tag, such as flagged, to the rule event.

Most workflows start with Create Alert. Without it, the workflow still runs its other steps and a clip is still saved, but no alert appears in the dashboard.

Without a subject or body, emails say which camera raised the alert, when, at which severity, and the caption. SMS messages say the same in one line.

Payload templates​

Send Webhook, API Call, Send Email and Send SMS fill in these placeholders before they send:

PlaceholderValue
{{event_id}}The ID of the rule event. Use it with the clips API.
{{camera_name}}The camera name.
{{severity}}The severity set on the step or the workflow, if any.
{{ts}}The time of the detection.
{{caption}}The clip caption.

For example, a webhook payload for a chat tool:

{ "text": "Alert on {{camera_name}} at {{ts}} (event {{event_id}})" }

For API Call, headers can use the same placeholders. With GET and DELETE, the payload is sent as query parameters. With POST and PUT, it is sent as a JSON body.

Requests time out after 10 seconds and don't follow redirects. A step fails if the request times out or the server answers with an error status.

Webhook and API call addresses can point at hosts on your local network, but not at the site's own loopback address, link-local addresses or cloud metadata addresses. Your administrator can allow specific internal targets with ARGUS_EGRESS_ALLOWLIST. See Install.

note

Steps run as soon as the rule matches, before the clip and its caption exist. {{caption}} is usually empty at that point. Send {{event_id}} so the receiving system can look up the clip and caption later.

Run history​

Every time a workflow matches, Argus records a run. Open Workflows and click Runs History to see each run, its trigger event and an Execution Log with the result of every step. Click Configuration to go back to the list.

StatusMeaning
successEvery step succeeded.
partialSome steps succeeded and some failed.
failedNo step succeeded, or the workflow has no steps.

Run history is deleted together with its event by the retention service.

One alert per object​

Each workflow fires once per tracked object on a camera. A person who walks through a zone raises one alert, not one per frame.

note

Argus remembers which objects have fired in the rule engine's memory. If the site-rule-engine service restarts, the memory is cleared and an object still in view can fire again. An object that leaves the frame and comes back may also get a new track, and a new alert.

Turn off or delete a workflow​

On the workflow's card:

  • Click the power button (Disable Workflow) to turn it off, and again (Enable Workflow) to turn it back on. A disabled workflow keeps its run history.
  • Click Edit Workflow to change it.
  • Click Delete Workflow to remove it.

Event types​

Event Types is a list of kinds of event, such as perimeter-breach. They connect detection profiles to workflows: a profile decides which event type its matches create, and a workflow set to an event type only runs for events of that type. A workflow on Any Event runs for all of them, and events from a profile without an event type reach every workflow.

To add one, open Event Types and fill in Add New Event Type:

  • A Display Name. Argus derives the Machine Key from it: lower case, words joined with hyphens. The key can't change after you save.
  • An optional Description.
  • A Category: security, safety or operational.
  • A Default Severity: info, medium or high. Alerts use it when neither the workflow nor the detection profile sets a severity.

Click Save Event Type.

Argus comes with two built-in event types, detection and rule_trigger. You can turn event types on or off with their switch. You can delete an event type only while no workflow and no detection profile uses it.

Was this page helpful?