# Pipeline nodes

> Every node of the pipeline editor with what it does, its settings, its outputs and the pipeline kinds it can be used in, plus the limits of a pipeline.

Source: https://proxus.io/docs/reference/pipeline-nodes

This page lists every node of the pipeline editor's **Canvas** tab. Each node has two names: the one in the
palette (used as the heading here) and the one at the top of its settings panel (given after "Panel name"). The
**Build** tab creates the same nodes from plain steps. How to build and publish a pipeline is in
[Pipelines](https://proxus.io/docs/automate/pipelines).

## Two kinds of pipeline

| Execution class | Runs | Starts from | Can use |
| --- | --- | --- | --- |
| **Transport Pipeline** | on each reading, before it is stored or sent anywhere. It can change, drop or set aside data. | exactly one **Transport Input** | the nodes marked **T** below |
| **Automation** | after the reading is stored. The stored data is not changed; the pipeline opens alarms, sends messages, writes to devices or calls APIs. | 1 to 8 source nodes | the nodes marked **A** below |

## Outputs and errors

Most nodes have one output, **out**, and an **error** output. Routing nodes have their own outputs, listed with
each node. When a node fails and nothing is connected to its **error** output:

- in an automation pipeline, processing of that event stops and the error is counted;
- in a transport pipeline, the pipeline's **On error** setting decides: **Pass Original** (default: the reading goes
  on unchanged), **Drop** or **Quarantine**.

Nodes without outputs (marked "ends the branch") are the last step of a branch.

## Field names

Settings that name a field use a path: `payload.<tag>` for a tag value, `metadata.<name>`, `attributes.<name>`,
`topic`, `origin`, `device.*`, `gateway.*` or `hierarchy.*`. A tag name starts with a letter or `_` and has at most
80 characters. The device and gateway identity (`device.id`, `gateway.id`, `metadata.DeviceId`,
`metadata.GatewayId`) cannot be changed or removed.

Under **Which data** (on sources) and **Conditions** (on **Filter** and **Switch**) you choose which readings a
node handles: by device, gateway, device profile, protocol, place (enterprise, site, area, line or cell, equipment),
tag, topic, a tag's value, type, unit or quality. **Required tags (advanced)** on a source limits the pipeline to
devices that have those tags.

## Sources

### Transport Input

Panel name **Incoming data**. **T**. Starts the pipeline for each reading of a matching device, before it is stored
or forwarded. Only one per pipeline.

| Setting | Values |
| --- | --- |
| **Run on** | **Every value** (default) or **Only when the value changes**. |

### Telemetry Input

Panel name **Device values**. **A**. Starts the pipeline when devices send new tag values. **Run on**: **Every value**
or **Only when the value changes**.

### Device Status Input

Panel name **Device status**. **A**. Starts the pipeline when a device connects, disconnects or changes state. No
settings besides **Which data**.

### Gateway Status Input

Panel name **Gateway status**. **A**. Starts the pipeline when a gateway connects or disconnects.

### Operational Log Input

Panel name **System log**. **A**. Starts the pipeline from platform log entries (warnings, errors).

### Runtime Metrics Input

Panel name **Runtime metrics**. **A**. Starts the pipeline from the gateway's performance figures.

### Schedule Input

Panel name **Schedule**. **A**. Starts the pipeline at fixed times.

| Setting | Values |
| --- | --- |
| **Schedule** | Five fields: minute, hour, day of month, month, day of week (0 to 7, both 0 and 7 are Sunday). `*`, lists (`1,15`), ranges (`8-17`) and steps (`*/5`) are allowed. Default `*/5 * * * *`. |
| **Time zone** | Default UTC. |

The schedule is checked once a minute. Runs missed while the gateway was off are not made up.

### No Data Input

Panel name **No data**. **A**. Notices when a device stops sending values, and when it starts again.

| Setting | Values |
| --- | --- |
| **Silence threshold (minutes)** | 1 to 10080. Default 5. |

Outputs **missing** and **restored**, each sent once per change. It is checked once a minute, so it can fire up to a
minute after the threshold.

## Shape data

### Filter

**T A**. Lets through only the data that matches **Conditions**; the rest goes to **false**. With no condition
everything passes. Outputs **true**, **false**.

### Select Fields

Panel name **Keep fields**. **T A**. Keeps only the tags you list and removes the others. Setting **Fields to keep**.

### Set Field

**T A**. Writes a value into a field.

| Setting | Values |
| --- | --- |
| **Destination** | The field to write. |
| **Value source** | **Copy from field** (then **Source field**) or **Constant** (then **Constant value**: text, number or true/false). |

