UNS trigger node
UNS Trigger Node
Start a pipeline when a value is published to Unified Namespace topics that match your patterns, including + and # wildcards.
- Starts on
- A publish to a matching UNS topic
- Wildcards
- + for one level · # for the rest, last only
- Trigger mode
- always (default) · onChange
Overview
The UNS Trigger Node automatically initiates MaestroHub pipelines when data is published to matching Unified Namespace topics. Unlike the UNS connector nodes which publish, fetch, or search within an already-running pipeline, the UNS Trigger starts new pipeline executions in response to incoming data events, enabling fully event-driven automation on your UNS infrastructure.
Core Functionality
What It Does
UNS Trigger enables real-time, event-driven pipeline execution by:
1. Event-Driven Pipeline Execution Start pipelines automatically when data is published to matching UNS topics, without manual intervention or polling. Perfect for reacting to real-time production data, equipment state changes, and cross-system data flows.
2. Flexible Topic Matching with Wildcards
Subscribe to specific topics or use MQTT-style wildcards (+ and #) to match multiple topics with a single pattern. Multiple topic patterns can be configured on a single trigger.
3. Data Payload Passthrough
Incoming UNS data (topic, payload, and timestamp) is passed directly to the pipeline, making it available to all downstream nodes via the $trigger variable. The published value is {{ $trigger.result }}; {{ $trigger._metadata }} carries topic, timestamp, workspaceId, retain, source (when the publisher identified itself) and quality (the quality the record was stored with, as good, uncertain or bad), plus quality_reason when the store kept one (comm_error, range_violation, stale, out_of_service, …). A UNS Publish node downstream inherits the quality and its reason automatically, so a reading a device reported as bad stays bad · comm_error through every pipeline that re-publishes it.
Topic Pattern Wildcards
UNS Trigger supports MQTT-style wildcard patterns for flexible topic matching.
What you type
In the Topic Patterns field you type only the path inside your workspace. The panel adds the other two levels for you:
- The version (for example
mHv1.0) comes from the dropdown in front of the field. - The workspace is your current workspace's slug, shown as a locked chip between the dropdown and the field.
So typing enterprise/site1/+/temperature with version mHv1.0 in a workspace whose slug is acme subscribes to mHv1.0/acme/enterprise/site1/+/temperature. The Subscribed Topics list shows this full form. If you paste a full topic that starts with a version, such as one copied from that list, the panel splits it back into the version and the path. Do not start the path with your workspace: the panel already adds it, so it would appear twice and the pattern would match nothing.
The examples below are written the way you type them.
| Wildcard | Behavior | Example | Matches |
|---|---|---|---|
+ | Matches exactly one level | +/temperature | site1/temperature, site2/temperature |
# | Matches zero or more levels at the end | enterprise/# | enterprise/site1, enterprise/site1/area1/temp |
+/+ | Multi-level single wildcards | +/+/pressure | Any site and area combination under pressure |
+ and # combined | Single-level then multi-level | +/packaging/# | Any site, all topics under packaging |
The multi-level wildcard (#) must be at the end of the topic pattern. Patterns like enterprise/#/temperature are invalid and will fail validation.
Configuration Options
Basic Information
| Field | Type | Description |
|---|---|---|
| Node Label | String (Required) | Display name for the node on the pipeline canvas |
| Description | String (Optional) | Explains what this trigger initiates |
Parameters
| Parameter | Type | Default | Required | Constraints | Description |
|---|---|---|---|---|---|
| Topic Patterns | string[] | [] | Yes | At least one | UNS topic paths to subscribe to. Pick the version, then type the path inside your workspace; see What you type. Supports + and # wildcards. |
| Trigger Mode | select | "always" | No | always / onChange | always: Trigger on every message. onChange: Only trigger when payload differs from last received value per topic. |
| Enabled | boolean | true | No | -- | Enable/disable the trigger. When disabled, the trigger will not listen for UNS data events. |
Change Detection Settings (Trigger Mode = onChange)
When Trigger Mode is set to onChange, additional settings control how payload deduplication works:
| Parameter | Type | Default | Constraints | Description |
|---|---|---|---|---|
| Max Tracked Topics | number | 1000 | 1-10,000 | Maximum number of distinct topics tracked for change detection. When exceeded, the least recently used topic is evicted. |
- The first message after a pipeline restart always fires, regardless of trigger mode.
- Change detection state is held in memory and resets when MaestroHub restarts.
Settings
Description
A free-text area for documenting the node's purpose and behavior. Notes entered here are saved with the pipeline and visible to all team members.
Execution Settings
| Setting | Options | Default | Description |
|---|---|---|---|
| Timeout (seconds) | number | Pipeline default | Maximum execution time for this node (1-3600). Leave empty for pipeline default. |
| Retry on Timeout | Pipeline Default / Enabled / Disabled | Pipeline Default | Whether to retry the node if it times out. |
| Retry on Fail | Pipeline Default / Enabled / Disabled | Pipeline Default | Whether to retry on failure. When Enabled, shows Advanced Retry Configuration. |
| On Error | Pipeline Default / Stop Pipeline / Continue Execution | Pipeline Default | Behavior when node fails after all retries. |
Advanced Retry Configuration (visible when Retry on Fail = Enabled)
| Field | Type | Default | Range | Description |
|---|---|---|---|---|
| Max Attempts | number | 3 | 1-10 | Maximum retry attempts. |
| Initial Delay (ms) | number | 1000 | 100-30,000 | Wait before first retry. |
| Max Delay (ms) | number | 120000 | 1,000-300,000 | Upper bound for backoff delay. |
| Multiplier | number | 2.0 | 1.0-5.0 | Exponential backoff multiplier. |
| Jitter Factor | number | 0.1 | 0-0.5 | Random jitter (+-percentage). |
Output Data Structure
When a matching UNS topic is published, the following data is available to downstream nodes via the $trigger variable.
A pipeline never triggers itself
A pipeline whose UNS Publish writes a topic its own UNS trigger subscribes to, directly or through other pipelines (A writes the topic B listens to, and B writes the topic A listens to), would start itself again on every run. MaestroHub refuses the second start: the run is recorded as failed with the reason "this pipeline already led to this value", naming the pipelines on the way, and nothing else happens. A longer chain where no pipeline appears twice (raw → clean → KPI → alert) runs as usual.
The designer warns while you build when a publish topic falls inside the same pipeline's subscription. To fix it, publish to a topic outside the subscription, or narrow the subscription.
Output Format
{
"_metadata": {
"type": "uns_trigger",
"topic": "enterprise/site1/line3/temperature",
"workspaceId": "workspace-1",
"retain": false,
"source": "mqtt-broker",
"quality": "good",
"timestamp": "2026-09-05T14:47:19.123Z"
},
"result": {
"value": 21.5,
"unit": "C"
}
}
Accessing Published Data
| Field | Expression | Description |
|---|---|---|
| Published Value | $trigger.result | The value published to the topic, exactly as stored; $trigger.result.value reads a field of an object value |
| Topic | $trigger._metadata.topic | The topic that was published; with a wildcard pattern, the concrete topic that matched |
| Workspace | $trigger._metadata.workspaceId | The ID of the workspace the topic belongs to |
| Retain | $trigger._metadata.retain | true when the publish was a retained write; a boolean, unlike connector triggers whose values are all strings |
| Source | $trigger._metadata.source | Who published; present only when the publisher identified itself |
| Causation | $trigger._metadata.causation | What led to the value: for a value a pipeline wrote, each pipeline on the way (pipeline:<id>). Present only when the publisher set one |
| Quality | $trigger._metadata.quality | The quality the record was stored with: good, uncertain or bad; present when the record carries one |
| Trigger Type | $trigger._metadata.type | Always uns_trigger |
| Timestamp | $trigger._metadata.timestamp | When the value was published (RFC 3339, UTC) |
Validation Rules
The UNS Trigger Node enforces these validation requirements:
Parameter Validation
Topic Patterns
- At least one topic pattern must be provided
- Each topic pattern must be a non-empty string
- Multi-level wildcard (
#) must be at the end of the pattern (e.g.,enterprise/#is valid,enterprise/#/temperatureis not)
Node Label
- Must be provided and non-empty
Usage Examples
Real-Time Production Monitoring
Scenario: React to live production metrics published to the UNS.
Configuration:
- Label: Production Metrics Monitor
- Topics:
enterprise/plant-1/+/production/# - Trigger Mode: always
- Enabled: true
Downstream Processing:
- Parse payload to extract OEE metrics
- Compare against target thresholds
- Update dashboard via REST API
- Send alerts if metrics fall below targets
Equipment State Change Detection
Scenario: Trigger workflows only when equipment state actually changes, ignoring duplicate readings.
Configuration:
- Label: Equipment State Watcher
- Topics:
+/+/equipment/+/state - Trigger Mode: onChange
- Max Tracked Topics: 5000
- Enabled: true
Downstream Processing:
- Identify which equipment changed state
- Log state transition to database
- Notify maintenance team for fault states
- Update digital twin model
Cross-Plant Data Aggregation
Scenario: Aggregate quality data from multiple plants for centralized analytics.
Configuration:
- Label: Quality Data Aggregator
- Topics:
enterprise/+/quality/# - Trigger Mode: always
- Enabled: true
Downstream Processing:
- Extract plant identifier from topic path
- Normalize quality metrics across plants
- Write aggregated data to InfluxDB
- Generate cross-plant quality reports
Configuration reference
The fields below are generated from the node's config contract, so they match what the pipeline validator enforces and what the designer's form offers.
trigger.uns.subscribe
| Field | Type | Required | Default | Values | Description |
|---|---|---|---|---|---|
topics | string[] | yes | - | - | UNS topic patterns to subscribe to, each including the version prefix, e.g. mHv1.0/<workspace-slug>/line1/temperature; + matches one level (mHv1.0/<workspace-slug>/+/temperature), # matches the rest of the path and must be last (mHv1.0/<workspace-slug>/line1/#). A pattern without the prefix never matches. The received payload is the node's result |
triggerMode | string | no | always | always, onChange | always fires on every message; onChange fires only when the payload differs from the last one seen on the same topic (state resets on restart, so the first message after a restart always fires) |
dedupMaxKeys | integer | no | - | 1 to 10000 | onChange mode: how many distinct topics this node remembers a last payload for, 1 to 10000; when exceeded the least recently seen topic is forgotten. Empty uses the system default (1000) |
enabled | boolean | no | true | - | false pauses this trigger without deleting it: the topics are not subscribed and nothing fires. Default true |
testData | any | no | - | - | Message payload the designer's sandbox (Test) run pretends to receive, read downstream as $trigger.result exactly as a real message would be. Unused in production |
testTopic | string | no | - | - | Sandbox (test run) only: the topic the run pretends the message arrived on, read downstream as $trigger._metadata.topic. A concrete topic one of the topics patterns covers, e.g. mHv1.0/<workspace-slug>/line1/temperature for mHv1.0/<workspace-slug>/+/temperature. Empty uses the first pattern as it is, wildcards included. Ignored by the live subscription |
sandboxQuality | string | no | - | good, uncertain, bad | Sandbox (test run) only: the quality band the sample trigger reports in _metadata.quality; good, uncertain or bad; so a quality-aware pipeline can be tested before it meets a real device. Empty uses the good sample. Ignored by the live subscription; triggers whose metadata carries no quality make no statement |
lateValues | string | no | deliver | deliver, skip | What to do with a late value: a reading older than the UNS late threshold (60s unless the installation changed it) when it arrived, as a gateway replaying its buffer after an outage produces. deliver (the default) fires the pipeline with _metadata.late true, so archiving and forwarding keep working on replays; a write to a device in that run is refused unless its node allows late input. skip does not fire for late values at all; they are still stored |