Alarms

The Alarm system in Meridian VMS provides configurable, rule-based alerting with standard operating procedures (SOPs), multi-channel notifications with per-escalation-level routing, and a full lifecycle from creation to resolution. Alarms bridge the gap between raw detection events and actionable operator responses.

Alarm Definitions

An alarm definition is a reusable rule that specifies what triggers an alarm, when it is active, how it should be handled, and who gets notified at each escalation level. Each definition is configured through Settings > Alarms.

Trigger Types

Trigger Type	Description
Detection	Fires when the AI detection engine identifies a specified object class in a configured zone
Motion	Fires when motion activity is detected on a camera
Camera Offline	Fires when a camera stops streaming or fails its health check
Server Offline	Fires when a recording server misses its heartbeat threshold
Lens Clarity	Fires when camera image quality degrades (blur, obstruction, defocus)
LPR Blacklist	Fires when a blacklisted license plate is detected
External / API	Fires via an external webhook, allowing third-party systems to raise alarms

Trigger Configuration

For detection and motion triggers, configure:

Camera Selection : Select one or more cameras. The alarm only triggers for events on selected cameras.

Zone Filters : Restrict to specific detection zones. Events outside selected zones are ignored.

Class Filters : For detection triggers, specify which object classes trigger the alarm (e.g., only “person”, or “person” and “vehicle”).

Example: After-hours perimeter alarm

• Cameras: All perimeter cameras at Site A
• Zones: Fence-line zones only
• Classes: Person
• Time profile: 18:00-06:00 weekdays, all day weekends
• Priority: Critical
• Escalation: Level 1 (Telegram to control room), Level 2 at 5 min (SMS to supervisor), Level 3 at 15 min (email to management)

Time Profiles

Each alarm definition has a time profile:

Always Active : Evaluates triggers 24/7.

Scheduled : Active only during configured windows with day-of-week and time range. Outside the schedule, triggers are ignored.

Priority and Category

Priority Levels:

Priority	Use Case
Critical	Immediate response — perimeter breach, server failure
High	Prompt attention — suspicious activity, camera offline
Medium	Standard operational — routine detection events
Low	Informational — non-urgent notifications

Categories provide organizational grouping (e.g., “Perimeter”, “Access Control”, “Infrastructure”) for filtering in the alarm dashboard.

Run Interval and Cooldown

Setting	Purpose
Run Interval	Minimum time between alarm creation for the same definition. Prevents alarm flooding from high-frequency events.
Cooldown	Minimum time between notifications. Alarms are still created during cooldown but do not trigger additional notifications.

SOP (Standard Operating Procedure)

Each alarm definition can include a detailed SOP that guides operators through the response procedure.

SOP Components

Instructions : Free-text steps describing the response procedure: verification, escalation contacts, physical response, documentation requirements.

Checklists : Structured action items that the operator must complete. Each item is individually checkable, creating an audit trail of completed steps.

Checklist: Perimeter Breach Response
  [ ] Verify alarm on live camera feed
  [ ] Check adjacent cameras for corroborating activity
  [ ] Contact on-site security: +27 82 555 1234
  [ ] If confirmed: dispatch response team
  [ ] If false alarm: close with "False Alarm" resolution
  [ ] Complete incident report in shift log

Checklist completion is tracked per alarm instance. Supervisors can review which steps were completed and when.

Notification Channels

Notifications are sent through configured channels when alarms trigger:

Channel	Description
Telegram	Message to a Telegram bot/group with alarm details and camera snapshot
Discord	Message to a Discord webhook with alarm details and snapshot
Email	Email to configured recipients with full alarm context
SMS	Text message to phone numbers (via configured SMS gateway)
Push	Mobile push notification (via Meridian mobile app)
Webhook	HTTP POST to a custom URL with JSON payload

Escalation Levels

Each alarm definition supports multiple escalation levels. If an alarm is not acknowledged within the configured time, it escalates to the next level with different notification routing.

Escalation Configuration

