> For the complete documentation index, see [llms.txt](https://docs.heisenware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heisenware.com/concepts/extensions-branching-and-errors.md).

# Extensions, branching and errors

Modifier, filter, recorder and error handler: steps on an output that reshape, gate, record and catch, and how to branch with them.

An **extension** is a step attached to an output that works on its value. Extensions need no executor of their own. They attach to a return, to an [event output](https://docs.heisenware.com/concepts/backend-events.md) or to another extension, and so chain into a pipeline: filter first, then reshape, then record.

Except for the recorder, an extension is an output in its own right. Wire it to inputs and triggers, link it to widgets, or publish it into a [variable](https://docs.heisenware.com/concepts/variables-and-endpoints.md), exactly like the output it sits on.

## The four kinds

| Extension                                                                                           | What it does                                                             |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [**Modifier**](https://docs.heisenware.com/app-builder/app-builder/flowboard/modifier.md)           | Reshapes the value with a JavaScript or JSONata expression.              |
| [**Filter**](https://docs.heisenware.com/app-builder/app-builder/flowboard/filter.md)               | Lets the value through or stops the branch. This is the platform's "if". |
| [**Recorder**](https://docs.heisenware.com/app-builder/app-builder/flowboard/recorder.md)           | Keeps the value's history in the timeseries database.                    |
| [**Error handler**](https://docs.heisenware.com/app-builder/app-builder/flowboard/error-handler.md) | Receives the error when the call fails.                                  |

* **Add**: click **+** on an output, an event output or an extension and choose the kind. Several extensions on the same output work side by side, each starting its own branch.
* **Chain**: add an extension to an extension. An error handler sits directly on an output, never behind another extension.
* **Try**: an extension shows its last result below it. Click the icon of a modifier or filter to evaluate it again while you build.
* **Delete**: right-click the extension and choose **Delete**.

## Expressions

A modifier or a filter holds one **expression** that works on `x`, the value that arrives:

```javascript
x.temperature > 80
```

* It is one expression, not a script. For several steps, wrap them in a function that is called at once: `(() => { const rows = x.filter(...); return rows.map(...) })()`.
* Variables are available by name: `x.machine === $machine`.
* Luxon's `DateTime`, `Duration` and `Interval` are available for dates, beside JavaScript's own `Date`, `Intl`, `JSON` and `Math`.
* Write expressions to be read: line breaks, indentation and `//` comments are free.
* JSONata is the alternative language for pure reshaping.

## What a filter passes on

A filter's value is what it lets through. When the expression is true, everything behind the filter receives the value that arrived. When it is false, nothing behind it receives anything, and the filter keeps the last value it let through.

For a true or false that must also turn false again, such as a widget's `visible`, use a modifier with the same expression beside the filter.

## Branching

* **If and else**: two filters on the same output, one with the condition, one with its opposite. Each feeds its branch.
* **Several cases**: a modifier that computes the case, and one filter per case behind it.

Nothing else is needed.

{% hint style="warning" %}
A branch that a filter can stop must not feed an **all updated** join: the join would wait for it forever. See [When streams meet](https://docs.heisenware.com/concepts/when-streams-meet.md#joining-branches-of-one-impulse).
{% endhint %}

## Errors

When a call fails:

* the executor's [status](https://docs.heisenware.com/concepts/executors-and-instances.md#status) turns red and shows the message;
* every error handler on its return receives `{ message, cause, originalPayload }`;
* the executor produces **no output**. Nothing behind it runs, and the branch ends there.

So an error does not travel down the flow as a strange value. It either reaches an error handler or stops.

* **Prevent** where you can: give inputs defaults, or put a filter in front, where a missing value would make the function fail.
* **Report** where a person must know: link the error handler to a toast. See [Pages and App actions](https://docs.heisenware.com/concepts/pages-and-app-actions.md#on-a-value).
* **Retry** with a `Timer`, not by wiring an output back to its start.

Inside a [loop](https://docs.heisenware.com/concepts/when-streams-meet.md#loops-once-per-element) a failing element becomes its error message in the list of results, and the loop goes on. A failure inside a [subflow](https://docs.heisenware.com/concepts/subflows.md) that no error handler took there fails the call, and the caller's error handler receives it.

A released App's failures are written to its log, each with the executor and the message.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.heisenware.com/concepts/extensions-branching-and-errors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
