Docs Designing the system 5
Rules: checking and adjusting data
On this page
When metadata is not enough ("at most 5 % over the work order's quantity"), write a rule script. Rules run as a pipe: each script gets a context, returns it, and passes it on. A script refuses by throwing; its message is what the person reads.


// lot_check_qty.js
export default async function lot_check_qty(ctx) {
if (ctx.event.kind !== "save" || !ctx.data.work_order) return ctx; // not mine: disregard
const order = await ctx.lookup("work_order", ctx.data.work_order);
const limit = order.qty * 1.05;
if (ctx.data.qty > limit) {
throw Object.assign(new Error(`At most ${limit}: 5% over the order quantity.`), { field: "qty" });
}
return ctx;
}
The contract:
- One file, one function, the same name:
lot_check_qty.jsexportslot_check_qty. Nothing else in the file: noimport, no other statement. - Throw to refuse.
field: "qty"puts the message beside that field;fields: { … }places several. - The pipe runs on every change of state, and your script decides whether it cares:
ctx.event.kind | When | Where it runs |
|---|---|---|
change | Every keystroke, pick or scan in the form; someone else's change arriving | The browser, as advice |
save | Create or update | The browser, then the server, which decides |
action | A transition (ctx.event.action names it) | The browser, then the server |
archive, restore | Archiving or restoring the record | The browser, then the server |
committed | After the change is saved (entries marked committed only) | The server |
- The context:
ctx.event(what changed:changed,prev,source),ctx.user,ctx.record(as stored),ctx.data(the values being checked),ctx.now(the clock: use it, notDate), andctx.lookup(object, key): one record, with your rights, by its id or by its title as a label reads it (a hold code"SPC", the newest in use); on the server only, so a script that looks up is backend only. - Changing data. A script may change a field in
ctx.dataonly if its pipe entry declares it in writes. An undeclared change stops the pipe. This way a reviewer sees, from the object alone, what each script can alter. - Pipe entry options: writes (the fields it may set), when (a condition to skip it without running it), backend only (it needs rights the person may not have, so it runs only on the server), committed (it runs after the save).
- After commit. An entry marked committed runs on the server once the save is in the database,
never before:
ctx.event.kindiscommittedandctx.event.writesays which write it follows (create,update,action,archiveorrestore). It sees the record as it is then, may look records up and may throw, and changes nothing: the save is done, so it declares no writes (the check refuses one that does), and a field it sets stops it as a fault. Its throw never reaches the person who saved and never undoes the save: it is written in the record's history ("Rules after the save"), said in the event log, and tried again a little later each time; after five tries it is given up on, as an error in the event log (which IT may send on as an alert). Use it to check what a save left behind; to act on another system after a save, use a service. - Scripts cannot reach the network, the page, or other systems, and have no randomness: the same context always gives the same outcome, so an auditor can replay any decision. To act on another system after a save, use a service (section 7).


Test cases are part of the script. Each case gives a context and the expected result
(data, changed fields, or the expected error). A new or changed script without test cases, or with
a failing one, cannot be submitted. A dry run saved as a test case keeps the moment it ran in its input (now), so it
gives the same output when the fitness test runs it again; its expected output leaves out who ran it.
{ "name": "over the limit", "run": { "event": { "kind": "save" }, "data": { "qty": 2000, "work_order": "…" } },
"expect": { "throws": { "field": "qty" } } }
Dry run executes the draft script on a context you give, with real lookups (your rights), and shows what it changed or the error on its line.
A script imports nothing: import(…) is reported as a problem where it is written (in a comment or
a text too, so word it another way), and has no typed arrays or WebAssembly to work with. Its data is
what its context holds.