Node-RED

Purpose

The Node-RED feature introduces Node-RED as the workflow automation layer in Omniglass. Node-RED is a flow-based programming tool that operators use to build custom automations — synthetic tests, device control sequences, event-driven workflows, data transformations, and ad-hoc integrations.

Node-RED serves as a Swiss Army knife for operators:

• Build synthetic test flows that Zabbix calls via HTTP agent items
• Automate device control sequences using vendor APIs (Crestron, Extron, AMX, etc.)
• Parse and transform data from external sources (email, webhooks, vendor portals)
• Bridge systems that lack native Zabbix integration
• Prototype automations visually before hardening them

Node-RED is a separate service, not part of the core binary. It connects to Zabbix through standard mechanisms (HTTP, zabbix_sender, trapper items). It has no dependency on Omniglass internals.

If Node-RED is removed, Zabbix continues to monitor normally. HTTP agent items that call Node-RED will show errors, and trapper items will stop receiving values — both of which are correct and visible to operators.

---

Design Principles

• Node-RED is optional and removable
• Node-RED does not own monitoring state — Zabbix does
• Node-RED does not own system structure — Omniglass does
• All Node-RED actions are transparent — flows are visual and inspectable
• Node-RED connects through supported Zabbix mechanisms (HTTP, trapper items, zabbix_sender)
• Operators own their flows — Omniglass does not generate, manage, or deploy Node-RED flows

---

Role in the Stack

┌──────────────────────────────────────────────────────┐
│ Omniglass Core                                       │
│  - System structure, types, reconciliation           │
│  - Projects system hosts into Zabbix                 │
│  - API for management                                │
└──────────────────────────────────────────────────────┘
         │                              │
         │ Zabbix API                   │ shared DB
         ▼                              ▼
┌──────────────────────────────────────────────────────┐
│ Zabbix Server                                        │
│  - Authoritative monitoring engine                   │
│  - Schedules checks (HTTP agent items)               │
│  - Stores results (item history)                     │
│  - Fires triggers, sends alerts                      │
│  - Calls Node-RED via HTTP agent items               │
│  - Receives results via trapper items                │
└──────────────────────────────────────────────────────┘
         │                              ▲
         │ HTTP request                 │ zabbix_sender / API
         ▼                              │
┌──────────────────────────────────────────────────────┐
│ Node-RED                                             │
│  - Workflow automation engine                        │
│  - Executes flows (vendor API calls, data transforms)│
│  - Returns results to Zabbix                         │
│  - Has access to shared wrapper scripts              │
└──────────────────────────────────────────────────────┘

Node-RED is a peer service on the backend network. It does not call the Omniglass API. It does not access the Omniglass database. It interacts with Zabbix through HTTP and zabbix_sender.

---

Deployment

Container

