Register books, limited fields and your Desk page

Part 4 of 7 · 7. Manifests

Back: Reports, reminders, settings records and multi-select fieldsNext: Print formats that read other records

The full rules are on the product's pages in contracts/.

• Register books (register_books, manifest version 2) — the books of a regulated-stock register (a pharmacy's controlled-drug register, a liquor or duty-free store's book), declared as data: one Retail Register Book per book, which items it takes (by class or item group), which movements enter it (up to three conditions on the line's own columns), how its lines are numbered and corrected, and the columns it prints with the source of each. The keys, what is refused when a book is saved, and what the register writes on every stock document are on the register books page; the shape is the register_book.v1 contract.
  • Who is refused at the line. A submit from Desk or through the API (a stock-take imported with more than 100 rows counts as one) that leaves a column the book declares required empty, or takes a balance below zero after its opening, is refused ("⟨column⟩ is required in ⟨book⟩."); the till's own sale, a drained sale and a background job's post are never refused, only flagged. A connector posting a receipt or a stock entry of a declared item meets this.
  • Install, update, uninstall. A book installs on or off as it declares, and its count_role is made if the site lacks it. An update cannot change a book, not even its title: ship a corrected book under a new id, which numbers from 1 while the old one stays switched off with its lines. An uninstall switches every book off; a book with lines, counts or periods is kept, switched off, never deleted, with your register print formats and its count role.
  • What it reads. A detail may read a record lookup (customer, customer_link: the one record of a record type whose unique customer field names the sale's customer, such as a patient record; or user), and a detail of type Age prints whole years from a date of birth. A print format of yours may declare default_print_language (a language the site has), and a market's layout reads the book through ivn_register_print(doc) on Retail Register Period.
  • A person's details. A line's person columns (counterparty, counterparty_address, correction_note, detail_1 … detail_6) sit at permission level 1: saving a switched-on book gives its count_role that level's read, and any other role reads a line without them. The record API returns them empty on one line and leaves them out of a list, so a service that copies the register elsewhere is given the level, or treats an empty column as possibly hidden. A print through ivn_rows or ivn_register_print(doc) shows only what its viewer may read; a template that reads a line by itself (the framework's own get_doc or db.get_value) reads it whole, so print the book through its period. Declare person: 1 on a detail that names someone other than the customer.
  • Retention. retention_years keeps each line whole at least that long after its period's last day (in a book without periods, after its entry); after it, the book's Erase persons' details (its count role, never on a schedule) blanks a person's columns, writes one Retail Register Erasure record, and keeps the quantities, the balance and the chain. A book's retention_years cannot be shortened once it has lines, a mistyped one included: the retailer switches that book off and you ship a corrected book under a new id (numbering from 1). Lengthening it is allowed. Full rules: the register books page §8.
  • Bound: an article first stocked after its book is switched on has no opening, so neither the balance check nor the count applies to it until a count sets its balance.
• A field only named roles read or change: a field you add may carry write_roles (the roles that change it, who read it too) and read_roles (the roles that read it; left out, every role that reads the record type). The installer picks the field's permission level (a record type has nine, and each install or update takes a new one for each set of roles it brings, so group your limited fields into few role sets). An update may add a limited field but may not change the roles of one already installed. With read_roles, System Manager reads the field only if you name it. An Item field limited to roles is never shown on a till or a receipt, for anyone.
  • Keep a field only some roles read out of your print formats, notifications, reports, number cards and charts: a print would show it to everyone who prints. A field everyone reads but only some change may be printed. A register book may name such a field only for a person's column, a detail slot (details) or the counterparty (columns_from → counterparty), which only a role given that level of the line reads (the register books page §8).
• Your Desk page is never in the menu. A workspace installs out of the Desk's menu, limited to your manifest's roles and System Manager: the retailer's administrator opens it with the App library's Open, and a user holding one of your roles finds it with the search bar or its route, /app/<page name>. On the page each user sees the shortcuts to the record types their roles read. Showing it in the menu is the retailer's choice. Write your guide's set-up line that way: "Open it from the App library; your users find it with the search bar."

Back: Reports, reminders, settings records and multi-select fieldsNext: Print formats that read other records

This page in the kit