OpenCore MES Try the demo

Docs Designing the system 3

Working in a change request

On this page

Open a change from the designer home: Change on an object, New service, New connection, or Start design for a new object (give it a name such as inspection and a label). A new object's name can be changed on its General tab until its first version is approved; after that it is fixed, and the label is what people read.

A change request for the lot object, at Design, its General tab open
A change request: the stage it is at (Design, Review, Approval, Execution), Undo and Redo, and the design's own tabs. Here the lot object's General tab.
A change request for the lot object, at Design, its General tab openA change request: the stage it is at (Design, Review, Approval, Execution), Undo and Redo, and the design's own tabs. Here the lot object's General tab.
A change's Changes tab: the machine object's description, the old words and the new
A change's Changes tab: each difference from the published version, as reviewers and approvers read it.
A change's Changes tab: the machine object's description, the old words and the newA change's Changes tab: each difference from the published version, as reviewers and approvers read it.

Finding a design. Every tab of the designer's home (Objects, Transactions, Screens, Flows, Report layouts, Menus, Queries, From suites, Services & connections, People & departments, Changes) has a search box (every word you type, in any order, in its name, label or what it is about), filters of its own (an object's area, a transaction's object and whether it is signed, a flow's kind and records, a query's parameters) and, on every tab of designs, Stewarded by a department and Open change; Changes filters by State and Author only, and People & departments has no filter. Sort orders it by name, id, version, an open change first or what fits the tab (a change by when it was updated), and the arrow beside it reverses the order. "3 of 41" and Clear show once you have narrowed it; each tab keeps its own while you move around.