Node-RED runs as a container on the backend network, accessible to the Zabbix server at a known URL (e.g. http://nodered:1880).

The Node-RED container is added to the compose configuration.

Central vs Edge

For v1, Node-RED is deployed centrally alongside the Zabbix server. System hosts are monitored server-side (not via proxy), so HTTP agent checks from the server reach Node-RED directly.

Edge deployment (Node-RED per proxy site) is a future consideration for environments where test execution must happen close to the devices.

Shared Tooling

Node-RED gets access to the same wrapper scripts available on the Zabbix proxy (e.g. device control scripts for Crestron, Extron, AMX). These are mounted into the Node-RED container.

This allows Node-RED flows to call the same vendor API wrappers that proxy external checks use, reducing duplication and keeping device interaction patterns consistent.

Flow Persistence

Node-RED persists flows to a volume mount. Flows are JSON files that can be version-controlled, exported, and shared between environments.

---

Integration Patterns

Node-RED integrates with Zabbix through two patterns. Both use standard Zabbix item types.

Pattern A: HTTP Agent (Synchronous)

Zabbix HTTP agent items call Node-RED HTTP endpoints. Node-RED executes a flow and returns a JSON response. Zabbix stores the response as item data.

Best for checks that complete quickly (under 30 seconds).

Zabbix Server                    Node-RED
    |                                |
    |-- HTTP GET /check/room-302 --->|
    |                                |-- execute flow
    |                                |-- call vendor APIs
    |                                |-- evaluate result
    |<-- JSON response --------------|
    |
    stores in item history

Zabbix template item configuration:

• Type: HTTP agent
• URL: http://nodered:1880/check/{$OG_SYSTEM_NAME}
• Update interval: operator-defined schedule (e.g. 1h)
• Preprocessing: JSONPath to extract structured fields from the response

The {$OG_SYSTEM_NAME} macro is set on system hosts by the Omniglass reconciler (see FEAT_SYSTEM_TYPES.md), allowing one template to work across all systems of the same type.

---

Pattern B: HTTP Agent + Trapper (Asynchronous)

For long-running operations (30-120+ seconds). An HTTP agent item initiates the flow. Node-RED pushes results to trapper items when done.

Zabbix Server                    Node-RED
    |                                |
    |-- HTTP POST /test/start ------>|
    |<-- 202 Accepted ---------------|
    |                                |
    |                                |-- long-running operation
    |                                |-- (30-120 seconds)
    |                                |
    |<-- zabbix_sender: status ------|
    |<-- zabbix_sender: duration ----|
    |<-- zabbix_sender: result ------|

Zabbix template configuration:

• One HTTP agent item (initiator, fires at scheduled intervals)
• Trapper items for results (status, duration, measurements)
• Node-RED pushes to trapper items using zabbix_sender protocol or the Zabbix JSON-RPC API

---

Use Cases

Synthetic Testing

The primary motivating use case. Synthetic tests validate that AV systems are operationally ready by executing multi-step workflows.

Prerequisites: System types assigned to systems (see FEAT_SYSTEM_TYPES.md). The system type links to a Zabbix template that contains synthetic test items.

Example: Daily Call Test

Zabbix template “Convene Medium - Synthetic Tests” contains:

Item key	Type	Description
og.synth.call-test	HTTP agent	Calls Node-RED to run a call test
og.synth.status	Trapper	passed, failed, error (async push)
og.synth.duration_ms	Trapper	Test duration in milliseconds
og.synth.audio_db	Trapper	Audio level measurement

HTTP agent item URL: http://nodered:1880/test/{$OG_SYSTEM_NAME}/call

Node-RED flow:

[http in: GET /test/:systemName/call]
  → [http request: GET device-api/status]        (check device reachable)
  → [function: initiate call via vendor API]       (Crestron, Extron, etc.)
  → [delay: 5s]                                   (wait for call to connect)
  → [http request: POST device-api/audio/play]     (inject test tone)
  → [delay: 5s]                                   (wait for audio)
  → [http request: GET device-api/audio/levels]    (read audio metering)
  → [function: evaluate thresholds]                (pass/fail decision)
  → [http response: JSON result]                   (return to Zabbix)

Zabbix triggers (defined in the template, using standard Zabbix trigger expression syntax):

Expression	Severity	Description
last(/Convene Medium - Synthetic Tests/og.synth.status)<>"passed"	Average	Synthetic test failed
nodata(/Convene Medium - Synthetic Tests/og.synth.status,7200)	Warning	No test result in 2 hours

When the template is assigned to a system host, trigger expressions resolve against that host automatically. Operators see synthetic test results in native Zabbix dashboards, receive alerts through native Zabbix triggers, and manage test schedules through native Zabbix item intervals.

Audio metering verification:

The method for verifying audio levels is intentionally left to the Node-RED flow. Possible approaches:

• Read audio meters from the device’s own API (DSP input levels, codec stats)
• Analyze far-end audio in a SIP loopback call
• Query an in-room sensor via its API
• Any combination

The Node-RED flow encapsulates this logic. The Zabbix template only cares about the result.

---

Device Health Checks

Node-RED flows that query vendor APIs to check device health beyond what SNMP or ICMP provides.

Example: verify that a Crestron processor’s program is running, or that an Extron switcher’s input routing matches expected state.

---

Event-Driven Automation

Node-RED flows triggered by external events:

• Parse incoming email for AV support tickets
• Receive webhooks from vendor portals (firmware updates, license alerts)
• Bridge MQTT messages from IoT sensors to Zabbix trapper items

---

Data Transformation

Node-RED flows that transform data between formats:

• Convert vendor-specific API responses to Zabbix-compatible formats
• Aggregate data from multiple device APIs into a single result
• Normalize disparate vendor health models into a common schema

---

Zabbix Template Patterns

When building templates that call Node-RED, follow these conventions.

Item Key Naming

Use the og. prefix for items that call Node-RED endpoints:

• og.synth.* — synthetic test items
• og.check.* — health check items
• og.data.* — data collection items

Macro Usage

System hosts have macros set by the Omniglass reconciler:

Macro	Value	Set by
{$OG_SYSTEM_NAME}	System name	Reconciler
{$OG_SYSTEM_TYPE}	System type name	Reconciler

Templates should use these macros in HTTP agent URLs to parameterize requests per system.

Template Organization

Separate concerns into distinct templates:

• “Convene Medium - Monitoring” — standard monitoring items (SNMP, agent, etc.)
• “Convene Medium - Synthetic Tests” — items that call Node-RED for synthetic tests

System types can reference multiple templates. Keeping synthetic test items in a separate template allows operators to enable or disable synthetic testing independently of monitoring.

---

Configuration

Setting	Value	Description
Container name	nodered	Service name on backend network
Port	1880	Default Node-RED HTTP port
Flow storage	Volume mount	Persistent flow storage

No Omniglass core configuration is needed. The Node-RED URL appears only in Zabbix template items (HTTP agent URLs), not in core config.

---

Network and Access

Node-RED runs on the backend network only. It is not exposed to end users or external networks.

Access to the Node-RED editor (port 1880) should be restricted to operators with administrative access. Node-RED’s built-in authentication can be configured to require credentials for the editor UI.

The Zabbix server reaches Node-RED via HTTP on the backend network. No inbound access from Node-RED to Omniglass core or the Omniglass database is required or expected.

---

Related Features

• FEAT_SYSTEM_TYPES.md — System types provide the structural foundation. System hosts receive templates that may contain items calling Node-RED.
• FEAT_SYSTEMS.md — Systems define the operational units that system types classify.

---

What Survives Removal

If Node-RED is removed:

• HTTP agent items that call Node-RED will fail — Zabbix shows item errors, which is correct and visible
• Trapper items stop receiving values — triggers fire “no data” eventually
• All other monitoring continues normally
• No Zabbix or Omniglass state is lost
• Operators see the problem through standard Zabbix alerting

Node-RED has no persistent state in Omniglass. It is a stateless automation layer that can be added, removed, or replaced without affecting system structure, monitoring state, or item history.

---

Non-Goals (v1)

The following are explicitly out of scope:

• Omniglass management of Node-RED flows (operators create and manage flows directly)
• Flow deployment automation (operators deploy flows through the Node-RED editor or file system)
• Per-edge Node-RED deployment (central only for v1)
• Node-RED authentication or access control through Omniglass
• Node-RED integration with the Omniglass API or database
• Reference flow shipping with the distribution (document patterns, let operators create)
• SIP stack or audio processing libraries in the Node-RED container (use external services or wrapper scripts)

---

Summary

Node-RED is the workflow automation layer in Omniglass. It handles tasks that do not belong in the core binary or in Zabbix configuration alone — multi-step device interactions, vendor API orchestration, data transformations, and synthetic tests.

It connects through standard Zabbix mechanisms: HTTP agent items call Node-RED, Node-RED pushes results to trapper items. No custom bus components, no custom scheduler, no custom runner.

Combined with system types (FEAT_SYSTEM_TYPES.md), Node-RED enables synthetic testing as a natural consequence: assign a type to a system, link the type to a template with HTTP agent items pointing at Node-RED, and tests run on Zabbix’s native schedule. The core binary, Zabbix, and Node-RED each do what they already do well.