3. The ladder and the four rules
The ladder is the order in which you try the ways into iVendNext; the four rules are what every project keeps. Every builder reads this before every project.
Reference implementation: one recipe per rung, linked in the table below.
When to use it
For each need in a project's blueprint. Start at rung 1 and go down only when the rung above cannot do the job. Most needs stop at rung 1 or 2.
The ladder
| Rung | Way in | What it is | Your code runs | Recipe |
|---|---|---|---|---|
| 1 | Configure | pricing, promotions, coupons, sale details, line details, till keys and layouts, receipt and label formats, workflows, numbering, permissions, reports, notifications — set in iVendNext Desk | nowhere | 4. Configure first |
| 2 | Outside app | your service reads and writes records over the API and reacts to the event feed; any language | your server or the customer's | Building a connected app · 5. Outside apps and the event feed |
| 3 | Till key | the cashier taps a key; the till calls your HTTPS service; you answer with a message or sale details | your server | A till key · 6. Till keys |
| 4 | Manifest | your own record types, fields, print formats, notifications and workspaces, declared as data and installed by us | nowhere — it is data | Shipping your own data in a manifest · 7. Manifests |
| 5 | Sandboxed function | a compiled WebAssembly function at a published extension point; the same answer on the server and on an offline till | inside a sandbox we run | 8. Sandboxed functions · the Wasm kit |
| 6 | Request an extension point | when no rung fits, ask us for a new published extension point | — | 9. The extension-point catalogue |
Combine rungs. A real project is usually several: a manifest for the records, configuration for the screens and approvals, an outside service for the logic, a till key for the cashier. Chapter 15 shows the combinations by customer size.
The steps, for each need
- Can configuration do it? Look in chapter 4 and chapter 16. If yes, stop.
- Can it happen outside the sale? Before it (prepare prices, promotions, customer groups) or after it (react to a sale, sync a system, send a message). If yes, an outside app.
- Does the cashier need an answer during the sale? A till key. If your service must have the last word before money is taken (allow, refuse, ask, call a manager), that is the check before payment; if it must be asked when an item is scanned or a customer is added, the capture (both rung 6, chapter 9).
- Do you need your own records in iVendNext? A manifest. Their screens are the native ones (chapter 13a).
- Must logic run inside the sale, the same online and offline? A sandboxed function, at an extension point that offers one.
- None of these? Check chapter 9. An extension point may already do it: a scan source for a unit's own barcode, field rules for what the till shows, a check before payment, a capture. Or one is being built. Then request one.
The four rules — what every build keeps, and why
Four rules, each with what to do instead. They are short on purpose: anything they do not forbid is open to you.
| Rule | Why | Instead |
|---|---|---|
| 1. Money enters the sale visibly, before payment. A price or discount may come from your service, but never change a price, tax or total after the cashier has seen it | The cashier, the receipt and the books must show the same amount. A total changed behind the till disagrees with what the cashier charged, and the sale is stopped — possibly after the card was taken | prices, promotions and coupons (configuration); a check before payment; a live price or discount through the deal extension point (being specified), within the shop's limits |
| 2. Don't override or patch iVendNext. | We upgrade every customer together. An override or a patch is a private copy of our code that the next release moves under, and on the till it is not even reached | an extension point; if none fits, request one |
| 3. Your code runs on your server. Inside the customer's site you ship data, not code — no server code of yours, no server scripts | Many customers share one installation, so code inside one site is code on all of them, and a script can send data anywhere with no review. Data installs into one site and touches no one else's | an outside app, a till key, a payment connector on your server; a manifest or a sandboxed function inside the site |
| 4. Your screens use our doors. Never your JavaScript inside Desk forms or the till | A script on a form runs in every user's browser, administrators included. The till loads only its own code | native screens, declared buttons, your page inside our frame, or your own app with Sign in with iVendNext (chapter 13a) |
When your service is down, and when the till is offline
Each rung answers this in its own chapter. The rule across all of them: the till never waits on a builder's service it cannot reach.
- Outside apps catch up from the event feed.
- Till keys are dimmed offline, and refused in words when your service is down.
- A check before payment and a capture are not called offline: the till applies the answer you declared for when your service is down.
- A sandboxed function is built to run on the till, offline too.
Offline behaviour is described here from the product's design. The kit has tried it only for a sandboxed function (chapter 8). Chapter 16 states the product's own offline limits.
Technical notes
Offline evidence
The kit did not run offline for any rung, apart from one browser test of a sandboxed function (chapter 8; chapter 16 states the product's own offline limits).
The tests
- Every need in your blueprint has one rung, and the rung's recipe.
- Your build keeps all four rules. The manifest checker refuses a manifest that declares code (chapter 14); what we run at intake on a sandboxed function or an endpoint is not covered by the kit yet (chapter 17).