Undo and redo. Undo and Redo above the editors take back the last edit to the change and put it forward again, whichever editor it was in (a field, a policy, a node, a person, a script): ⌘Z or Ctrl+Z, and ⇧⌘Z or Ctrl+Y, do the same while you are not in a text box (in a box, they undo your typing there as usual). Typing in one box is one step, and a click that changes several things (a node's script and its test) is one step. Undo is saved like any edit. The steps last while the change stays open in this window, up to 100; when someone else's edit to the change comes in (a co-designer, the copilot), they start again, so you never take back their work.

Several designs in one change. When one piece of work spans several designs (a new field on the lot and the work order, the transaction that fills them, the screen that shows them), bring them all into one change with Change also…. It is reviewed once, and each department any of them touches approves once (the approval route is every design's, together); it executes all at once, or not at all. Every rule still applies to each design: its own problems, its scripts' test cases, its scenarios if it is a transaction or a flow template that changed, and execution refuses the whole change if any of them changed live since it was brought in. A design brought in and left as it was asks no one's approval and is not published again. A design is in one open change at a time: one already in another is refused, naming that change; finish or withdraw that one, or make the edit there.

A copy of another. Every New form (object, service, connection, transaction, screen, flow template, report layout, query, menu, and a suite's design element, where the copy keeps its kind) offers blank or a copy of … a live one of its kind (or press Copy on a design's row, all but a menu's: the New form above takes it, the cursor in its name box): the new one starts as all of it, under its new name (its label, if left empty, says "(copy)"). A service brings its script, its function renamed; an object its rule scripts, each copied under a name of its own (lot_round_qty becomes batch_round_qty), so the copy's rules are its own; a transaction or a flow template its scenarios, running the copy. Nobody holds a role on a copied object yet: give them in People & departments. A copy is a new design, with no tie to the original, reviewed and approved like any other. Add to this change copies one drawn in the same change too.

The change request page:

  • The stage bar: Design · Review · Approval · Execution, with the current stage highlighted; where your organization executes changes by hand, Design · Review · Approval · Approved · Execution · Verification (problem reported, crossed out, when its executor reported one).
  • Execution (beside the change): who executes it, Execute for them once it is approved, then It works (sign) and Report a problem…; its designers may name someone else (Change who executes it…).
  • What it holds: the objects, scripts, services, connections, transactions, screens, flow templates, report layouts, queries, menus and a suite's design elements in the change. Add to this change makes a new one in it (blank, or a copy). Change also… → Bring in brings a live one in, to change it together with the rest: an object, a transaction, a screen, a flow template, a report layout, a query, a menu, a service (with its script) or a connection. Unsaved edits are saved first, and the one brought in opens in the first window, as it is live.
  • Windows. Split shows up to three editors side by side on the same draft, for example the object on the left and its rule script on the right. Every window edits the same draft.
  • The side panel:
    • Why this change: the reason. Required before you can submit; reviewers and approvers read it.
    • Problems: everything the platform would refuse, found as you type (a field that does not exist, a script that does not parse, a trigger on an unknown event…). You cannot submit while any remain.
    • Fitness test: runs the evidence reviewers will see (section 12). Run fitness test runs it now; submitting runs it again. Click a finding to go where it is put right; Fix with the copilot asks the copilot about it.
    • Will need approval from: the departments whose representatives will approve, recalculated as you type. Watch it: if a department appears that you did not expect, your change touches more than you meant.
    • Save draft, Submit for review, Withdraw. The whole panel folds away by Hide panel beside Maximize, for room to design, and comes back by Panel there; the choice is kept for you. The draft also saves itself two seconds after your last edit: reload the page, or open the change on another computer, and it is as you left it. A record form with unsaved edits asks before the page is reloaded or left.
  • Designers. A draft is its author's: to other designers it is read only. At the top of the side panel the author adds co-designers (other designers), who edit, save and submit it too. Like the author, they cannot review or approve it, and that stays so if the author takes them off the list later: the panel lists them under "also worked on it". If two of you save at once, the second save is refused and names who saved first; Load their version brings their work in (yours is then replaced). A fitness run or a review never counts as a save.
  • Presence. If someone else has the same change open, a banner says so, and says when they are editing.

Every tab has a JSON view showing the element exactly as it will be stored. You can edit it and Apply JSON; the same checks apply.

The test sandbox: trying changes together before approval

Approval is for a design you are done with. While you are still iterating, and when your change only makes sense together with someone else's, use the test sandbox: one shared copy of the system that holds what is live plus every change under test. A screen in your change can show the object in a colleague's, before either is approved.

  1. On your change, in the panel on the right, press Add to test sandbox. The change stays in design and stays yours to edit.
  2. Press Open the test sandbox. It opens in a tab of its own, with TEST SANDBOX in the top bar. You are signed in as yourself, with your own roles (and the ones the changes under test give you).
  3. Try things. Records you make there stay there; nothing reaches the plant. Go back to the change, edit, save: the test sandbox is rebuilt the next time it is opened, and your test records are kept.
  4. When the design has settled, submit each change for review as usual.

The order matters. The Designer's Test sandbox tab lists the changes under test in the order they are applied. A change that needs what another brings (a screen needs its object) must come after it; if it does not, it is marked could not be applied, with the reason, and the others still run. A designer moves changes up and down with the arrows. Build it again now rebuilds at once.

What it was tested with is recorded on each change, under Tested with: when, and which other changes were in the test sandbox with it. Reviewers and approvers see it.

Things to know:

  • The test sandbox starts with no records of the plant: make the ones you need there.
  • Being under test changes nothing about approval. Every change is still reviewed, approved and executed on its own. If your change needs another one to be live first, get that one approved first: a change whose needs are not live yet is refused when it executes, and says what is missing.
  • Take it out removes your change from the test sandbox. A change that executes or is withdrawn leaves it by itself.
  • Your session in the test sandbox ended. You stay signed in to the test sandbox when it is built again, and when the server is restarted, for as long as you are signed in to the live system. Signed out there (or your session there ended), an open test sandbox tab says so at the top; press Open the live system and, in the Designer's Test sandbox tab (or on your change), Open the test sandbox again.

Outside systems against the test sandbox. An ERP or a cell controller can be built against a transaction, a web service or a named query before its change is approved: put the change that publishes it over HTTP under test, and the outside system calls the test sandbox's web services, at the address the Designer's Test sandbox tab shows (…/svc/v1, this server's port + 1000 unless IT set another), exactly as it will call the live ones. It needs a test token, which IT issues (node app/mes/db/token.mjs <user> "<what will use it>" --test --scope transaction:run). A test token calls the test sandbox only, never the live system, and a live token never calls the test sandbox: each is told where it belongs. While something is under test, the test sandbox keeps answering, and is built again by itself a few seconds after a change under test is saved; whoever is in it stays signed in. It closes when nothing is under test. Records the outside system makes or changes there stay there. An installed suite reaches outside from the test sandbox only with its own test settings, which IT gives it apart from the live ones (a suite that talks to machines, say, only to simulators); without them it only pretends to send.

Rolling a change back

A change that has executed can be rolled back. You do not rebuild the old version by hand: the platform drafts the change that puts things back.

  1. Open the executed change (Designer → Changes → all), and press Roll back this change.
  2. Read what it will do: each design back to how it was before, anything that change created retired, anything it retired published again. Confirm, and the rollback opens as a new change, yours.
  3. It is tried in a sandbox at once. If rolling back would break something made since (a screen that shows a field you are taking away), the fitness report says what, and the rollback cannot be submitted until that is dealt with.
  4. Submit it. It is not reviewed again, since it restores what was reviewed and approved before.
  5. One approver signs, and it is approved. Anyone who approves for a department it touches, except you. The other departments are not waited for. Its executor then presses Execute (or the signature executes it, where your organization executes at the last signature) and verifies it.

Things to know:

  • Nothing is erased. The rollback is a change on the record like any other; the design gets a new version whose content is the old one. Both changes link to each other.
  • Records are not rolled back. If the change added a field and people filled it in, the field goes but the values are kept, unseen, and reappear if the field is added again. The plan tells you how many records hold a value.
  • Changed again since. If a later change touched the same design, rolling back would undo that too. You are asked: leave that design as it is, or roll it back as well.
  • Not rolled back by this: people & departments (change them in People & departments), and flow templates, report layouts, queries or a suite's design elements the change created (change them, or leave them unused).
  • If you edit the rollback before submitting, it stops being a rollback as far as approval goes: it is reviewed and approved in full, like any change.