PI Web API Trigger Node

Overview

The PI Web API Trigger Node automatically initiates MaestroHub pipelines when an OSIsoft / AVEVA PI System stream produces a new value, delivered through PI Web API Stream Updates. Unlike the PI Read nodes, which read a value inside an already-running pipeline, the PI Web API Trigger starts a new pipeline execution on each value change — enabling event-driven automation without you running a read loop.

The trigger is backed by a Subscribe (Stream Updates) function (piwebapi.subscribe) authored on a PI Web API connection. The connector registers the stream with PI, polls a marker URL on the function's configured interval, and emits every event that arrived since the previous poll.

---

Core Functionality

What It Does

1. Event-Driven Pipeline Execution Start pipelines automatically whenever the subscribed stream produces a new value. Latency is bounded by the function's Poll Interval (1–60 s).

2. Marker-Based Stream Updates The connector registers the stream once (POST /streams/{webId}/updates), then polls the returned marker on the configured interval. Each poll returns any events since the previous marker and advances it. A poll that returns nothing new is normal and emits no trigger.

3. Automatic Subscription Lifecycle The subscription is created when the pipeline becomes enabled and torn down when it's disabled. When PI expires the update marker (default ~30 minutes), the connector re-registers transparently — no manual subscription management required.

4. No Connector-Side Deduplication Every PI value envelope carries its own timestamp, so consecutive payloads differ even when the numeric value repeats. Like the OPC UA and Ignition triggers, the PI trigger does not hash-dedup — a repeated value with a new timestamp is a real new event. There is intentionally no onChange toggle, because one that could never suppress would mislead.

---

How PI Web API Triggering Works

PI Web API triggering is fundamentally different from on-demand reads:

Aspect	Get Current / Recorded (Read)	Subscribe (Trigger)
Model	Request-response (pull)	Poll-based streaming
Execution	One-time read per call	Continuous — one execution per new value
Lifecycle	Stateless	Stateful Stream Updates registration + marker polling
Use Case	On-demand data access	Real-time reaction to value changes

When you configure a PI Web API Trigger:

1. MaestroHub resolves the stream named by the Subscribe function to a WebID and registers it for Stream Updates.
2. The connector polls the marker on the function's Poll Interval; each poll returns any new events.
3. Each event is one value envelope (timestamp, value, quality) plus an action (Add / Update / Remove / Refresh).
4. The pipeline executes with the value available as $trigger.result and stream metadata as $trigger._metadata.

---

Reconnection Handling

MaestroHub automatically handles transport disruptions and marker expiry.

Automatic Recovery

Scenario	Behavior
Marker expired (PI evicted the update cache)	The connector re-registers with a new marker and resumes polling automatically.
Transient network error / failed poll	The poll is retried on the next tick; the subscription is not torn down (Stream Updates is self-healing).
PI restart / connection lost	Subscriptions are re-registered once the PI Web API host is reachable again.
MaestroHub restart	All triggers for enabled pipelines are restored on startup.

Minimising data loss

Stream Updates keeps only a bounded update cache. Events that occur entirely within a disconnection window — before the connector re-registers — are not replayed. For gap-critical signals, complement the trigger with a periodic Get Recorded read driven by a Schedule trigger so a polled backfill lands even if a live event is missed.

---

Configuration Options

Basic Information

Field	Type	Description
Node Label	String (Required)	Display name for the node on the pipeline canvas. Must be non-empty (trimmed).
Description	String (Optional)	Explains what this trigger initiates.

---

Configuration

The trigger configuration is organized across two tabs in the UI: Parameters and Settings.

Parameter	Type	Default	Required	Description
PI Web API Connection	Connection ID	""	Yes	The PI Web API connection profile to subscribe through. Filtered to PI Web API connections only.
Subscribe Function	Function ID	""	Yes	The piwebapi.subscribe function that defines the subscription (stream path + poll interval). Filtered to subscribe functions on the selected connection.
Enable Trigger	Boolean	true	No	When disabled, the subscription is not created even if the pipeline is enabled.

Function Requirement

The selected function must be a Subscribe (Stream Updates) function type (piwebapi.subscribe). Read and Write functions cannot be used with the PI Web API Trigger.

If the selected connection has no Subscribe functions yet, use the Edit connection link in the picker to jump to the connection's Functions tab and author one.

Subscribe Function Configuration

The selected function (authored in the Connect module) controls which stream is monitored and how often:

Setting	Description
Stream Path	The PI Point or AF attribute path to monitor (not templatable — one concrete stream).
Poll Interval (seconds)	How often to fetch new events (1–60). Lower = lower latency but more load on the PI Web API host.

See Subscribe (Stream Updates) for the full function reference.

Sample Payload

The Parameters tab also holds a Sample Payload editor and a Sample Quality picker. When you run the node with Test Node in Sandbox mode, the trigger emits the sample payload as result instead of waiting for a real Stream Updates event, so you can validate downstream nodes before a live PI stream is wired up. Sample Quality sets the quality the sample reports in $trigger._metadata.quality (good, uncertain or bad). The live subscription and the node's Fire Trigger action do not use the sample. Write the sample in the PI value envelope:

{
  "timestamp": "2026-05-21T08:00:00Z",
  "value": 42.1,
  "good": true
}

---

Settings

Execution Settings

Setting	Options	Default	Description
On Error	Pipeline Default / Stop Pipeline / Continue Execution	Pipeline Default	Behavior when the node fails.

