Programs
Write sandboxed JavaScript that derives telemetry and publish results.
Programs (/programs) run sandboxed JavaScript on the platform to transform, aggregate, or derive telemetry values.
What you'll do
- Write program code in the built-in editor
- Debug with sample telemetry before starting
- Start the program to publish derived values to NATS
Create a program
- Go to Programs → Add
- Write JavaScript in the built-in editor
- Configure input tags and output tags
- Save, then Debug or Start
Lifecycle
| State | Action | Permission |
|---|---|---|
| Draft | Edit code | programs.update |
| Running | Processing telemetry | programs.start |
| Stopped | Idle | programs.stop |
Programs publish derived values back to NATS using the standard telemetry event contract.
Run schedule
On the program detail page, Run mode controls how the runtime starts and stops:
| Mode | Behavior |
|---|---|
| Manual | Start and stop from the editor toolbar (programs.start / programs.stop) |
| Continuous | Keeps running until you stop it manually |
| Scheduled | Runs on a cron expression for a fixed duration, then stops automatically |
For Scheduled mode, set a cron pattern (for example 0 * * * * every hour) and a run duration (1 minute to 1 hour). While scheduled, manual Run / Stop on the toolbar is ignored — the scheduler owns start/stop.
The programs list shows a schedule badge (Manual / Continuous / Scheduled) per instance.
Declared outputs
Programs publish derived tags under programs/<programCode>/outputs/<name>. The editor Declared outputs panel lists outputs inferred from your script (via datahub.publish(...)).
These paths appear in:
- Debug results before you start in production
- Tag pickers when binding dashboards widgets or rules
- The program outputs catalog API (
GET /api/programs/outputs) for integrators
Use declared outputs for KPIs you want to chart or alarm on — they behave like any other tag path in UNS and dashboards.
Debug workflow
Before starting in production, use Debug on the program detail page:
- Click Debug — compiles the script and runs it against recent telemetry samples
- Review compile status (success or error message)
- Inspect outputs (derived tag values the program would publish)
- Read debug logs from
datahub.log(...)calls in your script - Fix errors, then Start when outputs look correct
The Logs panel also shows runtime log lines while a program is running.
Sandboxing
Programs run in an isolated sandbox with limited API access. They cannot access the filesystem, network (except publishing telemetry), or other programs.
Available helpers include reading input tag values and publishing outputs — see inline hints in the program editor.
Templates
Program templates (templates permission) provide reusable starting points. Apply a template when creating a new program.
Tips
- Test with simulator tags before connecting to production PLCs
- Keep programs focused — one derivation per program is easier to debug
- Monitor program status and logs on the detail page
- Only one active derivation per output tag — avoid conflicting programs