Steps

Part 1 of 7 · 7. Manifests

Back: the overview Next: The extension points' kinds

Choose your prefix: one to three upper-case words (ACME BLN) and the matching app name (acme_bln); ivn new acme_bln --from s2 sets both. Its first word is your company's own first word, which we give your company once: the App library accepts only your apps under it (Publish your app). The samples' PP … prefixes are placeholders. A name needs no prefix: only a field you add to one of the retailer's own record types starts with the lower-case form (acme_bln_default_bin), because iVendNext could read another name as one of its own flags. A prefix whose first word is one the system reads is refused (IS, IGNORE, FOR, HAS, SET, BASE, FREE, PRICE, POST, NOT and twelve more, listed on the save rules page): the system acts on fields whose names start that way, so never ask for one of those words as your company's.
Write manifest.json. Set "manifest_version": 2. The kinds it may carry:
- record data: record types (child tables allowed), fields (on your record types, and on any of the retailer's own record types and their child tables: a purchase order's lines, a stock transfer's rows, the till close; a field may name the roles that read it and the roles that change it, later in this chapter), display changes, print formats (which may read other records through ivn_rows and ivn_value, later in this chapter), notifications, workspaces, sale details, webhooks, a multi-select field and a settings record of your own (later in this chapter), and the register books of a regulated-stock register (later in this chapter);
  - Room on a shared record. A record's row has a fixed amount of room, shared by every app on the site and the retailer's own fields, and the sale is the fullest record: on a busy site it has room for only a few more short text fields. A short text field (Data, Link, Select) takes 562 bytes of that room; Small Text takes 10. So, before you add a field to the sale, try in this order: your own record type (a record linked to the sale has room of its own), a sale detail (sale_attributes: a short value, up to 140 characters, captured on the sale), and only then a field on the sale, declared Small Text unless something lists, filters or searches by it. The install measures each record your manifest adds fields to, and each record type it brings, before it makes anything, and refuses fields that would not fit in one line: the room left, what your fields need, and these homes. A rarer database error stops the install, which takes back what it made, that field included, and says why.
- screens: Report Builder reports (with columns from one table of the record), number cards, charts, dashboards, list settings, Connections links (your records listed under an iVendNext record), and list marks (a coloured label on a row of a Desk list, later in this chapter);
- approvals and numbering: workflows, on any record type but the till's own records (Worked example, later in this chapter), and numbering rules, on anything but the sale's own records;
- wiring: your event feed: one feed per app (registered_applications, with every record type your app follows in its events). The install also makes your app's own user, <app>@integration.invalid, and names it on the feed: it holds one role, <PREFIX> Integration, works through the API only and is never a person's (the event feed recipe says how its key reaches you, and the licence bound). Your remote till key goes on every store's till; a store moves or hides it in the Designer;
- extension points (later in this chapter): your services' subscriptions (a Desk action, a page, a check before payment, a capture, a document check, fulfil at sale, a payer), a certified module, Desk actions, save rules, a fiscal reader, scan sources and field rules.
Everything is on from the moment of install, under the one consent, for every store. The exceptions are named where they apply: a save rule limited to a role stays off until the customer names the role, a manifest's "enabled": 0 keeps a save rule off, a payer stays off until the customer names its clearing mode, and a fiscal reader stays off until the customer has set it up. What the customer does after the install is only what is theirs to decide: give staff the roles, fill a setting only they know.

Label layouts may be carried too: the label the till prints for an item or a basket line, as HTML or as Zebra printer commands, with placeholders from a closed list (the label layout page). A layout may also name up to three of the item's own fields, {item.<fieldname>} (the field name in lower case; each a Data, Select, Int or Check field open to every role), and one line detail, {detail.<attribute>}. A retailer's own receipt lines are not a manifest kind: they are two text fields the retailer fills in on its register (Receipt Header and Receipt Footer; the receipt page).
Say who may do what. A permission row names a role and its rights (read, write, create, delete, report, export, share, print, email); a right the row leaves out is off. Every record type your app makes also gives System Manager every right, unless your manifest gives System Manager its own row at level 0, so the retailer's administrator can use the app at once. A role the site lacks is made at install, as named, with no one in it, and the retailer gives it to people. A role named with your prefix is your app's own and goes when no installed app uses it; any other name (PO Approver) is the retailer's from then on and stays at uninstall. Guest and All are refused: they open your records to people outside the retailer's staff.
Check it yourself, before anyone installs it:
```
ivn check
```
It runs the same checker your customer's install runs, and your app's own tests, and gives one line. Every refusal names the element and the reason, for example "REFUSED webhooks[0] (ACME BLN Hook): a webhook calls an address the manifest lists in allowed_urls: the consent shows the shop each one". It also warns of two things the install stops on: a feed description over 140 characters and a record type's name over 61 characters.
Try it, then the customer installs it. ivn try installs it on your own sandbox: no key, no plan, no card and no questions. ivn publish --to <site> puts it on the customer's shelf and prints the message to send their administrator; ivn publish --public lists it for every retailer (Publish your app). The customer's administrator opens App library, presses Install, reads a summary our code writes from the manifest itself (every record type, field and role, every outside address, everything that runs from the moment of install, and each print format as a template that runs on the server when printed, able to read, change and send the retailer's data), ticks I agree and presses Install. From a private shelf they first press Open your shelf and paste the key you sent. The Retail Extension Package screen (paste, Check, Consent and install) does the same by hand. The site checks the manifest again, refuses names another app holds, and records each element as it creates it, in a background job. If anything fails half-way it removes what it made and shows Failed with the reason. An app CitiXsys hosts receives its secrets when the site connects to it; for an app you host, each secret (a webhook's, a service's) is shown once to whoever installed and stays readable on its own record.

To update, bring a higher version: each ivn try is a new version, and the screen first shows what changes from the installed version. An update adds and changes in place and removes nothing. It keeps each rule's switch, and a service the customer stopped stays stopped. A dropped or renamed record type or field is refused (the recipe, step 6). It writes a changed service whole, so a property the new version leaves out (its settings, time to answer, sequence, page roles) is cleared or takes the product's default. The full list is the install page, §4.
Use your records over the record API, like any other type (a connected app).
Uninstall exports first, always. Export and uninstall writes every record of your types (child rows and your added field values included) to a private file on the package before it removes anything. Uninstall leaves nothing behind: it drops your tables and the columns your fields added (the retailer's own delete keeps them), and removes what iVendNext did to your types after install. A sale detail that booked sales already use is kept, switched off, because a booked sale keeps its detail; a reinstall switches it on again. If any element cannot be removed, the uninstall says so, and Finish on the package completes it. The export holds the records with their comments and version history. The uninstall removes those from the site along with the records, so the export is where they are kept. Attachments stay, as files no longer linked to a record.
A reinstall is clean: exactly the first install's schema, and none of the old data.
Before you list it, write what a retailer reads. A retailer decides from your app's card, which is app.json's card (title, summary, what, pictures, industries, price, guide): ivn publish --public asks you once. The guide link may be any https page; your repository's README is enough. Say what leaves the retailer's iVendNext from your manifest, and never tell a retailer to create a role the install makes. The recipe has the shape.

Back: the overview Next: The extension points' kinds

This page in the kit