The tools, area by area
What every tool an agent can call does, grouped by the capability toggle that advertises it, and the help tools that need none.
Tool names are stable snake_case identifiers. Errors are structured and actionable: a
failed call returns what went wrong plus a hint naming the tool or step that fixes it,
so an agent self-corrects instead of guessing. The server instructs every agent to read
the help with help_search and help_read before answering a question about how the app
works and, when the Backups (manage) area is on, to create a configuration backup before
making configuration changes. Which of these lists an agent actually sees is
what each area opens, plus the help tools, which need no area.
Help
The two help tools read this documentation, as the installation carries it: the same articles the help panel opens, written for the version installed on the station. They come with the endpoint whenever the master switch is on, whatever the area toggles say, because the text is the public documentation and shows nothing of the station. Both keep working while the runtime is stopped.
| Tool | What it does |
|---|---|
help_search |
Finds articles by the words of a question and returns each one's slug, title, summary and the sections the words touch, best match first (10 by default, up to 50). Case and accents are ignored. Without a query it lists every article. |
help_read |
Reads one whole article by its slug as plain text: the title, the summary, the list of sections and the body, with each section on a heading line and tables one row per line, plus the slugs of the articles it links to. |
Both read the station's interface language by default, so the pages, buttons and fields an
answer names are the ones on screen. Either takes a culture naming another language the
installed help carries; a language it does not carry is refused with the list of the ones
it does, and no other language answers in its place. An installation whose help is missing
or cannot be read answers each call with the reason instead of articles.
Connector: read
| Tool | What it does |
|---|---|
connector_browse |
Lists the tree the Connector page draws, with live health: every driver added to the station, one with nothing under it included, and a driver holding a device, a serial line or a broker is always added; Modbus RTU as driver, serial line, device, tag; MQTT as driver, broker (with its session state), device, tag; every other driver as driver, device, tag with each device's folder beside it. Generic serial and TCP lists its serial lines like Modbus RTU and its network devices like any other driver, with each device's transport. SCPI instruments lists its serial lines and its other devices the same way. A File device carries its folder, its file name, how it reads (one file or an inbox folder) and its format. A Database device carries its database type (databaseKind). Each device carries error, the one sentence its page shows, in the station's language: a sentence that points to its serial line or broker when the error belongs to that one, else the device's own error (it does not connect, the connection is refused, the driver warns), else the summary of its tags whose reads are refused, each tag's reason being the readFailure of tag_read. It is null when the device holds none; the sentence tag_read gives for a tag whose device is not connected leads here. Reveals the tag aliases (Driver.Folders….Device.Tag) that tag_read, tag_write and Logic expressions use. Aliases are null while the Connector is stopped. |
tag_read |
Reads one tag's live values by alias: valueRaw, the device's own value before any stage, value, the engineering value after every stage of the conversion pipeline, Decimals included (a Double the device reports as 2.718281828459 reads 2.72 with Decimals at 2), quality, both timestamps and substitution, which says whether the value is a configured stand-in rather than what the device reported: None (a measurement, or no value at all), NaNReplaced (the reading was NaN and the declared number took its place), LastGoodHeld (the read failed and the last reading that landed is held, with that reading's raw value and timestamps) or ReadFailureReplaced (the read failed and the declared number is presented). A stand-in counts as a value, so the quality stays good unless a limit fault is raised, but it is never a measurement. communicating says whether the device is still answering: false when the latest read failed or nothing has been read yet. A reading that stood past the tag's poll interval, plus a short margin, without a new one counts as a failed read: the value, the quality and substitution answer as they do for one (no value and bad quality by default, the held reading or the declared number where the tag says so), communicating is false, and the timestamps date the last reading that landed. A value outside the tag's limits is not a connection fault: the quality goes bad while communicating stays true. readFailure says why a read did not land, in the one sentence the tag's panel shows, in the station's language: the reason the device or the driver gave when the tag's own read was refused, or a sentence that points to the tag's device when that device is not connected. It is null while the tag reads, and when a read that did not land has no reason on record yet. |
modbus_server_status |
Reports the station's own Modbus server: whether it is on (enabled), its port, its status (Off, Listening, PortInUse, Failed with the system's words in failure, or RuntimeStopped), the clients connected now (at most maximumClients at once), and every row of the register map: its registerClass, the 0-based register and lastRegister, its type and layout, its access (ReadOnly or ReadAndWrite), its source (a tag or a variable, by address and id) and what a client reads there now, value and good, or the gap (NoSource, SourceRemoved, NoGoodValue, NotRepresentable) for which a client is answered with exception 04. It keeps working while the runtime is stopped. |
station_broker_status |
Reports the station's own MQTT broker, the one devices publish to, never one of the brokers the station reads: whether it is on (enabled), its port, its status (Off, Listening, PortInUse, Failed with the system's words in failure, or RuntimeStopped), its authentication (Anonymous or UsernamePassword, with username and hasPassword, never the password), the devices connected now (at most maximumClients at once) and thisStationEntry, the MQTT driver's broker This station through which the station reads it. It keeps working while the runtime is stopped. |
mqtt_publish_list |
Lists what the station publishes to each MQTT broker it reads, the Publish card of each: the broker's publishTopicPrefix and whether it publishes, and each row with its source (by address, removed when the source was deleted), its topic and its message (value or alarm), with both messages described in payloads. It keeps working while the runtime is stopped. A row whose access is ReadAndWrite takes values on its writeTopic (its topic followed by /set), written to its source and journaled as MQTT <broker name>; payloads.write says what that topic takes. Each broker says its publishFormat; a broker in Sparkplug B adds sparkplug (its group, the station's edge node id and its devices), each of its rows says the device and metric it is published as, and payloads.sparkplug says how Sparkplug B goes out (Publishing in Sparkplug B). |
remote_access_devices |
Reports who opens the station's screens over the network: the browsers connected from another computer or tablet right now (address, browser and system, page, user, since, and the configured device each one is) and the configured devices with how each one opens (start screen, lock, who it signs in as, the minutes after which it goes back, view-only, and why it opens otherwise when its fixed user or its start screen changed). It never carries a key or its hash. It keeps working while the runtime is stopped. |
server_status |
Reports the embedded OPC UA server's health: whether it is turned on (enabled), whether it is running, its uptime, endpoint URL and connected client sessions, and the size of the configured address space; available says whether the Connector runtime reads, which it does while the server is off or stopped, and serverError why the server's last start failed. list is what the server serves, and all it serves: one row per tag, Logic variable, alarm or device command, each with its access and the node a client is configured with; while it is empty, servesNothing is true. |
Connector: configure
| Tool | What it does |
|---|---|
driver_capabilities |
Lists every driver the app can serve with the connection fields a device needs, the tag addressing model (free-text address and/or typed fields), discovery support and parameters, timing ranges and the supported value types, with defaultPort, the port a device that names none is dialed on. added says whether the driver is added to the station, which is what draws it in the Connector tree; creating a device, a serial line or a broker with device_upsert, serial_line_upsert or mqtt_broker_upsert adds its driver. AVEVA PI and HTTP dial the port of the transport the device speaks, so they also give defaultPortByTransport: 443 over HTTPS, their default, and 80 in the clear. Generic serial and TCP adds genericSerialTcp: its transports, how bytes are typed, how messages end, the checksums, the tag modes, filters and extractions, how values are read and written, and two worked examples. Omron adds omron: its two protocols with the device fields, address forms and data types each takes, the FINS transports and ranges, writes and discovery. SCPI instruments adds scpi: its transports, whether this computer has VISA (visa.installed), the terminators, the write confirmations, the setup commands, how queries and write commands are written and answers read, discovery, and two worked examples. NI-DAQmx adds niDaqmx: for each measurement, an example channel, the unit, its fields and the data types and accesses it allows. A driver whose devices need something the product cannot ship adds prerequisite (Fluke NetDAQ: the Visual C++ 2005 runtime; OPC DA: the OPC Core Components, OpcEnum and the OPC DA proxy and stub; NI-DAQmx: National Instruments' NI-DAQmx; SCPI: a 64-bit VISA, NI-VISA or the Keysight IO Libraries Suite, for its VISA devices only, with both pages; Database: a 64-bit ODBC driver or data source for an ODBC device, judged per device (perDevice true), so installed stays null and the device's own error says what is missing): whether this computer has it (installed, for a driver added to the station), the official download page, the file, how to install it, the known stumble and what happens next. SNMP adds snmp: its versions and the credentials each takes, the SNMPv3 security levels and protocols, the types by kind of value, every standard object the driver knows by name with its OID, how reads and writes behave, discovery, and two worked examples. File adds file: the simple path, the folder and the confinement to it, the file name forms, one file or an inbox folder, the formats with their address grammar, what a tag reads and its types, the text settings, how reads and writes behave, discovery, and three worked examples. Database adds database: each database with its fields and its own port, the encryption, the two ways a tag reads and the two ways it writes, the rule that a value enters a statement only as @value or @now, the timeouts, the advice on the database user, discovery, and four worked examples. The map an agent reads before device_upsert or tag_upsert. |
serial_line_list |
Lists every persisted serial line, disabled and empty ones included, with its stable id and its driver; a Modbus RTU line also with its mode and the configured, automatic and effective timing values. |
serial_line_upsert |
Creates a serial line or updates one by stable id. driver names the driver it belongs to, ModbusRtu (the default), GenericSerialTcp, Scpi or Omron, fixed at creation; a line of the generic, the SCPI or the Omron driver refuses mode, responseTimeoutMs and minimumTransactionIntervalMs. Name and enabled state change at any time; the minimum transaction interval also changes while enabled; serial port, baud rate, serial format, transmission mode and response timeout only change while the persisted line is disabled. |
serial_line_delete |
Deletes a line by stable id. A line that still contains devices is refused unless the call explicitly authorizes deleting every child device and tag. |
mqtt_broker_list |
Lists every persisted MQTT broker, disabled and empty ones included, with its stable id, where it answers, its transport, username, client id, keep-alive, topic prefix, publication format (publishFormat) and Sparkplug B group (sparkplugGroupId) and device count. It says whether a password is stored and never returns it. |
mqtt_broker_upsert |
Creates an MQTT broker or updates one by stable id: name, enabled state, host (a whole mqtt:// or mqtts:// address is read apart), port, TLS, username, password, client id, keep-alive the prefix its Publish card suggests topics under (publishTopicPrefix, an empty string back to the default), how that card goes out (publishFormat, Json or SparkplugB) and the Sparkplug B group of the station's edge node (sparkplugGroupId, an empty string back to GanterLab, a group holding /, + or # refused). Only supplied parameters change; a broker is enabled only with a host, and a client id another broker uses is refused. A saved change of the connection reconnects the session every device under the broker shares. |
mqtt_broker_delete |
Deletes a broker by stable id. A broker that still contains devices is refused unless the call explicitly authorizes deleting every child device and tag. |
mqtt_publish_upsert |
Creates a row of a broker's Publish card (brokerId and source: a tag, Connector. and its alias, a variable, Variables. and its path, or an alarm, Alarms. and its path) or edits one by id. topic is optional: omitted, the row takes the one suggested from the source's name under the broker's prefix, and an empty string takes it again. A broker publishes a source once and a topic once; a topic holds no + or # and does not start with $. A row never moves to another broker. access is ReadOnly, the default, or ReadAndWrite, which only a tag with write access on a driver that writes, or a memory variable, takes: the station then writes what is published on the row's topic followed by /set (Writing back). No row's topic may be another row's topic followed by /set. On a broker in Sparkplug B the row is published as a metric instead (row.sparkplug), and ReadAndWrite takes the values Sparkplug B commands send to it. |
mqtt_publish_delete |
Deletes a row of a Publish card by id. The station stops publishing it; the tag, variable or alarm is not touched. |
device_upsert |
Creates or updates a device by driver + name (the driver is immutable after creation). Only supplied parameters change; connection fields are per driver; moving a device into a folder rewrites every reference to its old tag addresses. A device of the generic serial and TCP driver takes transport and the fields of its Messages and Checksum cards, and serialLineId only for a line of its own driver; a device on a line refuses a host, a port and a folder. An Omron device takes omronProtocol (Fins or NjNx) and, over FINS, the fins* fields of its FINS card; a device read by tag name refuses a port. A SCPI device takes transport (Tcp, Visa, or SerialLine with serialLineId of a line of its own driver), visaResource, terminator, responseTimeoutMs, writeCheck and setupCommands. An NI-DAQmx device takes daqmxDevice, the name NI MAX gives it. An SNMP device takes snmpVersion, snmpCommunity (SNMPv1, SNMPv2c), username, password, snmpSecurityLevel, snmpAuthProtocol, snmpPrivacyProtocol and snmpPrivacyPassword (SNMPv3), responseTimeoutMs and snmpRetries; it returns whether each secret is set, never the secret. A File device takes fileFolder, fileName, fileMode (SingleFile or Inbox), fileFormat, fileEncoding, fileSeparator, fileDecimal, fileHeaderRow and fileWrites, with fileHeaderText and fileLineEnd once writing is on; it returns file.fileStatus, the file the running driver reads and what it read off it. A Database device takes databaseKind, and for a server host, port and databaseName (on SQL Server also databaseInstance, databaseWindowsSignIn and databaseEncryption), databaseFile for SQLite or databaseOdbc for ODBC, with username and password; it returns database, the address and whether the device still waits for its user, never the password. A port outside 0 to 65535 is refused; 0 stands for the port the driver dials. The change is reconciled into the running server immediately. |
device_delete |
Deletes a device and all its tags; reconciled into the running server immediately. |
tag_upsert |
Creates or updates a tag on a device. Addressing is driver-specific (free-text address and/or typed fields; for Generic serial and TCP the read mode, request, filter, extraction and write fields; for SCPI instruments the query as address, valueField and writeTemplate; for NI-DAQmx the physical channel as address and the daqmx* fields of its measurement; for SNMP the OID as address, by number or by standard name; for File the column or the path as address, fileSource, fileRow and its fields, fileWriteMode and fileLineTemplate, a free-text value taking the generic driver's value* fields, and a new tag born read only; for Database the value column as address, databaseSource, databaseTable, databaseRow and its fields or databaseQuery, and once the tag writes databaseWriteMode and databaseCommand, a new tag born read only as well); the response echoes the assembled wire address and the alias for tag_read. Includes the invalid-reading stages: the NaN action for numeric tags, and the read-failure presentation for every tag the station reads, where only Replace is limited to numeric and Boolean tags. A Replace already stored that the tag's new type cannot take is saved as the default instead: the NaN action becomes PassThrough once the type is not numeric, and the read-failure presentation becomes ShowError once the type is String, DateTime, Guid or ByteString. |
tag_delete |
Deletes a tag; reconciled immediately. |
server_start |
Turns the embedded OPC UA server on and starts it, as Enable does on its row: it serves its list, and stays on across restarts until server_stop. A no-op when already running; when the Connector itself is not running, it is started first, materializing the current configuration. |
server_stop |
Turns the server off and stops it gracefully, as Disable does: OPC UA clients are dropped and nothing is published until server_start turns it on again. The Connector goes on reading, and tag reads, the Logic and the recordings go on. |
server_restart |
Stop then start of the server alone, while it is on; the Connector reads throughout. A server that is off is refused, since server_start is what turns it on. Device and tag changes are applied with connector_refresh. |
server_list_upsert |
Creates a row of the OPC UA server's list, or updates one by id. source names a tag (Connector. and its alias), a variable (Variables. and its path), an alarm (Alarms. and its path) or a device command (the device's address, a dot, the command's name and ()); a source is listed once. access is ReadOnly, the default of every new row, or ReadAndWrite, which only a tag with write access or a memory variable takes; a client's write then goes through the Logic write funnel and is journaled with the client's session. The answer carries the row with its node. |
server_list_delete |
Deletes a row of the list by id. A client no longer finds its node; the source it served is not touched. |
modbus_server_configure |
Turns the Modbus server on or off (enabled) or moves it to another port, 1 to 65535, as its page does. A port the web server, agent access or the OPC UA server is set to, and a port another program holds, are refused; Windows Firewall is never changed. Turned on, it lets any machine that reaches the port read what the map serves. Answers with the whole server, as modbus_server_status does. |
station_broker_configure |
Turns the station's own MQTT broker on or off (enabled), moves it to another port and changes its authentication, username and password, as its page does, in that order: port, authentication, then on or off. A port the web server, agent access, the OPC UA server or the Modbus server is set to, and a port another program holds, are refused; Windows Firewall is never changed. Turned on, it adds the broker This station to the MQTT driver. Answers with the whole broker, as station_broker_status does. |
modbus_map_upsert |
Creates a row of the Modbus server's register map, or updates one by id. source names a tag by its address (Connector. and its alias, as connector_browse lists it) a variable (Variables. and its path) or an alarm (Alarms. and its path, always ReadOnly, serving the state alarmValue names: Active, Acked or State); registerClass (HoldingRegister by default), register (0-based), type (Float by default, Boolean in a coil or a discrete input), length for a String, mostSignificantByte and mostSignificantWord take the fields and the rules of a Modbus tag. access is ReadOnly, the default of every new row, or ReadAndWrite, which only a holding register or a coil takes, from a source that takes writes (a tag with write access, a memory variable). A new row needs its register and its source; a row the map refuses is answered with the reason and a hint. |
modbus_map_delete |
Deletes a row of the register map by id. A client reading its registers is answered with exception 02 from then on; the tag or the variable it served is not touched. |
remote_access_device_update |
Changes a configured device's name, start screen (a dashboard by id or name, or empty to clear it, which also unlocks it), lock, idle minutes (0 for never) and view-only setting, as its row on the Remote access page does. Who the device signs in as is not changed here: that takes a person with Manage local users. A device is configured and forgotten on the station's screen, never by a tool. Answers with the device as remote_access_devices lists it. |
Connector: operate
| Tool | What it does |
|---|---|
connector_refresh |
Incrementally reconciles the running server with the configured devices (adds, removes, recreates) without a full restart; the lighter way to apply changes. |
device_discover |
Runs a driver's device-discovery scan and returns candidates with their tags, persisting nothing. Only drivers whose protocol supports a real scan take part; candidates that already exist are marked as such. An SNMP scan walks either target with snmpCommunity, or snmpDevice, a configured device, which is how an SNMPv3 agent is scanned. A File scan reads either fileDevice, a configured device, or fileFolder, fileName, fileMode and fileFormat typed for the scan. A Database scan reads databaseDevice, a configured device, and optionally databaseTables, a table name or a pattern with *. A target the driver's Scan scope card would refuse, or none where the scan needs one, is refused with what it has to be. A Database, File or SNMP scan stopped at its bound of values, tables or objects says so in cut, with what to pass to see the rest; a whole list has no cut. |
Logic: read
| Tool | What it does |
|---|---|
logic_browse |
Browses the rooted Logic address space, the same dot tree every expression reads: System, Server, Connector, Variables, Alarms, Process and Assets. Operator folders are real address levels; child points include their live value and quality, and a Connector tag point also carries substitution and communicating, as logic_read reports them. |
logic_read |
Reads one point by its dot address (for example Variables.Setpoint) and returns the live value and quality. A Connector tag point also carries substitution and communicating, as tag_read reports them, which is what tells a stand-in, or a reading from a device that stopped answering, from a live measurement; other points carry neither. A reading that went silent reads there as a failed read. |
Logic: configure
Upserts are partial (omitted parameters keep their value) and every merged draft passes the same validation the Logic editors apply; an invalid draft is rejected and nothing is half-applied.
| Tool | What it does |
|---|---|
variable_upsert |
Creates or updates a variable: Expression (a single read-only JavaScript expression over the address space) or Memory (a writable, optionally retentive value). The name is the key and, sanitized, the address; the folder parameter files it, rewriting every reference to the old address. |
variable_delete |
Deletes a variable by path, its retained value included. Channels bound to it lose their source. |
action_upsert |
Creates or updates an action: a JavaScript statement block with exactly two write verbs, memory-variable assignment and the engineering tag write. Statically validated, never executed at save time. |
action_delete |
Deletes an action by name. Triggers bound to it idle. |
trigger_upsert |
Creates or updates an interval trigger: every intervalMs (minimum 100) the bound action fires on the actions lane; a tick during a pending run is skipped. The action binding is loose and by name. |
trigger_delete |
Deletes a trigger; the bound action is untouched. |
alarm_upsert |
Creates or updates an alarm: a Boolean condition expression, priority (Critical/High/Medium/Low), on/off delays, whether acknowledgement is required, and the annunciation style. Saving a changed condition or timing resets the running state machine. |
alarm_delete |
Deletes an alarm by path; an active annunciation is cleared first. |
logic_folder_upsert |
Creates, renames or re-files an organizing folder of one section (Variables, Alarms, Actions, Triggers; at most three levels). For Variables and Alarms the folder path is part of the address, so renames and moves rewrite every expression, script, condition and dashboard binding beneath. |
logic_folder_delete |
Deletes a folder. Nothing it held is destroyed: items and subfolders re-file one level up and references are rewritten; a name collision at the destination refuses the delete. |
Logic: operate
All of these ride the same Logic write funnel the pages ride and journal with origin MCP. A write leaves the Logic for the device's own delivery queue, and the tool call is what waits for the answer, so what comes back is what became of the value and not merely that it was sent.
| Tool | What it does |
|---|---|
variable_write |
Writes a value into a Memory variable (coerced to its output type, retained when retentive). Expression variables are computed and refuse writes. |
tag_write |
Writes an engineering value to a writable tag: reversed through the tag's conversion pipeline, coerced to the device type, written to the equipment. The answer carries what the tag presents once the write is through: the value, the quality, substitution and communicating, as tag_read reports them, so a device that took the write but has stopped answering reads is told apart from one that still answers. Read-only tags and read-only drivers are refused with the reason. |
action_run |
Runs one action on the actions lane and returns its outcome and duration. A disabled action fails without running. |
alarm_ack |
Acknowledges one alarm, the operator response; a no-op when nothing is pending. |
alarm_ack_all |
Acknowledges every alarm awaiting one, as one logic-queue item with each transition journaled. |
Logs: read
| Tool | What it does |
|---|---|
logs_read |
Reads the program-wide live log feed (the same one on the Events Console), filtered by minimum severity (Debug/Information/Warning/Error, default Information), area (App/Server/Connector/Logic/Process/Dashboard/Agent/Licensing), component and a contextual substring; returns the newest matches (default 100, at most 500). Agent actions journal under the Agent area. |
event_history_read |
Reads the persistent operational-event timeline, which survives restarts: alarm transitions, occurrence transitions and interlock transitions. Filter by kind (Alarm/Occurrence/Interlock), an inclusive UTC period and a level (alarm priority, occurrence severity or interlock transition); newest first, default 100, at most 500. Strictly read-only: nothing can clear or delete journal entries. |
Process: read
| Tool | What it does |
|---|---|
process_models |
Lists the Process models in full: channels, shared groups, units with resolved wiring and running state, procedures, panels, recipes, evaluations, occurrences, plus the global report-template library. The map an agent reads before starting anything. |
process_runs |
Lists runs, most recent first: id, name, state, verdict, what ran, who started it (Station/User/Automation/Agent), timing and cycle progress. Can be restricted to active runs, searched by a part of the name or of any metadata value (a serial number, a lot), and capped (default 50). |
process_run |
Reads one run's complete frozen record by id: snapshot, metadata, judged criteria with sample counts, occurrence episodes and events, as-executed recipe writes, comments, and the frozen report and label artifacts with their print attempts. Optionally computes datalog row count and time range. |
process_samples |
Reads the samples a run recorded, while it records or after it ended. A stretch of up to 500 samples comes as recorded: one point per sample, with a value per channel. A longer one comes summarized: its duration is divided into 500 equal slices, and each slice carries every channel's minimum, maximum and mean, so a peak survives in the maximum. The answer says which of the two it is and, summarized, how long each slice lasts and how many samples it joins. fromUtc and toUtc narrow the stretch, and one narrow enough comes back as recorded; channels reads only the channels it names. |
unit_status |
Reports a unit's live status: whether it is running (with the active run) and the current engineering value behind each channel, read without recording. |
Process: configure
| Tool | What it does |
|---|---|
process_view_configure |
Configures exactly one panel of a model: the icon drawn beside it and whether it stands on the View page. Nothing else of the Process aggregate is writable over MCP; the rest is edited on the Process page. |
Process: operate
Runs started, ended or commented by an agent record Agent as the actor, never the operator who happens to be signed in at the bench.
| Tool | What it does |
|---|---|
process_snapshot |
Captures one datalog row on a unit outside a procedure. Every call creates a new, already-completed Instant run in Histories with no evaluation (verdict None). |
process_evaluate |
Captures one datalog row and judges it with an evaluation; creates a completed Instant run and returns its verdict. |
process_recipe_apply |
Applies an Instant recipe once to a unit through the Process write funnel and source locks. Commands equipment; creates no run (the writes are journaled). Temporal recipes are refused. |
process_start |
Starts a procedure run on a unit, with a JSON object for the metadata fields the procedure prompts. Every value passed is recorded or nothing starts: a field the procedure does not prompt, a value for a sequential field (the app composes it at start) or a field named twice refuses the start, as do missing or invalid required metadata, a unit already running or a shared-channel lock conflict. Returns the new run id. |
process_stop |
Stops a running run: finalization block, frozen history snapshot, computed verdict. |
process_hold |
Holds a run's temporal profile at the last setpoint; the datalog keeps recording. |
process_resume |
Resumes a held run's temporal profile. |
process_abort |
Aborts a run from Running or Held: finalization runs, the snapshot is written, the state becomes Aborted and the verdict NOK. |
process_comment |
Adds a timestamped comment into a run's file: a timeline note while active, a post-run note after. |
process_report |
Generates (or regenerates) the PDF report of a finished run and returns its file path. A named template from the global library overrides the procedure's configured one; with neither, the all-sections default layout applies. Refused while the run is active. |
process_run_delete |
Permanently deletes a recorded run: its history-index pointer and per-run database file. Refused while active; configuration is untouched. |
Dashboard: configure
The role names these tools read and report are English on every station: Not signed in,
Viewer, Operator, Maintainer and Developer, whatever words the operator reads on
the screen. Admin is not listable: it always sees every dashboard. A role the
administrator renamed is named by what he typed.
| Tool | What it does |
|---|---|
dashboard_list |
Lists dashboards (or, naming a model, that model's screens): grid size, folder, icon, startup flag, role visibility and every component with its position, layer and properties JSON, plus every persisted connection network. Also returns the component-kind catalog with each kind's default size and default property bag. |
dashboard_upsert |
Creates or updates a dashboard by name: grid size (a shrink that would orphan a component is rejected), folder and icon in the View page's Visualization column, startup flag, status-bar visibility in full screen, and per-role visibility. Naming a model addresses that model's screens instead. Open dashboard pages reflect the change live. |
dashboard_delete |
Deletes a dashboard and its components by name; naming a model deletes that model's screen instead. |
component_upsert |
Adds a component by kind (placed at the first free cell with the kind's default size unless told otherwise) or updates one by id. Placement must lie inside the grid; overlapping is allowed with the z layer deciding rendering order; the properties JSON is the kind's typed bag. Naming a model addresses that model's screens instead, so a screen created there can be laid out here. |
component_delete |
Removes a component by id; naming a model addresses that model's screens instead. |
connection_upsert |
Connects two Symbol terminals with a typed connection network, resolving type, role and direction from the symbol catalog exactly as the canvas editor does. Ends that resolve to different types fail unless an undefined connection is explicitly allowed; an anchor already carrying a connection is rejected. Naming a model addresses that model's screens instead. |
connection_delete |
Removes one connection network by id and expected revision, so a stale delete is rejected instead of clobbering a newer edit; naming a model addresses that model's screens instead. |
UI: automate
These tools drive the real application window; they exist so an agent can verify the
operator-facing UI, not a simulation of it. Interactions are dispatched to the live
shell, so the intended conduct is to follow each gesture with ui_screenshot and
observe the effect, and ambiguous matches come back as candidate lists instead of a
guessed click.
| Tool | What it does |
|---|---|
ui_state |
Reports the shell's state: active page, available pages, theme, window size and visibility, and the loopback address this instance serves its UI on. The orientation call before anything else. |
ui_navigate |
Activates a page of the shell by its stable name, which is English on every station: View, Process, Logic, Connector, Users, Validation, Events, Agent, Settings, Account. The label the navigation rail draws in the station's own language is accepted too. |
ui_screenshot |
Captures the window as shown on screen into a PNG file and returns its absolute path; restores the window first when hidden to the tray. Can capture one named screen region (a unique, visible data-doc-region area) instead of the whole window, and a missing, hidden or ambiguous region fails with the visible regions listed rather than silently falling back to a full capture. |
ui_scroll |
Scrolls the active page's main scroll region to top or bottom or by viewport pages, returning the offsets so a long page can be swept. |
ui_set_theme |
Applies the station's theme (System, Light or Dark): the one the station's window draws in and every browser that has not chosen its own follows; a browser that has chosen its own keeps it. This persists exactly like a choice made with the theme keys in the station's window, so a well-behaved agent restores the original value when done. |
ui_resize |
Resizes the restored window in device-independent units, clamped to the window minimum; useful to audit compact layouts. |
ui_click |
Clicks the visible button, hyperlink, checkbox or toggle whose text matches; checkboxes and toggles are found by their field label and the result reports the landed state. Ambiguity returns the candidates instead of picking one. |
ui_set_text |
Writes a value into a text box identified by its field label, committing the binding like typing would. |
ui_select |
Selects an item by visible text: a slash-separated path walks a tree, expanding along the way; a single segment also matches list, tab, combo-box items and grid rows on the current page. |
Backups: manage
| Tool | What it does |
|---|---|
backup_create |
Creates an online snapshot of the configuration database into the backups folder, with an optional note. Recorded runs live outside the configuration and are never touched by backup or restore. |
backup_list |
Lists the configuration backups (file name, creation time, size, note) plus any restore already scheduled. |
There is deliberately no backup delete tool: retention is operator-only, on the Backups page.
Backups: restore
| Tool | What it does |
|---|---|
backup_restore |
Schedules a backup to replace the current configuration at the next application start. Nothing changes in the running app and the tool never restarts it; the configuration being replaced is snapshot automatically first, and the operator can cancel the pending restore from Settings until the restart. Refused while a recording is active. |
Settings: manage
| Tool | What it does |
|---|---|
settings_read |
Reads the station's display and lifecycle preferences: date/time/number formats, decimal places, theme, close-to-tray and crash-report flags. |
localization_set |
Updates the display preferences (partial: omitted parameters stay). Display only: storage, driver I/O and recordings always use the invariant format. |
asset_list |
Lists the user assets (images, icons, colors) with ids, values and paths. |
asset_import |
Imports a PNG/JPG from a local file path into the app-owned asset library and returns the new asset id. The bytes are copied, so the source file may move afterwards. |
symbol_validate |
Validates inline symbol content (raw SVG or a v2 package) without persisting anything: a dry run of the exact import, returning errors, sanitizer warnings and a summary of what was recognized. The tool description carries the complete portable symbol contract. |
symbol_import |
Imports inline symbol content as a new user-symbol asset and returns its id and user:<guid> reference. Always creates a new asset; a colliding name is auto-suffixed. |
Reports: draft
| Tool | What it does |
|---|---|
report_draft |
Opens the report form in the station's window, already filled in with what the agent wrote: kind (DriverRequest, Bug or Suggestion), summary (one line of at most 120 characters, refused rather than cut) and details (optional). Like the title bar's report button, it captures the window first and offers the capture with the report, ticked. It answers at once that the form is open and that nothing was sent. |
The tool never sends. The person at the station reads the report, corrects it if they want, and
presses Send; the outcome shows in the station's status bar and is not reported back to the agent.
While this area is on, the server asks every agent to offer a report when the person needs a driver
Ganter Lab does not have, when a call fails in a way that looks like a defect of the program, or when
the person asks for an improvement, and the descriptions of driver_capabilities, device_upsert
and device_discover say the same.
It refuses with a reason, and then opens nothing and captures nothing:
reason |
When |
|---|---|
not_permitted |
The role signed in at the station does not hold Send reports to Ganter. |
no_station_window |
The station has no window of its own to open the form in: a host that serves its pages to browsers only. |
no_credential |
The session cannot send: the demo profile, signed in or out, or a sign-in to the station's Ganter account that holds no credential. |
form_busy |
The report form is open at the station, or a report is being captured or sent. |
draft_in_progress |
The form holds a report a person is writing. An earlier draft of the agent's that nobody changed is replaced instead. |
A station not signed in to a Ganter account is not refused: the form opens, and says the report goes without an account, so Ganter cannot reply to it.
Like every tool that changes something, it answers Runtime stopped while the runtime is stopped.