The system API

system.* is the gateway's API as a script sees it, by area, in the manner of Ignition's system.*. This page lists the namespaces and which script contexts may call them; each namespace has its own page with every function's signature, parameters, return value and role.

Namespaces

Namespace	What it covers	Expression tag	Screen, cron, console, module
system.tag	Read, write, describe, browse and fetch the history of tags	read only	All
system.alarm	Standing alarms, alarm definitions, alarm history; acknowledge, shelve, unshelve	No	All
system.db	Queries and updates on the gateway's named database connections	No	All (engineer role)
system.gateway	Gateway version and uptime, modules, device connections	No	All
system.user	Who runs the script, role checks, the user list	No	All
system.date	Time helpers: now, format, parse, add, difference, start of day	Yes	All
system.util	Small helpers: uuid, JSON, clamp, round	Yes	All

Only the script console runs with every function available to its caller without further thought, because an administrator passes every role check. Elsewhere a function needs the role shown on its page: a screen script has the signed-in user's role, a cron or module script the engineer role.

Where a call runs

Two kinds of function sit under system:

• Worker-side. system.tag.read, system.tag.write, all of system.date and all of system.util are plain JavaScript inside the script's own engine. They cost nothing beyond the statements they run, and they are the only part of system an expression tag has.
• Gateway calls. Everything else (tag.reading, tag.exists, tag.info, tag.browse, tag.history, all of alarm, db, gateway and user) is sent from the worker to the gateway as the function's name and a JSON array of its arguments, run there as the script's caller, and answered in JSON. Only plain values cross: numbers, strings, booleans, null, arrays and objects. A Date arrives as its ISO 8601 text, which every time parameter accepts.

A script makes at most 100 gateway calls per run; the 101st throws A script may call the gateway at most 100 times. The arguments of one call are at most 256 KB of JSON. Gateway calls are synchronous from the script's point of view: the script waits for the answer, and that waiting is not CPU time, so it does not count against the script's time limit.

An expression tag that makes a gateway call fails with this kind of script can't call the gateway; an expression tag only reads tags.

Errors

A failed gateway call throws a JavaScript Error whose message is system.<area>.<function>: <reason>, for example:

system.db.query: the gateway has no database connections; add one under Connections > Databases.
system.tag.history: options.from is required: when the history starts.
system.alarm.acknowledge: Acknowledging alarms needs the operator role, and this script runs as viewer.
system.tag.reed: there is no such function.

An uncaught error fails the script (see Scripting). Wrap a call in try/catch to handle it inside the script.

Argument checks are the same for every function: a required text argument must be a non-empty string (path is required, as text.), a number a JSON number (minutes is required, as a number.), an options object an object (options is required, as an object.), and a role one of viewer, operator, engineer or admin. A time can be a Date, epoch milliseconds, or ISO 8601 text (from must be a time: a Date, epoch milliseconds or ISO 8601 text.).

Dry runs

In the script console with Dry run on, and in a cron job's Try it, the reading functions answer as usual while the changing ones (alarm.acknowledge, alarm.shelve, alarm.unshelve, db.update) do nothing and report what they would have done. db.query, db.scalar and db.update run inside a transaction that is rolled back.

The contract

Every editor checks scripts against apps/dashboard/script-types/scadex-script.d.ts, which declares these interfaces; the gateway implements exactly what is declared there. The signatures on the namespace pages are copied from it.