Systems & Locations

Zabbix monitors individual devices. AV operators think in rooms. Omniglass bridges the gap with four concepts:

• A system groups monitored devices into an operational unit (a conference room, a video wall, a broadcast chain).
• A system type classifies a system and attaches monitoring behavior to it (templates, synthetic checks).
• A location places things in a physical hierarchy (campus, building, floor, room).
• A location type defines the levels of that hierarchy and what metadata each level carries.

graph TD
    LT[Location Type] -- classifies --> L[Location]
    ST[System Type] -- classifies --> S[System]
    ST -- links to --> T[Zabbix Template]
    L -- contains --> CL[Child Location]
    L -- contains --> S
    S -- contains --> Sub[Subsystem]
    S -- members --> H[Zabbix Host]

    style LT fill:#1a3a38,stroke:#21cab9,color:#fff
    style L fill:#1a3a38,stroke:#21cab9,color:#fff
    style CL fill:#1a3a38,stroke:#21cab9,color:#fff
    style ST fill:#1a3a38,stroke:#21cab9,color:#fff
    style S fill:#1a3a38,stroke:#21cab9,color:#fff
    style Sub fill:#1a3a38,stroke:#21cab9,color:#fff
    style T fill:#121a2e,stroke:#445,color:#aaa
    style H fill:#121a2e,stroke:#445,color:#aaa

Systems live in locations, but they are independent concepts. All systems are in locations (unless not yet assigned); not all locations contain systems, and locations are not systems. A few examples to illustrate how the model handles real environments:

• Standard campus. A campus contains buildings, buildings contain floors, floors contain rooms. Each room has one system — a conference room with a codec, display, DSP, and camera. The location hierarchy gives you geographic filtering; the system gives you per-room health.
• Divisible room. One large ballroom (a location) contains a central AV system and three partition subsystems, each with its own location within the ballroom. A failure in the central system impacts all subsystems. A failure in one partition does not affect the others. The location hierarchy and the system hierarchy are modeled independently.
• Signage zones. A cafeteria (a location) has child locations called zones. Each zone contains a digital signage system. The signage systems share a system type, so they all get the same monitoring templates, but they report health independently per zone.
• Mobile cart. A portable broadcast kit is a system with no fixed location. It has members (camera, encoder, switcher) and a system type, but no location assignment. It can be placed into a location when deployed and removed when packed up.

---

Systems

A system represents something an operator would point at and say “that is one thing.” It might be a conference room with a codec, a display, a DSP, and a camera. It might be a video wall with a controller and sixteen panels. The system is the unit of health, the unit of reporting, and the unit of accountability.

What you get

When you create a system and assign devices to it:

• One health status for the whole system, computed from all member devices
• One place to look for every device in the room, its alerts, and its metrics
• Filtering and reporting by system across every native Zabbix page (dashboards, problems, SLA reports)
• Tag propagation — tags you set on the system automatically appear on every member device

Membership

Operators assign hosts to systems through Omniglass. A host can belong to one system (or one system and its subsystem simultaneously). Manual edits in Zabbix are treated as drift and corrected automatically.

Subsystems

Most systems are flat: one system, some devices. For more complex installations, a system can contain subsystems for functional decomposition:

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

The hierarchy is limited to two levels. Subsystems inherit their parent’s location and Zabbix host group.

---

System types

A system type classifies a system and attaches monitoring behavior to it. Types answer the question: “What kind of system is this, and what should we check?”

When you assign a type to a system, Omniglass creates a system host — a virtual Zabbix host that represents the system as a whole. The type’s templates are linked to this host, giving the system its own items, triggers, and calculated metrics without touching the member devices.

Example

A “Conference Room” type might link to templates that:

• Run a synthetic dialing test every 15 minutes via a Node-RED workflow
• Calculate an aggregate availability score from all member devices
• Poll the room’s UCaaS booking status from a cloud API

Every conference room system gets these checks automatically when the type is assigned. Change the type’s templates, and every conference room updates on the next reconciliation sweep.

System host properties

Each system host carries macros so that a single template works across all systems of the same type:

Macro	Example value
{$OG_SYSTEM_NAME}	board-room-302
{$OG_SYSTEM_TYPE}	conference-room
{$OG_SYSTEM_GROUP}	Systems/board-room-302

