Write a virtual tag script

Compute a tag's value from other tags — read scripts, write scripts, and worked examples.

A virtual tag gets its value from a script instead of a device. This guide shows how to write one. For the full list of functions, see the virtual tag reference.

1. Add a virtual tag

In a project’s Tags view, click New, choose Tag, and pick the Virtual type. Give it a name and a data type, then write its read script.

2. Reference other tags

Scripts read other tags by path, passed to the value() function. Instead of typing the path, press Shift + Alt + T to pick a tag and insert it; press Shift + Alt + A to insert an alarm. Autocomplete (Ctrl/⌘ + Space) lists every function you can call.

// The current value of another tag
value("Meters/Main meter");

3. Write the read script

A read script returns the tag’s value. A few common shapes:

Combine tags — sum two meters:

value("Meters/Meter A") + value("Meters/Meter B");

Convert units — Wh to kWh:

value("Boiler/Energy") / 1000;

Derive a status — 1 when an alarm is active, else 0:

alarmValue("Boiler/High temperature") ? 1 : 0;

Use history — the midpoint of the last hour’s range, using the time helpers:

const now = getCurrentTime();
const from = getTimeBefore("1h", now);
const high = historyMax("Outdoor/Temperature", from, now);
const low = historyMin("Outdoor/Temperature", from, now);
(high + low) / 2;

Set a recompute interval (in seconds) if the value should refresh on a timer; otherwise it recomputes when the tags it references change.

4. Add a write script (optional)

To make a virtual tag writable, add a write script as well — a virtual tag is writable only when it has both. The write script runs when someone writes to the tag and receives the incoming value from inputValue(). Forward it to real tags with writeValue().

For example, take a percentage (0–100) written to the virtual tag and send it to a fan as a 0–10 V setpoint:

writeValue("AHU/Fan", (inputValue() / 100) * 10);

5. Save and check

Save the tag and confirm it shows a sensible value in the Tags view. The editor flags syntax errors inline as you type; if the value looks wrong, check the tag paths and that the data type matches what the script returns.