OpenCore MES Try the demo

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.

The lot object's Rules tab: six rule scripts in pipe order, what each may write, backend only
An object's Rules tab: its rule scripts in the pipe's order, what each may write, and whether it runs on the server only.
The lot object's Rules tab: six rule scripts in pipe order, what each may write, backend onlyAn object's Rules tab: its rule scripts in the pipe's order, what each may write, and whether it runs on the server only.
// 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.js exports lot_check_qty. Nothing else in the file: no import, 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.kindWhenWhere it runs
changeEvery keystroke, pick or scan in the form; someone else's change arrivingThe browser, as advice
saveCreate or updateThe browser, then the server, which decides
actionA transition (ctx.event.action names it)The browser, then the server
archive, restoreArchiving or restoring the recordThe browser, then the server
committedAfter 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, not Date), and ctx.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.data only 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.kind is committed and ctx.event.write says which write it follows (create, update, action, archive or restore). 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).
A lot's History tab: Made, Move in and Track in, each with who, when, what changed and the rules that passed
A record's History: each change, who made it, what it changed, and every rule that ran on it.
A lot's History tab: Made, Move in and Track in, each with who, when, what changed and the rules that passedA record's History: each change, who made it, what it changed, and every rule that ran on it.

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.