Level	Time Threshold	Notification Channels
Level 1	Immediate (on trigger)	Telegram to control room operators
Level 2	5 minutes unacknowledged	SMS to shift supervisor + email to security manager
Level 3	15 minutes unacknowledged	Email to site management + phone call via webhook

Each level has its own set of notification channels and recipients. This ensures the right people are notified based on response urgency.

Per-Level Channel Routing

Different escalation levels can use entirely different notification channels:

Level 1: Telegram (control room group)
Level 2: SMS (supervisor phone) + Email ([email protected])
Level 3: Email ([email protected]) + Webhook (paging system API)

This allows a graduated response where initial alerts go to frontline operators, and progressively more urgent channels are used if the alarm remains unhandled.

Alarm Lifecycle

Every alarm instance follows a defined lifecycle:

New  -->  Acknowledged  -->  Investigating  -->  Closed
                |                  |
                |                  +--> On Hold --> Investigating
                |
                +--> Closed (false alarm)

State	Description
New	Just triggered. No operator has responded. Escalation timer is running.
Acknowledged	An operator has taken ownership. Escalation timer stops.
Investigating	Active investigation in progress, following the SOP.
On Hold	Paused (awaiting physical response, external information). Resumes to Investigating.
Closed	Resolved. Operator records a resolution note and category.

Each transition is logged with operator name, timestamp, and optional notes — providing a complete audit trail.

Resolution Categories

When closing an alarm, the operator selects a resolution:

Resolution	Description
Confirmed	Real incident, response was appropriate
False Alarm	No actual incident (environmental trigger, animal, etc.)
Test	Intentional test of the alarm system
Duplicate	Same incident already handled by another alarm

Alarm Dashboard

The alarm dashboard at Operations > Alarms provides a real-time view of all active alarms.

Dashboard Features

Feature	Description
Real-time updates	New alarms appear instantly via WebSocket push
Priority sorting	Critical alarms pinned to top, sorted by age within priority
Category filters	Filter by alarm category, priority, state, or camera
Quick actions	Acknowledge, view SOP, open camera feed — all from the dashboard
Sound alerts	Configurable audio alerts for new Critical and High priority alarms
Map view	Alarms plotted on site maps by camera location
Statistics	Response time averages, alarm counts by type, false alarm rates

Duplicate Prevention

Only one open alarm can exist per definition/camera pair. Repeat triggers update the existing alarm’s event count rather than creating duplicates.

Startup Grace Period

When the management server starts or a recording server reconnects, alarm evaluation is paused for 5 minutes. This prevents false “offline” alarms during planned restarts. Events are still recorded during the grace period.

External API

Third-party systems can create, query, and manage alarms via the REST API.

Creating External Alarms

curl -X POST https://vms.example.com/api/alarms/external \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Access Control Breach",
    "description": "Door forced open at Building A entrance",
    "priority": "critical",
    "camera_id": "550e8400-e29b-41d4-a716-446655440000",
    "metadata": {"door_id": "A-101", "source": "access_control"}
  }'

API Reference

Method	Endpoint	Description
GET	/api/alarms	List alarms with filters (state, priority, camera, date range)
GET	/api/alarms/{id}	Get alarm details with full audit trail
POST	/api/alarms/external	Create an alarm from an external system
PATCH	/api/alarms/{id}/acknowledge	Acknowledge an alarm
PATCH	/api/alarms/{id}/state	Transition alarm state
PATCH	/api/alarms/{id}/checklist/{item}	Check/uncheck an SOP checklist item
POST	/api/alarms/{id}/notes	Add a note to an alarm
GET	/api/alarms/stats	Alarm statistics and response metrics
GET	/api/alarms/definitions	List alarm definitions
POST	/api/alarms/definitions	Create an alarm definition
PATCH	/api/alarms/definitions/{id}	Update an alarm definition
DELETE	/api/alarms/definitions/{id}	Delete an alarm definition

RBAC and Visibility

• Operators see alarms only for cameras within their permitted locations.
• Alarm definition management requires administrative permissions.
• SOP checklists and state transitions are attributed to the logged-in user for audit.
• Escalation notifications respect role hierarchy — Level 3 notifications target users with supervisory roles.