---

Output Data Structure

When a Stream Updates event arrives and triggers pipeline execution, the trigger produces a structured output with two top-level keys: _metadata and result. One event is emitted per delivered value.

Output Format

{
  "_metadata": {
    "type": "piwebapi_trigger",
    "protocol": "piwebapi",
    "connectionId": "bf29be94-fc0a-4dc4-8e5c-092f1b74eb4b",
    "functionId": "aef374c3-aa2b-454e-aabc-5657faac5950",
    "piPath": "\\\\PISERVER\\Production\\Boiler1|Temperature",
    "webId": "F1AbEx...",
    "action": "Add",
    "timestamp": "2026-05-21T08:00:00Z"
  },
  "result": {
    "timestamp": "2026-05-21T08:00:00Z",
    "value": 72.5,
    "unitsAbbreviation": "°C",
    "good": true,
    "questionable": false,
    "substituted": false,
    "annotated": false,
    "action": "Add"
  }
}

result Fields

Field	Type	Description
value	any	The new stream value — numeric, string, or digital-state depending on the tag's PointType.
timestamp	string	ISO 8601 / RFC 3339 — the PI source timestamp for this value (UTC).
unitsAbbreviation	string	Engineering units abbreviation (may be empty).
good / questionable / substituted / annotated	boolean	PI quality flags for the value.
action	string	The Stream Updates action that produced the event: Add, Update, Remove, or Refresh.

_metadata Fields

Field	Type	Description
type	string	Always "piwebapi_trigger".
protocol	string	Always "piwebapi".
connectionId	string	The PI Web API connection profile ID.
functionId	string	The Subscribe function ID.
piPath	string	The monitored PI point or attribute path. Named for PI because path is the HTTP route on the webhook trigger — one word, one meaning.
webId	string	The resolved WebID of the monitored stream.
action	string	The Stream Updates action for this event.
timestamp	string	ISO 8601 / RFC 3339 — the value's source timestamp, UTC.

Referencing in Downstream Nodes

Use expressions to access trigger data in subsequent nodes:

• $trigger.result.value — the new stream value
• $trigger.result.timestamp — the PI source timestamp
• $trigger.result.good — the quality flag (gate on this to ignore bad data)
• $trigger._metadata.piPath — the monitored PI point or attribute path
• $trigger._metadata.connectionId — connection profile used
• $trigger._metadata.functionId — Subscribe function used

---

Validation Rules

Node Label

• Must not be empty or whitespace-only
• Error: "Node name is required"

PI Web API Connection

• Must be provided and non-empty
• Error: "PI Web API connection is required"

Subscribe Function

• Must be provided and non-empty
• Must be a piwebapi.subscribe function belonging to the selected connection
• Error: "Subscribe function is required"

Enabled Flag

• Must be a boolean if provided
• Error: "Enabled must be a boolean value"

---

Usage Examples

Real-Time Value Reaction

Key configuration

• Label: Boiler Temp Watcher
• Connection: Production PI Web API
• Function: Subscribe on \\PISERVER\Production\Boiler1|Temperature, poll interval 1 s
• Enabled: true
• Settings: on error stop

Downstream usage: $trigger.result.value for the temperature, $trigger.result.timestamp for the sample time. Forward into an Aggregator node to compute a sliding-window average before publishing to the Unified Namespace.

Alarm / Status Monitoring

Key configuration

• Label: Pump Status Monitor
• Connection: Production PI Web API
• Function: Subscribe on a status attribute, poll interval 2 s
• Enabled: true
• Settings: on error continue

Downstream usage: gate on $trigger.result.good to ignore bad-quality events, then branch on $trigger.result.value with a Switch node to route by state.

Change-Driven Historian Fan-Out

Key configuration

• Label: Tag Change Recorder
• Connection: Production PI Web API
• Function: Subscribe on a key process tag

Downstream usage: on each value, write to a time-series database or MQTT topic. Because every event carries its own timestamp, downstream sinks receive faithfully-timestamped points without client-side clock work.

---

Best Practices

Subscription Design

• Tune the Poll Interval to the latency you need. 1 s is the lowest; a larger interval reduces load on the PI Web API host when sub-second latency isn't required.
• Subscribe to the streams you act on, not everything. Each subscription is a registered Stream Updates poll loop against the PI host — keep the count reasonable per connection.
• Gate on quality. Check $trigger.result.good before acting on a value if the source can produce questionable or substituted data.

Designing for Reliability

Practice	Rationale
Add a polled Read fallback for gap-critical signals	Events during a disconnection window are not replayed — a periodic Schedule-driven Get Recorded backstops the live trigger
Spread subscriptions across connections	Many high-rate streams on one connection add polling load to a single PI host session
Buffer high-rate streams downstream	An Aggregator smooths bursts so a slow consumer never stalls processing

Error Handling Strategies

For Critical Workflows: set On Error to Stop Pipeline, monitor execution failures on the Health dashboard, and alert on stopped pipelines.

For Best-Effort Processing: set On Error to Continue Execution, log failed executions for later analysis, and ensure downstream nodes tolerate partial failures.

Enable vs. Disable

• Use the trigger's Enable Trigger toggle to pause monitoring without changing pipeline state.
• Disable triggers during maintenance windows to avoid processing stale reconnection data.
• Document the reason for disabled triggers in the node's Description field.