Docs Designing the system 16
Quick reference
On this page
Worked examples. USECASES.md has a design for each common need, from a lot's lifecycle to future holds, OCAP plans, ERP integration and the daily report, as JSON you can paste into an element's JSON tab or ask the copilot to adapt. Every whole element in it is checked against the designer's own checks by the test pipeline, so what it shows is what the designer takes.
A change's stages: design → review → approval → approved (waiting for the executor named at its first submission, who plans it first where there is a blackout, an exception signed for a plan inside it; where your organization executes at the last signature, this step is skipped) → executed → verified (its executor signed that it works) or problem reported (with a picture: a request for change, and the change offered for rolling back).


Rule script context: event (kind, object, action, changed, prev, source), user,
record, data, now, lookup(object, id or title) (backend only).


Service script context: service, input, event, user, now, output,
records.get/list/create/update/action/archive/restore, http(connection, request),
transactions.run(name, input, { key }), and what installed suites add.
**What a service may do with an object (uses.objects):** read, create, update, action,
archive (archiving and restoring).
Record events a trigger may name: create, update, archive, restore,
transition:<action>.
Schedule:
{ "schedule": { "every": { "minutes": 15 } | { "hours": 2 }, "at": ["06:00"],
"between": ["06:00", "22:00"], "days": ["mon", "…"], "tz": "Europe/Berlin" },
"missed": "last" | "none" | "all", "overlap": "skip" | "queue" }
(every or at, not both; between only with every.) Or a kind of schedule an installed suite adds:
{ "schedule": { "from": "<suite>.<kind>", "<setting>": value, "tz": "…" }, "missed": …, "overlap": … },
with no every, at, between or days.
Screen:
{ "name", "label", "params": { "machine": { "type": "ref", "to": "machine", "widget": "scan" } },
"blocks": [ { "block": "table", "object": "lot", "where": { "machine": { "param": "machine" }, "state": ["at_machine"] },
"columns": ["lot_no", "qty"], "rowActions": ["track_in"], "width": 6 },
{ "block": "kpi", "object": "lot", "where": {}, "measure": { "sum": "scrap_qty" }, "since": "today", "label": "scrapped" } ],
"callers": { "groups": [ … ] }, "stewards": [ … ] }
Blocks: record (of, show), table (where, columns, sort, limit, rowActions; or query, params, object for a named query's rows), kpi (where, measure,
since, label), breakdown (where, by, measure), chart (query, chart, x, y, series, … as a report's chart has them), transaction (name, fills), button (opens, with),
floor (object, status, picture, colours, image, places), text, media (a file of its own, or a
record's: object, of, field; height, steps), runs (transactions, limit, mine), plan (of, flows),
and a kind an installed suite adds
("<suite>.<kind>"). Every block may have title, width, tab, showWhen, enableWhen and
disabledBecause.
Transaction:
{ "name", "label", "inputs": { "lot": { "type": "ref", "to": "lot", "required": true },
"machine": { "type": "ref", "to": "machine", "from": "lot.machine" } },
"form": { "sections": [ … ] }, "appearsOn": { "object": "lot", "states": ["at_machine"], "fills": "lot" },
"require": [{ "that": <condition>, "message": "…", "field": "machine" }],
"steps": [{ "on": "lot", "set": { "field": <value> }, "action": "track_in", "when": <condition> }],
"confirm": true, "signature": { "meaning": "Performed" }, "maximize": "toggle",
"callers": { "groups": [ … ] }, "stewards": [ … ] }
A policy that applies only through transactions: "via": ["move_in", …].
Form layout entry:
{ "field": "reason", "width": 6, "widget": "textarea", "rows": 4, "help": "…", "placeholder": "…",
"show": { "eq": [{ "data": "disposition" }, "reject"] }, "enable": { "ne": [{ "record": "state" }, "released"] } }
A form is { "sections": [ { "label", "collapsible", "collapsed", "fields": [ … ] } ] } or
{ "tabs": [ { "label", "sections": [ … ] } ] }; a bare field name is an entry with its defaults.
{ "name", "label", "order": 100, "navigator": "shown" | "button" | "none",
"items": [{ "screen": "line_board", "label": "Board", "arg": "L1" }, { "transaction": "move_in" },
{ "heading": "Quality", "items": [{ "screen": "holds" }] }],
"callers": { "groups": [ … ] }, "stewards": [ … ] }
Translations, on any design: "translations": { "de": { "Move in": "Einschleusen", "@fields.qty.label": "Menge" } }:
the English text as it is shown, or @ and the path of one place that says it differently.
Flow templates, named queries and report layouts have shapes of their own: see Flow templates,
Named queries and AI Report: reports, layouts and the analytics copilot; the AI API's contract
(get_contract) gives each in full.
Common refusals and what they mean:
| Message | Fix |
|---|---|
| "It changes qty, which its binding does not declare (writes)" (dry run) | Add the field to the pipe entry's writes |
| "lot_check_qty.js has no test cases: a new or changed script carries its evidence." (fitness) | Add test cases to the script |
| "service … may not update lot: add it to the service's uses.objects" | Tick the operation on Reaches |
| "… is not allowed on connection erp" | Add the method and path to the connection's Allowed requests |
| "A record event or a schedule has no caller" | Set Identity to its service role or a user |
| "no live node has this tag" (monitor) | Ask IT to start a node with that tag (NODE_TAGS), or clear Run on nodes tagged |
| "It never runs: the window leaves no time for it" | Widen Only between, or shorten Every |
For IT (starting the servers): INSTANCE (the node's name), NODE_TAGS (its tags),
SCHEDULER=0 (it plans no schedules), OUTBOX=0 (it runs no triggers), PLANT_TZ (the plant's
time zone), MES_SECRET_<NAME> (a connection's secret), EVENT_LOG_DIR (where its event log is
written).