Script console

The Script console page runs a script as the administrator using it, with all of system.*, and shows what it returned, logged, and wrote or would have written. It is where to try a system.db query, check what an alarm filter returns, or test the body of a screen or cron script before attaching it. This page is for administrators; see Scripting for the sandbox and The system API for the calls.

Who can use it

Only the admin role. Other users see "Only administrators can use the script console" on the page, and the API route POST /api/v1/admin/script-console requires the admin policy. The script runs as the signed-in administrator, so system.user.current() returns you, and every role check passes.

A program with an API key of the admin role can call the route as well; the script then runs under the key's identity.

Dry run and running for real

The Dry run switch is on by default. A dry run reads everything and changes nothing:

• Tag writes are collected and listed under Would write, not made.
• Changing system.* calls return without acting and are listed under Would change: system.alarm.acknowledge returns 0 and reports Acknowledge 1 alarm: <id>; shelve and unshelve report; system.db.update runs its statement in a transaction that is rolled back and reports <connection>: <statement> (would change N rows). system.db.query and scalar also run inside that rolled-back transaction, so a dry run never leaves anything in a database.

Switch Dry run off and the button reads Run for real: writes are applied in order after the script finishes, stopping at the first that is refused, and acknowledgements, shelves and database changes are made. The script runs with the same limits as a screen script: 500,000 statements, 32 MiB and 2 s of CPU.

Press Run (or Ctrl+Enter; Cmd+Enter on a Mac) to run.

The request and the result

The page calls POST /api/v1/admin/script-console with {"source": "...", "dryRun": true}. The response:

Field	Meaning
ok	The script finished and, when run for real, every write was accepted
undefined	The script returned nothing
value	What it returned, as JSON
error	The script's error, or the refused write's
dryRun	What was asked
wouldWrite	Dry run only: each {path, value} the script asked to write
written	Real run only: each {path, value, accepted, error}
skipped	The changing system.* calls a dry run reported
logs	Each {level, message} from console.*
millis	How long the run took

The result pane

The Result pane shows Finished or Failed with the time taken, then:

• Returned: the return value, or Nothing.
• What went wrong: the error, when it failed.
• Logged: the console.log, info, warn, error and debug lines, at most 200 lines and 64 KB per run.
• Would write and Would change after a dry run; Written after a real run, with a mark per write for accepted or refused.
• "It changed nothing" when there was nothing to list.

What the script sees

The same globals as a screen script: tag(path), tags, writeTag(path, value), event, val, Math, console and system. event is { name: "console", params: {} } and val is undefined, so a script written for a screen runs here without event.value; give it a value of your own while testing.

The editor types the script against the same contract as the other editors; hover a name for what it does and press Ctrl+Space for what is there.

Testing a screen script here

1. Paste the script's body.
2. Replace {param} placeholders in tag paths with real paths, and val or event.value with a sample value: var val = 42; at the top.
3. Run it as a dry run. Check Would write for the paths and values you expect and Would change for alarm or database side effects.
4. Note that the console runs as you (admin). A screen script runs as the operator who clicks, so a call that works here may be refused there: system.db.* needs engineer, acknowledging needs operator, and tag writes need operator.
5. The return value is shown as JSON rather than acted on: { toast: 'Saved' } appears under Returned, and the console neither shows a toast nor navigates.

Example

The page opens with an example that lists standing alarms and reads the gateway's version:

const standing = system.alarm.active();
console.log(`${standing.length} alarms standing`);

return {
  gateway: system.gateway.info().version,
  now: system.date.format(system.date.now(), "yyyy-MM-dd HH:mm"),
  worst: standing[0]?.name ?? "none",
};

A dry run of a database change, reported and rolled back:

var changed = system.db.update('DELETE FROM shift_log WHERE at < ?', [system.date.addDays(system.date.now(), -90)], 'Reporting');
return changed + ' rows would go';