More you can add

Part 2 of 5 · Shipping your own data in a manifest

Adding details to a sale

Your app needs to keep something on a sale: a delivery slot, a prescription number, a tax authority's answer. The sale is the record every app and every retailer change wants a field on, and its row has a fixed amount of room, shared by all of them. On a busy site there is room for only a few more short fields. So choose where the detail lives in this order:

Your own record type, linked to the sale (a Link field to POS Invoice on your record). It has room of its own, your app owns it, and it can hold as many details as you need. Best for anything with more than two or three values, or anything your service writes after the sale.
A sale detail (sale_attributes): a short value, up to 140 characters, that the cashier or a till key fills on the sale. It takes no room on the sale's row. Best for one or two short values captured at the till.
A field on the sale (custom_fields on POS Invoice), only when the detail must sit on the sale itself, for example a fiscal reader's result. Declare it Small Text unless something lists, filters or searches by it: a Small Text field takes 10 bytes of the row, a Data, Link or Select field 562.

What happens when the fields do not fit. The install measures each record your manifest adds fields to, and each record type it brings, before it makes anything, on a first install and on an update. Fields that would not fit are refused, in one line, for example:

custom_fields[0] (POS Invoice): POS Invoice has 5,117 bytes of room left on this site (about 9 more Data, Link or Select fields), and this app's fields need 6,744 (the widest: pp_xyz_slot, pp_xyz_ref, pp_xyz_note). A record's row holds at most 65,535 bytes, shared by every app and the shop's own fields: put them in your app's own record type; a sale detail (sale_attributes) for a short value, up to 140 characters, captured on the sale; or use Small Text for text nothing searches, which uses almost no room

Nothing is made, so the retailer's administrator can install a corrected version straight away. A rarer database error (Row size too large) stops the install, which takes back what it made, that field included, and says why.

Technical notes. The room differs per site: it depends on the other apps installed and the retailer's own fields, so a manifest that installs on your sandbox may not fit a busy retailer's site. Your own record types have the same ceiling per row, so a record type with very many long fields is refused the same way; split it, or use a child table. An update counts only what it adds or widens: a field already installed is already counted.

A field only named roles read or change

A field your manifest adds may carry write_roles (the roles that change it, and so read it too) and read_roles (the roles that read it; left out, every role that reads the record type):

{"dt": "Customer", "fieldname": "acme_rxc_id_number", "label": "National or residence ID", "fieldtype": "Data",
 "insert_after": "customer_name", "write_roles": ["ACME RXC Pharmacist"], "read_roles": ["ACME RXC Pharmacist", "ACME RXC Records Officer"]}

Group your limited fields into few role sets: the installer gives each set of roles a permission level of its own, and a record type has nine.
An update may add a limited field, but may not change the roles of one already installed.
Who else reads such a field (System Manager, the till, a print): chapter 7, A field only named roles read or change.

A certified module in your package

A package may carry a module our certify service signed, for the check before payment or for pricing (the Wasm kit):

Have the module certified. Build it with the kit's meters; our review team signs its SHA-256 for one extension point and one version.
Declare it in extension_modules (manifest version 2): key (lower-case letters, digits and underscores), point, version (a whole number from 1), metered: true, sha256 and certificate (from the certificate file) and wasm (the module's bytes in base64, at most 256 KB).

Declare its service in extension_subscriptions: the same point, transport: "wasm" and module naming the module's key, with no address and no secret. Pricing takes a module only.

"extension_modules": [{"key": "member_price", "point": "price", "version": 1, "metered": true,
                       "sha256": "…", "certificate": "…", "wasm": "…"}],
"extension_subscriptions": [{"key": "price", "point": "price", "label": "Member price",
                             "transport": "wasm", "module": "member_price"}]

Install it like any package: only the service has a switch, and a pricing service's limit starts at 0 until the retailer raises it. A module version is used once on a site: installing the app again, or shipping a fix, needs a higher module version, certified again.

What the install refuses: a module our certify service did not sign, or one iVendNext has recalled.
The recall. iVendNext can recall one certified module by its SHA-256, in a POS release: from each retailer's next deploy of that release the module is refused where it is added or installed, the server stops running it, and the extension point takes its declared down answer on every till. A till that stays offline runs the module it holds until it next reads a snapshot.
Size: the App library serves a manifest of at most 256 KB, so a library app's module stays near 190 KB.

Back: Steps Next: What a retailer reads

This page in the kit