Docs Designing the system 9
Transactions: screens that change several records as one
On this page
Some work changes several records at once, and must change all of them or none. Putting a lot on a machine assigns the lot to the machine and loads the machine. A transaction is a screen you design for that: what the person enters or scans, what must hold, and the steps. The seed has four: Move in, Track in, Track out and Move out. They are designs like any object's, so your plant can cut them differently (one Start that moves in and tracks in at once) without anyone writing code.


Start one from the designer's home (Transactions → New transaction), or add one to a change (+ transaction). Its tabs:


- General: its label and description; Appears on puts a button on records of an object while
they are in the states you tick, with the record filled in (…filling in says which input), and
…only when a condition on the record holds, if you give one (
{"eq": [{"record": "step_kind"}, "spc"]}); from the navigator (a favorite, or found by searching its name) it opens empty. Confirm first shows the person what will change before it runs (recommended). Electronic signature: its meaning, if the person must sign. Verified by a second person: another person, signed in beside the one running it, verifies it (what their signature means, Verified, and who may give it: departments, or roles written<object>.<role>); at every submit both re-enter their passwords. Two signatures at most. Fill the window: a Maximize button on its page that sets the navigator, the top bar and the tabs aside, for a tablet at a machine or a board on a wall (on request), or the page opening that way (always at first). Filled, the page still shows who is signed in and whether it is live, and the database banners stay; Restore brings the rest back. Each device remembers the person's choice for that page, so a kiosk stays filled after a reload. - Inputs: what the person enters. A reference input names a record (a lot, a machine); set Filled in from to take it from another record (the lot's machine), shown, not typed. Any other input may be filled in from a field of the same type, its value shown beside what is typed (the lot's units beside Good and Rejected), as the person reads it. One filled in can fill in another (the product's route, then the route's first step), but not in a circle.
- Layout: the same layout editor as an object's form. Draw a reference as scan or type the label: the person scans the lot's barcode (or types "4711") and presses Enter. Enter takes the one suggestion the label begins, or the record it names whole (its title, or a field it is scanned by: a badge's sign-in id), and the input flow goes on to its next question. Set Required when here (a scrap reason when there is scrap).
- Input flow: how the form is filled from the keyboard or a scanner, drawn on the flow canvas (section 11): which input next, what moves on from it, decisions on what was entered, Check and Confirm, and the start again. None drawn: Enter goes from input to input in the layout's order.
- Scanning: which label goes to which input, as one table. Give an input the labels it accepts, each named (outer, inner, gtin) with what is printed before the value (Printed before it, and …and after if the label ends with a character) or the GS1 identifier that carries the value (01 a GTIN, 10 a lot, 21 a serial, 00 an SSCC). A scan carrying one of these goes to that input wherever the cursor is, the prefix and suffix taken off; one with no label is plain entry into the field with the cursor. The same label on two inputs (the lot, and a rows input collecting the box's labels) goes to both; the same prefix under two names is refused. A rows input collects one row per scan: say which row field takes the code and which the label's name; its min and max count the scans. What the scans must satisfy (the outer label present, every label this lot's) is a check of yours (Checks), over the rows. Try a scan: paste exactly what the scanner types and read where it goes.
- Checks: what must hold before anything changes, each with the words the person reads when it
does not, on the input it is about. Conditions read
{"input": "good_qty"},{"lookup": "machine.capacity"}(a field of the record an input names),{"user": "id"},{"user": "departments"}(the departments they belong to:{"in": [{"lookup": "tool.department"}, {"user": "departments"}]}keeps each department's tools to its own people),{"user": "certifications"}(the certifications they hold today, from People & departments' list:{"contains": [{"user": "certifications"}, "cnc_router"]}keeps a machine to those certified on it; a scenario's sandbox holds only those its records give),{"person": "certified_for"}(a field of the Person record of whoever runs it: hold an operator to what the plant certified them for) and{"count": {"object": "lot", "where": {"machine": {"input": "machine"}, "state": ["processing"]}}}, withaddandsubfor quantities. Checks run again, under lock, the moment it runs: two people can never both pass "the machine is not full". - Steps: in order, each on the record an input names: Sets fields (to an input, a looked-up
value, a fixed value or nothing), then takes the action (one of that object's transitions),
Only when a condition holds (the machine is loaded only if it was idle). Conditions (section 17) read the
records as they were before the first step.
Add a step that creates a record: Creates a (which object), How many (one, or one per row
of a rows input), and Sets its fields, a row's values read as
{"row": "value"}. It is checked by that object's own policies and rules, as the person, and its stewards approve the transaction too. Add a step that finds records: Finds records of (which object), Where its fields equal what the run works out (an input, a field of a record an input names, a route step's setting, ornullfor one left empty), Named (how the steps after it read it), At most how many (1 to 100), and, optionally, an action and Sets on each. The steps after it read{"found": "holds.count"}(how many) and{"found": "holds.first.reason"}(a field of the first): a hold set ahead for a lot at a step, used and copied onto the lot. An installed suite may add steps of its own (Add: <its name>); one that cannot be taken back must come after every step that can still refuse. - Then: what it runs next. The Then tab names transactions to run once this one has committed, as the same
person: Move out, then the next lot in. Add a transaction it runs next, pick it under Runs, and say what it
is given: each of its inputs, worked out like a step's values (
{"input": "machine"}is this run's machine), its required ones listed for you. Reads first reads a named query before it decides (the lots waiting for this machine, best first where the query ranks them): its parameters are worked out the same way, and its rows are read as{"found": "next.count"}(how many) and{"found": "next.first.id"}(a column of the first), next being the name you give them. Only when is a condition, on the records as the run left them:{"eq": [{"lookup": "machine.state"}, "idle"]}is the machine after the move-out. The next one is a run of its own: its own callers, checks, steps and history, which says which run it followed. If it is refused (the lot waiting is on hold), the first stays done, and the person sees why under its "done": Then Move in: not run: …. A transaction never runs itself next, at most five follow one another, and one already running in that chain is not run again. Sent again with the same submission, nothing runs twice. - Sampling: every Nth, skip-lot. The Sampling tab declares counters: what each counts by (an
expression, the product or the step), and Sample every N (1 samples every one). Skip-lot: once some sampled
ones in a row passed, only every larger Nth is sampled until one fails. Add a step that counts (sampling)
takes one against the counter, in the run's own database transaction (a run that is refused counts nothing, two at
once never count the same one); conditions read
{"sampling": "lot_check.sampled"}(whether this one is to be sampled: put it in a step's Only when; also.n,.every,.streak). Add a step that reports a sampled result says whether the last sampled one passed (Passed when): a pass lengthens the streak, a fail ends it and the rate is back. Two transactions that declare the same counter name share it: the one that moves lots counts, the one that measures them reports. Do not copysampling.ninto a record: it is read before the run is locked; what is sampled is read again under the lock. Only people who may design transactions change a plan, and a change to one is approved like any. - Statistics and run rules in a condition. Over a list (a rows input, the value read per row as
{"row": "value"}):{"stat": ["mean", {"input": "readings"}, {"row": "value"}]}(mean, stdev, min, max, range, median, count),{"capability": ["cpk", {"input": "readings"}, 9, 11, {"row": "value"}]}(cp, cpk, cpl, cpu against the limits) and{"violations": [{"input": "readings"}, 10, 0.2, ["we1", "we2"], {"row": "value"}]}: the run rules the last reading completes, as ids (we1towe4: Western Electric;nelson1tonelson8: Nelson),[]when none. A check:{"not": {"contains": [{"violations": […]}, "we1"]}}refuses a reading beyond 3 sigma. - A step that prints a label: Add a step that prints a label once a label layout exists (Layouts). Pick
the label, the input that names the record it is printed for, the printer (a reference input that names
one, or a field of a record one names:
{"lookup": "machine.printer"}, the press's own), and the copies. It prints once the transaction's writes are in, as the record then is; the Check says what will print, and the job shows on the integration monitor. - Rows (an input's type rows (a table)): the person fills in a table, one row per reading or
wafer. Give its fields as
value:decimal, note:string, and at least / at most how many rows (0 to 1000; at least 3 readings, say). A condition can read them withsomeorevery:{"some": [{"input": "readings"}, {"gt": [{"row": "value"}, 1.5]}]}, and add them up withsum: a journal entry whose lines must balance checks{"eq": [{"sum": [{"input": "lines"}, {"row": "debit"}]}, {"sum": [{"input": "lines"}, {"row": "credit"}]}]}.mulanddivwork out a yield:{"div": [{"input": "good"}, {"add": [{"input": "good"}, {"input": "reject"}]}]}. A field's type may also beenum(a choice: its values under it) orref(a record: pick its object under it; the person searches for it in the cell, among those they may read). Under the field names, each field has its label, required, and Read only when: a condition over the row's other fields and the inputs. Where it holds, the cell is shown read only on that row and kept empty, and a run with a value there is refused ("Row 2: Defect is read only on this row"); a required field is not asked for while it is read only. A defect named only for a part that failed: Read only when Result is not fail. Tick Rows can be dragged into another order and each row gets a handle: drag it, or click it and press the up and down arrow keys. The order is what is sent: the rows' numbers, and the order a step run once per row makes its records in. The table's columns are in the order you type the fields. - Scenarios: the runs kept from the change's sandbox (section 12), each with its last result and open in the sandbox to run it again. A new or changed transaction carries at least one, or the fitness test fails and the change is not submitted (one only routes run is proven by a scenario of such a route too).
- Callers: who may run it; nobody until named (deny by default): groups, people, services
whose scripts run it as their own service role (an ERP starting lots), and routes that run it at
every step (their As it leaves any step, run setting). A signed transaction is run by people only.
The web: tick Published over HTTP and an outside system (an ERP, a cell controller) runs it with
POST /svc/v1/<name>and a token (scopetransaction:run) whose person is among the users or groups above: the same checks and steps as at the screen, all or nothing, audited as that person. A reference is sent as its record's id or its title ("lot": "4713", as a scanner reads it);POST /svc/v1/<name>/previewsays what it would change and writes nothing; anIdempotency-Keymakes a retry answer the first run. Its name is its address: no web service or query published over HTTP may have it. A signed transaction, or one only routes or services run, cannot be published. Once others call it, a change that would break them (an input gone or made required) needs their notice first: Deprecated, with a sunset. - Try it: opens the published screen.
Each step goes through the object's own rules, as the person running it: its state machine, its policies, its rule pipe, its audit. So the object must allow it, only through the transaction: on the object's Roles & policies tab, give the policy that grants the step's fields and action Only through transactions: move_in (its names). That policy then grants nothing on the object's own form, which never offers Move in on its own; a person who tries is told "Move in is done through the Move in transaction", and Why? says so too. Put a state condition on it as well, so it grants only where the transaction applies.
What the person sees: the inputs; Check shows what will change, record by record ("Lot 4713: created → at machine; Machine M-101: idle → loaded"); Confirm runs it, all or nothing, and the screen is ready for the next lot. Anything refused says why, on the input concerned ("The machine is full.", "Lot 4713: The quantity must be more than zero."). Those messages belong to the inputs as they were checked: any edit clears them (a machine refused may be fixed by scanning another lot), and so does leaving the form, its page or its tab on a screen; what was typed stays. A label scanned that finds nothing leaves the input empty and says so. Clear empties the form and its messages, but for what the screen or the record fills in.
From the keyboard or a scanner, without a mouse. The cursor starts in the first empty input. Enter (what a scanner sends after a label, too) goes to the next, in the order the form is laid out; a scanned label first finds its record, and the cursor moves on only once it did. On the last input, Enter checks; the cursor is then on Confirm, and Enter again runs it (a signature's box: Enter ticks it; where two sign, Enter goes on to each password, then to Confirm). Ctrl+Enter (⌘+Enter on a Mac) checks or confirms from anywhere in the form, Esc goes back an input, or out of a check. An input that shows an error, or is required and empty, keeps the cursor until it is put right. Once done, the form is empty with the cursor in its first input, ready for the next lot. To design it otherwise (which input next, what moves on from it, a question only for a lot on hold, confirming at once), draw its input flow on the transaction's Input flow tab (section 11).
Approval: a transaction is approved by its stewards, and a change to its steps also by the
stewards of each object, field and transition they write. The via policies are the objects' own, so
their stewards approve what a transaction may do to their records.
Signed by two people
A transaction can need a second person to verify it (Verified by a second person on its General tab): a material checked by Quality, a recipe loaded under a witness. At the station:
- The operator signs in as usual. The second person signs in beside them: the people icon with a + beside the operator's name at the top, their sign-in id and their password, Sign in beside me. Two at most: a third is refused until one of them signs out.
- Both names show at the top (Olga Ortiz + Quinn Park). The form of a transaction that needs a verifier, once checked, asks for both passwords: Your password, and the second person's. Each signature shows its meaning and whose it is. Without a second person signed in, it says so and offers Add a second person.
- Confirm runs it only if the second person may verify it (one of its departments or roles, and not the operator), and both passwords are right. A wrong one refuses it, says whose, and writes nothing; it counts towards that person's lock (five wrong ones lock them for 15 minutes, as at sign-in).
- The run's entry in the audit trail keeps both signatures: names, meanings, the time.
- The second person stays signed in beside the operator, signing again at each submit with their password, until Sign … out (the × beside their name) or the operator signs out, which ends both.
Who signs in through single sign-on has no password here: they set a signing password on their Your password page, used only to sign (it never signs anyone in), or each uses Sign in again with single sign-on beside their password box. Who signs in through the plant's directory signs with their directory password. On a development or demo instance (anyone may be anyone) no password is asked; who may verify is checked all the same. In a sandbox or a scenario, a signed step names its verifier (Verified by), with no password.