Docs Designing the system 4
Designing an object
On this page
An object is a kind of record: a lot, a work order, a deviation, an inspection. Nothing is defined in advance: the object's fields, states, roles and rules are its design.
Open an object's change and use its tabs (beside them, Copilot (section 14), Changes, what this change alters, opened first in review, and Translations (section 15)):


General
A new object is given its Name first (lower case letters, digits and _; it cannot be changed once
published, as a field's).
Label, Area (where it appears in the navigator), Description, and the Title field: the field that names a record in lists, tabs and references (for a lot, the lot number).
Scanned by: up to three more fields a scan, or a name typed whole, finds a record by: a text or a whole number, never a sensitive field. Person is scanned by its sign-in id, so the badge a borrower holds up fills in "Borrowed by". A field you may not read finds nothing for you.
Analytics dimensions: up to five fields (for a lot: item, uom) copied into each stay of a
record in a state, so its analytics can be grouped by them. The value copied is the one the record
had when the stay began: a lot moved to another item later still counts under the item it had then.
Long text cannot be a dimension. Choosing dimensions is a design change like any other.
Excel import and export: whether the model may be exported, whether an import may create records or update (override) existing ones, and the field rows are matched by (section 13, "Import and export in Excel").
Flows: whether its records take part in flow templates (section 11), and as what: a traveler goes through a route (a lot), a resource is where a route's work is done (a tool), a subject's events may set a plan off, a reference is one a flow may read (a product). None ticked: they take no part. A traveler names Its step field: the sequence it is at, which a route marks as it enters one, and which, written (a move, a form, an import), moves the route there.
Fields
Each field has a name (lower case letters, digits and _, starting with a letter, at most 48; it cannot
be changed once published), a label, and a type:
- Renaming a field: until it is published, click its name (✎) and give the new one. Everything in the object that names it follows: the title field, the list, the form, policies and their conditions, hints, analytics and import. Scripts, transactions and screens in the same change that read it are named by the checks. A published field's name is locked (its records hold their values under it): change its label, which is what people see, or add a field and remove the old one.
- Removing a field: Remove takes it out of the form, the list's columns, analytics, the policies and approval of edits too. What decides by it (a condition, the title, the import key) is named by the checks, for you to point elsewhere. Removing a state takes its tone with it.
- Kept fields (the lock in the list): some parts of an object are relied on, by the platform (the built-in Person's sign-in id, name and active) or by an installed suite. A note at the top of Fields says who keeps what, and why. A kept field cannot be removed or retyped, stays required if it was, and keeps its choices (add more if you like); kept states, actions, rules and policies stay. The checks name anything that would break one. Removing the suite that keeps something lifts its lock.
| Type | Holds |
|---|---|
string | Short text: 500 characters unless the field says, at most 2000 |
text | Longer text: 500 characters unless the field says, at most 20000 |
integer, decimal | Numbers |
boolean | Yes or no |
date | A date (YYYY-MM-DD) |
enum | One of a list of values you give |
ref | A reference to a record of another object (a lot's work order) |
image | A picture (PNG, JPEG or WebP, up to 5 MB): whoever may write the field uploads it on the form |
file | A document, picture or video kept with the record (a PDF or spreadsheet up to 10 MB, a video 100 MB); see below |
Mark a field required (its column in Fields), or computed (set by a rule, not typed:
"computed": true in the JSON tab, as no column sets it). A computed field shows on the form what its rule
works out as the person types; the form never sends that value as theirs, and the save works it out again. Mark
every field a rule writes computed, or the save takes it for the person's own and checks their right to write it.
Names such as id, state,
type, archived_at, created_by, created_at, updated_by and updated_at are reserved: a
record keeps those itself.
What a field accepts is checked where it is entered, with the reason beside it: a whole number is one
the database can hold (not 1e300), a date is one that exists (not 31 February), a reference names a
record of the object it refers to that the person may read, and a choice lists each of its values
once. Numbers are shown as they were entered, grouped in the plant's format and never rounded: 0.0004
reads 0.0004 everywhere, in an approval too.
On Fields, the table scrolls in its own box: its head stays at the top, Name and Label at the left and the remove button (a bin) at the right. Values / refers to shows a summary (a choice's first values and how many more, what a reference refers to, where a derived field reads from); its expand button opens the field in a panel to manage its values, Multiple select, what it refers to, the files it takes and Derive….
- Longest (in a text or long text field's panel) is how many characters it may hold: up to 2 000 for a text, 20 000 for a long text, 500 if you say nothing. Typing stops there, a long text shows its count as it nears it, and a save that is longer (an import, a service) is refused, saying by how much.
- Decimal places (in a decimal field's panel, its expand button on Fields) says how many places a number has: money at 2 (100.99), a measurement at up to 10 (0.8899098234). At most is the most it takes (empty: any number); Shown with at least pads it when it is shown (money at 2 shows 100.10, in the plant's own separators, 100,10 in Germany); at most and at least the same is a fixed number of places. More places than that says what a value with more gets: refused (the save says "At most 2 decimal places (this has 3)", whether it came from a form, a transaction, a service, an import or the AI), or rounded half up (1.005 to 1.01) or rounded half to even (1.025 to 1.02, so sums do not drift). The form says the places under the box, says a number with too many as it is typed, and rounds it when you leave the box, so what you see is what is kept and signed. A transaction's decimal input takes places the same way (At most … decimal places beside it on Inputs). Lowering the places later changes no record: the change's fitness says how many records hold more, they keep what they hold and show it whole, and a save that changes that number must fit.
- Multiple select (in a choice field's panel) lets a field hold more than one: a lot's defects, a work order's lines. Turning it on or off in a change converts the stored records when the change is executed. A field used as an analytics dimension or an import key keeps a single value.
- Required when (in the field's inspector on Layout) makes a field required only under a
condition, for example a reason when the disposition is
reject:{"eq": [{"data": "disposition"}, "reject"]}. The server checks it too. - Sensitive (its own column on Fields) is for health or personal data: a patient's name or id. Its value is hidden wherever records are shown or exported ("Hidden: sensitive"); someone who may read it presses Show and says why, and sees it on that page until they leave it. Each showing is kept in the record's history, with who and why. It is never in Queries, Analytics, AI reports or the copilots, and never written into the audit trail (which says it changed, not to what). Who may read or write it at all is still up to the object's policies. A sensitive field cannot be the title, an analytics dimension, the list's sort or the import key, and a screen does not sort, sum or group by it.
- file (a type): a work instruction, a drawing, a video of the job, kept on the record. In the
Takes section of its Values / refers to panel, tick what it takes: picture, pdf,
video, spreadsheet (none ticked:
pictures, PDFs and videos). On the form it is shown small, its name and size, with Show here
(read the PDF or watch the video in place), Upload…, Replace… and Remove; a file of
another kind is refused, saying what it takes. A file is read through its record, by whoever may read
that record and field and nobody else. Derive one through a reference (a lot's Instruction from
Step → Instruction) and each lot shows its step's, and the new one as soon as the step's is
replaced. A screen shows one with a file block (Screens). A field that takes pdf alone has
Controlled copy: words such as
Controlled copy for {user.name}, {now.date}: {record.doc_no}printed across every page of each copy, and on its foot. The PDF is then served only through its record, as the copy for the person who asked (what they print or save carries their name and the day, and the browser keeps none), never by its kept bytes or its hash address, and each copy issued is written in the record's history. A PDF protected by a password cannot be stamped and is refused. A field can also be released only against a request (its design says which object holds the requests, byrelease): what is on the screen is then a stamped view, and a copy to print or save, from the Controlled copy button of a screen's file block, is issued only while an approved request of that person for that record has copies left; each copy is numbered (copy 2 of 3) and written in the request's history. - Erasable (its own column on Fields) marks personal data a privacy officer may erase from a record when someone asks (Data retention). Not on a picture, nor on a person's name or sign-in id (People & departments keeps those).
- Numbered (in the panel a text field's expand button opens) makes a field the platform numbers when its
record is saved, the next of its series with no gap: a journal entry's JV-2026-00042. Type its format:
{seq}where the number goes ({seq:5}pads it to five digits),{yyyy},{yy},{mm},{dd}the plant's date, and{branch}(any required text, choice, whole number or date field) another field's value. The series starts again when the rest changes:JV-{yyyy}-{seq}from 1 each year,{branch}-{seq}per branch. Nobody types or changes it (the form shows it read only, "numbered when saved"); a save that is refused takes no number, and records made at the same moment each get their own. Leave the format empty for a field people enter. - Derived from a reference (Derive… in the panel a field's expand button opens, under Values / refers to on Fields, once the object has a reference field) makes a field the platform keeps, from what the record's references point at. Pick a path a step at a time: one of this object's references, then a field of what it points to (a lot's Product → Control), and on through another reference when that field is one (a wafer's Lot → Product → Code). Or choose Use an expression for a condition over the record and the fields its references point at ("is its product military?": yes or no). Nobody types it: it is worked out at every save, and again, at once, when the record it reads changes (reclassify a product and its lots and their wafers follow; each is in their history as "derive", naming what it follows). Executing the change that adds one fills every record already there. Lists, queries, policies and an object's access read it like any field, which is what it is for: a lot reads its product's classification without anyone copying it. It is never required, sensitive or erasable, never from a sensitive field, and two fields may not read each other in a loop; the check says which. Whoever reads it reads what it copies, under this object's policies.
States
A list (departments, operations, reasons: reference data that is added and edited, never moved through a lifecycle) has one state and no transitions. A new object starts that way; its records show no state, and the tab says it is a list. Add states and transitions when the object has a lifecycle.


The record's life: its States (for a lot: created, in_process, on_hold, released,
consumed), the Initial state, and the transitions between them. Each transition is an
action with a label ("Release"), the states it may start from, and the state it leads to. Actions
appear as buttons on the record, for the people allowed to take them.
Tones: how each state shows, by what it means: ok (released), warn (on hold), danger (rejected), info, neutral (consumed), or plain. Each state's badge previews it. You choose a meaning, never a colour: the plant's theme colours it, in light and dark alike.
Lists of words are tags. Wherever a design takes several words (roles, an enum's values, states, the states a transition starts from, fields, columns, times of day, the plant's domains), they are chips: × removes one, the box suggests what already exists as you click into it or type, Enter or a click adds, Backspace in the empty box removes the last. Where a new one may be added, Add “…” is offered (and what is typed is kept when you leave the box); where it must already exist (a field, a state), only those are offered, and a word that is not one is said not to match.
One of many is found, not scrolled. Wherever a design names one thing out of a list that grows with the plant's model (an object, a field, a state, an action, a transaction, a screen, a route, a layout, a named query, a script, a service, a connection, a group), the box finds it as you type: every word you type must appear somewhere in the name, the label or the hint, in any order ("lot oper" finds "Lot · operator"); ↓ or Ctrl+Space lists what can be chosen as the box stands (a second press closes it), ↑ ↓ move, Enter or a click chooses, and the choice shows as a chip whose × clears it where the design allows none. A plant with five hundred objects, a thousand transactions and twenty thousand routes never sees a dropdown of them. Short fixed lists (a type, a width, a kind) stay dropdowns.
Where a box takes a name that may also be new, it suggests what the plant has and takes what you type: an object's Area, a block's Tab, a chart's columns (from its named query), a flow field's Value (column), an approval step's label, a link's Page, a Successor, a time zone, the plant's locale. Press Enter, or leave the box, to keep what you typed. Stewards are department chips: type part of a department's name to add it, × to take it off.
Roles & policies
Who may do what. Access is denied unless a policy grants it.
- Reserved to a certification comes after the object's Roles, at the top of the tab: records only the certified may see, whatever their roles. Reserve records to a certification adds one: the certification (People & departments lists them, Certifications) and For the records where, a condition on the record (empty: every record). A military product requires ITAR when its control is military; its lots and wafers derive that control from it (above) and require ITAR the same way, so the rule is written once and follows the product when it is reclassified. Someone without the certification, active and in date, sees nothing of such a record: not in a list or its count, a search, a query, an AI report, an export or analytics, and opening it by its id finds nothing, even for those who read every record. A save that would leave the record reserved from whoever makes it is refused, naming the certification. The plant's plans and machines are not held to it; a service with its own identity holds the certifications its design names (none unless named). It is approved by the object's stewards and governance. A policy's condition may also read their certifications.
- Roles are declared by the object (
operator,supervisor,quality,viewer). People and groups are given roles through their own change requests. The box suggests the roles other objects declare, so the plant's words stay alike; type a new one and press Enter to add it (lower case letters, digits and_; several at once with commas). A policy's Roles box offers this object's roles, and a new one typed there is declared on the object as well. - A policy's name only says what it is for (
lot-read,desktop-edit); what it grants is what is ticked in it. So each policy ends with In short: one sentence saying what it lets its roles do (its condition in words, its transactions, the fields it never lets them write), then, for a role other policies also name, what that role may do with all of them counted (desktop-readanddesktop-edittogether); it warns when roles may change records but no policy lets them read them, says where reading comes from when another policy grants it, and warns when the name says the opposite of what is ticked. Set it to Read only, Read and edit or Nothing sets the ticks at once; rename changes the name. - A policy grants something to one or more roles, optionally under a condition:
- may read records, may create records, may archive and restore records;
- per field: read or write (write includes read);
*for every field not named. Each field is a tile: click it to go from nothing to read to write and back; green is write, amber read; - per action: allow;
- Only through transactions: the policy grants only when a person works through those transactions;
- deny: Deny writing these fields whatever other policies say (a lock that wins); fields hidden
entirely and actions refused are written on the JSON tab (
deny.read,deny.actions). Each is a list of names; one name written alone is reported as a problem, never read as "deny nothing".
- A condition (section 17) reads the record (its state, type, any field) and the user: Only when, built with
Edit (or typed with JSON, and tried with Try), for
example
{"in": [{"record": "state"}, ["created", "in_process"]]}. Conditions never read the clock; a rule does that (section 5). A condition is checked as you design it: an operator the language does not have, or one given the wrong shape, is a problem on the policy, before anyone opens a record. - A team's records to its members. A condition may read their departments and their groups (every
group in People & departments they belong to, their departments too). Give the object a field naming the team
(a choice of the groups' ids,
team), and a policy for its role Only when the team is one of their groups:{"in": [{"record": "team"}, {"user": "groups"}]}. Everyone holding the role then sees, in a list, a search and on the record, the records of their own teams and no others; someone who joins a group in People & departments sees its records from then on. Lists find them by the index, however many records the object has. - In Queries and Analytics a policy counts as it does on a form, with two limits: a condition that reads the user's departments or groups, or that does arithmetic, cannot be said in SQL, so in a query that policy grants nothing (and what it hides stays hidden). Write such access by role or by state where people need it in Queries.
- Hints (on the JSON tab) say what a person can do instead, for example "A released lot's quantity is corrected through a deviation". They appear when someone asks Why?.


Overview. Below the roles and the certifications, a grid shows the whole object at a glance: its roles across, and down the side the records (read, create, archive), every field and every action. Each cell is what that role comes to over all the policies:
| Cell | Means |
|---|---|
| green write, yes, allow | granted |
| amber read | may read the field, not write it |
| — | not granted (the default) |
| red locked, hidden, refused | a deny applies, and wins over any grant |
a dashed outline and a * | only under a condition, or only through a transaction |
Point at a cell to read which policies make it so. Click a role's name to show only the policies that name it; click it again for all of them. The grid follows your edits as you make them.
Changing a grant from the grid. A cell is what several policies add up to, so a change is always a change to one policy:
- Click a cell: under the grid, every policy that names that role is listed with what it says on that field or action. Click a policy's tile to change it (a field goes — → read → write → —; the rest are granted or not). A policy shared with other roles says so in amber: a change here is also for maintenance, quality.
- Double-click a cell (or press Enter on it) to change it at once. This works when there is no doubt which policy to change: exactly one policy is for that role alone and has no condition. Otherwise the list opens for you to choose.
- Grant it in a new policy for the role alone adds a policy named after the role, when none of the existing ones is the right place.
- A cell may not change colour after your click: another policy may still grant as much. The list shows why.
- Denies, conditions and "only through transactions" are edited in the policy's own card below. It reads the design, not a record: what one person may do with one record at one moment is still answered by Why? on that record.
Every "no" can be explained: a person who cannot change something presses Why? and reads the policy, the condition and the state that decided it, from the system's own decision.
Archiving. "May archive and restore records" lets a role take a record out of use: it leaves the lists, becomes read-only and keeps its history (nothing is ever deleted). A condition applies both ways: if supervisors may archive lots that are on hold, only they may restore a lot archived while on hold.
Rules
The object's rule pipe (section 5): Add to pipe adds a published script, or one written in this change.
Layout
How the list and the form look. Nothing here grants or refuses anything; that is Roles & policies.
- List: the columns, in order, and how the list is sorted. Search first is for an object with too many records to browse (Person has it): its list starts empty, with a search box, and shows what matches. Development, the demo and test instances list them anyway.
- Form tabs: one page, or several tabs (+ tab); each tab holds sections.
- Sections: a heading and its fields. A section may fold (a person opens it when needed) and start folded.
- Fields: drag a card to move it, within a section or to another; or use ◀ ▶ to move it and − + to make it narrower or wider (a row is 12 columns: 4 is a third, 6 a half, 12 the whole row). A field goes no narrower than its widget fits: 2 for a text, number, checkbox, toggle or yes / no; 3 for a dropdown, search, scan, date, stepper or radio list; 4 for buttons, a checkbox list, a multi-select, chips or a text box; a table takes the whole row (12). In a narrow window the cards sit two to a row, as the form does on a small screen. Fields not on the form wait in the tray below; drag them in.
- Inspector (click a card):
- Width, Drawn as (the widget: a dropdown, a searchable dropdown, radio list or buttons; for several values a checkbox list, multi-select or chips; a checkbox, toggle or yes / no; a search as you type for a reference; a number with − +), Help text, Placeholder, the Height (lines) of a long text: at least so many lines, and, if you give the largest, growing with what is typed up to it, then scrolling;
- a reference is searched as typed unless you draw it otherwise: nothing is looked up until Letters before searching (2 unless you say; 1 to 6) are typed, then the first 20 records the person may see whose name holds them, those it begins first; more letters narrow them. A plant's thousands of lots are never sent to fill a list. A dropdown lists the 200 changed last: keep it for a short list (a handful of stations); scan takes a label read off a barcode;
- a searchable dropdown (a choice or a reference) opens its list when the field is clicked, its arrow pressed or ↓ typed, and narrows it to the choices holding every word typed, in any order: pick one with a click, or ↑ ↓ and Enter; Escape closes it. — at the top of the list (or the box emptied) takes the value off; words that name no choice are put back as you leave, so only a choice from the list is ever kept. A reference's list starts with the 20 records changed last that the person may see and gets 20 more as it is scrolled (100 at most: then type to narrow them); typing searches every one. Use it for a long list of choices (forty reasons, every department) or a reference people pick by browsing rather than by its label;
- Shown when: the field appears only under a condition, for example
{"eq": [{"data": "disposition"}, "reject"]}; - Enabled when: it can be typed in only under a condition; otherwise it is greyed out. A field a policy locks stays locked whatever this says;
- Required when: see Fields.
Conditions (section 17) read the form's
data, therecord(itsstate,type) and theuser, like a policy's, built with Edit (or typed with JSON). A condition applies as soon as it reads right; one that does not is shown in red. Take it off the form puts the field back in the tray.
- History (below the list): what a record's History tab says of each change. Every field's changes, or only the ones you list (a lot's tool, wafers and hold reason, without the counters a route keeps); Say each step of its route it enters (Entered Oxidation (CMOS route)); Name the transaction or plan behind each change (Track in · Wade Tanaka), a transaction's writes told as one. It is how the history reads, never what is kept: the audit trail keeps every change, and whoever reads the record can tick Show every change.
Preview
The list and the form as a person will see them, from the draft.
Stewards
The departments that answer for the object, and optionally for single fields, states, transitions
or policies. Stewards decide who approves: a change to the disposition field goes to its
stewards (Quality) and not to the whole object's. A new object is stewarded by its area's
department.
Approval of record changes (at the bottom of the tab): changes to this object's records made outside a transaction can wait until the stewards approve them.
- Changing values waits for approval: any field, or only the fields you tick, in any state or only the states you tick (a lot's quantity once it is released).
- A new record waits for approval: it exists once approved.
- Archiving (deleting) and restoring waits for approval: nothing is ever deleted; an archived record leaves the lists and is read-only. Asked like a change, with why, and done once signed.
- Actions wait for approval: every action, or the ones you tick (putting a lot on hold).
- Decided on: the fields the approvers decide on besides those a change makes (a loan's amount, term and documents, and the member's capital, beside its Submit; a review's score and the manager's final words beside its final rating). A change waiting for approval is applied on the record as it is when the last approver signs. It is void at once, its requester told what changed and who changed it, when what it was asked on changes meanwhile: the fields it changes, the state for an action or an archive, and the fields named here. Anything else (a lot moved in or tracked in, another field corrected) leaves it waiting. Name here what an action is approved for, or the record could change under it after people have signed.
- Who approves follows a value of the record: pick a field (a product's Engineering group: a choice, a text or a yes / no) and, for each value, the departments or groups that approve its records' changes, typed to find them: power by the Power engineers group, mcu by MCU engineering and Quality. A group (People & departments) is people from any departments: any one of its members signs for it, never the one who asked. Its departments and groups approve in place of the stewards above, or as well as them. A value you list nothing for is approved by the stewards as ever. A change that moves a record to another value (a product from power to mcu) is approved for both, the group it leaves and the group it joins, and each department's chip says which value it signs for. To route by a reference (a product's group as a record of its own), add a text field derived from it (its code) and choose that field.
- A parameter adjusted within approved limits. A number field's ⋯ panel has Adjustable within limits: its
Least and Most (a number, or the name of a number field of the record that holds the limit: put that field
under Changing values waits for approval, or the check refuses the design, since limits anyone could move bound
nothing), At most per adjustment, Only in states (a recipe's released state), Only by roles and A person
says why. Then whoever holds one of those roles changes it at once, with no approval, by a step no larger than that,
and inside the limits; the form says adjust 0 to 5 beside it, asks why on Save, and the audit trail keeps the
adjustment as its own entry (
adjust:<field>) with the limits it was held to and the reason. A larger step, or someone without the role, waits for approval as ever; outside the limits nothing writes it, whoever asks (a form, a transaction, a service, an import), with the limits named; to go beyond them the limit is changed, which waits. A transaction or a service writes it as it writes anything, inside the limits. Use it for a recipe's offsets, a tool's compensation, a setpoint an engineer trims between approved extremes. A value kept in a record of its own (one per lot, worked out for that lot) takes its limits from another record's: make its limit fields derived through the reference (recipe.offset_min), where that field waits for approval on the recipe. They follow the recipe's at once; a lot's value made outside them is refused, and one that the recipe's narrowed limits now leave outside is never sent to a tool: the transaction that would send it is refused, naming them. - Who approves follows an approval flow: pick a flow template of kind approval whose subject is this object (section 12, Approval flows): its steps say who signs, from the requester's department and the departments above it, a fixed department, a group, a role or a person a field names; it branches on the record and may escalate. With one, the stewards and the value above do not route record changes.
- Mail when a change waits, Mail when it is decided: a mail layout each (section 13, Mail layouts), sent to whoever may sign (their own address, and the department's mailbox) and to whoever asked; the organization's, else the platform's words, when none is picked.
Transactions never wait: they are the approved way to change records. So a transaction, a service or a route that writes what an approval controls (a product's yield limit, its engineering group) is approved by that approval's departments and groups when it is designed or changed: the Power engineers sign the transaction once, and its runs go through at once. Leave this off for lists and master data that do not need it.
A change that waits shows on its record to everyone who may read the record: that it waits, why, and for whom. The values themselves (as it is → as asked) are shown to who asked, to those who approve it, and to anyone who may read that field; for anyone else a hidden field reads "hidden from you".
Printers (General tab): tick its records are label printers on the object whose records are the printers,
and say which of its text fields holds the adapter a printer is spoken through (file: what it would print as
SVG into a folder; browser: the person prints it from their own browser; or one a suite installs, such as a Zebra's
ZPL) and which its address. A transaction's print step then names a printer by expression (section 9).