Systems & Locations

Omniglass introduces three connected concepts that give AV environments the structure Zabbix does not provide out of the box: systems, system types, and locations.

A system is a logical grouping of monitored devices (a conference room, a video wall, a broadcast chain).
A system type classifies the system and links it to Zabbix templates for monitoring.
A location places systems in a physical hierarchy (campus, building, floor, room).

All three are defined in Omniglass and projected into Zabbix as host groups, virtual hosts, and tags. If Omniglass is removed, the projected artifacts remain and Zabbix continues monitoring.

Systems

A system is an operational unit composed of one or more monitored hosts. Systems represent functional boundaries — what operators think of as “rooms” or “signal chains” — not individual devices.

Systems may optionally contain subsystems for functional decomposition:

Video Wall Controller
└── Decoder Bank
└── Display Cluster

Flat systems (no hierarchy) are expected to be the majority of deployments.

Zabbix projection

Each system is projected into Zabbix as a host group:

Systems/room-302
Systems/video-wall/decoder-bank

Host groups exist for visibility and compatibility with native Zabbix pages. They are not the source of truth — Omniglass is authoritative for system structure and membership.

Membership

Operators manage membership through Omniglass. A host may belong to a system and any of its subsystems simultaneously. Manual membership edits in Zabbix are treated as drift and corrected by the reconciler.

Lifecycle

Operation	What happens
Create system	Inserts row, creates Zabbix host group, stores `zbx_groupid`
Rename system	Updates host group name; descendant groups rename automatically
Move system	Updates `parent_id`; all descendant paths update
Delete system	Removes membership rows, deletes host group. Children must be deleted or reassigned first.

System Types

A system type classifies a system and links it to one or more Zabbix templates (e.g., “Conference Room”, “Huddle Space”, “Digital Signage”).

When a system has a type assigned, the control plane projects a system host — a virtual Zabbix host (og-system-<id>) that represents the system as a whole. The type’s templates are assigned to this host, giving the system its own monitoring items, triggers, and calculated metrics.

System host properties

Property	Value
Host name	`og-system-<system-id>`
Visible name	System display name
Host groups	The system’s projected host group
Templates	All templates from the system type
Tags	`og:system=<name>`, `og:system-type=<type-name>`

Host macros

The reconciler sets macros on each system host so templates can reference system context:

Macro	Value
`{$OG_SYSTEM_NAME}`	System name
`{$OG_SYSTEM_TYPE}`	System type name
`{$OG_SYSTEM_GROUP}`	Zabbix host group name

A single Zabbix template can work across all systems of the same type. For example, an HTTP agent item with URL http://nodered:1880/check/{$OG_SYSTEM_NAME} resolves differently for each system host.

Lifecycle

Operation	What happens
Assign type	Reconciler creates system host, assigns templates, sets tags and macros
Change type	Reconciler updates template assignment; old items removed by Zabbix
Remove type	Reconciler deletes system host; item history retained per Zabbix retention policy
Update type templates	All systems with that type get updated template assignments on next sweep

If a system has no type assigned, no system host is created.

Locations

A location places systems in a physical hierarchy. Locations model geography: campuses, buildings, floors, rooms.

Location types

Location types define the levels of the hierarchy and are ordered by sort_order. A child location’s type must have a strictly higher sort order than its parent’s.

Default types (seeded on first boot):

Type	Sort Order
Campus	10
Building	20
Floor	30
Room	40

Operators can define custom location types to match their organization.

Hierarchy and naming

Locations/north-america/headquarters/floor-3/room-302

Locations form a tree with scoped name uniqueness — siblings cannot share a name. The name field is used for Zabbix host group paths and cannot contain /. The optional display_name is used in the UI.

Coordinates

Locations can store geographic coordinates (latitude, longitude). Coordinates inherit down the tree: a room without explicit coordinates inherits from its floor, building, or campus. Coordinates are synced to Zabbix host inventory fields (location_lat, location_lon) on hosts in systems assigned to that location.

Metadata

Each location type defines a field_schema (JSON Schema) that describes what custom metadata locations of that type can carry. For example, a “Room” type might define fields for capacity, AV tier, or building code. Metadata is validated against the schema at creation and update time.

Zabbix projection

Each location is projected into Zabbix as a host group under the Locations/ prefix. When a system is assigned to a location, its member hosts are added to the location’s host group. This gives operators native Zabbix filtering and reporting by physical location.

Lifecycle

Operation	What happens
Create location	Inserts row, creates Zabbix host group
Rename/move location	Updates host group path; descendants update automatically
Delete location	Fails if location has children; removes host group
Assign system to location	System’s hosts join the location’s host group; coordinates propagate to host inventory

How they connect

A system can have both a type and a location:

Type determines what gets monitored (which templates, which checks)
Location determines where (which building, which floor, which room)

The reconciler keeps both projections in sync:

System: "Board Room 302"
  ├── Type: "Conference Room" → system host with conference room templates
  ├── Location: "HQ / Floor 3 / Room 302" → hosts in Locations/hq/floor-3/room-302 group
  └── Members: codec, display, DSP, camera → hosts in Systems/board-room-302 group

Both the Systems/ and Locations/ host group trees are visible in native Zabbix, so operators can filter and report by either dimension.

Reconciliation

The control plane continuously reconciles projected state against desired state.

Audit-log polling

The control plane polls the Zabbix audit log every 1 second. Relevant events (host group changes, host membership changes, host deletion) trigger targeted reconciliation for the affected systems and locations.

The audit log is used as a wake-up signal. Actual state is read directly from Zabbix via API.

Full sweep

Every 2 minutes, a full reconciliation sweep runs as a safety net. All systems and locations are checked for:

Host groups exist and names match
Host group membership matches
System hosts exist with correct templates, tags, and macros
Location coordinates are synced to host inventory

Drift handling

Drift	Resolution
Host added to group via Zabbix UI	Removed
Host removed from group via Zabbix UI	Re-added
Host group renamed	Renamed back
Host group deleted	Recreated
Host deleted in Zabbix	Membership rows cleaned up
System host deleted	Recreated with correct templates
System host templates changed	Reset to type’s templates
System host tags/macros changed	Reset
Orphaned `Locations/*` group	Deleted

All corrections emit reconciliation events visible in the administration UI and container logs.

What survives Omniglass removal

If Omniglass is removed:

All Zabbix host groups (Systems/*, Locations/*) remain
System virtual hosts remain with their templates, items, and triggers still executing
Full item and trigger history is retained
Host inventory coordinates remain set
No Zabbix schema modifications to undo
Omniglass schema tables can be dropped without affecting Zabbix

The projected artifacts are self-explanatory. An operator reading the Zabbix UI without Omniglass can still understand the structure from the host group names and system host naming convention.