A missing source field is an error.

### Rename Field

**T A**. Settings **From** and **To**. A missing field is an error.

### Remove Field

**T A**. Setting **Field**.

### Convert Type

**T A**. Settings **Field** and **Target type**: Number (default), Integer, Boolean, String, DateTime or Any. A value
that cannot be converted goes to **error**.

## Calculate

### Calculate

**T A**. Computes a new value from other fields.

| Setting | Values |
| --- | --- |
| **Formula** | Numbers, tag names, `+ - * /`, brackets and the functions `abs(x)`, `round(x)`, `min(a, b)`, `max(a, b)`, `clamp(value, low, high)`. For example `flow * 60` or `round(power / 1000)`. At most 1024 characters. |
| **Output field** | A new field. It must not exist yet. |

Tag names are written without `payload.` and must be required by the source or produced by an earlier node.
Division by zero, a missing value or a result that is not a finite number goes to **error**. The result is a number
of quality Good.

### Expression

**T A**. The same node as **Calculate**, with the same settings.

### Set Unit

**T A**. Settings **Field** and **Unit**, picked from the unit catalog (type part of a name, such as `Celsius` or
`pressure`).

### Set Quality

**T A**. Settings **Field** and **Quality**: Good, Bad or Uncertain. Later nodes that calculate refuse values that
are not Good.

### Add Context

**T A**. Adds facts about the device as attributes (`attributes.site`, ...). Setting **Context to add**: enterprise,
site, area, line, equipment, device name, profile, protocol. Facts that are empty for the device are skipped.

## Window and state

These nodes remember earlier values, separately for each device.

### Moving Average

**T A**. The average of the last readings. Settings **Input field**, **Output field**, **Window samples** (1 to
1024, default 8).

### Rate Of Change

**T A**. Change per second since the previous reading. Settings **Input field**, **Output field**. The first reading
only starts the count and goes to **error**.

### Event Time Window

Panel name **Time window average**. **A**. The average over a time span. Settings **Input field**, **Output field**,
**Duration (ms)** (default 60000), **Maximum samples** (1 to 1024, default 128). A reading older than the window goes
to **error**.

### Latest Join

Panel name **Combine**. **A**. Puts the latest values of two devices side by side, for example inlet and outlet
pressure on one line.

| Setting | Values |
| --- | --- |
| **Pair values from** | The same device, equipment, line / cell, area or site. |
| **First value**, **Store first as** | The first tag and the field it is stored in. |
| **Second value**, **Store second as** | The second tag and its field. |
| **At most this far apart (ms)** | Default 1000. |
| **Roles (advanced)** | **First role**, **Second role**: which device plays which part. |

Inputs **left** and **right**. Until both values are known and close enough in time, readings go to **error**.

### Debounce

**A**. Lets through at most one reading per device in each **Quiet period (ms)** (default 1000). The others go to
**error**.

### Hysteresis

Panel name **Band**. **A**. Turns a value into an open or closed state with a dead band, so it does not flicker
around one threshold. Settings **Input field**, **Open at or above** (default 60), **Close at or below** (default 40).
Outputs **open** and **closed**.

### Detect Anomaly

Panel name **Detect unusual values**. **A**. Compares each value with the average and spread of the recent values.

| Setting | Values |
| --- | --- |
| **Value** | The tag. |
| **Learn from the last values** | 10 to 1024. Default 120. |
| **Sensitivity** | In standard deviations, 1 to 10. Default 3. Higher means fewer findings. |
| **Values before judging (warm-up)** | At least 5, at most the window. |

Outputs **unusual** and **normal**. During warm-up every value is normal.

### Summarize

Panel name **Summarize per period**. **A**. One result per period.

| Setting | Values |
| --- | --- |
| **Value** | The tag. |
| **Summary** | average, lowest value, highest value, sum of values, number of values, change of a counter, total over time (value × hours). |
| **Period** | 15 minutes, 30 minutes, hour, 4 hours, shift (8 hours), 12 hours, day. |
| **Result field**, **Time zone** | |

Outputs **period** (once, when the first value of the next period arrives) and **collecting** (every other value).
A value older than the current period is ignored.

## Route

### Switch

**T A**. Sends data to **true** or **false**. **Condition type**:

- **Numeric comparison**: **Input field**, **Operator** (`>`, `>=`, `<`, `<=`, `==`, `!=`), **Threshold**.
- **Conditions (all / any)**: the same conditions as **Filter**.

In a pipeline that runs after data is stored, a switch can also have a lasting time: it sends data to **true** only
once its condition has held for that long without a break, on each device. The **Conditions** step of the builder sets
it ("once that has lasted … s"). Use it where a start-up surge or a noisy value would otherwise raise an alarm.

