Data transformers

Incoming data rarely arrives in the shape you want to show. It might be raw text, a JSON string, a deeply nested object, or a binary image. Transformers reshape that data before it reaches your dashboard.

You link transformers together into a chain of transformers. Each transformer reads the current value and can replace it before passing it to the next one.

Three places to add transformers

You can attach a chain of transformers in three places:

  1. On the data source — MQTT, WebSocket, and Timer sources run transformers as soon as new data arrives, before it's stored as the source's value. HTTP sources have no separate transformer list: fetch and reshape live in the Actions / Transformers pipe. Every data piece that uses this source starts from this result.
  2. On the data piece — runs next, on the root source value for this data piece. Components with Inherited on and the same source as the data piece start from this result. The data piece itself has no Inherited switch.
  3. On a component — runs after that, for that one component only, when Inherited is off.

A data piece can have an optional root data source. Components inherit it unless you pick another source on that component.

Every component and group has Inherited (on by default) at the top of Data transformers pipe. When it is on and the component uses the same source as its parent (the data piece, or the group for a component inside a group), the rest of that pipe is hidden and those transformers do not run — the component shows the same data as the parent after the parent's transformers.

If you pick a different source, Inherited stays off and you cannot turn it on.

Use source transformers (or the Actions / Transformers pipe on an HTTP source) to clean up data once for everyone (for example, pull one field out of a JSON object that every data piece needs). Use data piece transformers when several components on the same data piece should share a reshape. Use component transformers to adjust how a single component displays that data, without touching the source or other components.

Source transformers Data piece transformers Component transformers
Run on Data as it arrives The source's value, after source transformers The source's value, when Inherited is off
Affect The value stored on that data source Components with Inherited on that use this data piece source Only that one component, when Inherited is off

The full path: data arrives → source transformers (MQTT, WebSocket, Timer) or the Actions / Transformers pipe (HTTP) → source value → data piece transformers → if Inherited is on, that parent result is what the component shows; if Inherited is off, component transformers run on the source's value. See Incoming data flow for the complete picture.

Keep scripts cheap

Transformers run every time new data arrives. Many scripts in many places add up. Put them at the widest level that does the job:

  1. Data source
  2. Data piece
  3. Group
  4. Component

Go to a lower level only when the task needs it — for example, one Label must show something different from the rest. That is fine.

If one script can do several things, put them all in one Lua or JavaScript transformer. That is cheaper than splitting them into several transformers.

Scripts in tap actions (on tap, on change, and other events) are different. They run only when you use a control, so they are not run often. Put them wherever you need them and split them as you like.

Types of transformers

Actions (same list; tap Add... to add a row)

Every row can be Always run, Run if, or Do not run if. The condition is a {{ }} template, same as other interpolating fields — write {{ value.temp > 30 }}, not the inner text without braces. Run if skips that row only when the condition is not met. Do not run if skips it when the condition is met. If the condition cannot be evaluated, that row is also skipped, and the list continues. That is not a failure.

Sending from a tap is not a transformer — use HTTP request, MQTT send, WebSocket send, or Trigger data destination. See Tap actions.

Transformers run one after another, never at the same time. Each transformer's result becomes the new value for the next one. A Lua or JavaScript script that returns nothing, or an expression that gives null, passes on an empty value (null) — not the old one. A skipped row, Stop pipeline, and Debounce leave the value as it was.

In the editor, tap a row to configure a transformer, drag its handle to reorder it, and swipe it right to left to delete it.

If the incoming data is a string that looks like JSON, Routix Dash decodes it automatically before your first transformer runs — so your chain usually starts from an object or array, not the raw string. A Simple expression transformer's result gets the same treatment: if the result looks like JSON, it's decoded so the next transformer can work with an object or array.

How the value moves: variables you can use

Lua, JavaScript, and Simple expression transformers can read a few built-in variables:

