# Pipelines, rules and functions

> The three ways to act on data in Proxus, what each is for, where it runs, and how to choose between them.

Source: https://proxus.io/docs/concepts/pipelines-and-rules

Proxus gives you three tools to do something with the values it reads. They overlap a little, but each has a
job it does best:

- A **pipeline** changes values on their way, or reacts to them. You start it from a goal in plain sentences, or
  build it from steps on a canvas.
- A **rule** watches values or logs for a condition and raises an alarm when it is met.
- A **function** is your own C# code, for what the other two cannot express.

All three are set up in the hub, under **Automate**, and run on the edge gateways you choose, next to the data.
A new rule or function runs on the **SYSTEM** gateway until you pick others.

## Pipelines

A pipeline is a chain of steps you build on a canvas, or start from a goal in the gallery and adjust. A pipeline
does one of two things:

- **Shape the data on its way.** It runs on every matching value before the value is stored, published or sent
  anywhere: convert a unit, scale a raw count, rename a tag, add context, check the quality, drop or route a
  value. Everything after it (the historian, the Unified Namespace, the outbound targets, the rules) receives
  the shaped value.
- **React to the data.** It runs after shaping, on the final values, and also on device and gateway events,
  logs and schedules: raise an alarm when a value stays out of range, notice that a device has gone silent, send
  a value to a target, write to a device.

A pipeline is not tied to one device. It chooses the values it works on by device, profile, protocol, place,
tag or other properties, so a single pipeline can cover every filler in a plant, including fillers added later.

Pipelines are published in two stages:

1. **Publish in Shadow** runs the pipeline on its gateways and records what it would do, without changing data,
   opening alarms or writing to devices.
2. **Publish Active** lets it take effect, once Shadow has shown the right results.

Steps that write to a device or call an outside API only take effect on gateways where these effects are turned
on in the configuration (`[Flows]`, `EffectsEnabled`); they are off by default.

Use a pipeline when the logic can be drawn as steps, when it must change the data itself, or when it should
apply to many devices at once. See [Pipelines](https://proxus.io/docs/automate/pipelines).

## Rules

A rule is a condition with consequences. It checks the values, device status changes and log entries on its gateways and, when the
condition is met, raises an **alert** that operators see in **Monitor > Alerts** and can acknowledge.

A rule's condition is either:

- an **expression** on values, such as "Temperature greater than 60", or
- **anomaly detection**, which learns how a tag normally behaves and flags a sudden jump, a fast rise or fall,
  a slow drift, a value that stops moving (flatline), or a gap in the data.

What happens next is set by **Rule Actions**: send a notification through a notification channel, or trigger
an outbound target. The same detector runs in the Trend Workspace, so an anomaly you see on a trend can be
turned into a rule that behaves the same way.

Use a rule when the question is "tell someone when this happens". Rules do not change the data. See
[Rules](https://proxus.io/docs/automate/rules) and [Rule actions](https://proxus.io/docs/automate/rule-actions).

## Functions

A function is a C# class you write in the hub. The hub compiles it and sends it to the gateways you choose,
where it runs for as long as it is deployed. A function can:

- see every value the gateway reads, before pipelines do;
- run on a schedule;
- subscribe and publish to MQTT topics;
- read from a database and save the result as values of a device;
- send values back into the data flow, where pipelines, rules and targets treat them like any other value.

Use a function for logic that needs real code: a calculation over many devices, or a system Proxus
has no connector for. A function is more powerful than a pipeline, but it is code
you maintain. See [Functions](https://proxus.io/docs/automate/functions) and the [functions SDK](https://proxus.io/docs/develop/functions-sdk).

## Choosing

| You want to | Use |
| --- | --- |
| Convert, scale, rename or filter values before they are stored and published | A pipeline that shapes data |
| Raise an alarm when a value crosses a limit | A rule, or a pipeline that reacts to data |
| Spot unusual behaviour without setting a limit | A rule with anomaly detection |
| Notify someone by email, SMS or chat | A rule with a notification action |
| Notice that a device stopped sending | A pipeline that reacts to data |
| Send selected values to one system only | A pipeline that sends to an outbound target set to **Pipelines Only** |
| Combine data from several devices, or reach a system Proxus has no connector for | A function |

## Where they run in the flow

On a gateway, a value meets them in this order: functions see the value first, then pipelines that shape data,
then the gateway marks changed values, and then rules, pipelines that react and the outbound targets work on
the result. [How data flows](https://proxus.io/docs/concepts/data-flow) follows a value through these stages.

## What's next

- [Pipelines](https://proxus.io/docs/automate/pipelines): build your first pipeline and publish it in Shadow mode.
- [Rules](https://proxus.io/docs/automate/rules): raise an alarm when a value crosses a limit.
- [Functions](https://proxus.io/docs/automate/functions): run your own C# code on the edge gateways.