### Split

**T**. Copies the data into **Branches** parallel branches (2 to 16). Outputs **branch 1** to **branch N**.

### Drop

Panel name **Stop**. **T**. Ends the branch; the data goes no further. Setting **Operational reason**.

### Quarantine

**T**. Takes suspicious data out of normal processing so it can be inspected. Setting **Operational reason**. Ends the
branch.

### Transport Output

Panel name **Continue**. **T**. Sends the processed data on to storage and outbound targets. Ends the branch.

### Alarm Status Route

Panel name **Alarm status**. **A**. Sends data to **true** or **false** depending on an alarm of this pipeline for the
device. **Take TRUE when the alarm is**: **Open**, **Closed (or never opened)** or **Open and acknowledged on the
hub**. **Alarm**: one alarm key, or any alarm of this pipeline.

## Automation

### Create Or Update Alarm

Panel name **Open alarm**. **A**. Opens an alarm, or updates it if it is already open. Ends the branch.

| Setting | Values |
| --- | --- |
| **Alarm key** | A short name; **Clear Alarm** uses the same key. |
| **Severity** | Info, Warning (default), Critical. |
| **Message** | Up to 512 characters. |
| **Entity key** | What the alarm is about. Default `device.id`. |

### Clear Alarm

**A**. Closes an alarm opened earlier in this pipeline. **Alarm to clear** picks one of the pipeline's alarm keys.
Ends the branch.

### Notification

Panel name **Notify**. **A**. Sends **Message** through a **Notification channel**. Ends the branch. See
[Notification channels](https://proxus.io/docs/reference/notification-channels).

## Effects

Effects reach outside Proxus. They run only when the pipeline is published in **Active** mode; in **Shadow** mode
they are recorded as "would" actions. **Send to target**, **Write to device** and **Call an API** also need
`[Flows] EffectsEnabled = true` on the gateway; see [Configuration keys](https://proxus.io/docs/reference/configuration#flows).

### Target Output

Panel name **Send to target**. **A**. Sends the data to outbound targets. Ends the branch.

| Setting | Values |
| --- | --- |
| **Targets** | **Current device targets**, **Specific outbound channel** (then **Outbound channel**) or **Platform storage only (store as tag)**. |
| **Minimum interval (ms)** | 100 or more. Default 1000. |

This is an extra delivery: the device's normal delivery to its targets continues.

### Device Write

Panel name **Write to device**. **A**. Writes a value to a device's tag. Ends the branch.

| Setting | Values |
| --- | --- |
| **Device** | **Ingress device** (the device the data came from) or **Specific device** (then **Fixed device**). |
| **Writable register** | A tag that is not read-only. |
| **Value field** | The field holding the value. |
| **Minimum**, **Maximum** | Values outside this range are not written and go to **error**. |
| **Minimum interval (ms)** | Default 1000. |

A write is tried once, with a 10-second limit. A write that timed out is not repeated.

### Call Api

Panel name **Call an API**. **A**. Fetches one value from a REST API target and stores it as a tag of a device. Ends
the branch.

| Setting | Values |
| --- | --- |
| **API connection** | An outbound target of type **REST API**. |
| **Device** | The device the value is stored on. |
| **Path (optional)** | Added to the target's address; starts with `/` or `?`. It cannot change the host. |
| **Value in the response** | Where the value is in the answer, for example `data.items[0].price`. |
| **Store as tag** | The tag name. |

Each call has a 20-second limit.

## Observe

### Capture Sink

Panel name **Trace**. **T A**. Keeps a short live sample of the data for the **Trace** tab. Setting **Trace label**.

### Error Sink

Panel name **Errors**. **T A**. Collects and counts data that failed a step. Connect **error** outputs to it.

## Limits of a pipeline

| Limit | Value |
| --- | --- |
| Nodes | 1 to 128 |
| Connections | 256 |
| Size of the definition | 256 KB |
| Sources in an automation pipeline | 8 |
| Branches from one node | 16 |
| Window size of a node | 1024 values |
| Pipelines on one gateway | 256 |
| Name | 1 to 120 characters |

The graph may not loop back, and every node must be reachable from a source. The **Trace** tab keeps the last 64
items per pipeline.

## Related

- [Pipelines](https://proxus.io/docs/automate/pipelines): build, test and publish.
- [Pipelines and rules](https://proxus.io/docs/concepts/pipelines-and-rules): when to use which.
- [Troubleshoot automation](https://proxus.io/docs/troubleshoot/automation).