Name What it holds
value The current data at this point in the chain (after any earlier transformers)
raw The data as it first entered this chain, before any transformer touched it. The automatic JSON decoding has already happened, so JSON text arrives here as an object or array. Use this when an earlier transformer narrowed value down but you still need the full original data.
ctx Extra information for this run. ctx.error is null, or holds a network error; ctx.transport holds connection details for this run (MQTT topic, HTTP method/url/requestHeaders/status/response time, WebSocket event, Timer tick, …). You can also store your own fields here for later transformers in this same chain. None of this is saved to your configuration
env App-wide text from ENV variables. Read env.my_key. See ENV variables.
vars App-wide values that scripts keep while the app runs. Read vars.my_key. See Runtime vars.
params Custom screens only. Values passed when the screen opened, for example params.room.

Simple expression transformers can also read another data source by name with source_value("Name") (after that source's own transformers) or source_raw("Name") (before them). Lua supports the same two functions. JavaScript uses sourceValue("Name") and sourceRaw("Name").

JSONPath tip: $ holds the same names: $.value…, $.raw…, $.ctx…, $.env…, $.vars…, and $.params… on a custom screen. Read data with $.value… — for example $.value.temperature. To read a variable, start the path with $.env — for example $.env.my_key. Reading an error field with JSONPath doesn't clear it — only Lua or JavaScript can do that.

Passing extra data with ctx

value is what each transformer returns to the next one. Use ctx when you need to keep something extra while value changes.

In Lua or JavaScript, later transformers in the same chain see what you write:

ctx.unit = value.unit
return value.temperature

The next Lua, JavaScript, expression (ctx.unit), or JSONPath ($.ctx.unit) can read ctx.unit. Expressions and JSONPath can read extra keys; Lua and JavaScript can write them in a transformer chain.

Extra keys you set on a source transformer stay in that source chain. Extra keys on a data piece transformer stay in that data piece chain. Component transformers do not inherit them — each component starts with a copy of ctx.error and ctx.transport (when the source provided it). Don't overwrite error or transport. Put your own extras on other ctx keys; do not mix them into ctx.transport.

Sending from a tap is not a transformer. On tap, use HTTP request, MQTT send, WebSocket send, or Trigger data destination — HTTP can also store a response on ctx. See Tap actions.

Network errors

When something goes wrong with the network — a timed-out request, a broken subscription — the error shows up as ctx.error in the source's transformers (or in later actions):

{"message":"Request timed out","kind":"timeout"}

It always has a message and a kind, and sometimes a statusCode. When everything is fine, ctx.error is null.

A transformer that throws an error (rather than reading ctx.error) is a different thing entirely — it stops the rest of the chain immediately. A skipped Conditional run does not stop the chain.

You can throw one deliberately in Lua with error(ctx.error.message), or in JavaScript with throw new Error(ctx.error.message).

Examples

Pull one field from JSON

Say an API returns {"temperature": 21.5, "unit": "C"}, and you just want the number.

HTTP availability across two components

To monitor HTTP availability, turn Stop pipeline if failed off on that HTTP request. Otherwise a timeout or a lost connection stops the list before the next action. Then add a Lua or JavaScript action after the HTTP request in the Actions / Transformers pipe that stores the response time in milliseconds, or 0 when the request fails.

You can also clear ctx.error so later actions in this list start from a cleared state. Leftover ctx.error does not make a Label show #error. Only Lua or JavaScript can clear it — a Simple expression can read ctx.error but leaves it in place (see Network errors above):

if ctx.error then
  ctx.error = nil
end
return ctx.transport.responseTime or 0

Bind that source on the data piece (root source) and show the number on a Label — no extra component transformers needed for the milliseconds.

For a second Label on the same source, add a component Simple expression that turns the number into a status label:

value > 0 ? "UP" : "DOWN"

The first Label keeps the raw milliseconds; the second shows UP or DOWN. Both reuse the same Lua or JavaScript in the Actions / Transformers pipe — only the second Label adds its own layer on top.