A template item with URL http://nodered:1880/workflow/check/{$OG_SYSTEM_NAME} resolves differently for each system host.

---

Locations

Locations model your physical environment as a hierarchy. The default levels are campus, building, floor, and room, but you can define your own location types to match your organization.

What you get

When you create a location hierarchy and assign systems to locations:

• Geographic filtering — show me all systems in Building A, or on Floor 3, or in the EMEA campus
• Inherited coordinates — set latitude/longitude on a building, and every room inside it inherits those coordinates into host inventory fields
• Custom metadata — each location type defines a schema for structured data (room capacity, AV tier, building code)
• Native Zabbix integration — locations project as host groups, so location-based filtering works in dashboards, problems, SLA reports, and maps

Hierarchy

North America (campus)
  └── Headquarters (building)
      ├── Floor 1
      │   ├── Lobby Display (system)
      │   └── Reception Desk (system)
      └── Floor 3
          ├── Room 301 (system)
          ├── Room 302 (system)
          └── Room 303 (system)

A child location’s type must have a strictly higher sort order than its parent. This prevents nonsensical hierarchies (a campus inside a room). Sibling names must be unique within their parent.

Location types

Location types define the levels of your hierarchy and are ordered by sort_order:

Type	Sort Order
Campus	10
Building	20
Floor	30
Room	40

You can add custom types (e.g., “Wing” at sort order 25) or redefine the defaults entirely.

---

Systems and locations together

A system can have both a type and a location:

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

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

Both the Systems/ and Locations/ host group trees are visible in native Zabbix. An operator can filter problems by system (“show me Board Room 302”) or by location (“show me everything on Floor 3”) using stock Zabbix pages.

The distinction matters

All systems are in locations. But systems and locations are not the same thing.

	System	Location
Represents	A functional unit (room AV, signage cluster, broadcast chain)	A physical place (campus, building, floor, room)
Has members	Yes — monitored hosts are assigned to it	No — hosts belong to systems, which belong to locations
Has health status	Yes — computed from member devices	No — a building does not have a health score
Can exist without the other	Yes — a mobile kit has no location	Yes — an empty floor has no systems
Zabbix projection	Systems/ host group tree	Locations/ host group tree

A location with no systems is simply an empty node in the hierarchy. A system with no location is fully functional — it just does not appear in the location-based host group tree.

---

How it works under the hood

Implementation detail

The rest of this page covers the Zabbix projection model, reconciliation mechanics, and drift handling. This is reference material for operators who need to understand what Omniglass creates in Zabbix and how it maintains consistency. You do not need to read this to use systems and locations.

Zabbix projection

Every system and location is projected into Zabbix as a host group:

Omniglass entity	Zabbix artifact
System “Board Room 302”	Host group Systems/board-room-302
Subsystem “Decoder Bank” under “Video Wall”	Host group Systems/video-wall/decoder-bank
Location “HQ / Floor 3 / Room 302”	Host group Locations/hq/floor-3/room-302
System with type assigned	Virtual host og-system-<id> with type’s templates

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.

System host details

When a system has a type assigned, the reconciler creates a virtual host with these 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>

Reconciliation

The control plane continuously reconciles projected state against desired state through two mechanisms:

Audit-log polling (every 1 second): The control plane polls the Zabbix audit log for relevant events (host group changes, host membership changes, host deletion) and triggers 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 safety-net sweep checks all systems and locations for correctness — host groups exist and names match, membership is correct, system hosts have the right templates, tags, and macros, and location coordinates are synced to host inventory.

Drift handling

Manual edits in Zabbix that conflict with Omniglass state are treated as drift and corrected automatically:

Drift	Resolution
Host added to group via Zabbix UI	Removed
Host removed from group via Zabbix UI	Re-added
Host group renamed or deleted	Renamed back or recreated
System host deleted or templates changed	Recreated or reset
System host tags/macros changed	Reset
Orphaned Locations/* group	Deleted

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

Lifecycle reference

System 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.
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

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

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
• Additive og_ columns on Zabbix tables (from build-time patches) remain but are inert without Omniglass
• 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.