@lotics/cli 0.320.9 → 0.320.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/src/cli.js +7 -3
- package/docs/app_bindings.md +2 -1
- package/docs/design.md +3 -1
- package/package.json +1 -1
package/dist/src/cli.js
CHANGED
|
@@ -1845,7 +1845,7 @@ async function saveSignedLinks(links, dir, timeoutMs) {
|
|
|
1845
1845
|
}
|
|
1846
1846
|
|
|
1847
1847
|
// src/version.ts
|
|
1848
|
-
var VERSION = "0.320.
|
|
1848
|
+
var VERSION = "0.320.11";
|
|
1849
1849
|
|
|
1850
1850
|
// src/timezone.ts
|
|
1851
1851
|
function machineTimezone() {
|
|
@@ -1867,7 +1867,7 @@ var getting_started_default = '# Getting started\n\nA workspace is where one bus
|
|
|
1867
1867
|
var build_default = '# Build \u2014 a workspace or an app, call by call\n\nBuild from this page, `design` and the treatment the rows call for; a refusal names the `reference/<id>` page for the rest. The worked business: a bakery takes cake orders at the counter, a customer and one line per cake from the menu, moving taken, baking, ready, collected, with a slip printed when ready.\n\n`get_workspace` shows what already exists and `get_app` an app\'s tree: an app added or changed later starts there and states only the difference (`reference/changing-an-app`). Each write to an app makes a new version of it, and the live app is the only copy; sending an earlier tree restores the app, never a table or a row a write made, so try a write on a throwaway row. Before the first write, send the person who asked one message covering: the jobs and lists this business runs beyond those named, the trade\'s usual ones stated as defaults that stand; who does each job (`get_workspace` kind `member` lists the organization\'s people, not who works in this business or what each does); and the lists and papers they already keep, attached. A busy owner answers what comes first, so the message\'s first line is its first question, and it asks only what their papers and your defaults cannot settle, among them the papers they keep, asked by what they hold, and what else they keep track of; the defaults come after. "Go ahead" is a full answer. No second round: build from the answer. A short request names a business, not everything it runs on, so the workspace holds what that kind of business can\'t run without, such as what must never happen, what people are paid for and the papers it sends; your report names what you assumed, for them to change. What no one could guess from the data goes into a knowledge doc with `set_knowledge` (`knowledge_docs`).\n\n## 1. Tables and their checks: `set_tables`\n\nLinked tables go in one call, since they name each other by `ref`; `records` and checks may follow in the next call, so a refusal costs a patch rather than the whole document. A new table is named by its `ref`, which becomes its alias. One table per kind of thing, one column per fact, a link wherever one record points at another (`data_model`). A status is the stage of the work; a touch ("called") is a log row, a money fact ("paid in full") a formula, a quantity a number with its unit in `notation`. Read `design` before stating `records`, since a row\'s face, picture and mark are stated there. Over rows already there, read a sample before building on a field: one mostly empty holds up no screen. A table people work states `title` (who or what a row is; a code only where nothing else names it), `records` (an app over a table without it is refused) and `singular` (so is an Add over a table lacking it).\n\n```json\n{\n "tables": [\n {\n "ref": "customer", "label": "Customers", "singular": "Customer", "title": "name",\n "fields": {"name": {"type": "text", "label": "Name", "required": true}},\n "records": {"party": "person"}\n },\n {\n "ref": "menu_item", "label": "Menu", "singular": "Menu item", "title": "name",\n "fields": {\n "name": {"type": "text", "label": "Cake", "required": true},\n "price": {"type": "number", "label": "Price", "required": true, "notation": {"style": "currency", "currency": "USD"}}\n },\n "records": {"figure": "price"}\n },\n {\n "ref": "cake_order", "label": "Cake orders", "singular": "Cake order", "title": "reference",\n "fields": {\n "reference": {"type": "autonumber", "label": "Number", "prefix": "CK-"},\n "customer": {"type": "link", "label": "Customer", "table": "customer", "multi": false, "required": true},\n "due_on": {"type": "date", "label": "Pickup on"},\n "pay_by": {"type": "date", "label": "Pay balance by"},\n "lines": {"type": "link", "label": "Cakes", "table": "cake_line", "multi": true, "pair": "order"},\n "total": {"type": "rollup", "label": "Total", "via": "lines", "op": "sum", "field": "amount"},\n "prepaid": {"type": "number", "label": "Prepaid", "notation": {"style": "currency", "currency": "USD"}},\n "paid": {"type": "formula", "label": "Paid", "expression": "{total} > 0 && {prepaid} >= {total}", "output_type": "boolean"},\n "slip": {"type": "files", "label": "Slip"},\n "stage": {"type": "select", "label": "Stage", "default": ["taken"], "options": [\n {"alias": "taken", "label": "Taken", "color": "slate"}, {"alias": "baking", "label": "Baking", "color": "amber"},\n {"alias": "ready", "label": "Ready", "color": "blue"}, {"alias": "collected", "label": "Collected", "color": "green"}\n ]}\n },\n "records": {"subtitle": ["customer"], "figure": "total", "due": ["pay_by"], "settled": "paid", "status": {"field": "stage", "closed": ["collected"]}},\n "checks": {"pay_by_before_pickup": {"on": ["create", "update"], "field": "pay_by",\n "when": "!isNull(record.pay_by) && !isNull(record.due_on)", "fail_when": "record.pay_by > record.due_on",\n "message": "\\"The balance is due on or before the pickup day\\""}}\n },\n {\n "ref": "cake_line", "label": "Cakes on orders", "singular": "Cake", "title": "item",\n "fields": {\n "item": {"type": "link", "label": "Cake", "table": "menu_item", "multi": false, "required": true},\n "order": {"type": "link", "label": "Order", "table": "cake_order", "multi": false, "required": true, "pair": "lines"},\n "quantity": {"type": "number", "label": "Quantity", "required": true, "min": 1},\n "unit_price": {"type": "number", "label": "Unit price", "default_from": "item.price", "notation": {"style": "currency", "currency": "USD"}},\n "amount": {"type": "formula", "label": "Amount", "expression": "{quantity} * {unit_price}", "notation": {"style": "currency", "currency": "USD"}}\n },\n "unique": [["order", "item"]],\n "records": {"figure": "amount"}\n }\n ]\n}\n```\n\n`default_from` copies the menu\'s price when a line is made, so a later change leaves taken orders alone. `min`, `unique` and a check hold on every write; a check\'s language is `workflows/table-checks`, an effect after a write a table workflow (`workflows/table-workflows`). A check at its smallest, under an alias in the table\'s `checks`: `{"on": ["create"], "fail_when": "record.quantity < 1", "message": "\\"Quantity is at least 1\\""}`; `message` is an expression, so fixed text is a quoted string.\n\nA `date` field is a day, or a moment with `"format": "datetime"`; a time of day is a `text` field with `"format": "time"`. Days between two dates in a formula is `differenceInCalendarDays(later, earlier)`; the helpers are named exactly (`reference/formula`). Two rows that must not hold one resource at once are the table\'s `no_overlap`: `{"from": "start_at", "to": "end_at", "by": "room"}`, a list where a row holds two resources (`reference/no-overlap`).\n\n## 2. The paper: `set_template`\n\nAn Act names a template by its alias, made from its name (`order_slip`), so the paper comes first.\n\n```\nset_template {"type": "html", "name": "Order slip",\n "template": "<h1>{{reference}}</h1><p>{{customer}}, {{date due_on}}</p>{{#each lines}}<p>{{item}} \xD7 {{quantity}}</p>{{/each}}<p>{{money total \\"USD\\"}}</p>",\n "variables": {"reference": "string", "customer": "string", "due_on": "string", "lines": "array", "total": "string"}}\n```\n\nOne template per paper the owner sends. A slot is named after a field of the record; the cakes loop under the name of the link to them (`lines`). More: `document_templates`.\n\n## 3. The app and its acts: `set_app`\n\n**Which apps**, and who gets each, is `app_architecture`. **How each row reads** comes before the first List: `design/treatments` names the view per kind of row.\n\n**Start from one root List.** `{"type": "List", "entity": "cake_order"}` in the App\'s `children` is a whole app: the platform draws the page every row opens, the add and the Delete. `set_app` answers with what it drew and what it placed or folded; state only the difference.\n\n```json\n{\n "body": {\n "type": "App", "key": "counter", "name": "Counter",\n "children": [\n {"type": "List", "entity": "cake_order", "filters": ["customer"], "create": ["customer", "due_on", "pay_by"], "children": [\n {"type": "Reading", "label": "By pickup day", "value": "total", "by": "due_on"}\n ]}\n ],\n "pages": [\n {"type": "Record", "entity": "cake_order", "children": [\n {"type": "Section", "title": "Order", "at": ["taken", "baking"], "children": [\n "due_on",\n "pay_by",\n {"type": "List", "entity": "cake_line", "create": ["item", "quantity"]},\n {"type": "Act", "key": "start_baking", "label": "Start baking", "when": {"stage": ["taken"]}, "requires": ["due_on"], "asks": ["prepaid"], "set": {"stage": "baking"}},\n {"type": "Act", "key": "ready", "label": "Ready", "when": {"stage": ["baking"]}, "set": {"stage": "ready"}, "template": "order_slip", "into": "slip"}\n ]},\n {"type": "Section", "title": "Pickup", "at": ["ready"], "children": [\n {"field": "slip", "edit": false},\n {"type": "Act", "key": "collect", "label": "Collected", "when": {"stage": ["ready"], "paid": true}, "set": {"stage": "collected"}}\n ]}\n ]}\n ]\n }\n}\n```\n\n**Give each main List a band** of what its person watches, a figure or a chart in its `children`, never a bare count.\n\n**A press can be a mistake.** An Act also moves a row back (`when` the later stage, `set` the earlier), at the foot of the Section of the stage it leaves. **Someone with no seat** who signs or approves one record, a customer or a supplier, gets a Record\'s `Outside`: a link a member makes of that record.\n\n`dry_run` checks a body and writes nothing; then share each app (`app_architecture`). An Act\'s or stage\'s `owner` decides who presses.\n\n## 4. What the owner will ask an agent: Query and Workflow nodes\n\nWhat the business asks its assistant again and again (orders waiting for pickup) is a Query or Workflow node of the app, with a `description` for an agent that has not seen the screen (`agent_surface/declaring-more`). A figure\'s name is not its definition: which rows count, by which field, now or over a window, is the owner\'s; where no field holds it, say so rather than total a near one. The App\'s `description` heads what a member\'s chat agent reads every turn, so a standing process the app expects of it goes there. A connected service is reached by a Workflow node\'s step (`workflows`).\n\n## 5. The owner\'s rows: `create_records`\n\nBatch the owner\'s rows: the customers and menu, then the orders, linked by the ids those calls return, then each order\'s cakes (`field_values` has the value each type takes). Load as an admin: a row past the first stage is refused unless that stage\'s owner or an admin makes it, and a row loaded at a later stage states each earlier stage\'s date field (`<option>_at`). Example rows the papers ask for and do not list come from the owner\'s lists, each at the stage it should show, written like the owner\'s own rows (no flag field, no "Example" in a name) and listed in your report for the owner to keep or delete. An owner who sent no lists opens what you leave, so a few example rows, listed the same way, show them the app working.\n\n```\ncreate_records {"table_id": "cake_line", "field_keys": ["order", "item", "quantity"],\n "rows": [["<the order\'s record id>", "<Lemon cake\'s record id>", 2]]}\n```\n\n## 6. Verify: `run_app_workflow`, `screenshot_app`\n\nMove the owner\'s rows through the app as their person would, each only as far as the stage the owner says it is at. Every Act runs as `act_<key>`, the one name, handed what it asks. A dry run walks the moves and files nothing; then press each paper Act for real, on one row the owner\'s stage allows or on an example row left at its last stage: what is left on a row is what the owner opens. Prove a rule by sending the write with `dry_run: true`; never switch a check off. Only an admin passes `as_member`: it shows a member\'s view and reads, which is how each person\'s screen is checked. What the shots and runs must show is `design/the-rubric`.\n```\nrun_app_workflow {"app_id": "app_\u2026", "alias": "act_start_baking", "inputs": {"record_id": "rec_\u2026", "prepaid": 20}, "dry_run": true}\nscreenshot_app {"app_id": "app_\u2026", "as_member": "<member id>"}\n```\n\n## 7. Hand over\n\nName the workspace and its organization after the business with `set_workspace` (`name`, `organization_name`, and `organization_language`: the language its papers, invitations and members default to, `vi` until set), and leave standing instructions there (`instructions`, one entry per rule): who the business is, its people\'s words, what any agent here must keep to. As an admin, invite the people named with `set_members` (`members` keyed by email, role `member` or `admin`), else say whom to invite.\n\nBefore you report, answer each question of `design/the-rubric` with a call, and put right or name each gap. Then show the owner what you built, job by job, each paper and what makes it, with the choices you made for them to change.\n';
|
|
1868
1868
|
|
|
1869
1869
|
// docs/design.md
|
|
1870
|
-
var design_default = '# Designing an app\n\nAn app is a tree of components: a List of one table, the Record a row opens, its Sections, the Acts that move it. The\ntree states COMPOSITION \u2014 which fields, lists and acts each job\'s screen holds; how each piece looks is the platform\'s,\none way per concept. A node the tree leaves out draws its default, from the table\'s facts (`records`, the stage, the\nwrite rules): a List\'s Readings band, the stage buttons, the picture, a Record\'s Sections. State a node to change it,\nor `false` at it to turn it off (`"readings": false`, a Record\'s `"row": { "image": false }`). A field is written where its Record declares it: a Section\'s Field, the table\'s face (title, line, picture, figure), or every field where the Record states no Section; the head, a line, a column or a board draws it, and never makes one written; every head part (`row.title`, each `row.subtitle` entry, `row.figure`, `row.image`) takes `edit: false` to be read. A drawn Field is a control unless it\nor its entity is read-only (`edit: false`); a stepped status never is, since Acts move it. Which apps a business needs is `app_architecture`.\n\n**The visual bar.** Every screen is judged against it; a miss is a change to the tree.\n\n- Each app looks like its own rows: the view its kind of row takes (`design/treatments`) \u2014 cards for things found by\n their photo, a calendar or lanes for dated work, faces for people and organisations. A List left as a table is drawn\n as one, the most common failure of an app; the answers of `set_app` and `get_app` note the view rows that are work in time call for (a calendar, lanes, a roster, a gantt where rows wait on one another).\n- What needs attention leads the row: `records.mark` on a select or a computed category (a formula stating its options;\n where it is empty, its seat is blank). A yes that needs attention (papers still owed) is a `Check` of its List over a\n yes/no formula, in the warning tone on the row\'s line; every other yes reads in the success tone.\n- A list\'s columns: the name and its lead, the status, then the columns the job reads on every row, as many as fit a desk. Each\n fact once: a column the row draws itself stands once. A generated number (`autonumber`) as the title yields\n the row\'s name to the subtitle\'s first part and stands first on its line.\n- A list worked by a date states `sort` on that date\'s column, newest first; without one, a register reads newest made\n first and a record\'s child List in the order its rows were added.\n- Someone is a face wherever they are read: a link to a table stating `records.party` draws its row\'s face; a member\n field is one already; select options naming people or organisations who are neither each take the `mark`\n `{"kind": "avatar", "name": "person"}`, never a colour dot.\n- A thing shows its picture, a file its preview, a plan its days on a time axis, a quantity a meter (`records.limits`) or\n a chart, a register its Readings, and long text reads whole (a markdown Field; `block: true` on plain long text).\n- Every category the job reads is coloured: each option\'s `color`, and a `mark` where a brand or glyph names it, on\n every option of a select read down a column (how it was paid, the channel). Colour an option only where the colour\n means something.\n- Every app states its tile\'s `color`, apart from the workspace\'s other apps where it can be.\n- The paperwork is the proof of the work: a files field per purpose (what arrived, what was issued to the customer, the\n carrier, the authority) in the Section where that work happens, and the source of a\n figure (a screenshot, an email, a sheet) on its row. Every files field is drawn somewhere.\n\n<!-- generated:start words -->\n\n**The words most builds state.** A node\'s page holds its rules and every other word: `reference/list-node`, `reference/records`, `reference/field`.\n\n**Table**\n\n- `ref` (alias): A created table\'s handle in this call\n- `label` (text, required): The table\'s name in the workspace\n- `singular` (text): One row of this table, in the business\'s own words\n- `title` (alias): The alias of the field that names a row wherever a link or a record shows one\n- `fields` (map of alias \u2192 Field, required): The table\'s columns, each under its alias, which is its key here and so is never stated inside it\n- `records` (any value): How a row is recognised\n- `checks` (map of alias \u2192 table check (`workflows/table-checks`)): The conditions a write of the table\'s rows may not meet, each under its alias\n- `unique` (list (at least one) of list of alias (at least one)): Sets of fields whose values no two live rows share\n\n**Any field**\n\n- `label` (text, required): The field\'s name in the workspace\n- `required` (boolean): Refuse a record whose cell for this field is empty\n- `default_from` (text): Copied when a record is made off the row a one-row link of this entity names\n\n**`number` field**\n\n- `notation` (notation): How the figure reads\n- `min` (number | text): Refuse a create or update whose value is below this\n\n**`select` field**\n\n- `options` (list of Select option (at least one), required): The choices, in the order every picker and every ladder lists them\n- `multi` (boolean): Allow multiple selections\n\n**`link` field**\n\n- `table` (text, required): The table the link points at\n- `multi` (boolean, required): Whether a row links to one row or many\n- `pair` (`true` | alias): Makes the link two-way\n\n**`formula` field**\n\n- `expression` (text, required): The expression, over fields of THIS entity by alias in braces\n- `output_type` (`"number"` | `"text"` | `"date"` | `"datetime"` | `"boolean"` | `"select"`): Holds a formula to the type its readers need\n\n**`rollup` field**\n\n- `via` (alias, required): The alias of a link of this table to roll up from\n- `op` (operation, required): The operation over the linked rows\n- `field` (alias): The alias of the field on the linked table the operation reads\n\n**`lookup` field**\n\n- `via` (alias, required): The alias of a link of this table to look up through\n- `field` (alias, required): The alias of the field on the linked table to show\n\n**`autonumber` field**\n\n- `prefix` (text): Literal prefix prepended to every display value (e.g. \'KH-\' \u2192 \'KH-001\')\n\n**`records`**\n\n- `subtitle` (list of alias (1\u20132)): Up to two fields read under the title wherever a row is drawn (a code, a date, a party)\n- `figure` (alias): The one number the row stands for, read at its right (a total, a quantity left)\n- `status` (Status): The stage a row moves through, a single select, drawn in the record\'s head, or its Side where the Side states it\n- `due` (list of alias (at least one)): Dates that are deadlines (stored, or computed as a date)\n- `image` (alias): A files field that pictures the row, or a one-row link to a table with a picture, whose picture the row leads with\n- `party` (`"person"` | `"organization"` | `"organisation"`): What each row is where the rows are people (a contact, a patient) or organisations (a customer, a supplier, a carrier)\n- `limits` (map of alias \u2192 (alias | number)): A number read against a bound\n- `starts` (map of alias \u2192 `"today"` | `"me"`): What a field of a row being added starts at, where that start is certain\n- `mark` (alias): A single select (or a lookup of one through a one-row link), or a formula that states its options, whose option leads the row wherever a mark leads it\n- `settled` (alias): A yes/no of the row (stored, a formula: an invoice paid in full, or looked up through a one-row link: a line settled with its parent) that ends its deadlines\n\n**`records.status`**\n\n- `field` (alias, required): The single select that is the row\'s state, its options in the order the work goes through them, read as steps by itself on a record whose parts state no `at`\n- `closed` (list of alias (at least one)): Options that end the work\n- `history` (text): A table every write that sets or moves the status appends one row to (its link to this table, the new status, the moment and who)\n- `dates` (map of alias \u2192 alias): Option alias \u2192 a date field of this entity the record write path stamps with the moment a row moves into that option, or is made at it\n- `stages` (map of alias \u2192 Stage): Option alias \u2192 who owns that stage and how long it should take\n\n**App**\n\n- `key` (alias, required): The app\'s alias, its name among apps\n- `name` (text, required): The job, in the words of the people who do it\n- `children` (list of (List | Sheet | Query | Workflow) (at least one)): The App\'s Views in order\n- `color` (colour): The launcher tile\'s colour\n- `pages` (list of Record (at least one)): The page the rows of an entity open, one per entity, each a Record stating its `entity`\n\n**List**\n\n- `entity` (alias, required): The table whose rows the List draws\n- `create` (boolean | list of alias (at least one)): The fields an add asks\n- `columns` (list of (alias | Edit column)): Fields read after the row\'s title\n- `label` (text): The register\'s name in the app\'s lists and tab strip\n- `filters` (list of (alias | Tiered filter) (at most 3)): Fields the reader narrows by every day, beside the stage chips\n- `children` (list of (Tab | Reading | Export | Act | List) (at least one)): Its Tabs, band Readings, Exports and Acts over ticked rows or every row in view\n- `key` (alias): Names the List among its siblings and in a Query\'s `list`\n- `sort` (Sort key | list of Sort key (at least one)): The rows\' order\n- `layout` (layout): A word, or an object stating one layout with its data\n- `remove` (boolean): Rows offer a Delete\n- `search` (list of alias (at least one)): Fields the search box reads\n- `where` (narrowing): A fixed narrowing on the server, for every reader\n- `group` (alias): A field the rows stand grouped by\n- `expect` (alias | Expect): What a record should hold, shown before it does\n- `opens` (narrowing): The view the register opens on, a chip the reader may take away\n\n**Record**\n\n- `entity` (alias, required): The table whose rows open on this page\n- `children` (list of (alias | Field | Fieldset | Section | Side | Outside | List | Reading | Statement | Act | Check) (at least one)): Parts (Section, Side), or for a one-part record its Fields, Fieldsets, Lists, Readings and Statements directly\n- `add` (`false` | list of alias (at least one)): What a new row asks where a picker of this entity offers one, anywhere in the App\n- `row` (Record row): How the App reads this entity\'s rows wherever it lists them\n- `door` (`"page"` | `"drawer"`): How a row opens, on a page or in a drawer\n\n**Section**\n\n- `title` (text, required): The part\'s heading\n- `key` (alias): Unique among its siblings\n- `children` (list of (alias | Field | Fieldset | List | Reading | Statement | Act | Check) (at least one)): What the part draws, in reading order\n- `at` (list of alias (at least one)): Options of the record\'s status during which this part is the work now\n- `when` (condition): Drawn only while this holds\n\n**Field**\n\n- `field` (alias, required): The field\'s alias\n- `edit` (boolean): Shows a value nobody changes here\n- `label` (text): The heading of the field\'s gallery or prose block, where it draws as one\n- `block` (boolean): Gives a field room of its own\n\n**Act**\n\n- `key` (alias, required): The act\'s name\n- `label` (text, required): The verb, as the reader says it\n- `when` (condition): The act works only while this holds\n- `set` (map of alias \u2192 value): What the act writes\n- `asks` (list of (alias | `{ "field": alias, "starts": "today" | "me" }` | Asked input) (at least one)): What the reader states on pressing\n- `confirm` (`true` | text): The press asks first\n- `requires` (list of alias (at least one)): Fields filled first, each drawn where the act stands\n- `template` (alias): A document template it makes a file from\n- `into` (alias): The record\'s files field keeping the document\n- `owner` (`"field"` | `"link.field"` | `{ "group": id }`): Who presses it\n- `workflow` (alias): The workflow it runs for what `set` cannot say\n- `danger` (`true`): The act destroys or cannot be undone\n\n**Check**\n\n- `field` (alias, required): A yes/no or text formula of the page\'s entity\n- `on` (`"all"` | list of (`"update"` | alias) (at least one)): What the standing check refuses\n- `resolve` (alias): An Act on one row of this entity that clears it\n\n**Reading**\n\n- `label` (text): What the figure is called\n- `value` (alias | `{ "avg": alias }`): A number field summed over the rows, or `{ avg }` averaged over the rows holding one\n- `by` (alias | Tiered filter): Splits the rows into parts\n- `where` (narrowing): Only the rows whose select holds one of these options, whose yes/no is this value, whose number or date meets its bounds (`gt`, `gte`, `lt`, `lte`; a date\'s `{ "now": true }` is read when the rows are), whose field is `{ "empty": true | false }`, or whose member field holds the reader (`{ "me": true }`)\n- `entity` (alias): The List\'s rows\n- `over` (alias): The date that places a row in time\n\n<!-- generated:end words -->\n\n## Look at it\n\nAfter an apply, `screenshot_app` draws each app as its people see it \u2014 the register, and a record by its `path` or its `record_id`\n(with a `path` on that record, such as one Section; `screen` for a later screen of a long one) \u2014 at a desk\'s width and a phone\'s, naming the columns a table left off at each width;\n`-o <dir>` saves the shots from the CLI. Beside them, `verdict` is what a write of the stored tree would be refused for\nnow, and its notes. Answer `design/the-rubric`, change the tree with `nodes`, and write again. To go back,\nsend the tree saved before the change as `body` with `app_id`, nulling an App prop stated since (`words`, `scope`,\n`period`, `icon`); tables and rows stay as they are.\n\n## The rubric\n\nWhether the build does the owner\'s work, answered by a call each, never from what you meant to write:\n\n1. Each job the owner named, and each their kind of business cannot run without: which screen does it, and which press? Find each on a `screenshot_app` shot of the person who does it (`as_member`).\n2. Can an agent do each job in one call, an `act_<key>` or a Query or Workflow node whose `description` names it? `get_app` lists them; `run_app_workflow` with `dry_run` proves one (`agent_surface/prove-an-app-as-an-agent`).\n3. Is each kind of row in its treatment (`design/treatments`)? Timed work reads in a calendar or lanes, and a weekly plan as the dated rows it makes.\n4. Does each screen show the least its next step needs, each fact once, the signal that a step is due leading?\n5. Is anything cramped at desk or phone width?\n6. Is every paper and every Export made, those this kind of business sends unasked too, with no blank? Press each paper Act and read the file it files; prove an Export with `run_app_query` and `export`.\n\nA failed answer is a change to the tree, or a gap named to the owner.\n\n## Treatments\n\nThe answers of `set_app` and `get_app` note the view rows that are work in time call for (a calendar, lanes, a roster, a gantt\nwhere rows wait on one another), naming the node that would state it; a note refuses nothing. No other treatment below is noted.\nEach kind of row\'s view is chosen before its List is written:\n\n| The rows are | The treatment | Its own page |\n|---|---|---|\n| People or organisations | `records.party`, with a photo or logo as its `image` | |\n| Things with a photo, a scan or a paper | `records.image`; List `layout: "cards"` where the picture is how a row is found | `reference/cards` |\n| Read by their day | List `layout: "calendar"`; on a record, a child List with `layout: {"agenda": \u2026}` | `reference/calendar`, `reference/layouts` |\n| Ranked by a figure, or worked by a date | List `sort: {"field": \u2026, "desc": true}` on that column | |\n| Booked on a resource | List `layout: {"lanes": {"by": \u2026}}`, and the table\'s `no_overlap` \u2014 a list of rules where a row holds two (a room and a teacher) | `reference/lanes`, `reference/write-rules` |\n| A day\'s work given out to people or vehicles | List `layout: {"lanes": {"by": \u2026}}` over rows holding a day and no hour | `reference/lanes` |\n| A log of what happened | a child List with `layout: "timeline"` | `reference/layouts` |\n| Opened to be worked on | the Record\'s Sections \u2014 each one area of the record\'s data, its lists and field groups inside it; a status\'s stage acts stand at the foot of the rows they move, `at` where the work moves in steps; fields only one kind of row holds (a delay\'s cause, a safety issue\'s hours lost) in a Section whose `when` names that kind | |\n| Rows that each belong to another row | a child List on that row\'s Record, with `create` and `remove` \u2014 and a child\'s own rows a List in that child\'s page, as deep as the data goes, and every row\'s \u22EF offers Duplicate; a List with `same` where read-only | |\n| A related row\'s value on the list (the newest contract\'s end date) | a `lookup` field of the table, ordered, as a column | `reference/lookup` |\n| Moving through a status | an Act per move, `status.dates` for the moment of each stage, and the register\'s Readings | |\n| Counted over a period | the register\'s Tabs over one `period`; a Tab\'s `totals` for a child\'s sums before, during and through it; an open Tab\'s `where` reads only what was true at the period\'s end, never a status the row moves on from | |\n| Papers a case gathers | a List with `expect`; the papers made, an Act\'s `templates` | |\n| A plan of spans | List `layout: {"gantt": {"start": \u2026}}` | `reference/gantt` |\n| Stood at a place on a plan, flat or in 3D \u2014 pallets, bins | List `layout: {"plan": \u2026}`; places state `plan_place` | `reference/plan` |\n| Checked item by item against a standard | a List with `checklist: {"photo": \u2026, "clause": \u2026, "failed": [\u2026], "passed": \u2026}`: each row a mark (passed at `closed`, failed at a `failed` option, or by the yes/no `passed` names \u2014 a measured verdict, no task or status needed), its photo and the clause it is checked against; with `expect` on the standard\'s items, each item is a line marked the same way and filled by the block\'s columns | |\n| A place before and after the work | a List with `compare: {"before": \u2026, "after": \u2026}`: two files fields read side by side, or two value fields read as one struck-then-new column | |\n| Spots on a drawing | `records.pin: {"on": \u2026, "x": \u2026, "y": \u2026}` on the spots\' table: a record listing rows that link to them draws the picture with a numbered pin at each; the picture is the `on` row\'s `records.image` | `reference/record-places-pins-and-cadence` |\n| Photos that must be taken on site | `records.on_site: {"photos": [\u2026]}`: a photo taken through the camera keeps where the device stood, and a record holding one taken away says so | `reference/record-places-pins-and-cadence` |\n| The real size of the thing (a carton, a piece of furniture, a pallet) | `records.size: {"across": \u2026, "along": \u2026, "up": \u2026}`: three number fields in one length unit, read as one fact "400 \xD7 300 \xD7 250 mm" after the subtitle; a plan register draws each box at that size | `reference/record-places-pins-and-cadence`, `reference/plan` |\n| A number painted on the thing, or a barcode or QR code on it | `records.scan: "iso6346"` or `"text"` (read off one photo by an agent), or `"code"` (decoded on the device, no agent): the title read on a phone, beside each search matching it | `reference/record-places-pins-and-cadence` |\n| The rows a weekly pattern owes (a class\'s lessons on Tue and Thu at 16:00) | `records.cadence: [{"entity": \u2026, "on": "<a multi-select of mon\u2013sun>", "start": \u2026, "end": \u2026, "planned": \u2026, "except": \u2026}]` on the parent, and an Act `makes: "<child>"`: the press lists the rows still owed, each with what would stop it, and writes the ones ticked; pressed again it lists what is missing, and moves a row to the pattern\'s hours and copied fields where it differs and no person or linked row has touched it (ticked), else leaves it unticked saying why | `reference/record-places-pins-and-cadence` |\n| Who did what on which day | List `layout: "roster"` with the List of its cells inside | `reference/roster` |\n| Someone with no seat signs off one record (a buyer approves a proof, a client signs a handover) | the Record\'s `Outside`: the Fields and Lists the link shows as they are, and Acts that each move the status out of its `at` \u2014 a link a member makes of the record, never a seat; the link\'s page names the record only where the Outside states its title\'s field | |\n| Steps people drop out of between | a Reading with `steps` on the record whose child rows count them | |\n| A record\'s own numbers nobody keys, read at a glance | consecutive Readings with no `entity` (up to eight tiles) | |\n| Rows that are each a place a record is sent | a List with `expect` on the link to those places and `post`: each ticked, the post written there and read as its feed shows it | `reference/publish-desk` |\n| Papers an agent reads, where the owner asked for one | an Act\'s `intake` with `fills` | |\n| Calls and visits | an Act\'s `record` | |\n| Changes a workflow proposes that a person approves row by row \u2014 a price list applied, a statement matched to what is owed | an Act\'s `workflow` with `review`, its body returning a changeset in `data.review` | |\n| Documents covering lines | a List with `under` | |\n| Rows on file a record takes in | a List with `pick` | |\n| One owner\'s question across jobs | an App of Tabs and Readings and no register | |\n\nWhat these nodes do not state, a long-form writing page or a bespoke tool, is a custom-code app (`lotics app create <name> --custom`, `app_bindings`), never a new node.\n\n### Faces and pictures\n\n#### Party\n\n`records.party` is `"person"` where the rows are people (a contact, a patient, a driver) and\n`"organization"` where they are companies (a customer, a supplier, a carrier). Every surface drawing one of\nits rows then draws a face: its `image` (a photo, a logo), else its initials. Without it, a person is drawn as a thing. A workspace\nmember is a `member` field, and is drawn by their face already. A column holding a link to several rows of people,\nor several members, draws their faces as a stack that names them on hover. Worked: `examples/party`.\n\n#### Image\n\n`records.image` names the files field that pictures a row \u2014 a product\'s photo, a damage photo, a\nscan, a receipt. Every row of it then leads with its picture, or its paper\'s preview, wherever it is drawn \u2014\na row holding no picture leads with the placeholder; a link to it previews the file. `image` may instead name a\none-row link to a table with a picture (an order line\'s `item`): the row leads with that row\'s picture, still titled by\nits own words. Never a field an Act keeps the paper it makes in (`into`). List\n`layout: "cards"` where the picture is how a row is found. A files field the record keeps as a folder of\npapers is drawn as a Field, read whole. Worked: `examples/cards`.\n\n#### A link opens its row\n\nEvery row an app draws opens on its page, the one you state or a default. A List\'s rows default to the table\'s fields; a link\'s row defaults to its name, line, status and figure. State `pages/<e>` to show more or to edit.\n\n### Rows in time\n\nRows that each stand on a day, or hold a run of days or hours, are read where they stand in time \u2014 never\nas two date columns. A row holds a span when two dates a person states are ordered, the second after the first by a\n`min` or a table check, both required or the second the row\'s `due`; else it is an appointment when one required date\nis stated that no Act stamps, that a new row does not start at `today` and that is not derived. A stamp is an event,\nand a `due` is a deadline, never the day a row is held on. A `no_overlap` by a person or a value alone keeps one row at\na time each \u2014 a member\'s periods in turn \u2014 read by what they hold.\n\n#### Calendar\n\n`layout: "calendar"`, or `{ "calendar": { "date": "starts_at", "end": "ends_at" } }`: the rows by their day \u2014 a\nmonth, a week, a day or a list; an entry at its hour where `date` holds one, over its span where `end` names the date it\nruns to. The bare word takes both from the rows\' facts and is refused, naming `date`, where they name none. An entry pressed opens its row beside the calendar; where the app saves the row, a drag or F2 moves it. Worked:\n`examples/calendar`.\n\n#### Lanes\n\n`layout: {"lanes": {"by": \u2026}}` with `by` naming a one-row link whose target\'s rows are the lanes (a chair, a\nmachine, a room), each drawn even when empty: every row a block from the first date on its line to the\nsecond, and a free stretch adds a row there. `loads` reads what a lane carries against what it holds: hours summed\nwithin each day (across days, the fullest day, named), any other number the most its rows add up to at one time. A\n`no_overlap` `by` the same link refuses two rows on one resource at once. A lane per person: `by` a member field\nand `of` a role of the model, each member of it a lane, idle ones too. Worked: `examples/lanes`.\n\nA day\'s work given out (stops to drivers, jobs to technicians): rows holding a day and no hour read at one day as cards\nin lanes, those no lane holds, or holding no day, first in a tray. Each lane\'s head reads its count, its loads and its\nrow\'s status; a lane its link no longer admits (`options_where`) says so in its head and refuses a card. Where the app writes the link, cards ticked or\ndragged go to a lane in one write, every row checked before any is written, and the List\'s first `sort`, ascending on a\nnumber the app writes, is a card\'s place in its lane.\n\n#### Gantt\n\n`layout: {"gantt": {"start": \u2026}}` (and `end`, else the table\'s first `due`; a `due` is a deadline, never an appointment date): one bar a row over\nits run of days, read against today. `milestones` marks\ndates on the bar, `planned` the plan under it, `progress` how far it is done, `after` the rows it waits on;\nthe List\'s `group` is its lanes; a table holding rows under rows nests each bar under its row above, folded as the\nregister\'s outline is. A child List on a record with this layout draws the bars of the rows its link names. Worked: `examples/gantt`.\n\n#### Roster\n\n`layout: "roster"` with a List inside it over the child whose rows fill the days \u2014 one link back to the\nregister\'s table and a date on its line: what each row did on each day (shifts, runs, attendance). With\n`expect` (and `of`) on the cells the columns are the options of a select instead of days: which papers each row holds.\nAn `Export` with an html or Excel `template` prints the grid as the screen reads it (`document_templates/a-template`). Worked: `examples/roster`.\n\n#### Weekly pattern\n\nA row that owes a child\'s rows on set weekdays (a class\'s lessons, a person\'s shifts) states `records.cadence`, its days\na multi-select whose options are aliased `mon` to `sun`, and its times two `format: "time"` fields. The multi-select draws\nas a week strip wherever a person writes it; a Section holding the cadence\'s fields draws them as one week pattern; the\nrow\'s line reads it as one fact ("Tue, Thu \xB7 16:00\u201317:30"); a roster of the child reads each row\'s own days. An Act\n`makes: "<child>"` lists the rows still owed under the row each is made for, a group\'s count and tick at its head, a\nrow that would be refused unticked with why, and writes the ticked ones (`reference/record-places-pins-and-cadence`). A row that differs from a changed pattern is proposed as a move, ticked only where no person edited its day, end or a copied field and no row links to it; the class says how many rows differ.\n\n#### Agenda\n\nA child List with `layout: {"agenda": {\u2026}}` on a record: a child\'s planned entries by day, soonest first, today marked, each with its\npicture; within a day by the hour, or by a single select of the part of the day. `start` counts Day 1 from a\ndate of the record.\n\n#### Timeline\n\nA child List with `layout: "timeline"` on a record: a child read as a log of dated entries, newest first, with a composer \u2014 the\ncalls, visits and notes about the record, each with who and when, and its files where the child\'s `image`\nnames them. An app\'s Record draws no comment thread: a team\'s discussion on a record is a child table. Entries planned ahead are an agenda; the status\'s moves are its history. Worked:\n`examples/party`.\n\n### Moves and numbers\n\n#### Moves\n\nThe rows of a root List that a status stages towards its `closed` options move by Acts: each moves one option on to the next (`when` the\nstatus holds it, `set` to the next), at the foot of the Section whose work it ends. A status with nothing closed is a\ncondition a person sets. A value decided as a row reaches an outcome \u2014 why it was lost, refused, voided \u2014 is that\nAct\'s `asks`, never a field the reader must remember to fill. An Act reaching past the workspace \u2014 sending an invoice\nto a service, a letter by mail \u2014 runs its `workflow`, and what the workflow keeps from the answer (an invoice\'s id,\nits link) is named in the Act\'s `set`. Work sent back for changes moves back to the earlier\nstep; a hold is a yes/no field (and its reason) the step\'s Acts wait on in their `when`; work only some rows take is a\nstage\'s `when` (below); an issue to resolve is a row of its own. An Act also moves a row back (`when` the later\nstage, `set` the earlier): the row draws it beside the way on, and without one a row moved on by mistake stays until an\nadmin edits the table. What a `workflow` or a paper did stands, so a way back there is a correction of its own.\n\n#### Stages\n\nName each job\'s work plan by its shape: a status a person sets; a pipeline, where who holds the row and for how long\nmatter; or tasks, where only how many are done counts (`records.task`). A pipeline states each stage once in\n`records.status.stages` \u2014 its `owner` (a member field, a link\'s member field, or `{ "group": <id> }`, a member group) and its target\n`within` days \u2014 and the server holds it: only the owner\'s Acts move the row on, and a row created at a stage past the first is a move into that stage from nothing, which the stage\'s owner, an unowned stage\'s writer or a workspace admin (loading history) may make, on every path a row is written by, and a level an amount skips stands\nnamed with why. A move forward passes each owned stage between that binds the row, each its owner\'s. A stage\'s `when`\nnames the rows it binds, held as an Act\'s `when` holds them on the row\'s own fields, as the row stood before a write\nand as the write leaves it; with none, it binds every row. Expense claims over a limit wait for the finance group while\nsmaller ones go straight to payment: `"finance_review": { "owner": { "group": <id> }, "when": { "amount": { "gt": 5000000 } } }`.\nA row at a stage leaves it by its owner whatever its `when`; `dropped` names the closed options\nthat leave the work undone (cancelled, rejected), which whoever holds the row moves it to from any stage. A stage\'s owner gates who moves a row out of it; who may move a row into a stage ("only a bookkeeper marks an invoice paid") is a check. Late rows, rows due soon, a warning the line draws and rows waiting on the reader stand first in a\nregister; a register whose job is a strict order, a first-come queue, states `attention: false`.\n\n#### Stage dates and history\n\nWho changed what and when is the platform\'s audit trail, never a table and never shown by an app. When a stage\'s moment matters\nto the business \u2014 reported, filtered, printed \u2014 it is a date on the row that `records.status.dates` stamps as the row\nenters the option, whoever writes: the one way a status is timed, and the moment a stage\'s `within` runs from (each stage, and\neach open option of a status with stages, naming none gets `<option>_at`). A straight-line process is one select of its steps in order, each dated (a record whose parts state no `at` draws it as steps by itself: no date fields or formulas copy it); a move whose\nday may already be past `asks` that date with `starts: "today"`. `records.status.history` names a child the record write path appends one row to per\nstatus move (its link to the row, the new status, the moment and who) for a business that reports on every move: moves\nper person, or time in a stage a row re-enters. An event with facts of its own \u2014 a reason, an amount, a signature \u2014 is\nits own table, made by the act that records it. The rail reads the history. Worked: `examples/approval`, whose history is kept because a group\'s\nstage is signed once per person, read off who moved the row.\n\n#### Readings\n\nA List usually opens with one band of figures or a chart, chosen for what that person watches. Its Readings stand above the rows and its filters and read the rows under the open tab, never narrowed by the controls below them. Lead with the job\'s headline number \u2014\nits exception as a formula\'s yes/no in a Reading\'s `where` (what is short), never a stage the\nstatus chips already count, nor the overdue rows the register\'s summary line counts from `records.due` \u2014 then at most the mix (`by` a field) and the movement (`by` a date), varied by job. A movement over a date is stated, never defaulted; so is a sum, but for the one a status register with a money figure leads with by default: that figure over its open rows. A register with no such figure and no single select to split by gets no default band.\nA grid (`by` and `across`) reads on a Sheet. A Sheet \u2014 a View of Readings at the App\'s root, beside its Lists or alone \u2014\nanswers one owner\'s question across jobs, each Reading windowed by the reader\'s period (the App\'s `period`), and a\nList on it hands over the rows to act on. Many Readings stand on several Sheets, each a View the reader picks. A\ndashboard varies its charts by the job. A question one app\'s rows answer goes on a Sheet there; one spanning apps gets a small app of its own. A Record\'s Readings read its own child rows. Sums of each row\'s child rows are a Tab\'s `totals`. Worked: `examples/approval`, `examples/dashboard`.\n\n#### Funnel\n\nA Reading with `steps` reads a record\'s child rows as steps, each a number column summed over them \u2014 an order\'s lines\nfrom ordered to shipped. It states how much of the first step\neach later one keeps, the share lost between two neighbours, and the last over the first. State two to six\n`steps` in one unit; where the path turns \u2014 reach, then conversion \u2014 state two Readings one straight after the\nother, so the second\'s bars are read over its own first step, on one grid. A step no row holds a number in reads as not measured: leave it empty, never a zero nobody measured.\n\n#### Priced lines\n\nA quote\'s items, an estimate\'s works, a repair sheet\'s damages are lines priced off a book: a table whose\n`records` names each item, puts the code people type on its line and its price as its `figure`. The line links to\nit, asks the link and its quantities in its List\'s `create`, and copies the price (`default_from`), so the quote\nkeeps what was quoted when the book moves. A line\'s amount is a formula, the record\'s total a rollup over the rows\nthe List shows \u2014 what is not paid for is a second rollup, never a filter on the first, so each group subtotals.\nGroup the lines by the parts the record is quoted in (a container, a room, a leg), a field the line asks. A book worked only while a quote is written is the picker on the quote\'s lines; a book with a keeper, Acts or a history of its own is\nan app (`app_architecture`).\n\n### The record\n\n#### Sections\n\nA record is a head, its parts and at most one Side. From three parts it shows one part at a time; fewer stack. A part is one area of the record\'s data a person comes to for its own job, like the tabs of a settings page; its related lists and field groups sit inside it under their headings. A status\'s stages are not areas: their acts stand at the foot of the rows they move. State each\npart whole for the work there: a field may stand in any number of parts, and a field an Act requires draws beside it\nunstated. A step may hold nothing but its name. What a person needs in view at every part (who it is for, how to reach\nthem) goes in a Side: it leaves the head and stays on the rows. The status stands in the head or the Side, never a\nSection. `row` changes how the app\'s rows read, never a page nor what the app writes. A List, Reading, Statement or Act stated alike in several\nSections draws once, in the first; a Check stated in a Section guards the whole record.\n\nThe Record\'s Sections, in the order the work reaches them: the fields people write, a Field per paper the record\nkeeps, a child List per child, the Acts at each one\'s foot. A register\'s `columns` are in the order the job reads them, as many as fit a desk; what is read only on the way deeper is the Record\'s, and a figure that is final only from a stage is a Field of that stage\'s Section, never a column read on every row at every stage. A register laid out in time (calendar, lanes, roster) opens the\ndefault record: every field a person writes. Behaviour belongs in an Act.\n\nA Section of more than about six fields reads as Fieldsets of related facts: a patient\'s record holds "Contact" and\n"Insurance" rather than one run of nine, each Fieldset\'s `label` a few words. A gallery or prose Field stands beside the Fieldsets (`reference/fieldset-node`). Fields stand two\nto a line in the order stated, and files, prose and a link to several rows take the whole line: stated after a lone\nshort field, one leaves the half beside that field empty.\n\n#### Children\n\nRows that each belong to one row of another table (a one-row link to it) are drawn under that row: a List on\nits Record, `layout: "timeline"` where they are a log, `layout: {"agenda": \u2026}` where they are planned on a day and within it, a roster of\nthem, or lanes of them by that link. Which children a record lists is the author\'s \u2014 one of them at least. A List\nlisting only some of them narrows by its `where`: a select (one leg\'s fees), or a yes/no \u2014 a formula\'s for what is\nstill owed \u2014 on a List that adds no rows. A child List stating no `create` asks the table\'s required fields, natural key and\ntitle; where defaults fill them all, it adds none. Rows on\nfile before the row they come to belong to \u2014 a job\'s cost lines before the supplier bill over them \u2014 are picked into\nit: a List with `pick`, often with no `create` and no `remove`.\n\n### Papers\n\n#### Expect\n\nA List with `expect` naming the child\'s title \u2014 a single select of kinds, or a one-row link to a\ncatalog: one line per kind, the ones not yet filled standing empty, filled in place. `of` narrows the kinds\nto the record\'s own multi-select of those it needs. The papers a case gathers, the fees a record knows it\nowes. Worked: `examples/case`.\n\n`only` lists the kinds a List holds a line for, so each kind stands in the Section whose job it is, once. The Act making a paper (`paper: "<child>.<kind>"`), stated in the Record beside its Sections and moving the record as any Act does, is its line\'s button while it applies, the upload in the \u22EF.\n\n#### Templates\n\nA paper the business makes is an Act\'s `template`, kept in the record\'s files field `into` \u2014 or several at\nonce, `templates`: listed where the Act stands, each made one as its file, each not yet made a placeholder,\nthe reader ticking which to make. Worked: `examples/case`.\n\n#### Intake\n\nA paper the business is brought and reads is an Act\'s `intake`: the press takes the papers, an agent reads\nthem, and each is filed as the line of its kind in the child the record `expect`s, while `fills` writes what\nthey state into the record\'s fields \u2014 a single link as a row the agent finds among those the app reads \u2014 shown before it is saved. Stated with `on: "view"` at the register\'s title, the papers make a NEW record instead: `fills` names what it requires, `<link>.<field>` fills the row a required link names (found on its entity\'s `natural_key`, else added), and the register opens the record made. Worked: `examples/case`.\n\nAn agent Act \u2014 an `intake`, a `record`\'s `fills` \u2014 spends a run on every press, so it is stated only where the\nowner asked for an agent to do that job; otherwise a paper brought is its `expect` line, and a person types what it states.\n\n#### Under\n\nA List with `under`: the documents that cover lines (an invoice over its fee lines) stand as headings\nover the lines they cover, and a line no document covers offers to make one. A document entered as it arrives over lines\nalready on file (a supplier bill) picks them with `pick` instead; choose one per document.\n\n### Calls\n\n#### Record act\n\nAn Act\'s `record`: the press records a call, visit or meeting \u2014 audio, transcript, screen where captured \u2014 and\nfiles it as a new row of the record\'s `timeline` child (`into`), stamped `at` and `by`; `fills` lets an agent fill\nthat row\'s fields from the transcript, where the owner asked. Worked: `examples/calls`.\n\n';
|
|
1870
|
+
var design_default = '# Designing an app\n\nAn app is a tree of components: a List of one table, the Record a row opens, its Sections, the Acts that move it. The\ntree states COMPOSITION \u2014 which fields, lists and acts each job\'s screen holds; how each piece looks is the platform\'s,\none way per concept. A node the tree leaves out draws its default, from the table\'s facts (`records`, the stage, the\nwrite rules): a List\'s Readings band, the stage buttons, the picture, a Record\'s Sections. State a node to change it,\nor `false` at it to turn it off (`"readings": false`, a Record\'s `"row": { "image": false }`). A field is written where its Record declares it: a Section\'s Field, the table\'s face (title, line, picture, figure), or every field where the Record states no Section; the head, a line, a column or a board draws it, and never makes one written; every head part (`row.title`, each `row.subtitle` entry, `row.figure`, `row.image`) takes `edit: false` to be read. A drawn Field is a control unless it\nor its entity is read-only (`edit: false`); a stepped status never is, since Acts move it. Which apps a business needs is `app_architecture`.\n\n**The visual bar.** Every screen is judged against it; a miss is a change to the tree.\n\n- Each app looks like its own rows: the view its kind of row takes (`design/treatments`) \u2014 cards for things found by\n their photo, a calendar or lanes for dated work, faces for people and organisations. A List left as a table is drawn\n as one, the most common failure of an app; the answers of `set_app` and `get_app` note the view rows that are work in time call for (a calendar, lanes, a roster, a gantt where rows wait on one another).\n- What needs attention leads the row: `records.mark` on a select or a computed category (a formula stating its options;\n where it is empty, its seat is blank). A yes that needs attention (papers still owed) is a `Check` of its List over a\n yes/no formula, in the warning tone on the row\'s line; every other yes reads in the success tone.\n- A list\'s columns: the name and its lead, the status, then the columns the job reads on every row, as many as fit a desk. Each\n fact once: a column the row draws itself stands once. A generated number (`autonumber`) as the title yields\n the row\'s name to the subtitle\'s first part and stands first on its line.\n- A list worked by a date states `sort` on that date\'s column, newest first; without one, a register reads newest made\n first and a record\'s child List in the order its rows were added.\n- Someone is a face wherever they are read: a link to a table stating `records.party` draws its row\'s face; a member\n field is one already; select options naming people or organisations who are neither each take the `mark`\n `{"kind": "avatar", "name": "person"}`, never a colour dot.\n- A thing shows its picture, a file its preview, a plan its days on a time axis, a quantity a meter (`records.limits`) or\n a chart, a register its Readings, and long text reads whole (a markdown Field; `block: true` on plain long text).\n- Every category the job reads is coloured: each option\'s `color`, and a `mark` where a brand or glyph names it, on\n every option of a select read down a column (how it was paid, the channel). Colour an option only where the colour\n means something.\n- Every app states its tile\'s `color`, apart from the workspace\'s other apps where it can be.\n- The paperwork is the proof of the work: a files field per purpose (what arrived, what was issued to the customer, the\n carrier, the authority) in the Section where that work happens, and the source of a\n figure (a screenshot, an email, a sheet) on its row. Every files field is drawn somewhere. A paper a counterparty\n sends (a supplier\'s invoice, a delivery receipt) is added on the record it arrives with \u2014 the order it is for \u2014 and\n listed again where it is settled, never only in the counterparty\'s ledger.\n\n<!-- generated:start words -->\n\n**The words most builds state.** A node\'s page holds its rules and every other word: `reference/list-node`, `reference/records`, `reference/field`.\n\n**Table**\n\n- `ref` (alias): A created table\'s handle in this call\n- `label` (text, required): The table\'s name in the workspace\n- `singular` (text): One row of this table, in the business\'s own words\n- `title` (alias): The alias of the field that names a row wherever a link or a record shows one\n- `fields` (map of alias \u2192 Field, required): The table\'s columns, each under its alias, which is its key here and so is never stated inside it\n- `records` (any value): How a row is recognised\n- `checks` (map of alias \u2192 table check (`workflows/table-checks`)): The conditions a write of the table\'s rows may not meet, each under its alias\n- `unique` (list (at least one) of list of alias (at least one)): Sets of fields whose values no two live rows share\n\n**Any field**\n\n- `label` (text, required): The field\'s name in the workspace\n- `required` (boolean): Refuse a record whose cell for this field is empty\n- `default_from` (text): Copied when a record is made off the row a one-row link of this entity names\n\n**`number` field**\n\n- `notation` (notation): How the figure reads\n- `min` (number | text): Refuse a create or update whose value is below this\n\n**`select` field**\n\n- `options` (list of Select option (at least one), required): The choices, in the order every picker and every ladder lists them\n- `multi` (boolean): Allow multiple selections\n\n**`link` field**\n\n- `table` (text, required): The table the link points at\n- `multi` (boolean, required): Whether a row links to one row or many\n- `pair` (`true` | alias): Makes the link two-way\n\n**`formula` field**\n\n- `expression` (text, required): The expression, over fields of THIS entity by alias in braces\n- `output_type` (`"number"` | `"text"` | `"date"` | `"datetime"` | `"boolean"` | `"select"`): Holds a formula to the type its readers need\n\n**`rollup` field**\n\n- `via` (alias, required): The alias of a link of this table to roll up from\n- `op` (operation, required): The operation over the linked rows\n- `field` (alias): The alias of the field on the linked table the operation reads\n\n**`lookup` field**\n\n- `via` (alias, required): The alias of a link of this table to look up through\n- `field` (alias, required): The alias of the field on the linked table to show\n\n**`autonumber` field**\n\n- `prefix` (text): Literal prefix prepended to every display value (e.g. \'KH-\' \u2192 \'KH-001\')\n\n**`records`**\n\n- `subtitle` (list of alias (1\u20132)): Up to two fields read under the title wherever a row is drawn (a code, a date, a party)\n- `figure` (alias): The one number the row stands for, read at its right (a total, a quantity left)\n- `status` (Status): The stage a row moves through, a single select, drawn in the record\'s head, or its Side where the Side states it\n- `due` (list of alias (at least one)): Dates that are deadlines (stored, or computed as a date)\n- `image` (alias): A files field that pictures the row, or a one-row link to a table with a picture, whose picture the row leads with\n- `party` (`"person"` | `"organization"` | `"organisation"`): What each row is where the rows are people (a contact, a patient) or organisations (a customer, a supplier, a carrier)\n- `limits` (map of alias \u2192 (alias | number)): A number read against a bound\n- `starts` (map of alias \u2192 `"today"` | `"me"`): What a field of a row being added starts at, where that start is certain\n- `mark` (alias): A single select (or a lookup of one through a one-row link), or a formula that states its options, whose option leads the row wherever a mark leads it\n- `settled` (alias): A yes/no of the row (stored, a formula: an invoice paid in full, or looked up through a one-row link: a line settled with its parent) that ends its deadlines\n\n**`records.status`**\n\n- `field` (alias, required): The single select that is the row\'s state, its options in the order the work goes through them, read as steps by itself on a record whose parts state no `at`\n- `closed` (list of alias (at least one)): Options that end the work\n- `history` (text): A table every write that sets or moves the status appends one row to (its link to this table, the new status, the moment and who)\n- `dates` (map of alias \u2192 alias): Option alias \u2192 a date field of this entity the record write path stamps with the moment a row moves into that option, or is made at it\n- `stages` (map of alias \u2192 Stage): Option alias \u2192 who owns that stage and how long it should take\n\n**App**\n\n- `key` (alias, required): The app\'s alias, its name among apps\n- `name` (text, required): The job, in the words of the people who do it\n- `children` (list of (List | Sheet | Query | Workflow) (at least one)): The App\'s Views in order\n- `color` (colour): The launcher tile\'s colour\n- `pages` (list of Record (at least one)): The page the rows of an entity open, one per entity, each a Record stating its `entity`\n\n**List**\n\n- `entity` (alias, required): The table whose rows the List draws\n- `create` (boolean | list of alias (at least one)): The fields an add asks\n- `columns` (list of (alias | Edit column)): Fields read after the row\'s title\n- `label` (text): The register\'s name in the app\'s lists and tab strip\n- `filters` (list of (alias | Tiered filter) (at most 3)): Fields the reader narrows by every day, beside the stage chips\n- `children` (list of (Tab | Reading | Export | Act | List) (at least one)): Its Tabs, band Readings, Exports and Acts over ticked rows or every row in view\n- `key` (alias): Names the List among its siblings and in a Query\'s `list`\n- `sort` (Sort key | list of Sort key (at least one)): The rows\' order\n- `layout` (layout): A word, or an object stating one layout with its data\n- `remove` (boolean): Rows offer a Delete\n- `search` (list of alias (at least one)): Fields the search box reads\n- `where` (narrowing): A fixed narrowing on the server, for every reader\n- `group` (alias): A field the rows stand grouped by\n- `expect` (alias | Expect): What a record should hold, shown before it does\n- `opens` (narrowing): The view the register opens on, a chip the reader may take away\n\n**Record**\n\n- `entity` (alias, required): The table whose rows open on this page\n- `children` (list of (alias | Field | Fieldset | Section | Side | Outside | List | Reading | Statement | Act | Check) (at least one)): Parts (Section, Side), or for a one-part record its Fields, Fieldsets, Lists, Readings and Statements directly\n- `add` (`false` | list of alias (at least one)): What a new row asks where a picker of this entity offers one, anywhere in the App\n- `row` (Record row): How the App reads this entity\'s rows wherever it lists them\n- `door` (`"page"` | `"drawer"`): How a row opens, on a page or in a drawer\n\n**Section**\n\n- `title` (text, required): The part\'s heading\n- `key` (alias): Unique among its siblings\n- `children` (list of (alias | Field | Fieldset | List | Reading | Statement | Act | Check) (at least one)): What the part draws, in reading order\n- `at` (list of alias (at least one)): Options of the record\'s status during which this part is the work now\n- `when` (condition): Drawn only while this holds\n\n**Field**\n\n- `field` (alias, required): The field\'s alias\n- `edit` (boolean): Shows a value nobody changes here\n- `label` (text): The heading of the field\'s gallery or prose block, where it draws as one\n- `block` (boolean): Gives a field room of its own\n\n**Act**\n\n- `key` (alias, required): The act\'s name\n- `label` (text, required): The verb, as the reader says it\n- `when` (condition): The act works only while this holds\n- `set` (map of alias \u2192 value): What the act writes\n- `asks` (list of (alias | `{ "field": alias, "starts": "today" | "me" }` | Asked input) (at least one)): What the reader states on pressing\n- `confirm` (`true` | text): The press asks first\n- `requires` (list of alias (at least one)): Fields filled first, each drawn where the act stands\n- `template` (alias): A document template it makes a file from\n- `into` (alias): The record\'s files field keeping the document\n- `owner` (`"field"` | `"link.field"` | `{ "group": id }`): Who presses it\n- `workflow` (alias): The workflow it runs for what `set` cannot say\n- `danger` (`true`): The act destroys or cannot be undone\n\n**Check**\n\n- `field` (alias, required): A yes/no or text formula of the page\'s entity\n- `on` (`"all"` | list of (`"update"` | alias) (at least one)): What the standing check refuses\n- `resolve` (alias): An Act on one row of this entity that clears it\n\n**Reading**\n\n- `label` (text): What the figure is called\n- `value` (alias | `{ "avg": alias }`): A number field summed over the rows, or `{ avg }` averaged over the rows holding one\n- `by` (alias | Tiered filter): Splits the rows into parts\n- `where` (narrowing): Only the rows whose select holds one of these options, whose yes/no is this value, whose number or date meets its bounds (`gt`, `gte`, `lt`, `lte`; a date\'s `{ "now": true }` is read when the rows are), whose field is `{ "empty": true | false }`, or whose member field holds the reader (`{ "me": true }`)\n- `entity` (alias): The List\'s rows\n- `over` (alias): The date that places a row in time\n\n<!-- generated:end words -->\n\n## Look at it\n\nAfter an apply, `screenshot_app` draws each app as its people see it \u2014 the register, and a record by its `path` or its `record_id`\n(with a `path` on that record, such as one Section; `screen` for a later screen of a long one) \u2014 at a desk\'s width and a phone\'s, naming the columns a table left off at each width;\n`-o <dir>` saves the shots from the CLI. Beside them, `verdict` is what a write of the stored tree would be refused for\nnow, and its notes. Answer `design/the-rubric`, change the tree with `nodes`, and write again. To go back,\nsend the tree saved before the change as `body` with `app_id`, nulling an App prop stated since (`words`, `scope`,\n`period`, `icon`); tables and rows stay as they are.\n\n## The rubric\n\nWhether the build does the owner\'s work, answered by a call each, never from what you meant to write:\n\n1. Each job the owner named, and each their kind of business cannot run without: which screen does it, and which press? Find each on a `screenshot_app` shot of the person who does it (`as_member`).\n2. Can an agent do each job in one call, an `act_<key>` or a Query or Workflow node whose `description` names it? `get_app` lists them; `run_app_workflow` with `dry_run` proves one (`agent_surface/prove-an-app-as-an-agent`).\n3. Is each kind of row in its treatment (`design/treatments`)? Timed work reads in a calendar or lanes, and a weekly plan as the dated rows it makes.\n4. Does each screen show the least its next step needs, each fact once, the signal that a step is due leading?\n5. Is anything cramped at desk or phone width?\n6. Is every paper and every Export made, those this kind of business sends unasked too, with no blank? Press each paper Act and read the file it files; prove an Export with `run_app_query` and `export`.\n\nA failed answer is a change to the tree, or a gap named to the owner.\n\n## Treatments\n\nThe answers of `set_app` and `get_app` note the view rows that are work in time call for (a calendar, lanes, a roster, a gantt\nwhere rows wait on one another), naming the node that would state it; a note refuses nothing. No other treatment below is noted.\nEach kind of row\'s view is chosen before its List is written:\n\n| The rows are | The treatment | Its own page |\n|---|---|---|\n| People or organisations | `records.party`, with a photo or logo as its `image` | |\n| Things with a photo, a scan or a paper | `records.image`; List `layout: "cards"` where the picture is how a row is found | `reference/cards` |\n| Read by their day | List `layout: "calendar"`; on a record, a child List with `layout: {"agenda": \u2026}` | `reference/calendar`, `reference/layouts` |\n| Ranked by a figure, or worked by a date | List `sort: {"field": \u2026, "desc": true}` on that column | |\n| Booked on a resource | List `layout: {"lanes": {"by": \u2026}}`, and the table\'s `no_overlap` \u2014 a list of rules where a row holds two (a room and a teacher) | `reference/lanes`, `reference/write-rules` |\n| A day\'s work given out to people or vehicles | List `layout: {"lanes": {"by": \u2026}}` over rows holding a day and no hour | `reference/lanes` |\n| A log of what happened | a child List with `layout: "timeline"` | `reference/layouts` |\n| Opened to be worked on | the Record\'s Sections \u2014 each one area of the record\'s data, its lists and field groups inside it; a status\'s stage acts stand at the foot of the rows they move, `at` where the work moves in steps; fields only one kind of row holds (a delay\'s cause, a safety issue\'s hours lost) in a Section whose `when` names that kind | |\n| Rows that each belong to another row | a child List on that row\'s Record, with `create` and `remove` \u2014 and a child\'s own rows a List in that child\'s page, as deep as the data goes, and every row\'s \u22EF offers Duplicate; a List with `same` where read-only | |\n| A related row\'s value on the list (the newest contract\'s end date) | a `lookup` field of the table, ordered, as a column | `reference/lookup` |\n| Moving through a status | an Act per move, `status.dates` for the moment of each stage, and the register\'s Readings | |\n| Counted over a period | the register\'s Tabs over one `period`; a Tab\'s `totals` for a child\'s sums before, during and through it; an open Tab\'s `where` reads only what was true at the period\'s end, never a status the row moves on from | |\n| Papers a case gathers | a List with `expect`; the papers made, an Act\'s `templates` | |\n| A plan of spans | List `layout: {"gantt": {"start": \u2026}}` | `reference/gantt` |\n| Stood at a place on a plan, flat or in 3D \u2014 pallets, bins | List `layout: {"plan": \u2026}`; places state `plan_place` | `reference/plan` |\n| Checked item by item against a standard | a List with `checklist: {"photo": \u2026, "clause": \u2026, "failed": [\u2026], "passed": \u2026}`: each row a mark (passed at `closed`, failed at a `failed` option, or by the yes/no `passed` names \u2014 a measured verdict, no task or status needed), its photo and the clause it is checked against; with `expect` on the standard\'s items, each item is a line marked the same way and filled by the block\'s columns | |\n| A place before and after the work | a List with `compare: {"before": \u2026, "after": \u2026}`: two files fields read side by side, or two value fields read as one struck-then-new column | |\n| Spots on a drawing | `records.pin: {"on": \u2026, "x": \u2026, "y": \u2026}` on the spots\' table: a record listing rows that link to them draws the picture with a numbered pin at each; the picture is the `on` row\'s `records.image` | `reference/record-places-pins-and-cadence` |\n| Photos that must be taken on site | `records.on_site: {"photos": [\u2026]}`: a photo taken through the camera keeps where the device stood, and a record holding one taken away says so | `reference/record-places-pins-and-cadence` |\n| The real size of the thing (a carton, a piece of furniture, a pallet) | `records.size: {"across": \u2026, "along": \u2026, "up": \u2026}`: three number fields in one length unit, read as one fact "400 \xD7 300 \xD7 250 mm" after the subtitle; a plan register draws each box at that size | `reference/record-places-pins-and-cadence`, `reference/plan` |\n| A number painted on the thing, or a barcode or QR code on it | `records.scan: "iso6346"` or `"text"` (read off one photo by an agent), or `"code"` (decoded on the device, no agent): the title read on a phone, beside each search matching it | `reference/record-places-pins-and-cadence` |\n| The rows a weekly pattern owes (a class\'s lessons on Tue and Thu at 16:00) | `records.cadence: [{"entity": \u2026, "on": "<a multi-select of mon\u2013sun>", "start": \u2026, "end": \u2026, "planned": \u2026, "except": \u2026}]` on the parent, and an Act `makes: "<child>"`: the press lists the rows still owed, each with what would stop it, and writes the ones ticked; pressed again it lists what is missing, and moves a row to the pattern\'s hours and copied fields where it differs and no person or linked row has touched it (ticked), else leaves it unticked saying why | `reference/record-places-pins-and-cadence` |\n| Who did what on which day | List `layout: "roster"` with the List of its cells inside | `reference/roster` |\n| Someone with no seat signs off one record (a buyer approves a proof, a client signs a handover) | the Record\'s `Outside`: the Fields and Lists the link shows as they are, and Acts that each move the status out of its `at` \u2014 a link a member makes of the record, never a seat; the link\'s page names the record only where the Outside states its title\'s field | |\n| Steps people drop out of between | a Reading with `steps` on the record whose child rows count them | |\n| A record\'s own numbers nobody keys, read at a glance | consecutive Readings with no `entity` (up to eight tiles) | |\n| Rows that are each a place a record is sent | a List with `expect` on the link to those places and `post`: each ticked, the post written there and read as its feed shows it | `reference/publish-desk` |\n| Papers an agent reads, where the owner asked for one | an Act\'s `intake` with `fills` | |\n| Calls and visits | an Act\'s `record` | |\n| Changes a workflow proposes that a person approves row by row \u2014 a price list applied, a statement matched to what is owed | an Act\'s `workflow` with `review`, its body returning a changeset in `data.review` | |\n| Documents covering lines | a List with `under` | |\n| Rows on file a record takes in | a List with `pick` | |\n| One owner\'s question across jobs | an App of Tabs and Readings and no register | |\n\nWhat these nodes do not state, a long-form writing page or a bespoke tool, is a custom-code app (`lotics app create <name> --custom`, `app_bindings`), never a new node.\n\n### Faces and pictures\n\n#### Party\n\n`records.party` is `"person"` where the rows are people (a contact, a patient, a driver) and\n`"organization"` where they are companies (a customer, a supplier, a carrier). Every surface drawing one of\nits rows then draws a face: its `image` (a photo, a logo), else its initials. Without it, a person is drawn as a thing. A workspace\nmember is a `member` field, and is drawn by their face already. A column holding a link to several rows of people,\nor several members, draws their faces as a stack that names them on hover. Worked: `examples/party`.\n\n#### Image\n\n`records.image` names the files field that pictures a row \u2014 a product\'s photo, a damage photo, a\nscan, a receipt. Every row of it then leads with its picture, or its paper\'s preview, wherever it is drawn \u2014\na row holding no picture leads with the placeholder; a link to it previews the file. `image` may instead name a\none-row link to a table with a picture (an order line\'s `item`): the row leads with that row\'s picture, still titled by\nits own words. Never a field an Act keeps the paper it makes in (`into`). List\n`layout: "cards"` where the picture is how a row is found. A files field the record keeps as a folder of\npapers is drawn as a Field, read whole. Worked: `examples/cards`.\n\n#### A link opens its row\n\nEvery row an app draws opens on its page, the one you state or a default. A List\'s rows default to the table\'s fields; a link\'s row defaults to its name, line, status and figure. State `pages/<e>` to show more or to edit.\n\n### Rows in time\n\nRows that each stand on a day, or hold a run of days or hours, are read where they stand in time \u2014 never\nas two date columns. A row holds a span when two dates a person states are ordered, the second after the first by a\n`min` or a table check, both required or the second the row\'s `due`; else it is an appointment when one required date\nis stated that no Act stamps, that a new row does not start at `today` and that is not derived. A stamp is an event,\nand a `due` is a deadline, never the day a row is held on. A `no_overlap` by a person or a value alone keeps one row at\na time each \u2014 a member\'s periods in turn \u2014 read by what they hold.\n\n#### Calendar\n\n`layout: "calendar"`, or `{ "calendar": { "date": "starts_at", "end": "ends_at" } }`: the rows by their day \u2014 a\nmonth, a week, a day or a list; an entry at its hour where `date` holds one, over its span where `end` names the date it\nruns to. The bare word takes both from the rows\' facts and is refused, naming `date`, where they name none. An entry pressed opens its row beside the calendar; where the app saves the row, a drag or F2 moves it. Worked:\n`examples/calendar`.\n\n#### Lanes\n\n`layout: {"lanes": {"by": \u2026}}` with `by` naming a one-row link whose target\'s rows are the lanes (a chair, a\nmachine, a room), each drawn even when empty: every row a block from the first date on its line to the\nsecond, and a free stretch adds a row there. `loads` reads what a lane carries against what it holds: hours summed\nwithin each day (across days, the fullest day, named), any other number the most its rows add up to at one time. A\n`no_overlap` `by` the same link refuses two rows on one resource at once. A lane per person: `by` a member field\nand `of` a role of the model, each member of it a lane, idle ones too. Worked: `examples/lanes`.\n\nA day\'s work given out (stops to drivers, jobs to technicians): rows holding a day and no hour read at one day as cards\nin lanes, those no lane holds, or holding no day, first in a tray. Each lane\'s head reads its count, its loads and its\nrow\'s status; a lane its link no longer admits (`options_where`) says so in its head and refuses a card. Where the app writes the link, cards ticked or\ndragged go to a lane in one write, every row checked before any is written, and the List\'s first `sort`, ascending on a\nnumber the app writes, is a card\'s place in its lane.\n\n#### Gantt\n\n`layout: {"gantt": {"start": \u2026}}` (and `end`, else the table\'s first `due`; a `due` is a deadline, never an appointment date): one bar a row over\nits run of days, read against today. `milestones` marks\ndates on the bar, `planned` the plan under it, `progress` how far it is done, `after` the rows it waits on;\nthe List\'s `group` is its lanes; a table holding rows under rows nests each bar under its row above, folded as the\nregister\'s outline is. A child List on a record with this layout draws the bars of the rows its link names. Worked: `examples/gantt`.\n\n#### Roster\n\n`layout: "roster"` with a List inside it over the child whose rows fill the days \u2014 one link back to the\nregister\'s table and a date on its line: what each row did on each day (shifts, runs, attendance). With\n`expect` (and `of`) on the cells the columns are the options of a select instead of days: which papers each row holds.\nAn `Export` with an html or Excel `template` prints the grid as the screen reads it (`document_templates/a-template`). Worked: `examples/roster`.\n\n#### Weekly pattern\n\nA row that owes a child\'s rows on set weekdays (a class\'s lessons, a person\'s shifts) states `records.cadence`, its days\na multi-select whose options are aliased `mon` to `sun`, and its times two `format: "time"` fields. The multi-select draws\nas a week strip wherever a person writes it; a Section holding the cadence\'s fields draws them as one week pattern; the\nrow\'s line reads it as one fact ("Tue, Thu \xB7 16:00\u201317:30"); a roster of the child reads each row\'s own days. An Act\n`makes: "<child>"` lists the rows still owed under the row each is made for, a group\'s count and tick at its head, a\nrow that would be refused unticked with why, and writes the ticked ones (`reference/record-places-pins-and-cadence`). A row that differs from a changed pattern is proposed as a move, ticked only where no person edited its day, end or a copied field and no row links to it; the class says how many rows differ.\n\n#### Agenda\n\nA child List with `layout: {"agenda": {\u2026}}` on a record: a child\'s planned entries by day, soonest first, today marked, each with its\npicture; within a day by the hour, or by a single select of the part of the day. `start` counts Day 1 from a\ndate of the record.\n\n#### Timeline\n\nA child List with `layout: "timeline"` on a record: a child read as a log of dated entries, newest first, with a composer \u2014 the\ncalls, visits and notes about the record, each with who and when, and its files where the child\'s `image`\nnames them. An app\'s Record draws no comment thread: a team\'s discussion on a record is a child table. Entries planned ahead are an agenda; the status\'s moves are its history. Worked:\n`examples/party`.\n\n### Moves and numbers\n\n#### Moves\n\nThe rows of a root List that a status stages towards its `closed` options move by Acts: each moves one option on to the next (`when` the\nstatus holds it, `set` to the next), at the foot of the Section whose work it ends. A status with nothing closed is a\ncondition a person sets. A value decided as a row reaches an outcome \u2014 why it was lost, refused, voided \u2014 is that\nAct\'s `asks`, never a field the reader must remember to fill. An Act reaching past the workspace \u2014 sending an invoice\nto a service, a letter by mail \u2014 runs its `workflow`, and what the workflow keeps from the answer (an invoice\'s id,\nits link) is named in the Act\'s `set`. Work sent back for changes moves back to the earlier\nstep; a hold is a yes/no field (and its reason) the step\'s Acts wait on in their `when`; work only some rows take is a\nstage\'s `when` (below); an issue to resolve is a row of its own. An Act also moves a row back (`when` the later\nstage, `set` the earlier): the row draws it beside the way on, and without one a row moved on by mistake stays until an\nadmin edits the table. What a `workflow` or a paper did stands, so a way back there is a correction of its own.\n\n#### Stages\n\nName each job\'s work plan by its shape: a status a person sets; a pipeline, where who holds the row and for how long\nmatter; or tasks, where only how many are done counts (`records.task`). A pipeline states each stage once in\n`records.status.stages` \u2014 its `owner` (a member field, a link\'s member field, or `{ "group": <id> }`, a member group) and its target\n`within` days \u2014 and the server holds it: only the owner\'s Acts move the row on, and a row created at a stage past the first is a move into that stage from nothing, which the stage\'s owner, an unowned stage\'s writer or a workspace admin (loading history) may make, on every path a row is written by, and a level an amount skips stands\nnamed with why. A move forward passes each owned stage between that binds the row, each its owner\'s. A stage\'s `when`\nnames the rows it binds, held as an Act\'s `when` holds them on the row\'s own fields, as the row stood before a write\nand as the write leaves it; with none, it binds every row. Expense claims over a limit wait for the finance group while\nsmaller ones go straight to payment: `"finance_review": { "owner": { "group": <id> }, "when": { "amount": { "gt": 5000000 } } }`.\nA row at a stage leaves it by its owner whatever its `when`; `dropped` names the closed options\nthat leave the work undone (cancelled, rejected), which whoever holds the row moves it to from any stage. A stage\'s owner gates who moves a row out of it; who may move a row into a stage ("only a bookkeeper marks an invoice paid") is a check. Late rows, rows due soon, a warning the line draws and rows waiting on the reader stand first in a\nregister; a register whose job is a strict order, a first-come queue, states `attention: false`.\n\n#### Stage dates and history\n\nWho changed what and when is the platform\'s audit trail, never a table and never shown by an app. When a stage\'s moment matters\nto the business \u2014 reported, filtered, printed \u2014 it is a date on the row that `records.status.dates` stamps as the row\nenters the option, whoever writes: the one way a status is timed, and the moment a stage\'s `within` runs from (each stage, and\neach open option of a status with stages, naming none gets `<option>_at`). A straight-line process is one select of its steps in order, each dated (a record whose parts state no `at` draws it as steps by itself: no date fields or formulas copy it); a move whose\nday may already be past `asks` that date with `starts: "today"`. `records.status.history` names a child the record write path appends one row to per\nstatus move (its link to the row, the new status, the moment and who) for a business that reports on every move: moves\nper person, or time in a stage a row re-enters. An event with facts of its own \u2014 a reason, an amount, a signature \u2014 is\nits own table, made by the act that records it. The rail reads the history. Worked: `examples/approval`, whose history is kept because a group\'s\nstage is signed once per person, read off who moved the row.\n\n#### Readings\n\nA List usually opens with one band of figures or a chart, chosen for what that person watches. Its Readings stand above the rows and its filters and read the rows under the open tab, never narrowed by the controls below them. Lead with the job\'s headline number \u2014\nits exception as a formula\'s yes/no in a Reading\'s `where` (what is short), never a stage the\nstatus chips already count, nor the overdue rows the register\'s summary line counts from `records.due` \u2014 then at most the mix (`by` a field) and the movement (`by` a date), varied by job. A movement over a date is stated, never defaulted; so is a sum, but for the one a status register with a money figure leads with by default: that figure over its open rows. A register with no such figure and no single select to split by gets no default band.\nA grid (`by` and `across`) reads on a Sheet. A Sheet \u2014 a View of Readings at the App\'s root, beside its Lists or alone \u2014\nanswers one owner\'s question across jobs, each Reading windowed by the reader\'s period (the App\'s `period`), and a\nList on it hands over the rows to act on. Many Readings stand on several Sheets, each a View the reader picks. A\ndashboard varies its charts by the job. A question one app\'s rows answer goes on a Sheet there; one spanning apps gets a small app of its own. A Record\'s Readings read its own child rows. Sums of each row\'s child rows are a Tab\'s `totals`. Worked: `examples/approval`, `examples/dashboard`.\n\n#### Funnel\n\nA Reading with `steps` reads a record\'s child rows as steps, each a number column summed over them \u2014 an order\'s lines\nfrom ordered to shipped. It states how much of the first step\neach later one keeps, the share lost between two neighbours, and the last over the first. State two to six\n`steps` in one unit; where the path turns \u2014 reach, then conversion \u2014 state two Readings one straight after the\nother, so the second\'s bars are read over its own first step, on one grid. A step no row holds a number in reads as not measured: leave it empty, never a zero nobody measured.\n\n#### Priced lines\n\nA quote\'s items, an estimate\'s works, a repair sheet\'s damages are lines priced off a book: a table whose\n`records` names each item, puts the code people type on its line and its price as its `figure`. The line links to\nit, asks the link and its quantities in its List\'s `create`, and copies the price (`default_from`), so the quote\nkeeps what was quoted when the book moves. A line\'s amount is a formula, the record\'s total a rollup over the rows\nthe List shows \u2014 what is not paid for is a second rollup, never a filter on the first, so each group subtotals.\nGroup the lines by the parts the record is quoted in (a container, a room, a leg), a field the line asks. A book worked only while a quote is written is the picker on the quote\'s lines; a book with a keeper, Acts or a history of its own is\nan app (`app_architecture`).\n\n### The record\n\n#### Sections\n\nA record is a head, its parts and at most one Side. From three parts it shows one part at a time; fewer stack. A part is one area of the record\'s data a person comes to for its own job, like the tabs of a settings page; its related lists and field groups sit inside it under their headings. A status\'s stages are not areas: their acts stand at the foot of the rows they move. State each\npart whole for the work there: a field may stand in any number of parts, and a field an Act requires draws beside it\nunstated. A step may hold nothing but its name. What a person needs in view at every part (who it is for, how to reach\nthem) goes in a Side: it leaves the head and stays on the rows. The status stands in the head or the Side, never a\nSection. `row` changes how the app\'s rows read, never a page nor what the app writes. A List, Reading, Statement or Act stated alike in several\nSections draws once, in the first; a Check stated in a Section guards the whole record.\n\nThe Record\'s Sections, in the order the work reaches them: the fields people write, a Field per paper the record\nkeeps, a child List per child, the Acts at each one\'s foot. A register\'s `columns` are in the order the job reads them, as many as fit a desk; what is read only on the way deeper is the Record\'s, and a figure that is final only from a stage is a Field of that stage\'s Section, never a column read on every row at every stage. A register laid out in time (calendar, lanes, roster) opens the\ndefault record: every field a person writes. Behaviour belongs in an Act.\n\nA Section of more than about six fields reads as Fieldsets of related facts: a patient\'s record holds "Contact" and\n"Insurance" rather than one run of nine, each Fieldset\'s `label` a few words. A gallery or prose Field stands beside the Fieldsets (`reference/fieldset-node`). Fields stand two\nto a line in the order stated, and files, prose and a link to several rows take the whole line: stated after a lone\nshort field, one leaves the half beside that field empty.\n\n#### Children\n\nRows that each belong to one row of another table (a one-row link to it) are drawn under that row: a List on\nits Record, `layout: "timeline"` where they are a log, `layout: {"agenda": \u2026}` where they are planned on a day and within it, a roster of\nthem, or lanes of them by that link. Which children a record lists is the author\'s \u2014 one of them at least. A List\nlisting only some of them narrows by its `where`: a select (one leg\'s fees), or a yes/no \u2014 a formula\'s for what is\nstill owed \u2014 on a List that adds no rows. A child List stating no `create` asks the table\'s required fields, natural key and\ntitle; where defaults fill them all, it adds none. Rows on\nfile before the row they come to belong to \u2014 a job\'s cost lines before the supplier bill over them \u2014 are picked into\nit: a List with `pick`, often with no `create` and no `remove`.\n\n### Papers\n\n#### Expect\n\nA List with `expect` naming the child\'s title \u2014 a single select of kinds, or a one-row link to a\ncatalog: one line per kind, the ones not yet filled standing empty, filled in place. `of` narrows the kinds\nto the record\'s own multi-select of those it needs. The papers a case gathers, the fees a record knows it\nowes. Worked: `examples/case`.\n\n`only` lists the kinds a List holds a line for, so each kind stands in the Section whose job it is, once. The Act making a paper (`paper: "<child>.<kind>"`), stated in the Record beside its Sections and moving the record as any Act does, is its line\'s button while it applies, the upload in the \u22EF.\n\n#### Templates\n\nA paper the business makes is an Act\'s `template`, kept in the record\'s files field `into` \u2014 or several at\nonce, `templates`: listed where the Act stands, each made one as its file, each not yet made a placeholder,\nthe reader ticking which to make. Worked: `examples/case`.\n\n#### Intake\n\nA paper the business is brought and reads is an Act\'s `intake`: the press takes the papers, an agent reads\nthem, and each is filed as the line of its kind in the child the record `expect`s, while `fills` writes what\nthey state into the record\'s fields \u2014 a single link as a row the agent finds among those the app reads \u2014 shown before it is saved. Stated with `on: "view"` at the register\'s title, the papers make a NEW record instead: `fills` names what it requires, `<link>.<field>` fills the row a required link names (found on its entity\'s `natural_key`, else added), and the register opens the record made. Worked: `examples/case`.\n\nAn agent Act \u2014 an `intake`, a `record`\'s `fills` \u2014 spends a run on every press, so it is stated only where the\nowner asked for an agent to do that job; otherwise a paper brought is its `expect` line, and a person types what it states.\n\n#### Under\n\nA List with `under`: the documents that cover lines (an invoice over its fee lines) stand as headings\nover the lines they cover, and a line no document covers offers to make one. A document entered as it arrives over lines\nalready on file (a supplier bill) picks them with `pick` instead; choose one per document.\n\n### Calls\n\n#### Record act\n\nAn Act\'s `record`: the press records a call, visit or meeting \u2014 audio, transcript, screen where captured \u2014 and\nfiles it as a new row of the record\'s `timeline` child (`into`), stamped `at` and `by`; `fills` lets an agent fill\nthat row\'s fields from the transcript, where the owner asked. Worked: `examples/calls`.\n\n';
|
|
1871
1871
|
|
|
1872
1872
|
// docs/app_architecture.md
|
|
1873
1873
|
var app_architecture_default = '# App architecture \u2014 which apps, and who gets each\n\n**Which apps.** One app per main entity, a thing the owner\'s words give its own list. A row that makes sense only under one parent (an employee\'s contracts, an order\'s lines) is a child List on the parent\'s page, never another app or a Tab. A second root List is rare: one job working two unrelated entities side by side. A related row\'s value on the list is a lookup column; work over many rows (a month\'s payroll) an Act on the list\'s rows. A person\'s part of the work doesn\'t make an app; a different job may.\n\nOne bakery\'s wholesale arm, five people, seven apps:\n\n| App (its list) | Opened by | On a row\'s page |\n|---|---|---|\n| Customers | Sales rep, owner | Their prices, orders and unpaid invoices |\n| Products | Sales rep, head baker | Price breaks, recipe, stock on hand |\n| Orders | Sales rep, head baker, owner | Lines, the quote paper (an Act), the bake orders it starts |\n| Bake orders | Head baker | Steps, the Acts that move a stage, the tasting |\n| Suppliers | Buyer | Their price list and purchase orders |\n| Purchase orders | Buyer, storekeeper | Lines, goods received |\n| Materials | Storekeeper, buyer | Movements in and out, the Receive and Issue Acts |\n\nAn order\'s lines, a bake order\'s steps and a customer\'s prices make sense only under their parent: each is a child\nList on that row\'s page, never an app or a Tab. An order stands in the Orders app and on its customer\'s page: one\nrecord, one page. The owner reads the figures each register leads with. Each app\'s `name` is its list and its `description` says what is worked there:\n\n```json\n{\n "type": "App",\n "key": "orders",\n "name": "Orders",\n "description": "Takes a customer\'s order from quote to dispatch.",\n "children": [{ "type": "List", "entity": "order" }]\n}\n```\n\nHow each tree is composed is `design`.\n\n## Who gets each\n\nWho does which job is asked in `build`\'s one message before the first write. An app stays with admins until the answer comes, and sharing waits on it. `set_access` then gives each app to everyone who works its rows (ids from `get_workspace`); none loses access. They need no\ntable access: an app runs as its owner. With no `rows` on the App they read every row; where people differ, `rows`\nstates one rule per table (`reference/read-scope`):\n\n| The business says | The app states |\n|---|---|\n| Everyone sees every order | nothing |\n| Each rep sees only their own deals | `"rows": { "deal": { "any": [{ "field": "rep", "is": "self" }] } }` |\n| Reps see their own deals; managers see all | `"rows": { "deal": { "any": [{ "field": "rep", "is": "self" }, { "member_of": "<managers group id>" }] } }` |\n| Each branch manager sees their branch\'s orders | `"rows": { "order": { "any": [{ "through": ["branch"], "field": "manager", "is": "self" }] } }` |\n| Each employee sees only their own payslips; HR sees all | two apps: one stating `"payslip": { "any": [{ "field": "employee", "is": "self" }] }`, one for HR stating none |\n| Team leads see people, not salaries | an app that draws no salary field |\n\nA public link or an API key reaches every alias an app declares, so what outsiders may call is a second app over the\nsame tables, and the team\'s desk stays private (`app_bindings/api-apps`).\n';
|
|
@@ -1909,7 +1909,7 @@ var workflows_default = '# Workflows \u2014 the steps a workflow runs\n\nA workf
|
|
|
1909
1909
|
var workflow_steps_default = '<!-- Generated by backend/scripts/generate_workflow_steps_doc.ts from each step\'s schemas \u2014 never edit by hand. -->\n\n# Workflow steps\n\nThe steps only a workflow body runs: a connection\'s (an invoice issuer, a mailbox, \u2026) and the platform\'s own. Each is\ncalled as `await <step>({ ...inputs })` (see `workflows`); a step\'s inputs and answer are its entry here. A connection\nstep takes the `connected_account_id` that `get_workspace` lists under kind `connection`, and the app\'s owner must be\nable to use that connection. A step\'s `connected_account_id` is a literal, a\nconstant bound to one, or a choice among them: every possible value is judged at save, and one read from an input, a\nrecord or a call is refused. A template may come from data; a run refuses one its owner cannot use.\n\n**How a step fails.** A step that is refused \u2014 an input the schema rejects, a connection the workspace lacks, an\nanswer the provider refuses \u2014 ends the run, and the run\'s error reads `[<step>] <reason>`. Inside `try { \u2026 } catch\n(e) { \u2026 }` the body handles it instead: `e` is `{ message, type, step_id?, detail? }`, `message` the reason as\nabove. A provider\'s refusal carries the provider\'s own words.\n\n## aggregate\n\n### aggregate_records (workflow step)\n\n- Compute aggregate statistics over records.\n- Fields and select options are named by their alias, as get_table shows them. (chat, MCP, CLI)\n- A workspace admin\'s `as_member` computes over what that member would see.\n- Pass either `aggregate_option` for a single statistic, or `aggregations` to compute several in one call.\n- Example: { "table_id": "...", "aggregate_option": { "operation": "sum", "field_key": "amount" } } Operations by field type: No field: count \u2014 the rows matching `filters`.\n- `filled` counts populated CELLS, which is a different number the moment any are empty.\n- All fields: empty, filled, percent_empty, percent_filled, unique, percent_unique Number: sum, avg, median, min, max, range Date: earliest, latest, date_range Boolean: checked, unchecked, percent_checked, percent_unchecked `group_by` breaks every requested statistic down per distinct value of one field, computed over the same filters \u2014 one call in place of a call per bucket.\n- Example: { "table_id": "...", "group_by": "status", "filters": {...}, "aggregations": [{ "operation": "filled", "field_key": "created_on" }, { "operation": "sum", "field_key": "amount" }] } Restrict the period through `filters` on a date field rather than grouping by that date \u2014 a raw date/datetime groups per distinct stored value.\n- Filters: Operators: `is`, `is_not` on a field holding one value; `is_any_of`, `is_none_of` on text, number, date, select, member and link fields; `lt`, `lte`, `gt`, `gte` on number and date; `is_empty`, `is_not_empty` on every field but yes/no.\n- A date is "YYYY-MM-DD" for that whole day.\n- On text, `contains`, `starts_with` and `ends_with` ignore case and keep accents: `c\xE1` finds `C\xE1 h\u1ED3i`, not `C\xE0 chua`.\n- `ignore_accents: true` makes `ca` and `c\xE1` find both.\n- `equals` and `is_any_of` keep accents.\n- `docs path="filters"`. (chat, MCP, CLI)\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `table_id` | string | yes | |\n| `as_member` | string | | For a workspace admin: reads as this member would \u2014 their row rules and access. Anyone else is refused. |\n| `filters` | any | | |\n| `aggregate_option` | any | | |\n| `aggregations` | any[] | | At most 25 entries. |\n| `group_by` | string | | Field alias to break the statistics down by. Rows with no value in it are reported separately, not folded into a group. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `result` | number \\\\| string | | Result of a single `aggregate_option` call \u2014 a number, or a string for dates. |\n| `_units` | object[] | | One answer per unit or currency the rows hold, most rows first; unit null for rows naming none. `result` is the first. |\n| `_units[].unit` | string \\\\| null | yes | |\n| `_units[].value` | number | yes | |\n| `results` | object[] | | One entry per aggregation when `aggregations` is used. |\n| `results[].operation` | string | yes | |\n| `results[].field_key` | string | yes | |\n| `results[].field_name` | string | yes | |\n| `results[].result` | number \\\\| string | yes | |\n| `results[].units` | object[] | | One answer per unit or currency the rows hold, most rows first; unit null for rows naming none. `result` is the first. |\n| `results[].units[].unit` | string \\\\| null | yes | |\n| `results[].units[].value` | number | yes | |\n| `groups` | object[] | | One entry per distinct value of `group_by`, each carrying every requested statistic. |\n| `groups[].key` | string | yes | The group\'s identity. `label` is a spelling of it, and two rows can spell one identity differently. |\n| `groups[].label` | string | | Readable name for `key` where one is known: an option\'s name, a linked record\'s display text, a filename. Absent means no name was available, never that the group is empty. |\n| `groups[].results` | object[] | yes | |\n| `groups[].results[].operation` | string | yes | |\n| `groups[].results[].field_key` | string | yes | |\n| `groups[].results[].field_name` | string | yes | |\n| `groups[].results[].result` | number \\\\| string | yes | |\n| `groups[].results[].units` | object[] | | One answer per unit or currency the rows hold, most rows first; unit null for rows naming none. `result` is the first. |\n| `groups[].results[].units[].unit` | string \\\\| null | yes | |\n| `groups[].results[].units[].value` | number | yes | |\n| `_ungrouped_rows` | number | | Matching rows with no value in the `group_by` field \u2014 counted in no group. |\n| `_group_field_name` | string | | |\n| `_operation` | string | | |\n| `_field_key` | string | | |\n| `_field_name` | string | | |\n| `_value_coverage` | object | | |\n| `_value_coverage.requested` | number | yes | |\n| `_value_coverage.field_name` | string | yes | |\n| `_value_coverage.composite` | boolean | | |\n| `_value_coverage.per_value` | object | | |\n| `_value_coverage.per_value.matched` | number | yes | |\n| `_value_coverage.per_value.missing` | string[] | yes | |\n| `_narrowed_hops` | string[] | | The tables a filter looked through whose rows this reader\'s access limits. |\n\n## bkav\n\n### bkav_attach_files (workflow step)\n\n- Attach workspace files (a bi\xEAn b\u1EA3n, a b\u1EA3ng k\xEA) to an invoice on Bkav.\n- Bkav accepts PDF and Excel, at most 1 MB each.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string | | |\n| `partner_invoice_id` | string | | Your PartnerInvoiceStringID, when invoice_guid is not set |\n| `file_ids` | string[] | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes | |\n| `results[].PartnerInvoiceID` | number | yes | |\n| `results[].PartnerInvoiceStringID` | string \\\\| null | yes | Null on a delete\'s answer |\n| `results[].InvoiceGUID` | string | yes | |\n| `results[].InvoiceForm` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceSerial` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |\n| `results[].MTC` | string \\\\| null | yes | M\xE3 tra c\u1EE9u the buyer looks the invoice up with; null on a draft\'s link answer |\n| `results[].MaCuaCQT` | string \\\\| null | | |\n| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |\n| `results[].MessLog` | string | yes | |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_cancel_invoices (workflow step)\n\n- Cancel issued invoices.\n- A cancelled invoice still reports to the tax authority; correcting one instead is a replacement or adjustment through bkav_submit_invoices. (workflow step, chat)\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guids` | string[] | | InvoiceGUIDs Bkav returned |\n| `partner_invoice_ids` | string[] | | Your PartnerInvoiceStringIDs |\n| `reason` | string | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes | |\n| `results[].PartnerInvoiceID` | number | yes | |\n| `results[].PartnerInvoiceStringID` | string \\\\| null | yes | Null on a delete\'s answer |\n| `results[].InvoiceGUID` | string | yes | |\n| `results[].InvoiceForm` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceSerial` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |\n| `results[].MTC` | string \\\\| null | yes | M\xE3 tra c\u1EE9u the buyer looks the invoice up with; null on a draft\'s link answer |\n| `results[].MaCuaCQT` | string \\\\| null | | |\n| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |\n| `results[].MessLog` | string | yes | |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_create_bill (workflow step)\n\n- Record a cash-register bill on Bkav.\n- Field names are Bkav\'s.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `bill` | object | yes | |\n| `bill.Bill` | object | yes | |\n| `bill.Bill.BillCode` | number | yes | |\n| `bill.Bill.OriginalBillCode` | number | | |\n| `bill.Bill.BillDate` | string | yes | |\n| `bill.Bill.BillStatusID` | number | yes | |\n| `bill.Bill.PayMethod` | string | | |\n| `bill.Bill.Note` | string | | |\n| `bill.ListBillDetails` | object[] | yes | |\n| `bill.ListBillDetails[].ItemTypeID` | number | | 0 goods, 4 description line, 15 promotional goods, \u2026 |\n| `bill.ListBillDetails[].IsDiscount` | boolean | | |\n| `bill.ListBillDetails[].ItemCode` | string | | |\n| `bill.ListBillDetails[].ItemName` | string | yes | |\n| `bill.ListBillDetails[].UnitName` | string | | |\n| `bill.ListBillDetails[].Qty` | number | | |\n| `bill.ListBillDetails[].Price` | number | | |\n| `bill.ListBillDetails[].Amount` | number | | |\n| `bill.ListBillDetails[].TaxRateID` | number | | 1 0%, 2 5%, 3 10%, 4 kh\xF4ng ch\u1ECBu thu\u1EBF, 9 8%, \u2026 |\n| `bill.ListBillDetails[].TaxRate` | number | | |\n| `bill.ListBillDetails[].TaxAmount` | number | | |\n| `bill.ListBillDetails[].OtherAmount` | number | | |\n| `bill.ListBillDetails[].DiscountRate` | number | | |\n| `bill.ListBillDetails[].DiscountAmount` | number | | |\n| `bill.ListBillDetails[].UserDefineDetails` | string | | |\n| `bill.ListBillDetails[].IsIncrease` | boolean \\\\| null | | On an adjustment: true raises the amount, false lowers it, absent adjusts information |\n| `bill.ListBillDetails[].SpecialtyItems` | string | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `created` | true | yes | |\n\n### bkav_create_invoice_from_bills (workflow step)\n\n- Raise one invoice from cash-register bills, by their BillGUIDs.\n- Field names are Bkav\'s.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `input` | object | yes | |\n| `input.Invoice` | object | yes | |\n| `input.Invoice.InvoiceTypeID` | number | yes | 1 GTGT, 2 b\xE1n h\xE0ng, 5 PXK ki\xEAm VCNB, 6 PXK g\u1EEDi b\xE1n \u0111\u1EA1i l\xFD |\n| `input.Invoice.InvoiceDate` | string | yes | ISO date |\n| `input.Invoice.BuyerCode` | string | | |\n| `input.Invoice.BuyerName` | string | | |\n| `input.Invoice.BuyerTaxCode` | string | | |\n| `input.Invoice.BuyerUnitName` | string | | |\n| `input.Invoice.BuyerAddress` | string | | |\n| `input.Invoice.BuyerBankAccount` | string | | Sent empty when absent: Bkav refuses it missing |\n| `input.Invoice.PayMethodID` | number | | 1 TM, 2 CK, 3 TM/CK, \u2026 |\n| `input.Invoice.ReceiveTypeID` | number | | 1 email, 2 SMS, 3 both, 4 courier |\n| `input.Invoice.ReceiverEmail` | string | | |\n| `input.Invoice.ReceiverMobile` | string | | |\n| `input.Invoice.ReceiverAddress` | string | | Sent empty when absent: Bkav refuses it missing |\n| `input.Invoice.ReceiverName` | string | | Sent empty when absent: Bkav refuses it missing |\n| `input.Invoice.Note` | string | | |\n| `input.Invoice.BillCode` | string | | Sent empty when absent: Bkav refuses it missing |\n| `input.Invoice.CurrencyID` | string | | |\n| `input.Invoice.ExchangeRate` | number | | |\n| `input.Invoice.InvoiceForm` | string | | M\u1EABu s\u1ED1 |\n| `input.Invoice.InvoiceSerial` | string | | K\xFD hi\u1EC7u |\n| `input.Invoice.InvoiceNo` | number | | S\u1ED1; 0 when Bkav assigns it |\n| `input.Invoice.MaCuaCQT` | string | | Set only by a cash-register flow that already holds the authority\'s code |\n| `input.Invoice.UserDefine` | string | | JSON-encoded template fields agreed with Bkav |\n| `input.Invoice.UIDefine` | string | | JSON-encoded delivery-note fields (InvoiceTypeID 5 and 6) |\n| `input.Invoice.isBTH` | boolean | | |\n| `input.Invoice.CCCD` | string | | |\n| `input.Invoice.PassportNumber` | string | | |\n| `input.Invoice.FiscalCodes` | string | | |\n| `input.Invoice.Reason` | string | | Why \u2014 required on a replacement or adjustment |\n| `input.Invoice.OriginalInvoiceIdentify` | string | | `[m\u1EABu s\u1ED1]_[k\xFD hi\u1EC7u]_[s\u1ED1]` of the invoice a replacement or adjustment corrects |\n| `input.Invoice.InvoiceGUID` | string | | Addresses the invoice for an update by guid |\n| `input.BillGUIDs` | string[] | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes | |\n| `results[].PartnerInvoiceID` | number | yes | |\n| `results[].PartnerInvoiceStringID` | string \\\\| null | yes | Null on a delete\'s answer |\n| `results[].InvoiceGUID` | string | yes | |\n| `results[].InvoiceForm` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceSerial` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |\n| `results[].MTC` | string \\\\| null | yes | M\xE3 tra c\u1EE9u the buyer looks the invoice up with; null on a draft\'s link answer |\n| `results[].MaCuaCQT` | string \\\\| null | | |\n| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |\n| `results[].MessLog` | string | yes | |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_delete_invoices (workflow step)\n\n- Delete invoices that were never issued.\n- A numbered one can be deleted only if its number is the highest in its range.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guids` | string[] | | InvoiceGUIDs Bkav returned |\n| `partner_invoice_ids` | string[] | | Your PartnerInvoiceStringIDs |\n| `reason` | string | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes | |\n| `results[].PartnerInvoiceID` | number | yes | |\n| `results[].PartnerInvoiceStringID` | string \\\\| null | yes | Null on a delete\'s answer |\n| `results[].InvoiceGUID` | string | yes | |\n| `results[].InvoiceForm` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceSerial` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |\n| `results[].MTC` | string \\\\| null | yes | M\xE3 tra c\u1EE9u the buyer looks the invoice up with; null on a draft\'s link answer |\n| `results[].MaCuaCQT` | string \\\\| null | | |\n| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |\n| `results[].MessLog` | string | yes | |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_explain_invoice_error (workflow step)\n\n- Explain an erroneous invoice to the tax authority without replacing or adjusting it, optionally answering one of its notices.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string | yes | |\n| `reason` | string | yes | |\n| `notice_number` | string | | S\u1ED1 of the authority\'s notice being answered |\n| `notice_date` | string | | yyyy-mm-dd; with notice_number |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes | |\n| `results[].InvoiceGUID` | string | yes | |\n| `results[].Status` | number | yes | 0 succeeded; otherwise Msg says why |\n| `results[].Msg` | string | yes | |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_explain_replaced_invoice (workflow step)\n\n- Explain to the tax authority an invoice that was replaced or adjusted.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string | yes | |\n| `reason` | string | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes | |\n| `results[].InvoiceGUID` | string | yes | |\n| `results[].Status` | number | yes | 0 succeeded; otherwise Msg says why |\n| `results[].Msg` | string | yes | |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_get_bill (workflow step)\n\n- Read a cash-register bill.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `seller_tax_code` | string | yes | |\n| `organization_code` | string | yes | |\n| `bill_code` | number | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `bill` | object | yes | |\n\n### bkav_get_error_notice_pdf (workflow step)\n\n- Save the PDF of an invoice\'s 04/SS error notice as a workspace file.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `partner_invoice_id` | string | yes | Your PartnerInvoiceStringID |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n### bkav_get_file_by_lookup_code (workflow step)\n\n- Save an invoice\'s display copy, conversion copy or XML as a workspace file, found by the m\xE3 tra c\u1EE9u the buyer was sent.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `lookup_code` | string | yes | M\xE3 tra c\u1EE9u |\n| `kind` | "display" \\\\| "converted" \\\\| "xml" | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n### bkav_get_invoice (workflow step)\n\n- Read one invoice as Bkav holds it \u2014 header, lines, status and m\xE3 tra c\u1EE9u.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `id` | string | yes | Your PartnerInvoiceStringID or Bkav\'s InvoiceGUID |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `invoice` | object | yes | |\n\n### bkav_get_invoice_file (workflow step)\n\n- Save an invoice\'s PDF or signed XML as a workspace file.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `partner_invoice_id` | string | yes | Your PartnerInvoiceStringID |\n| `format` | "pdf" \\\\| "xml" | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n### bkav_get_invoice_history (workflow step)\n\n- Read everything that happened to an invoice on Bkav, oldest first.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `entries` | object[] | yes | |\n\n### bkav_get_invoice_link (workflow step)\n\n- Get a download link for an invoice\'s display copy, conversion copy, or its 04/SS error notice.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `partner_invoice_id` | string | yes | Your PartnerInvoiceStringID |\n| `kind` | "display" \\\\| "converted" \\\\| "notice_04ss" | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `url` | string | yes | |\n\n### bkav_get_invoice_status (workflow step)\n\n- Read an invoice\'s status on Bkav.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `invoice_status_id` | number | yes | 1 m\u1EDBi t\u1EA1o, 2 \u0111\xE3 ph\xE1t h\xE0nh, 3 \u0111\xE3 hu\u1EF7, 5\u20138 ch\u1EDD/\u0111\xE3 thay th\u1EBF\u2013\u0111i\u1EC1u ch\u1EC9nh, 11 \u0111\xE3 c\u1EA5p s\u1ED1 ch\u1EDD k\xFD |\n\n### bkav_get_listing (workflow step)\n\n- Save the b\u1EA3ng k\xEA of one invoice type over a window as a workspace spreadsheet.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_type_id` | number | yes | 1 GTGT, 2 b\xE1n h\xE0ng, \u2026 |\n| `from_date` | string | yes | yyyy-mm-dd |\n| `to_date` | string | yes | yyyy-mm-dd |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n### bkav_get_report_bc26 (workflow step)\n\n- Save the BC26/AC invoice usage report for a window as a workspace XML file.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `from_date` | string | yes | yyyy-mm-dd |\n| `to_date` | string | yes | yyyy-mm-dd |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n### bkav_get_tax_status (workflow step)\n\n- Read the tax authority\'s status for an invoice and its m\xE3 c\u1EE7a CQT once granted.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `statuses` | object[] | yes | |\n| `statuses[].BkavStatus` | number | yes | InvoiceStatusID: 1 m\u1EDBi t\u1EA1o, 2 \u0111\xE3 ph\xE1t h\xE0nh, 3 \u0111\xE3 hu\u1EF7, \u2026 |\n| `statuses[].TaxStatus` | number | yes | 32 waiting, 33 accepted, 34\u201339 returned or failed |\n| `statuses[].TaxAuthorityCode` | string \\\\| null | yes | M\xE3 c\u1EE7a C\u01A1 quan thu\u1EBF, once granted |\n| `statuses[].ErrorContent` | string \\\\| null | yes | |\n\n### bkav_list_invoices_by_date (workflow step)\n\n- List invoices dated within a window, one page at a time.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `from_date` | string | yes | yyyy-mm-dd |\n| `to_date` | string | yes | yyyy-mm-dd |\n| `page` | number | | 1-based |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `invoices` | object[] | yes | |\n\n### bkav_list_invoices_by_number (workflow step)\n\n- List invoices of one m\u1EABu s\u1ED1 and k\xFD hi\u1EC7u by number range.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `form` | string | yes | M\u1EABu s\u1ED1 |\n| `serial` | string | yes | K\xFD hi\u1EC7u |\n| `from_number` | number | yes | |\n| `to_number` | number | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `invoices` | object[] | yes | |\n\n### bkav_lookup_company (workflow step)\n\n- Look up a company in the tax registry by M\xE3 s\u1ED1 thu\u1EBF, through the Bkav account.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `tax_code` | string | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `company` | object | yes | |\n| `company.MaSoThue` | string | yes | |\n| `company.TenChinhThuc` | string | yes | |\n| `company.DiaChiGiaoDichChinh` | string | yes | |\n| `company.DiaChiGiaoDichPhu` | string | yes | |\n| `company.TrangThaiHoatDong` | string | yes | |\n| `company.ChuDoanhNghiep` | string | | |\n| `company.SoDienThoai` | string \\\\| null | | |\n| `company.LastUpdate` | string | | |\n\n### bkav_send_lookup_email (workflow step)\n\n- Send an invoice\'s lookup email to the buyer again, or to another email or phone.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string | yes | |\n| `email` | string | | |\n| `mobile` | string | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `sent` | true | yes | |\n\n### bkav_sign_invoices (workflow step)\n\n- Sign \u2014 issue \u2014 invoices with the account\'s HSM signature, making them tax-registered documents.\n- An account that signs with a USB token cannot sign this way.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guids` | string[] | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `signed` | string[] | yes | |\n\n### bkav_submit_invoices (workflow step)\n\n- Create, replace or adjust invoices on Bkav, in Bkav\'s field names.\n- Each carries PartnerInvoiceStringID, your own id for it, which Bkav uses to refuse a duplicate.\n- Attachments are not accepted here.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `kind` | "create_draft" \\\\| "create" \\\\| "create_draft_own_serial" \\\\| "create_own_number" \\\\| "create_own_serial" \\\\| "replace_draft" \\\\| "adjust_draft" \\\\| "adjust_discount_draft" \\\\| "replace" \\\\| "adjust" \\\\| "adjust_external_draft" \\\\| "adjust_discount" \\\\| "adjust_external" \\\\| "replace_external" \\\\| "replace_external_draft" | yes | create_draft: no number, deletable. create: Bkav numbers it. *_own_*: your form/serial. replace_* / adjust_*: each invoice names its original in Invoice.OriginalInvoiceIdentify and gives Invoice.Reason. *_external*: corrects an invoice issued outside Bkav; its first line is an ItemTypeID 4 description of it. *_draft kinds stay unnumbered. |\n| `invoices` | object[] | yes | |\n| `invoices[].Invoice` | object | yes | |\n| `invoices[].Invoice.InvoiceTypeID` | number | yes | 1 GTGT, 2 b\xE1n h\xE0ng, 5 PXK ki\xEAm VCNB, 6 PXK g\u1EEDi b\xE1n \u0111\u1EA1i l\xFD |\n| `invoices[].Invoice.InvoiceDate` | string | yes | ISO date |\n| `invoices[].Invoice.BuyerCode` | string | | |\n| `invoices[].Invoice.BuyerName` | string | | |\n| `invoices[].Invoice.BuyerTaxCode` | string | | |\n| `invoices[].Invoice.BuyerUnitName` | string | | |\n| `invoices[].Invoice.BuyerAddress` | string | | |\n| `invoices[].Invoice.BuyerBankAccount` | string | | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.PayMethodID` | number | | 1 TM, 2 CK, 3 TM/CK, \u2026 |\n| `invoices[].Invoice.ReceiveTypeID` | number | | 1 email, 2 SMS, 3 both, 4 courier |\n| `invoices[].Invoice.ReceiverEmail` | string | | |\n| `invoices[].Invoice.ReceiverMobile` | string | | |\n| `invoices[].Invoice.ReceiverAddress` | string | | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.ReceiverName` | string | | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.Note` | string | | |\n| `invoices[].Invoice.BillCode` | string | | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.CurrencyID` | string | | |\n| `invoices[].Invoice.ExchangeRate` | number | | |\n| `invoices[].Invoice.InvoiceForm` | string | | M\u1EABu s\u1ED1 |\n| `invoices[].Invoice.InvoiceSerial` | string | | K\xFD hi\u1EC7u |\n| `invoices[].Invoice.InvoiceNo` | number | | S\u1ED1; 0 when Bkav assigns it |\n| `invoices[].Invoice.MaCuaCQT` | string | | Set only by a cash-register flow that already holds the authority\'s code |\n| `invoices[].Invoice.UserDefine` | string | | JSON-encoded template fields agreed with Bkav |\n| `invoices[].Invoice.UIDefine` | string | | JSON-encoded delivery-note fields (InvoiceTypeID 5 and 6) |\n| `invoices[].Invoice.isBTH` | boolean | | |\n| `invoices[].Invoice.CCCD` | string | | |\n| `invoices[].Invoice.PassportNumber` | string | | |\n| `invoices[].Invoice.FiscalCodes` | string | | |\n| `invoices[].Invoice.Reason` | string | | Why \u2014 required on a replacement or adjustment |\n| `invoices[].Invoice.OriginalInvoiceIdentify` | string | | `[m\u1EABu s\u1ED1]_[k\xFD hi\u1EC7u]_[s\u1ED1]` of the invoice a replacement or adjustment corrects |\n| `invoices[].Invoice.InvoiceGUID` | string | | Addresses the invoice for an update by guid |\n| `invoices[].ListInvoiceDetailsWS` | object[] | yes | |\n| `invoices[].ListInvoiceDetailsWS[].ItemTypeID` | number | | 0 goods, 4 description line, 15 promotional goods, \u2026 |\n| `invoices[].ListInvoiceDetailsWS[].IsDiscount` | boolean | | |\n| `invoices[].ListInvoiceDetailsWS[].ItemCode` | string | | |\n| `invoices[].ListInvoiceDetailsWS[].ItemName` | string | yes | |\n| `invoices[].ListInvoiceDetailsWS[].UnitName` | string | | |\n| `invoices[].ListInvoiceDetailsWS[].Qty` | number | | |\n| `invoices[].ListInvoiceDetailsWS[].Price` | number | | |\n| `invoices[].ListInvoiceDetailsWS[].Amount` | number | | |\n| `invoices[].ListInvoiceDetailsWS[].TaxRateID` | number | | 1 0%, 2 5%, 3 10%, 4 kh\xF4ng ch\u1ECBu thu\u1EBF, 9 8%, \u2026 |\n| `invoices[].ListInvoiceDetailsWS[].TaxRate` | number | | |\n| `invoices[].ListInvoiceDetailsWS[].TaxAmount` | number | | |\n| `invoices[].ListInvoiceDetailsWS[].OtherAmount` | number | | |\n| `invoices[].ListInvoiceDetailsWS[].DiscountRate` | number | | |\n| `invoices[].ListInvoiceDetailsWS[].DiscountAmount` | number | | |\n| `invoices[].ListInvoiceDetailsWS[].UserDefineDetails` | string | | |\n| `invoices[].ListInvoiceDetailsWS[].IsIncrease` | boolean \\\\| null | | On an adjustment: true raises the amount, false lowers it, absent adjusts information |\n| `invoices[].ListInvoiceDetailsWS[].SpecialtyItems` | string | | |\n| `invoices[].PartnerInvoiceStringID` | string | yes | |\n| `invoices[].AttachListNumber` | string | | S\u1ED1 of a b\u1EA3ng k\xEA the invoice refers to |\n| `invoices[].AttachListDate` | string | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes | |\n| `results[].PartnerInvoiceID` | number | yes | |\n| `results[].PartnerInvoiceStringID` | string \\\\| null | yes | Null on a delete\'s answer |\n| `results[].InvoiceGUID` | string | yes | |\n| `results[].InvoiceForm` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceSerial` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |\n| `results[].MTC` | string \\\\| null | yes | M\xE3 tra c\u1EE9u the buyer looks the invoice up with; null on a draft\'s link answer |\n| `results[].MaCuaCQT` | string \\\\| null | | |\n| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |\n| `results[].MessLog` | string | yes | |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_update_invoices (workflow step)\n\n- Change invoices not yet issued. by names how each invoice is found: partner (its partner id), number (Invoice.InvoiceForm + InvoiceSerial + InvoiceNo) or guid (Invoice.InvoiceGUID).\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `by` | "partner" \\\\| "number" \\\\| "guid" | yes | |\n| `invoices` | object[] | yes | |\n| `invoices[].Invoice` | object | yes | |\n| `invoices[].Invoice.InvoiceTypeID` | number | yes | 1 GTGT, 2 b\xE1n h\xE0ng, 5 PXK ki\xEAm VCNB, 6 PXK g\u1EEDi b\xE1n \u0111\u1EA1i l\xFD |\n| `invoices[].Invoice.InvoiceDate` | string | yes | ISO date |\n| `invoices[].Invoice.BuyerCode` | string | | |\n| `invoices[].Invoice.BuyerName` | string | | |\n| `invoices[].Invoice.BuyerTaxCode` | string | | |\n| `invoices[].Invoice.BuyerUnitName` | string | | |\n| `invoices[].Invoice.BuyerAddress` | string | | |\n| `invoices[].Invoice.BuyerBankAccount` | string | | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.PayMethodID` | number | | 1 TM, 2 CK, 3 TM/CK, \u2026 |\n| `invoices[].Invoice.ReceiveTypeID` | number | | 1 email, 2 SMS, 3 both, 4 courier |\n| `invoices[].Invoice.ReceiverEmail` | string | | |\n| `invoices[].Invoice.ReceiverMobile` | string | | |\n| `invoices[].Invoice.ReceiverAddress` | string | | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.ReceiverName` | string | | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.Note` | string | | |\n| `invoices[].Invoice.BillCode` | string | | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.CurrencyID` | string | | |\n| `invoices[].Invoice.ExchangeRate` | number | | |\n| `invoices[].Invoice.InvoiceForm` | string | | M\u1EABu s\u1ED1 |\n| `invoices[].Invoice.InvoiceSerial` | string | | K\xFD hi\u1EC7u |\n| `invoices[].Invoice.InvoiceNo` | number | | S\u1ED1; 0 when Bkav assigns it |\n| `invoices[].Invoice.MaCuaCQT` | string | | Set only by a cash-register flow that already holds the authority\'s code |\n| `invoices[].Invoice.UserDefine` | string | | JSON-encoded template fields agreed with Bkav |\n| `invoices[].Invoice.UIDefine` | string | | JSON-encoded delivery-note fields (InvoiceTypeID 5 and 6) |\n| `invoices[].Invoice.isBTH` | boolean | | |\n| `invoices[].Invoice.CCCD` | string | | |\n| `invoices[].Invoice.PassportNumber` | string | | |\n| `invoices[].Invoice.FiscalCodes` | string | | |\n| `invoices[].Invoice.Reason` | string | | Why \u2014 required on a replacement or adjustment |\n| `invoices[].Invoice.OriginalInvoiceIdentify` | string | | `[m\u1EABu s\u1ED1]_[k\xFD hi\u1EC7u]_[s\u1ED1]` of the invoice a replacement or adjustment corrects |\n| `invoices[].Invoice.InvoiceGUID` | string | | Addresses the invoice for an update by guid |\n| `invoices[].ListInvoiceDetailsWS` | object[] | yes | |\n| `invoices[].ListInvoiceDetailsWS[].ItemTypeID` | number | | 0 goods, 4 description line, 15 promotional goods, \u2026 |\n| `invoices[].ListInvoiceDetailsWS[].IsDiscount` | boolean | | |\n| `invoices[].ListInvoiceDetailsWS[].ItemCode` | string | | |\n| `invoices[].ListInvoiceDetailsWS[].ItemName` | string | yes | |\n| `invoices[].ListInvoiceDetailsWS[].UnitName` | string | | |\n| `invoices[].ListInvoiceDetailsWS[].Qty` | number | | |\n| `invoices[].ListInvoiceDetailsWS[].Price` | number | | |\n| `invoices[].ListInvoiceDetailsWS[].Amount` | number | | |\n| `invoices[].ListInvoiceDetailsWS[].TaxRateID` | number | | 1 0%, 2 5%, 3 10%, 4 kh\xF4ng ch\u1ECBu thu\u1EBF, 9 8%, \u2026 |\n| `invoices[].ListInvoiceDetailsWS[].TaxRate` | number | | |\n| `invoices[].ListInvoiceDetailsWS[].TaxAmount` | number | | |\n| `invoices[].ListInvoiceDetailsWS[].OtherAmount` | number | | |\n| `invoices[].ListInvoiceDetailsWS[].DiscountRate` | number | | |\n| `invoices[].ListInvoiceDetailsWS[].DiscountAmount` | number | | |\n| `invoices[].ListInvoiceDetailsWS[].UserDefineDetails` | string | | |\n| `invoices[].ListInvoiceDetailsWS[].IsIncrease` | boolean \\\\| null | | On an adjustment: true raises the amount, false lowers it, absent adjusts information |\n| `invoices[].ListInvoiceDetailsWS[].SpecialtyItems` | string | | |\n| `invoices[].PartnerInvoiceStringID` | string | yes | |\n| `invoices[].AttachListNumber` | string | | S\u1ED1 of a b\u1EA3ng k\xEA the invoice refers to |\n| `invoices[].AttachListDate` | string | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes | |\n| `results[].PartnerInvoiceID` | number | yes | |\n| `results[].PartnerInvoiceStringID` | string \\\\| null | yes | Null on a delete\'s answer |\n| `results[].InvoiceGUID` | string | yes | |\n| `results[].InvoiceForm` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceSerial` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |\n| `results[].MTC` | string \\\\| null | yes | M\xE3 tra c\u1EE9u the buyer looks the invoice up with; null on a draft\'s link answer |\n| `results[].MaCuaCQT` | string \\\\| null | | |\n| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |\n| `results[].MessLog` | string | yes | |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n## delete\n\n### delete_file (workflow step)\n\n- Soft-delete a file by its file_id \u2014 archives it (never a hard delete).\n- Deleting an original file deletes every version of it; a file\'s current version cannot be deleted on its own.\n- Refuses while the file or a version it takes along is still referenced by a record, comment, knowledge doc, document template, voice session, or pending change request, and names the referents so you can detach them first.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `id` | string | yes | |\n| `filename` | string | yes | |\n| `archived` | boolean | yes | |\n\n## drive\n\n### drive_export_file (workflow step)\n\n- Upload a Lotics file to the member\'s Google Drive.\n- The file is uploaded as-is \u2014 a .docx stays a .docx, a .xlsx stays a .xlsx.\n- It is deliberately NOT converted into a Google Doc or Sheet: conversion re-flows the layout of a generated document, and a native Google file is live, so its figures would drift away from the record they came from.\n- Use this to archive a finished document, the way you would attach it to an email.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | The ID of the connected Google Drive account to use |\n| `file_id` | string | yes | Lotics file ID to upload |\n| `folder_id` | string | | Drive folder ID to place the file in; omit for the member\'s Drive root |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `drive_file_id` | string | yes | Drive file ID of the uploaded copy |\n| `web_view_link` | string \\\\| null | yes | URL to open the uploaded file in Drive |\n\n### drive_import_file (workflow step)\n\n- Import a Google Drive file into the workspace as a Lotics file, and return its file id.\n- Google Docs arrive as .docx, Sheets as .xlsx, Slides as .pptx; everything else transfers unchanged. **This is also how you READ a Drive file.** There is no separate Drive read tool: import the file, then use `view_files` on the returned id. (chat, MCP, CLI)\n- That path handles scanned documents \u2014 a photographed B/L or a stamped invoice inside a .docx reaches the model as a picture.\n- Exporting Drive content as plain text would return an empty document for exactly those files.\n- Folders, Forms, shortcuts and other Drive items with no file form cannot be imported.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | The ID of the connected Google Drive account to use |\n| `file_id` | string | yes | Drive file ID, from drive_query_files (workflow step, chat) |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `id` | string | yes | Lotics file ID \u2014 pass this to view_files to read the contents (chat, MCP, CLI) |\n| `filename` | string | yes | |\n| `mime_type` | string | yes | |\n| `url` | string | yes | |\n\n### drive_query_files (workflow step)\n\n- Search the member\'s Google Drive using Drive query syntax. ## Query syntax Terms are `field operator value`; combine with `and` / `or` / `not`.\n- String values are single-quoted. - Name: `name = \'Rate card\'`, `name contains \'invoice\'` - Full text (body + title): `fullText contains \'CMA CGM\'` - Type: `mimeType = \'application/vnd.google-apps.spreadsheet\'`, `mimeType contains \'pdf\'` - Folder: `\'<folder_id>\' in parents` - Time (RFC 3339): `modifiedTime > \'2026-01-01T00:00:00\'` - Exclude deleted: `trashed = false` (always worth adding) - Starred / shared: `starred = true`, `sharedWithMe = true` Google-native types: `application/vnd.google-apps.document` (Docs), `.spreadsheet` (Sheets), `.presentation` (Slides), `.folder`.\n- Examples: - `name contains \'packing list\' and trashed = false` - `\'1a2b3c\' in parents and modifiedTime > \'2026-08-01T00:00:00\'` - `fullText contains \'demurrage\' and mimeType = \'application/vnd.google-apps.document\'` Results carry enough metadata (name, type, modified time, size, owner) to pick a file WITHOUT importing it.\n- Import only the one you actually need \u2014 `drive_import_file` persists a copy in the workspace. (workflow step, chat)\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | The ID of the connected Google Drive account to use |\n| `query` | string | yes | Drive query syntax expression |\n| `max_result` | number | yes | Maximum number of files to retrieve (1-50) |\n| `order_by` | string | | Sort order, e.g. \'modifiedTime desc\', \'name\' |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `files` | object[] | yes | List of matching Drive files |\n| `files[].id` | string | yes | Drive file ID \u2014 pass this to drive_import_file (workflow step, chat) |\n| `files[].name` | string | yes | File name as it appears in Drive |\n| `files[].mime_type` | string | yes | Drive MIME type; \'application/vnd.google-apps.*\' means Google-native |\n| `files[].modified_time` | string \\\\| null | yes | RFC 3339 timestamp of the last modification |\n| `files[].size_bytes` | number \\\\| null | yes | Size in bytes; null for Google-native files, which have no stored size until exported |\n| `files[].owner` | string \\\\| null | yes | Email address of the file\'s owner |\n| `files[].web_view_link` | string \\\\| null | yes | URL to open the file in Drive |\n\n## easyinvoice\n\n### easyinvoice_attach_ikey (workflow step)\n\n- Give an invoice numbered on EasyInvoice\'s own site an ikey, so the other EasyInvoice tools can name it.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | EasyInvoice connected account |\n| `pattern` | string | | The invoice symbol, e.g. 1C26TAA (Th\xF4ng t\u01B0 78 puts the whole symbol here and leaves serial empty); needed when the account issues under more than one |\n| `serial` | string | | K\xFD hi\u1EC7u of a Th\xF4ng t\u01B0 32 range |\n| `no` | string | yes | The invoice\'s number |\n| `ikey` | string | yes | A new key of your own, at most 50 characters |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `ikey` | string | yes | |\n| `no` | string | yes | |\n\n### easyinvoice_cancel_invoice (workflow step)\n\n- Cancel an issued invoice.\n- Under Ngh\u1ECB \u0111\u1ECBnh 70 EasyInvoice may refuse, or issue a 0-\u0111\u1ED3ng replacement in its place and return it in Invoices.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | EasyInvoice connected account |\n| `pattern` | string | | The invoice symbol, e.g. 1C26TAA (Th\xF4ng t\u01B0 78 puts the whole symbol here and leaves serial empty); needed when the account issues under more than one |\n| `serial` | string | | K\xFD hi\u1EC7u of a Th\xF4ng t\u01B0 32 range |\n| `ikey` | string | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `Pattern` | string \\\\| null | yes | |\n| `Serial` | string \\\\| null | yes | |\n| `Invoices` | object[] | yes | |\n| `Invoices[].Ikey` | string \\\\| null | yes | |\n| `Invoices[].Pattern` | string \\\\| null | yes | |\n| `Invoices[].Serial` | string \\\\| null | yes | |\n| `Invoices[].No` | string \\\\| null | yes | The invoice number; empty until issued |\n| `Invoices[].InvoiceStatus` | number \\\\| null | yes | -1 reserved, 0 unsigned, 1 signed, 2 tax-declared, 3 replaced, 4 adjusted, 5 cancelled, 6 approved |\n| `Invoices[].TCTCheckStatus` | number \\\\| null | yes | Tax authority: null not sent, 0 not processed, -1 checking, 1 valid, -2 invalid |\n| `Invoices[].TCTErrorMessage` | string \\\\| null | yes | |\n| `Invoices[].TaxAuthorityCode` | string \\\\| null | yes | M\xE3 c\u1EE7a c\u01A1 quan thu\u1EBF, a few minutes after issuing |\n| `Invoices[].LookupCode` | string \\\\| null | yes | M\xE3 tra c\u1EE9u, which the buyer looks the invoice up by |\n| `Invoices[].LinkView` | string \\\\| null | yes | |\n| `Invoices[].ArisingDate` | string \\\\| null | yes | dd/MM/yyyy |\n| `Invoices[].IssueDate` | string \\\\| null | yes | dd/MM/yyyy |\n| `Invoices[].Buyer` | string \\\\| null | yes | |\n| `Invoices[].CustomerName` | string \\\\| null | yes | |\n| `Invoices[].CustomerCode` | string \\\\| null | yes | |\n| `Invoices[].CustomerTaxCode` | string \\\\| null | yes | |\n| `Invoices[].Total` | number \\\\| null | yes | |\n| `Invoices[].TaxAmount` | number \\\\| null | yes | |\n| `Invoices[].Amount` | number \\\\| null | yes | |\n\n### easyinvoice_convert_invoice (workflow step)\n\n- Convert an issued invoice to paper (b\u1EA3n chuy\u1EC3n \u0111\u1ED5i), to prove where goods came from or to archive, and save the PDF as a workspace file.\n- The invoice is named by ikey or by its lookup code.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | EasyInvoice connected account |\n| `purpose` | "proof_of_origin" \\\\| "archive" | yes | |\n| `ikey` | string | | |\n| `lookup_code` | string | | M\xE3 tra c\u1EE9u |\n| `pattern` | string | | The invoice symbol, e.g. 1C26TAA |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n### easyinvoice_correct_invoice (workflow step)\n\n- Adjust or replace one issued invoice with a new invoice, in EasyInvoice\'s field names.\n- The new invoice\'s totals and amount in words are summed from its lines.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | EasyInvoice connected account |\n| `kind` | "adjust" \\\\| "replace" \\\\| "adjust_draft" \\\\| "replace_draft" | yes | adjust, replace: created and signed at once. adjust_draft, replace_draft: created unsigned, issued later by easyinvoice_issue_invoices. (workflow step, chat) |\n| `pattern` | string | | The invoice symbol, e.g. 1C26TAA (Th\xF4ng t\u01B0 78 puts the whole symbol here and leaves serial empty); needed when the account issues under more than one |\n| `serial` | string | | K\xFD hi\u1EC7u of a Th\xF4ng t\u01B0 32 range |\n| `original_ikey` | string | | Ikey of the invoice corrected |\n| `related_invoice` | object | | An original issued outside EasyInvoice, in place of original_ikey (adjust and replace only) |\n| `related_invoice.Pattern` | string | yes | |\n| `related_invoice.Serial` | string | yes | |\n| `related_invoice.No` | string | yes | |\n| `related_invoice.ArisingDate` | string | yes | The original\'s date, YYYY-MM-DD |\n| `related_invoice.RelatedType` | number | yes | 1 a Th\xF4ng t\u01B0 78 e-invoice; 3 a Th\xF4ng t\u01B0 32 or paper invoice |\n| `invoice` | object | yes | The new invoice; its Ikey is a new key of your own |\n| `invoice.Ikey` | string | yes | Your own key for this invoice, at most 50 characters; every later call names the invoice by it |\n| `invoice.ArisingDate` | string | yes | Invoice date, YYYY-MM-DD |\n| `invoice.PaymentMethod` | string | yes | Ti\u1EC1n m\u1EB7t, Chuy\u1EC3n kho\u1EA3n, Ti\u1EC1n m\u1EB7t/Chuy\u1EC3n kho\u1EA3n, \u0110\u1ED1i tr\u1EEB c\xF4ng n\u1EE3, Kh\xF4ng thu ti\u1EC1n, or other words printed as given |\n| `invoice.CurrencyUnit` | string | yes | VND, USD, EUR, \u2026 |\n| `invoice.ExchangeRate` | number | | Required unless VND |\n| `invoice.VATRate` | number | yes | 0, 5, 8, 10; -1 not taxable; -2 not declared; -3 another rate, stated in VATRateOther; -5 financial leasing; -6 outside the VAT law; -7 not in the taxable price |\n| `invoice.VATRateOther` | number | | |\n| `invoice.Products` | object[] | yes | |\n| `invoice.Products[].No` | number | | Printed line number; 0 prints none |\n| `invoice.Products[].Feature` | number | yes | 1 goods/service, 2 promotion, 3 commercial discount (positive, subtracted from the invoice), 4 note line, 5 special goods |\n| `invoice.Products[].Code` | string | | |\n| `invoice.Products[].ProdName` | string | yes | |\n| `invoice.Products[].BusinessProdGroupCode` | string | | Business group, e.g. 01_2 |\n| `invoice.Products[].ProdUnit` | string | | |\n| `invoice.Products[].ProdQuantity` | number | | |\n| `invoice.Products[].ProdPrice` | number | | |\n| `invoice.Products[].Discount` | number | | Line discount rate, % |\n| `invoice.Products[].DiscountAmount` | number | | |\n| `invoice.Products[].Total` | number | yes | Before VAT, after the line\'s own discount; 0 on a note line |\n| `invoice.Products[].VATRate` | number | | The invoice\'s VATRate when absent |\n| `invoice.Products[].VATRateOther` | number | | The rate when VATRate is -3 |\n| `invoice.Products[].VATAmount` | number | | Absent only on a note line |\n| `invoice.Products[].Extra` | string | | A JSON object: {"Pos":""} on a note line, the special-goods attributes on Feature 5 |\n| `invoice.CusCode` | string | | EasyInvoice files the buyer under this code, creating or updating it |\n| `invoice.Buyer` | string | | The buyer\'s personal name; this or CusName is required |\n| `invoice.CusName` | string | | The buyer company\'s name; required with CusTaxCode |\n| `invoice.CusTaxCode` | string | | |\n| `invoice.CusAddress` | string | | Required with CusTaxCode |\n| `invoice.CusEmails` | string | | Comma-separated; where the issuance notice goes |\n| `invoice.Email` | string | | |\n| `invoice.EmailCC` | string | | |\n| `invoice.CusBankName` | string | | |\n| `invoice.CusBankNo` | string | | |\n| `invoice.CusPhone` | string | | |\n| `invoice.CusIdentification` | string | | Buyer\'s citizen ID, 9 or 12 characters |\n| `invoice.PassportNo` | string | | |\n| `invoice.BudgetaryRelationshipCode` | string | | |\n| `invoice.ProvinceCode` | string | | |\n| `invoice.ProvinceName` | string | | |\n| `invoice.CommuneCode` | string | | |\n| `invoice.CommuneName` | string | | |\n| `invoice.LocationCode` | string | | Required for a household or individual business, with LocationName and LocationAddress |\n| `invoice.LocationName` | string | | |\n| `invoice.LocationAddress` | string | | |\n| `invoice.StoreCode` | string | | |\n| `invoice.StoreName` | string | | |\n| `invoice.Note` | string | | |\n| `invoice.ListAttachNum` | string | | Number of the b\u1EA3ng k\xEA the invoice carries |\n| `invoice.ListAttachDate` | string | | Its date, YYYY-MM-DD |\n| `invoice.IdentityCardNumber` | string | | National-reserve sale: the buyer\'s ID when they have no tax code |\n| `invoice.TaxAuthorityCode` | string | | An invoice made from a cash register: the code it already holds |\n| `invoice.ComRelateCode` | string | | Public-asset sale: the seller\'s budget unit code |\n| `invoice.CusRelateCode` | string | | Public-asset sale: the buyer\'s budget unit code |\n| `invoice.DecisionCode` | string | | |\n| `invoice.DecisionDate` | string | | YYYY-MM-DD |\n| `invoice.DecisionAgent` | string | | |\n| `invoice.SellMethod` | string | | |\n| `invoice.TransportAddress` | string | | |\n| `invoice.TransportDateFrom` | string | | YYYY-MM-DD |\n| `invoice.TransportDateTo` | string | | YYYY-MM-DD |\n| `invoice.Extra` | string | | A JSON object of fields agreed with EasyInvoice |\n| `invoice.AdjustReplaceReasonCode` | number | yes | 1\u201314 (Th\xF4ng t\u01B0 91 \u0110i\u1EC1u 10); 13 corrects an invoice issued wrong |\n| `invoice.Type` | number | | Required on an adjustment, absent on a replacement: 2 increase, 3 decrease, 4 information only |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `Pattern` | string \\\\| null | yes | |\n| `Serial` | string \\\\| null | yes | |\n| `Invoices` | object[] | yes | |\n| `Invoices[].Ikey` | string \\\\| null | yes | |\n| `Invoices[].Pattern` | string \\\\| null | yes | |\n| `Invoices[].Serial` | string \\\\| null | yes | |\n| `Invoices[].No` | string \\\\| null | yes | The invoice number; empty until issued |\n| `Invoices[].InvoiceStatus` | number \\\\| null | yes | -1 reserved, 0 unsigned, 1 signed, 2 tax-declared, 3 replaced, 4 adjusted, 5 cancelled, 6 approved |\n| `Invoices[].TCTCheckStatus` | number \\\\| null | yes | Tax authority: null not sent, 0 not processed, -1 checking, 1 valid, -2 invalid |\n| `Invoices[].TCTErrorMessage` | string \\\\| null | yes | |\n| `Invoices[].TaxAuthorityCode` | string \\\\| null | yes | M\xE3 c\u1EE7a c\u01A1 quan thu\u1EBF, a few minutes after issuing |\n| `Invoices[].LookupCode` | string \\\\| null | yes | M\xE3 tra c\u1EE9u, which the buyer looks the invoice up by |\n| `Invoices[].LinkView` | string \\\\| null | yes | |\n| `Invoices[].ArisingDate` | string \\\\| null | yes | dd/MM/yyyy |\n| `Invoices[].IssueDate` | string \\\\| null | yes | dd/MM/yyyy |\n| `Invoices[].Buyer` | string \\\\| null | yes | |\n| `Invoices[].CustomerName` | string \\\\| null | yes | |\n| `Invoices[].CustomerCode` | string \\\\| null | yes | |\n| `Invoices[].CustomerTaxCode` | string \\\\| null | yes | |\n| `Invoices[].Total` | number \\\\| null | yes | |\n| `Invoices[].TaxAmount` | number \\\\| null | yes | |\n| `Invoices[].Amount` | number \\\\| null | yes | |\n\n### easyinvoice_create_invoices (workflow step)\n\n- Create invoices on EasyInvoice, in its own field names.\n- An Ikey that already holds a draft updates that draft.\n- Each invoice\'s totals and amount in words are summed from its lines.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | EasyInvoice connected account |\n| `kind` | "draft" \\\\| "reserved" \\\\| "issue" | yes | draft: unsigned and unnumbered, deletable, issued later by easyinvoice_issue_invoices. reserved: numbered by its InvNo from a reserved range, awaiting signature. issue: created and signed at once. (workflow step, chat) |\n| `pattern` | string | | The invoice symbol, e.g. 1C26TAA (Th\xF4ng t\u01B0 78 puts the whole symbol here and leaves serial empty); needed when the account issues under more than one |\n| `serial` | string | | K\xFD hi\u1EC7u of a Th\xF4ng t\u01B0 32 range |\n| `invoices` | object[] | yes | |\n| `invoices[].Ikey` | string | yes | Your own key for this invoice, at most 50 characters; every later call names the invoice by it |\n| `invoices[].ArisingDate` | string | yes | Invoice date, YYYY-MM-DD |\n| `invoices[].PaymentMethod` | string | yes | Ti\u1EC1n m\u1EB7t, Chuy\u1EC3n kho\u1EA3n, Ti\u1EC1n m\u1EB7t/Chuy\u1EC3n kho\u1EA3n, \u0110\u1ED1i tr\u1EEB c\xF4ng n\u1EE3, Kh\xF4ng thu ti\u1EC1n, or other words printed as given |\n| `invoices[].CurrencyUnit` | string | yes | VND, USD, EUR, \u2026 |\n| `invoices[].ExchangeRate` | number | | Required unless VND |\n| `invoices[].VATRate` | number | yes | 0, 5, 8, 10; -1 not taxable; -2 not declared; -3 another rate, stated in VATRateOther; -5 financial leasing; -6 outside the VAT law; -7 not in the taxable price |\n| `invoices[].VATRateOther` | number | | |\n| `invoices[].Products` | object[] | yes | |\n| `invoices[].Products[].No` | number | | Printed line number; 0 prints none |\n| `invoices[].Products[].Feature` | number | yes | 1 goods/service, 2 promotion, 3 commercial discount (positive, subtracted from the invoice), 4 note line, 5 special goods |\n| `invoices[].Products[].Code` | string | | |\n| `invoices[].Products[].ProdName` | string | yes | |\n| `invoices[].Products[].BusinessProdGroupCode` | string | | Business group, e.g. 01_2 |\n| `invoices[].Products[].ProdUnit` | string | | |\n| `invoices[].Products[].ProdQuantity` | number | | |\n| `invoices[].Products[].ProdPrice` | number | | |\n| `invoices[].Products[].Discount` | number | | Line discount rate, % |\n| `invoices[].Products[].DiscountAmount` | number | | |\n| `invoices[].Products[].Total` | number | yes | Before VAT, after the line\'s own discount; 0 on a note line |\n| `invoices[].Products[].VATRate` | number | | The invoice\'s VATRate when absent |\n| `invoices[].Products[].VATRateOther` | number | | The rate when VATRate is -3 |\n| `invoices[].Products[].VATAmount` | number | | Absent only on a note line |\n| `invoices[].Products[].Extra` | string | | A JSON object: {"Pos":""} on a note line, the special-goods attributes on Feature 5 |\n| `invoices[].CusCode` | string | | EasyInvoice files the buyer under this code, creating or updating it |\n| `invoices[].Buyer` | string | | The buyer\'s personal name; this or CusName is required |\n| `invoices[].CusName` | string | | The buyer company\'s name; required with CusTaxCode |\n| `invoices[].CusTaxCode` | string | | |\n| `invoices[].CusAddress` | string | | Required with CusTaxCode |\n| `invoices[].CusEmails` | string | | Comma-separated; where the issuance notice goes |\n| `invoices[].Email` | string | | |\n| `invoices[].EmailCC` | string | | |\n| `invoices[].CusBankName` | string | | |\n| `invoices[].CusBankNo` | string | | |\n| `invoices[].CusPhone` | string | | |\n| `invoices[].CusIdentification` | string | | Buyer\'s citizen ID, 9 or 12 characters |\n| `invoices[].PassportNo` | string | | |\n| `invoices[].BudgetaryRelationshipCode` | string | | |\n| `invoices[].ProvinceCode` | string | | |\n| `invoices[].ProvinceName` | string | | |\n| `invoices[].CommuneCode` | string | | |\n| `invoices[].CommuneName` | string | | |\n| `invoices[].LocationCode` | string | | Required for a household or individual business, with LocationName and LocationAddress |\n| `invoices[].LocationName` | string | | |\n| `invoices[].LocationAddress` | string | | |\n| `invoices[].StoreCode` | string | | |\n| `invoices[].StoreName` | string | | |\n| `invoices[].Note` | string | | |\n| `invoices[].ListAttachNum` | string | | Number of the b\u1EA3ng k\xEA the invoice carries |\n| `invoices[].ListAttachDate` | string | | Its date, YYYY-MM-DD |\n| `invoices[].IdentityCardNumber` | string | | National-reserve sale: the buyer\'s ID when they have no tax code |\n| `invoices[].TaxAuthorityCode` | string | | An invoice made from a cash register: the code it already holds |\n| `invoices[].ComRelateCode` | string | | Public-asset sale: the seller\'s budget unit code |\n| `invoices[].CusRelateCode` | string | | Public-asset sale: the buyer\'s budget unit code |\n| `invoices[].DecisionCode` | string | | |\n| `invoices[].DecisionDate` | string | | YYYY-MM-DD |\n| `invoices[].DecisionAgent` | string | | |\n| `invoices[].SellMethod` | string | | |\n| `invoices[].TransportAddress` | string | | |\n| `invoices[].TransportDateFrom` | string | | YYYY-MM-DD |\n| `invoices[].TransportDateTo` | string | | YYYY-MM-DD |\n| `invoices[].Extra` | string | | A JSON object of fields agreed with EasyInvoice |\n| `invoices[].InvNo` | number | | The number, from a reserved range; only on reserved invoices |\n| `invoices[].StoreAddress` | string | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `Pattern` | string \\\\| null | yes | |\n| `Serial` | string \\\\| null | yes | |\n| `Invoices` | object[] | yes | |\n| `Invoices[].Ikey` | string \\\\| null | yes | |\n| `Invoices[].Pattern` | string \\\\| null | yes | |\n| `Invoices[].Serial` | string \\\\| null | yes | |\n| `Invoices[].No` | string \\\\| null | yes | The invoice number; empty until issued |\n| `Invoices[].InvoiceStatus` | number \\\\| null | yes | -1 reserved, 0 unsigned, 1 signed, 2 tax-declared, 3 replaced, 4 adjusted, 5 cancelled, 6 approved |\n| `Invoices[].TCTCheckStatus` | number \\\\| null | yes | Tax authority: null not sent, 0 not processed, -1 checking, 1 valid, -2 invalid |\n| `Invoices[].TCTErrorMessage` | string \\\\| null | yes | |\n| `Invoices[].TaxAuthorityCode` | string \\\\| null | yes | M\xE3 c\u1EE7a c\u01A1 quan thu\u1EBF, a few minutes after issuing |\n| `Invoices[].LookupCode` | string \\\\| null | yes | M\xE3 tra c\u1EE9u, which the buyer looks the invoice up by |\n| `Invoices[].LinkView` | string \\\\| null | yes | |\n| `Invoices[].ArisingDate` | string \\\\| null | yes | dd/MM/yyyy |\n| `Invoices[].IssueDate` | string \\\\| null | yes | dd/MM/yyyy |\n| `Invoices[].Buyer` | string \\\\| null | yes | |\n| `Invoices[].CustomerName` | string \\\\| null | yes | |\n| `Invoices[].CustomerCode` | string \\\\| null | yes | |\n| `Invoices[].CustomerTaxCode` | string \\\\| null | yes | |\n| `Invoices[].Total` | number \\\\| null | yes | |\n| `Invoices[].TaxAmount` | number \\\\| null | yes | |\n| `Invoices[].Amount` | number \\\\| null | yes | |\n\n### easyinvoice_delete_draft (workflow step)\n\n- Delete an invoice that was never signed.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | EasyInvoice connected account |\n| `pattern` | string | | The invoice symbol, e.g. 1C26TAA (Th\xF4ng t\u01B0 78 puts the whole symbol here and leaves serial empty); needed when the account issues under more than one |\n| `serial` | string | | K\xFD hi\u1EC7u of a Th\xF4ng t\u01B0 32 range |\n| `ikey` | string | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `deleted_ikey` | string | yes | |\n\n### easyinvoice_get_invoice_file (workflow step)\n\n- Save an invoice\'s PDF or XML as a workspace file, the invoice named by ikey or by its lookup code.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | EasyInvoice connected account |\n| `format` | "xml" \\\\| "pdf" | yes | |\n| `ikey` | string | | |\n| `lookup_code` | string | | M\xE3 tra c\u1EE9u |\n| `pattern` | string | | The invoice symbol, e.g. 1C26TAA |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n### easyinvoice_get_invoices (workflow step)\n\n- Read invoices by their ikeys: status, number, lookup code and the tax authority\'s verdict and code.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | EasyInvoice connected account |\n| `ikeys` | string[] | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `invoices` | object[] | yes | |\n| `invoices[].Ikey` | string \\\\| null | yes | |\n| `invoices[].Pattern` | string \\\\| null | yes | |\n| `invoices[].Serial` | string \\\\| null | yes | |\n| `invoices[].No` | string \\\\| null | yes | The invoice number; empty until issued |\n| `invoices[].InvoiceStatus` | number \\\\| null | yes | -1 reserved, 0 unsigned, 1 signed, 2 tax-declared, 3 replaced, 4 adjusted, 5 cancelled, 6 approved |\n| `invoices[].TCTCheckStatus` | number \\\\| null | yes | Tax authority: null not sent, 0 not processed, -1 checking, 1 valid, -2 invalid |\n| `invoices[].TCTErrorMessage` | string \\\\| null | yes | |\n| `invoices[].TaxAuthorityCode` | string \\\\| null | yes | M\xE3 c\u1EE7a c\u01A1 quan thu\u1EBF, a few minutes after issuing |\n| `invoices[].LookupCode` | string \\\\| null | yes | M\xE3 tra c\u1EE9u, which the buyer looks the invoice up by |\n| `invoices[].LinkView` | string \\\\| null | yes | |\n| `invoices[].ArisingDate` | string \\\\| null | yes | dd/MM/yyyy |\n| `invoices[].IssueDate` | string \\\\| null | yes | dd/MM/yyyy |\n| `invoices[].Buyer` | string \\\\| null | yes | |\n| `invoices[].CustomerName` | string \\\\| null | yes | |\n| `invoices[].CustomerCode` | string \\\\| null | yes | |\n| `invoices[].CustomerTaxCode` | string \\\\| null | yes | |\n| `invoices[].Total` | number \\\\| null | yes | |\n| `invoices[].TaxAmount` | number \\\\| null | yes | |\n| `invoices[].Amount` | number \\\\| null | yes | |\n\n### easyinvoice_get_report (workflow step)\n\n- Save a period\'s invoice-usage report (BC26/AC) or listing of sales documents (b\u1EA3ng k\xEA) as a workspace file.\n- The htkk kinds are for import into HTKK.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | EasyInvoice connected account |\n| `kind` | "usage_excel" \\\\| "usage_htkk_excel" \\\\| "usage_htkk_xml" \\\\| "sales_listing_html" \\\\| "sales_listing_excel" | yes | |\n| `from_date` | string | yes | YYYY-MM-DD |\n| `to_date` | string | yes | YYYY-MM-DD |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n### easyinvoice_issue_invoices (workflow step)\n\n- Sign and issue drafts and reserved invoices, all under one symbol.\n- An issued invoice goes to the tax authority and is corrected only by adjustment or replacement.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | EasyInvoice connected account |\n| `pattern` | string | yes | The invoice symbol they share, e.g. 1C26TAA |\n| `serial` | string | | K\xFD hi\u1EC7u of a Th\xF4ng t\u01B0 32 range |\n| `ikeys` | string[] | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `Pattern` | string \\\\| null | yes | |\n| `Serial` | string \\\\| null | yes | |\n| `Invoices` | object[] | yes | |\n| `Invoices[].Ikey` | string \\\\| null | yes | |\n| `Invoices[].Pattern` | string \\\\| null | yes | |\n| `Invoices[].Serial` | string \\\\| null | yes | |\n| `Invoices[].No` | string \\\\| null | yes | The invoice number; empty until issued |\n| `Invoices[].InvoiceStatus` | number \\\\| null | yes | -1 reserved, 0 unsigned, 1 signed, 2 tax-declared, 3 replaced, 4 adjusted, 5 cancelled, 6 approved |\n| `Invoices[].TCTCheckStatus` | number \\\\| null | yes | Tax authority: null not sent, 0 not processed, -1 checking, 1 valid, -2 invalid |\n| `Invoices[].TCTErrorMessage` | string \\\\| null | yes | |\n| `Invoices[].TaxAuthorityCode` | string \\\\| null | yes | M\xE3 c\u1EE7a c\u01A1 quan thu\u1EBF, a few minutes after issuing |\n| `Invoices[].LookupCode` | string \\\\| null | yes | M\xE3 tra c\u1EE9u, which the buyer looks the invoice up by |\n| `Invoices[].LinkView` | string \\\\| null | yes | |\n| `Invoices[].ArisingDate` | string \\\\| null | yes | dd/MM/yyyy |\n| `Invoices[].IssueDate` | string \\\\| null | yes | dd/MM/yyyy |\n| `Invoices[].Buyer` | string \\\\| null | yes | |\n| `Invoices[].CustomerName` | string \\\\| null | yes | |\n| `Invoices[].CustomerCode` | string \\\\| null | yes | |\n| `Invoices[].CustomerTaxCode` | string \\\\| null | yes | |\n| `Invoices[].Total` | number \\\\| null | yes | |\n| `Invoices[].TaxAmount` | number \\\\| null | yes | |\n| `Invoices[].Amount` | number \\\\| null | yes | |\n\n### easyinvoice_list_invoices (workflow step)\n\n- List invoices dated within a window, a page at a time.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | EasyInvoice connected account |\n| `from_date` | string | yes | YYYY-MM-DD |\n| `to_date` | string | yes | YYYY-MM-DD |\n| `page` | number | | 1-based |\n| `page_size` | number | | At most 100 |\n| `pattern` | string | | Only invoices under this symbol |\n| `include_web_invoices` | boolean | | Also invoices made on EasyInvoice\'s own site, not only through this connection\'s API |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `page` | number \\\\| null | yes | |\n| `page_size` | number \\\\| null | yes | |\n| `total_records` | number \\\\| null | yes | |\n| `total_pages` | number \\\\| null | yes | |\n| `invoices` | object[] | yes | |\n| `invoices[].Ikey` | string \\\\| null | yes | |\n| `invoices[].Pattern` | string \\\\| null | yes | |\n| `invoices[].Serial` | string \\\\| null | yes | |\n| `invoices[].No` | string \\\\| null | yes | The invoice number; empty until issued |\n| `invoices[].InvoiceStatus` | number \\\\| null | yes | -1 reserved, 0 unsigned, 1 signed, 2 tax-declared, 3 replaced, 4 adjusted, 5 cancelled, 6 approved |\n| `invoices[].TCTCheckStatus` | number \\\\| null | yes | Tax authority: null not sent, 0 not processed, -1 checking, 1 valid, -2 invalid |\n| `invoices[].TCTErrorMessage` | string \\\\| null | yes | |\n| `invoices[].TaxAuthorityCode` | string \\\\| null | yes | M\xE3 c\u1EE7a c\u01A1 quan thu\u1EBF, a few minutes after issuing |\n| `invoices[].LookupCode` | string \\\\| null | yes | M\xE3 tra c\u1EE9u, which the buyer looks the invoice up by |\n| `invoices[].LinkView` | string \\\\| null | yes | |\n| `invoices[].ArisingDate` | string \\\\| null | yes | dd/MM/yyyy |\n| `invoices[].IssueDate` | string \\\\| null | yes | dd/MM/yyyy |\n| `invoices[].Buyer` | string \\\\| null | yes | |\n| `invoices[].CustomerName` | string \\\\| null | yes | |\n| `invoices[].CustomerCode` | string \\\\| null | yes | |\n| `invoices[].CustomerTaxCode` | string \\\\| null | yes | |\n| `invoices[].Total` | number \\\\| null | yes | |\n| `invoices[].TaxAmount` | number \\\\| null | yes | |\n| `invoices[].Amount` | number \\\\| null | yes | |\n\n### easyinvoice_list_reserved_numbers (workflow step)\n\n- List the numbers of a reserved range still waiting to be signed.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | EasyInvoice connected account |\n| `pattern` | string | yes | The invoice symbol, e.g. 1C26TAA |\n| `serial` | string | yes | Empty under Th\xF4ng t\u01B0 78 |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `numbers` | string[] | yes | |\n\n### easyinvoice_preview_invoice (workflow step)\n\n- Save how an invoice would print, as a PDF or HTML workspace file, before it is created.\n- Nothing is created on EasyInvoice.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | EasyInvoice connected account |\n| `kind` | "invoice" \\\\| "replacement" \\\\| "adjustment_increase" \\\\| "adjustment_decrease" \\\\| "adjustment_information" | yes | invoice: a new one. The others: a replacement or adjustment, whose invoice states its AdjustReplaceReasonCode |\n| `format` | "pdf" \\\\| "html" | yes | |\n| `pattern` | string | | The invoice symbol, e.g. 1C26TAA (Th\xF4ng t\u01B0 78 puts the whole symbol here and leaves serial empty); needed when the account issues under more than one |\n| `serial` | string | | K\xFD hi\u1EC7u of a Th\xF4ng t\u01B0 32 range |\n| `invoice` | object | yes | |\n| `invoice.Ikey` | string | yes | Your own key for this invoice, at most 50 characters; every later call names the invoice by it |\n| `invoice.ArisingDate` | string | yes | Invoice date, YYYY-MM-DD |\n| `invoice.PaymentMethod` | string | yes | Ti\u1EC1n m\u1EB7t, Chuy\u1EC3n kho\u1EA3n, Ti\u1EC1n m\u1EB7t/Chuy\u1EC3n kho\u1EA3n, \u0110\u1ED1i tr\u1EEB c\xF4ng n\u1EE3, Kh\xF4ng thu ti\u1EC1n, or other words printed as given |\n| `invoice.CurrencyUnit` | string | yes | VND, USD, EUR, \u2026 |\n| `invoice.ExchangeRate` | number | | Required unless VND |\n| `invoice.VATRate` | number | yes | 0, 5, 8, 10; -1 not taxable; -2 not declared; -3 another rate, stated in VATRateOther; -5 financial leasing; -6 outside the VAT law; -7 not in the taxable price |\n| `invoice.VATRateOther` | number | | |\n| `invoice.Products` | object[] | yes | |\n| `invoice.Products[].No` | number | | Printed line number; 0 prints none |\n| `invoice.Products[].Feature` | number | yes | 1 goods/service, 2 promotion, 3 commercial discount (positive, subtracted from the invoice), 4 note line, 5 special goods |\n| `invoice.Products[].Code` | string | | |\n| `invoice.Products[].ProdName` | string | yes | |\n| `invoice.Products[].BusinessProdGroupCode` | string | | Business group, e.g. 01_2 |\n| `invoice.Products[].ProdUnit` | string | | |\n| `invoice.Products[].ProdQuantity` | number | | |\n| `invoice.Products[].ProdPrice` | number | | |\n| `invoice.Products[].Discount` | number | | Line discount rate, % |\n| `invoice.Products[].DiscountAmount` | number | | |\n| `invoice.Products[].Total` | number | yes | Before VAT, after the line\'s own discount; 0 on a note line |\n| `invoice.Products[].VATRate` | number | | The invoice\'s VATRate when absent |\n| `invoice.Products[].VATRateOther` | number | | The rate when VATRate is -3 |\n| `invoice.Products[].VATAmount` | number | | Absent only on a note line |\n| `invoice.Products[].Extra` | string | | A JSON object: {"Pos":""} on a note line, the special-goods attributes on Feature 5 |\n| `invoice.CusCode` | string | | EasyInvoice files the buyer under this code, creating or updating it |\n| `invoice.Buyer` | string | | The buyer\'s personal name; this or CusName is required |\n| `invoice.CusName` | string | | The buyer company\'s name; required with CusTaxCode |\n| `invoice.CusTaxCode` | string | | |\n| `invoice.CusAddress` | string | | Required with CusTaxCode |\n| `invoice.CusEmails` | string | | Comma-separated; where the issuance notice goes |\n| `invoice.Email` | string | | |\n| `invoice.EmailCC` | string | | |\n| `invoice.CusBankName` | string | | |\n| `invoice.CusBankNo` | string | | |\n| `invoice.CusPhone` | string | | |\n| `invoice.CusIdentification` | string | | Buyer\'s citizen ID, 9 or 12 characters |\n| `invoice.PassportNo` | string | | |\n| `invoice.BudgetaryRelationshipCode` | string | | |\n| `invoice.ProvinceCode` | string | | |\n| `invoice.ProvinceName` | string | | |\n| `invoice.CommuneCode` | string | | |\n| `invoice.CommuneName` | string | | |\n| `invoice.LocationCode` | string | | Required for a household or individual business, with LocationName and LocationAddress |\n| `invoice.LocationName` | string | | |\n| `invoice.LocationAddress` | string | | |\n| `invoice.StoreCode` | string | | |\n| `invoice.StoreName` | string | | |\n| `invoice.Note` | string | | |\n| `invoice.ListAttachNum` | string | | Number of the b\u1EA3ng k\xEA the invoice carries |\n| `invoice.ListAttachDate` | string | | Its date, YYYY-MM-DD |\n| `invoice.IdentityCardNumber` | string | | National-reserve sale: the buyer\'s ID when they have no tax code |\n| `invoice.TaxAuthorityCode` | string | | An invoice made from a cash register: the code it already holds |\n| `invoice.ComRelateCode` | string | | Public-asset sale: the seller\'s budget unit code |\n| `invoice.CusRelateCode` | string | | Public-asset sale: the buyer\'s budget unit code |\n| `invoice.DecisionCode` | string | | |\n| `invoice.DecisionDate` | string | | YYYY-MM-DD |\n| `invoice.DecisionAgent` | string | | |\n| `invoice.SellMethod` | string | | |\n| `invoice.TransportAddress` | string | | |\n| `invoice.TransportDateFrom` | string | | YYYY-MM-DD |\n| `invoice.TransportDateTo` | string | | YYYY-MM-DD |\n| `invoice.Extra` | string | | A JSON object of fields agreed with EasyInvoice |\n| `invoice.AdjustReplaceReasonCode` | number | | 1\u201314 (Th\xF4ng t\u01B0 91 \u0110i\u1EC1u 10); 13 corrects an invoice issued wrong |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n### easyinvoice_reserve_numbers (workflow step)\n\n- Reserve invoice numbers in a range, for invoices created later with kind reserved.\n- Give quantity or ikey_dates.\n- EasyInvoice must have granted the account reserved ranges.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | EasyInvoice connected account |\n| `pattern` | string | yes | The invoice symbol, e.g. 1C26TAA |\n| `serial` | string | yes | Empty under Th\xF4ng t\u01B0 78 |\n| `quantity` | number | | |\n| `ikey_dates` | object | | Ikey \u2192 invoice date (YYYY-MM-DD): one number each |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `Pattern` | string \\\\| null | yes | |\n| `Serial` | string \\\\| null | yes | |\n| `numbers` | string[] | yes | Reserved by quantity |\n| `by_ikey` | object | yes | Reserved by ikey: ikey \u2192 number |\n\n### easyinvoice_save_customers (workflow step)\n\n- Create or update customers in EasyInvoice\'s customer list, in its own field names.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | EasyInvoice connected account |\n| `customers` | object[] | yes | |\n| `customers[].Code` | string | yes | Fixed once created |\n| `customers[].AccountName` | string | yes | The buyer\'s lookup account; fixed once created |\n| `customers[].Name` | string | yes | |\n| `customers[].Buyer` | string | | |\n| `customers[].Address` | string | | |\n| `customers[].TaxCode` | string | | Required for a company |\n| `customers[].BankName` | string | | |\n| `customers[].BankAccountName` | string | | |\n| `customers[].BankNumber` | string | | |\n| `customers[].Email` | string | | |\n| `customers[].EmailCC` | string | | Comma-separated |\n| `customers[].Fax` | string | | |\n| `customers[].Phone` | string | | |\n| `customers[].ContactPerson` | string | | |\n| `customers[].RepresentPerson` | string | | |\n| `customers[].CusType` | number | | 1 the customer keeps accounts, 0 not |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `saved` | number | yes | |\n\n### easyinvoice_save_products (workflow step)\n\n- Create or update products and services in EasyInvoice\'s product list, in its own field names.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | EasyInvoice connected account |\n| `products` | object[] | yes | |\n| `products[].Code` | string | yes | |\n| `products[].Name` | string | yes | |\n| `products[].Price` | number | | |\n| `products[].Unit` | string | | |\n| `products[].Des` | string | | |\n| `products[].VATRate` | number | yes | As on an invoice line |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `saved` | number | yes | |\n\n### easyinvoice_send_error_notice (workflow step)\n\n- File an error notice (04/SS-H\u0110\u0110T) with the tax authority for erroneous invoices, through EasyInvoice.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | EasyInvoice connected account |\n| `notice_type` | number | yes | 1 the seller\'s own notice; 2 answering a notice from the tax authority |\n| `created_date` | string | yes | YYYY-MM-DD |\n| `tax_authority_notice_no` | string | | Type 2: the tax authority\'s notice number |\n| `tax_authority_notice_date` | string | | Type 2: its date, YYYY-MM-DD |\n| `invoices` | object[] | yes | |\n| `invoices[].Pattern` | string | yes | |\n| `invoices[].Serial` | string | | |\n| `invoices[].No` | number | yes | |\n| `invoices[].ArisingDate` | string | yes | YYYY-MM-DD |\n| `invoices[].TaxAuthorityCode` | string | | Required unless the invoice carries none |\n| `invoices[].InvType` | number | yes | 1 N\u0110 123/2020 e-invoice; 2 authenticated under Q\u0110 1209/2660; 3 under N\u0110 51/2010 or 04/2014; 4 printed to order under N\u0110 123/2020 |\n| `invoices[].Note` | string | yes | The reason |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `sent` | number | yes | Invoices the notice names |\n\n### easyinvoice_send_issuance_notice (workflow step)\n\n- Send invoices\' issuance notices again, each to the address given for it.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | EasyInvoice connected account |\n| `emails` | object | yes | Ikey \u2192 email address |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object | yes | Ikey \u2192 EasyInvoice\'s answer for it, sent or refused |\n\n## evaluate\n\n### evaluate_formula (workflow step)\n\n- Compute a formula over one record as its table\'s own formula fields compute: fields referenced as `{alias}`, lookups and rollups read as the row holds them.\n- Writes nothing.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `table_id` | string | yes | |\n| `record_id` | string | yes | |\n| `expression` | string | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `value` | number \\\\| string \\\\| boolean \\\\| null | yes | |\n\n## excel\n\n### excel_get_rows (workflow step)\n\n- Read every row of a sheet in an .xlsx, .xls or .csv file as a list of objects keyed by the header row\'s text.\n- A cell is its typed value: a number, true or false, text, a date as ISO text ("2026-03-02", "2026-03-02T09:30:00", or "09:30:00" for a time alone), null when blank.\n- A formula cell is the value the file last computed; an error cell is its code as text ("#N/A").\n- Every CSV cell is text or null.\n- A header cell inside a merge takes the merge\'s text; a blank header is keyed by its column letter ("C"), and a header text that repeats gets its column letter added ("Amount (F)"). headers lists the keys in sheet order.\n- Rows above header_row and rows blank in every column are left out.\n- One call reads a sheet of at most 10000 rows, its header counted, and returns at most 250000 cells (rows \xD7 kept columns); a sheet past either is refused with its row count, never cut short.\n- Read-only.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | A stored file\'s id. A files field read in a workflow holds file objects: first(record.file).id |\n| `worksheet` | string \\\\| number | | Sheet name, or 0-based index. |\n| `header_row` | number | | 1-based row holding the headers. |\n| `columns` | string[] | | Keys to keep, as headers lists them. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | |\n| `worksheet_name` | string | yes | |\n| `header_row` | number | yes | |\n| `headers` | string[] | yes | The key of each returned column, in sheet order |\n| `row_count` | number | yes | |\n| `rows` | object[] | yes | |\n\n## facebook\n\n### facebook_create_post (workflow step)\n\n- Publish a post to a Facebook Page feed.\n- Requires a Facebook connected account whose page allows content management.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | |\n| `page_id` | string | yes | Facebook Page to post to \u2014 one of the connected account\'s managed pages. |\n| `message` | string | yes | |\n| `link` | string | | A post carries either a link or media. |\n| `media_file_ids` | string[] | | Photos, or one video on its own. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `post_id` | string | yes | |\n| `url` | string | yes | |\n\n### facebook_list_comments (workflow step)\n\n- Read the most recent comments left on a Facebook Page\'s posts.\n- Reply with facebook_reply_to_comment, passing the comment_id. (workflow step, chat)\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | |\n| `page_id` | string | yes | One of the connected account\'s managed pages. |\n| `limit` | integer | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `comments` | object[] | yes | |\n| `comments[].comment_id` | string | yes | |\n| `comments[].post_id` | string | yes | |\n| `comments[].author_id` | string | yes | |\n| `comments[].author_name` | string | yes | |\n| `comments[].message` | string | yes | |\n| `comments[].created_time` | string | yes | |\n\n### facebook_list_conversations (workflow step)\n\n- Read a Facebook Page\'s Messenger conversations with their recent messages.\n- Answer someone with facebook_send_message, passing the person_id. (workflow step, chat)\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | |\n| `page_id` | string | yes | One of the connected account\'s managed pages. |\n| `limit` | integer | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `conversations` | object[] | yes | |\n| `conversations[].conversation_id` | string | yes | |\n| `conversations[].person_id` | string \\\\| null | yes | |\n| `conversations[].person_name` | string \\\\| null | yes | |\n| `conversations[].messages` | object[] | yes | |\n| `conversations[].messages[].from_id` | string | yes | |\n| `conversations[].messages[].from_name` | string | yes | |\n| `conversations[].messages[].message` | string | yes | |\n| `conversations[].messages[].created_time` | string | yes | |\n\n### facebook_reply_to_comment (workflow step)\n\n- Reply publicly to a comment on a Facebook Page post, as the page.\n- The reply is visible to everyone who can see the comment.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | |\n| `page_id` | string | yes | The page that owns the post the comment is on. |\n| `comment_id` | string | yes | From facebook_list_comments. (workflow step, chat) |\n| `message` | string | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `comment_id` | string | yes | The reply\'s own id. |\n\n### facebook_send_message (workflow step)\n\n- Answer someone who messaged a Facebook Page, as the page.\n- Meta accepts a reply only within 24 hours of that person\'s last message.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | |\n| `page_id` | string | yes | The page the person wrote to. |\n| `person_id` | string | yes | From facebook_list_conversations. Page-scoped to this page. (workflow step, chat) |\n| `message` | string | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `message_id` | string | yes | |\n\n## fedex\n\n### fedex_cancel_draft (workflow step)\n\n- Cancel (delete) an unconfirmed FedEx draft (Open Ship) booking by its reference.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | FedEx connected account |\n| `reference` | string | yes | The draft\'s reference (Open Ship index) |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `cancelled` | boolean | yes | |\n\n### fedex_confirm_shipment (workflow step)\n\n- Confirm a FedEx draft (Open Ship) booking by its reference, generating the label / AWB.\n- Returns the master tracking number and any piece tracking numbers + label URLs.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | FedEx connected account |\n| `reference` | string | yes | The draft\'s reference (Open Ship index) from fedex_create_draft_shipment (workflow step, chat) |\n| `master_tracking_number` | string | | The master_tracking_number returned by fedex_create_draft_shipment \u2014 required to finalize the label (workflow step, chat) |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `master_tracking_number` | string | | |\n| `tracking_numbers` | string[] | yes | |\n| `label_urls` | string[] | yes | |\n\n### fedex_create_draft_shipment (workflow step)\n\n- Create a FedEx draft (Open Ship) booking \u2014 no label yet.\n- Confirm later with fedex_confirm_shipment. reference is a unique key you choose (e.g. the shipment order number) used to confirm or cancel. (workflow step, chat)\n- Supports multiple packages, special services, and (international) customs commodities.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | FedEx connected account |\n| `reference` | string | yes | Unique key for this draft (the Open Ship index) |\n| `shipper` | object | yes | |\n| `shipper.contact` | object | | |\n| `shipper.contact.person_name` | string | | |\n| `shipper.contact.company_name` | string | | |\n| `shipper.contact.phone_number` | string | | |\n| `shipper.address` | object | yes | |\n| `shipper.address.postal_code` | string | yes | |\n| `shipper.address.country_code` | string | yes | ISO 3166-1 alpha-2 country code, e.g. VN, US, SG |\n| `shipper.address.city` | string | | |\n| `shipper.address.state_or_province_code` | string | | |\n| `shipper.address.street_lines` | string[] | | |\n| `shipper.address.residential` | boolean | | |\n| `recipient` | object | yes | |\n| `recipient.contact` | object | | |\n| `recipient.contact.person_name` | string | | |\n| `recipient.contact.company_name` | string | | |\n| `recipient.contact.phone_number` | string | | |\n| `recipient.address` | object | yes | |\n| `recipient.address.postal_code` | string | yes | |\n| `recipient.address.country_code` | string | yes | ISO 3166-1 alpha-2 country code, e.g. VN, US, SG |\n| `recipient.address.city` | string | | |\n| `recipient.address.state_or_province_code` | string | | |\n| `recipient.address.street_lines` | string[] | | |\n| `recipient.address.residential` | boolean | | |\n| `service_type` | string | yes | FedEx service type e.g. INTERNATIONAL_PRIORITY |\n| `packaging_type` | string | | FedEx packaging type e.g. YOUR_PACKAGING |\n| `packages` | object[] | yes | One entry per package; weight in kg |\n| `packages[].weight` | number | yes | |\n| `packages[].weight_units` | "KG" \\\\| "LB" | | Weight units; FedEx requires LB for US domestic express |\n| `packages[].length` | number | | |\n| `packages[].width` | number | | |\n| `packages[].height` | number | | |\n| `packages[].dimension_units` | "CM" \\\\| "IN" | | |\n| `ship_datestamp` | string | | Ship date YYYY-MM-DD |\n| `pickup_type` | string | | FedEx pickup type e.g. USE_SCHEDULED_PICKUP |\n| `special_services` | string[] | | FedEx special service types e.g. SATURDAY_DELIVERY, FEDEX_ONE_RATE |\n| `commodities` | object[] | | Customs commodities for international shipments |\n| `commodities[].description` | string | yes | |\n| `commodities[].quantity` | number | yes | |\n| `commodities[].customs_value` | number | yes | |\n| `commodities[].currency` | string | yes | |\n| `commodities[].weight` | number | yes | |\n| `commodities[].weight_units` | "KG" \\\\| "LB" | | |\n| `commodities[].country_of_manufacture` | string | | ISO 3166-1 alpha-2 |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `reference` | string | yes | |\n| `status` | "draft" | yes | |\n| `master_tracking_number` | string | | Pass this to fedex_confirm_shipment to finalize the draft (workflow step, chat) |\n\n### fedex_create_shipment (workflow step)\n\n- Create a FedEx shipment and generate the label / AWB in one call.\n- Returns the master tracking number, piece tracking numbers, and label URLs.\n- Use the Open Ship draft flow instead when you need to stage a booking before committing.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | FedEx connected account |\n| `shipper` | object | yes | |\n| `shipper.contact` | object | | |\n| `shipper.contact.person_name` | string | | |\n| `shipper.contact.company_name` | string | | |\n| `shipper.contact.phone_number` | string | | |\n| `shipper.address` | object | yes | |\n| `shipper.address.postal_code` | string | yes | |\n| `shipper.address.country_code` | string | yes | ISO 3166-1 alpha-2 country code, e.g. VN, US, SG |\n| `shipper.address.city` | string | | |\n| `shipper.address.state_or_province_code` | string | | |\n| `shipper.address.street_lines` | string[] | | |\n| `shipper.address.residential` | boolean | | |\n| `recipient` | object | yes | |\n| `recipient.contact` | object | | |\n| `recipient.contact.person_name` | string | | |\n| `recipient.contact.company_name` | string | | |\n| `recipient.contact.phone_number` | string | | |\n| `recipient.address` | object | yes | |\n| `recipient.address.postal_code` | string | yes | |\n| `recipient.address.country_code` | string | yes | ISO 3166-1 alpha-2 country code, e.g. VN, US, SG |\n| `recipient.address.city` | string | | |\n| `recipient.address.state_or_province_code` | string | | |\n| `recipient.address.street_lines` | string[] | | |\n| `recipient.address.residential` | boolean | | |\n| `service_type` | string | yes | FedEx service type e.g. INTERNATIONAL_PRIORITY |\n| `packaging_type` | string | | FedEx packaging type e.g. YOUR_PACKAGING |\n| `packages` | object[] | yes | One entry per package; weight in kg |\n| `packages[].weight` | number | yes | |\n| `packages[].weight_units` | "KG" \\\\| "LB" | | Weight units; FedEx requires LB for US domestic express |\n| `packages[].length` | number | | |\n| `packages[].width` | number | | |\n| `packages[].height` | number | | |\n| `packages[].dimension_units` | "CM" \\\\| "IN" | | |\n| `ship_datestamp` | string | | Ship date YYYY-MM-DD |\n| `pickup_type` | string | | FedEx pickup type e.g. USE_SCHEDULED_PICKUP |\n| `special_services` | string[] | | FedEx special service types |\n| `commodities` | object[] | | Customs commodities for international shipments |\n| `commodities[].description` | string | yes | |\n| `commodities[].quantity` | number | yes | |\n| `commodities[].customs_value` | number | yes | |\n| `commodities[].currency` | string | yes | |\n| `commodities[].weight` | number | yes | |\n| `commodities[].weight_units` | "KG" \\\\| "LB" | | |\n| `commodities[].country_of_manufacture` | string | | ISO 3166-1 alpha-2 |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `master_tracking_number` | string | | |\n| `tracking_numbers` | string[] | yes | |\n| `label_urls` | string[] | yes | |\n\n### fedex_rate (workflow step)\n\n- Get FedEx rate quotes for a shipment.\n- Returns one priced row per available service (or just the requested service_type).\n- Use before booking to compare costs.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | FedEx connected account |\n| `shipper` | object | yes | |\n| `shipper.postal_code` | string | yes | |\n| `shipper.country_code` | string | yes | ISO 3166-1 alpha-2 country code, e.g. VN, US, SG |\n| `shipper.city` | string | | |\n| `shipper.state_or_province_code` | string | | |\n| `shipper.street_lines` | string[] | | |\n| `shipper.residential` | boolean | | |\n| `recipient` | object | yes | |\n| `recipient.postal_code` | string | yes | |\n| `recipient.country_code` | string | yes | ISO 3166-1 alpha-2 country code, e.g. VN, US, SG |\n| `recipient.city` | string | | |\n| `recipient.state_or_province_code` | string | | |\n| `recipient.street_lines` | string[] | | |\n| `recipient.residential` | boolean | | |\n| `packages` | object[] | yes | One entry per package; weight in kg |\n| `packages[].weight` | number | yes | |\n| `packages[].weight_units` | "KG" \\\\| "LB" | | Weight units; FedEx requires LB for US domestic express |\n| `packages[].length` | number | | |\n| `packages[].width` | number | | |\n| `packages[].height` | number | | |\n| `packages[].dimension_units` | "CM" \\\\| "IN" | | |\n| `service_type` | string | | FedEx service type e.g. INTERNATIONAL_PRIORITY. Omit to rate all available services. |\n| `packaging_type` | string | | FedEx packaging type e.g. YOUR_PACKAGING |\n| `pickup_type` | string | | FedEx pickup type e.g. USE_SCHEDULED_PICKUP |\n| `ship_datestamp` | string | | Ship date YYYY-MM-DD |\n| `special_services` | string[] | | FedEx special service types e.g. SATURDAY_DELIVERY |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `services` | object[] | yes | |\n| `services[].service_type` | string | yes | |\n| `services[].service_name` | string | | |\n| `services[].total_charge` | number | | |\n| `services[].currency` | string | | |\n\n### fedex_service_availability (workflow step)\n\n- Check what FedEx services serve a lane. query "transit_times" returns delivery commitments per service; "package_and_service_options" returns valid service/packaging combinations; "special_service_options" returns available special services.\n- Use before rating/booking to learn the valid service types for an origin \u2192 destination.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | FedEx connected account |\n| `query` | "transit_times" \\\\| "special_service_options" \\\\| "package_and_service_options" | yes | |\n| `shipper` | object | yes | |\n| `shipper.postal_code` | string | yes | |\n| `shipper.country_code` | string | yes | ISO 3166-1 alpha-2 country code, e.g. VN, US, SG |\n| `shipper.city` | string | | |\n| `shipper.state_or_province_code` | string | | |\n| `shipper.street_lines` | string[] | | |\n| `shipper.residential` | boolean | | |\n| `recipient` | object | yes | |\n| `recipient.postal_code` | string | yes | |\n| `recipient.country_code` | string | yes | ISO 3166-1 alpha-2 country code, e.g. VN, US, SG |\n| `recipient.city` | string | | |\n| `recipient.state_or_province_code` | string | | |\n| `recipient.street_lines` | string[] | | |\n| `recipient.residential` | boolean | | |\n| `packages` | object[] | yes | One entry per package; weight in kg unless weight_units set |\n| `packages[].weight` | number | yes | |\n| `packages[].weight_units` | "KG" \\\\| "LB" | | Weight units; FedEx requires LB for US domestic express |\n| `packages[].length` | number | | |\n| `packages[].width` | number | | |\n| `packages[].height` | number | | |\n| `packages[].dimension_units` | "CM" \\\\| "IN" | | |\n| `ship_datestamp` | string | | Ship date YYYY-MM-DD |\n| `carrier_codes` | string[] | yes | FedEx carrier codes \u2014 at least one, e.g. FDXE (Express), FDXG (Ground) |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `result` | object | yes | |\n\n### fedex_validate_address (workflow step)\n\n- Validate one or more addresses with FedEx.\n- Returns each resolved address plus its classification (e.g.\n- BUSINESS / RESIDENTIAL) and deliverability attributes.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | FedEx connected account |\n| `addresses` | object[] | yes | At most 100 per call. |\n| `addresses[].postal_code` | string | yes | |\n| `addresses[].country_code` | string | yes | ISO 3166-1 alpha-2 country code, e.g. VN, US, SG |\n| `addresses[].city` | string | | |\n| `addresses[].state_or_province_code` | string | | |\n| `addresses[].street_lines` | string[] | | |\n| `addresses[].residential` | boolean | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `resolved_addresses` | object[] | yes | |\n| `resolved_addresses[].city` | string | | |\n| `resolved_addresses[].state_or_province_code` | string | | |\n| `resolved_addresses[].postal_code` | string | | |\n| `resolved_addresses[].country_code` | string | | |\n| `resolved_addresses[].classification` | string | | |\n| `resolved_addresses[].attributes` | object | | |\n\n## generate\n\n### generate_bank_qr_code (workflow step)\n\n- Generate a bank-payment QR code (VietQR for Vietnam) and save it as a PNG to the workspace.\n- The QR encodes the recipient bank, account number, and optional amount/description so any banking app can scan and pre-fill the transfer.\n- Call list_banks first to discover valid bank codes. (workflow step, chat)\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `country` | "VN" | yes | Country whose bank-payment QR standard to use. Currently only \'VN\' (Vietnam / VietQR) is supported. |\n| `bank_code` | "ICB" \\\\| "VCB" \\\\| "BIDV" \\\\| "VBA" \\\\| "OCB" \\\\| "MB" \\\\| "TCB" \\\\| "ACB" \\\\| "VPB" \\\\| "TPB" \\\\| "STB" \\\\| "HDB" \\\\| "VCCB" \\\\| "SCB" \\\\| "VIB" \\\\| "SHB" \\\\| "EIB" \\\\| "MSB" \\\\| "CAKE" \\\\| "Ubank" \\\\| "TIMO" \\\\| "SGICB" \\\\| "BAB" \\\\| "momo" \\\\| "PVDB" \\\\| "PVCB" \\\\| "MBV" \\\\| "NCB" \\\\| "SHBVN" \\\\| "ABB" \\\\| "VAB" \\\\| "NAB" \\\\| "PGB" \\\\| "VIETBANK" \\\\| "BVB" \\\\| "SEAB" \\\\| "COOPBANK" \\\\| "LPB" \\\\| "KLB" \\\\| "KBank" \\\\| "CIMB" \\\\| "WVN" | yes | Bank code from list_banks. Must belong to the specified country. (workflow step, chat) |\n| `account_number` | string | yes | Beneficiary account number at the bank. |\n| `amount` | number | | Payment amount in the local currency (VND for Vietnam). Omit for a static QR with no fixed amount. |\n| `description` | string | | Transfer description / memo. Max 50 bytes; Vietnamese diacritics use 2\u20133 bytes per character. |\n| `account_name` | string | | Beneficiary name shown on the payer\'s banking app confirmation screen. Max 25 bytes \u2014 banks normalize Vietnamese names to ASCII uppercase, pass the normalized form (e.g. \'NGUYEN VAN A\'). |\n| `filename` | string | | Output filename. Defaults to \'bank_qr_<bank_code>.png\'. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `id` | string | yes | |\n| `filename` | string | yes | |\n| `mime_type` | string | yes | |\n| `url` | string | yes | |\n| `bank` | object | yes | |\n| `bank.country` | string | yes | |\n| `bank.code` | string | yes | |\n| `bank.short_name` | string | yes | |\n| `bank.full_name` | string | yes | |\n\n### generate_qr_code (workflow step)\n\n- Generate a QR code PNG from text or a URL and save it to the workspace.\n- For bank payment QR codes, use generate_bank_qr_code instead \u2014 it builds the correct EMVCo payload from a bank code and account number. (workflow step, chat)\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `data` | string | yes | Text or URL to encode into the QR code. |\n| `filename` | string | | Output filename. Defaults to \'qr_code.png\'. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `id` | string | yes | |\n| `filename` | string | yes | |\n| `mime_type` | string | yes | |\n| `url` | string | yes | |\n\n## get\n\n### get_record (workflow step)\n\n- Fetch a single record with all field values.\n- Returns data (raw values) and display (human-readable labels).\n- A workspace admin\'s `as_member` fetches it as that member would see it.\n- Cell shapes in `data`, keyed by field alias: select / member / link, and a formula with options, read back as arrays \u2014 a single-select as ["open"], the option\'s alias; one member as ["mbr_x"].\n- A workflow body reads the same single-select, single-member or option-formula cell as the bare value, and a files cell as a list of file objects, each with id, filename and mime_type: `first(record.file).id` is the id a file tool takes.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `record_id` | string | yes | |\n| `table_id` | string | | |\n| `as_member` | string | | For a workspace admin: reads as this member would \u2014 their row rules and access. Anyone else is refused. |\n| `field_keys` | string[] | | Field aliases to return. Omit to return all fields. |\n| `comments` | boolean | | Return the record\'s newest comments, 20 at most; `comment_count` is the whole thread. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `id` | string | yes | |\n| `data` | object | yes | |\n| `display` | object | yes | Human-readable display values for select, member, and record link fields. |\n| `links` | object | | Each link field\'s linked rows with the title the cell carries, by field alias; `data` holds their ids. |\n| `locked` | boolean | | |\n| `comment_count` | number | yes | How many comments the record holds. |\n| `comments` | object[] | | With `comments: true`: the newest first. |\n| `comments[].id` | string | yes | Unique identifier for the comment |\n| `comments[].member_id` | string | yes | ID of the member who created this comment |\n| `comments[].content` | string | yes | Comment text content (0-10,000 characters) |\n| `comments[].files` | object[] \\\\| null | | Array of files attached to this comment |\n| `comments[].created_at` | string | yes | Timestamp when comment was created |\n| `comments[].updated_at` | string | yes | Timestamp of last update |\n| `archived_at` | string \\\\| null | | |\n| `created_at` | string | | |\n| `updated_at` | string | | |\n| `_field_names` | object | | |\n| `units` | object | | The unit or currency this row reads a figure in, by the figure\'s field alias, where each row states its own. |\n\n## gmail\n\n### gmail_get_thread (workflow step)\n\n- Retrieve all messages in a Gmail thread.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | The ID of the connected Gmail account to use |\n| `thread_id` | string | yes | Gmail thread ID |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `messages` | object[] | yes | |\n| `messages[].id` | string | yes | Gmail message ID |\n| `messages[].threadId` | string | yes | Gmail thread ID |\n| `messages[].labelIds` | string[] | yes | Gmail label IDs (e.g. INBOX, UNREAD) |\n| `messages[].subject` | string | yes | Email subject |\n| `messages[].from` | string | yes | Sender email address |\n| `messages[].to` | string | yes | Recipient email address |\n| `messages[].date` | string | yes | Email date in the workspace timezone, with its offset |\n| `messages[].snippet` | string | yes | Short plain-text preview of the email body |\n| `messages[].cc` | string \\\\| null | | CC recipients |\n| `messages[].bcc` | string \\\\| null | | BCC recipients |\n\n### gmail_query_emails (workflow step)\n\n- Search Gmail messages using Gmail search syntax. ## Query syntax Operators (no space after colon): - People: from:, to:, cc:, bcc:, deliveredto: - Content: subject:, "exact phrase", +exact_word, AROUND N (proximity) - Status: is:unread, is:read, is:starred, is:important, is:muted - Labels: label:name, in:inbox, in:sent, in:drafts, in:spam, in:trash, in:anywhere - Category: category:primary, category:social, category:promotions, category:updates, category:forums - Attachments: has:attachment, has:drive, filename:pdf, filename:report.xlsx (has:attachment matches non-inline attachments only \u2014 it misses inline-embedded PDFs, common in receipts/invoices; open the message with gmail_read_email to detect those) - Size: larger:5M, smaller:2M, size:1000000 - Dates (YYYY/MM/DD): after:2024/01/01, before:2024/12/31 - Relative dates: newer_than:7d, older_than:3m, newer_than:1y (d=days, m=months, y=years) Combining: space = AND, OR (uppercase), - (exclude), () for grouping, {} alternative OR syntax. (workflow step, chat)\n- Examples: - from:alice is:unread has:attachment - subject:"quarterly review" newer_than:2d - {from:alice from:bob} subject:project -in:drafts - larger:5M filename:pdf older_than:6m - in:anywhere deliveredto:billing@company.com\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | The ID of the connected Gmail account to use |\n| `query` | string | yes | Gmail search syntax expression |\n| `max_result` | number | yes | Maximum number of emails to retrieve (1-50) |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `messages` | object[] | yes | List of matching Gmail messages |\n| `messages[].id` | string | yes | Gmail message ID |\n| `messages[].threadId` | string | yes | Gmail thread ID |\n| `messages[].labelIds` | string[] | yes | Gmail label IDs (e.g. INBOX, UNREAD) |\n| `messages[].subject` | string | yes | Email subject |\n| `messages[].from` | string | yes | Sender email address |\n| `messages[].to` | string | yes | Recipient email address |\n| `messages[].date` | string | yes | Email date in the workspace timezone, with its offset |\n| `messages[].snippet` | string | yes | Short plain-text preview of the email body |\n| `messages[].cc` | string \\\\| null | | CC recipients |\n| `messages[].bcc` | string \\\\| null | | BCC recipients |\n\n### gmail_query_labels (workflow step)\n\n- List Gmail labels with message and thread counts.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | The ID of the connected Gmail account to use |\n| `name` | string | | Match labels by name prefix. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `labels` | object[] | yes | |\n| `labels[].id` | string | yes | |\n| `labels[].name` | string | yes | |\n| `labels[].type` | string | yes | system or user |\n| `labels[].messagesTotal` | number | yes | |\n| `labels[].messagesUnread` | number | yes | |\n| `labels[].threadsTotal` | number | yes | |\n| `labels[].threadsUnread` | number | yes | |\n\n### gmail_read_email (workflow step)\n\n- Fetch a Gmail message\'s body and the list of its attachments.\n- Attachments are stored as workspace files \u2014 the result names each one\'s file_id; read one with view_files, attach one to a record with update_records. (chat, MCP, CLI)\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | The ID of the connected account |\n| `message_id` | string | yes | The ID of the Gmail message to retrieve |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `message` | object | yes | The full Gmail message |\n| `message.id` | string | | Gmail message ID |\n| `message.threadId` | string | | Gmail thread ID |\n| `message.historyId` | string | | Gmail history ID |\n| `message.labelIds` | string[] | | Gmail label IDs |\n| `message.subject` | string | yes | Email subject |\n| `message.from` | string | yes | Sender email address |\n| `message.to` | string | yes | Recipient email address |\n| `message.date` | string | yes | Email date in the workspace timezone, with its offset |\n| `message.body` | object | yes | Email body |\n| `message.body.type` | "text" \\\\| "html" | yes | Body content type |\n| `message.body.content` | string | yes | Body content |\n| `message.cc` | string \\\\| null | | CC recipients |\n| `message.bcc` | string \\\\| null | | BCC recipients |\n| `message.inReplyTo` | string \\\\| null | | In-Reply-To header |\n| `message.replyTo` | string \\\\| null | | Reply-To header |\n| `message.references` | string[] \\\\| null | | References header |\n| `message.attachments` | object[] | yes | Email attachments |\n| `message.attachments[].partId` | string | yes | MIME part ID |\n| `message.attachments[].filename` | string | yes | Attachment filename as stored, which may differ from the sender\'s |\n| `message.attachments[].mimeType` | string | yes | MIME type as stored, recovered from the filename when the sender declared a generic one |\n| `message.attachments[].attachmentId` | string | yes | Gmail attachment ID |\n| `message.attachments[].file_id` | string | | Stored file ID \u2014 pass to view_files to read it, or to update_records to attach it (chat, MCP, CLI) |\n| `message.attachments[].size` | number | | Stored size in bytes |\n\n### gmail_reply_email (workflow step)\n\n- Draft or send a reply to a Gmail message.\n- Use reply_body (markdown) or template_id + template_data \u2014 not both.\n- Attach stored files by passing their file_ids.\n- Leaves an unsent draft unless draft is false.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | |\n| `original_message_id` | string | yes | |\n| `reply_body` | string | | Reply body (markdown). Mutually exclusive with template_id. |\n| `template_id` | string | | |\n| `template_data` | object | | |\n| `cc` | string | | CC recipients, comma-separated |\n| `bcc` | string | | BCC recipients, comma-separated |\n| `draft` | boolean | | Leave true to save an unsent draft the member reviews. Pass false only to deliver the message now \u2014 delivery is irreversible. |\n| `file_ids` | string[] | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `message_id` | string | yes | The ID of the sent message or saved draft |\n| `subject` | string | yes | The subject as sent |\n| `html` | string | yes | The body as sent, rendered to HTML |\n| `markdown` | string | | The body as written in markdown; absent when a template rendered it |\n| `to` | string | yes | The original sender the reply went to |\n\n### gmail_send_email (workflow step)\n\n- Draft or send a Gmail email.\n- Use content (markdown) or template_id + template_data \u2014 not both.\n- Attach stored files by passing their file_ids.\n- Leaves an unsent draft unless draft is false.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | |\n| `to` | string | | Recipient email(s), comma-separated. Required unless using a template. |\n| `subject` | string | | |\n| `cc` | string | | CC recipients, comma-separated |\n| `bcc` | string | | BCC recipients, comma-separated |\n| `content` | string | | Email body (markdown). Mutually exclusive with template_id. |\n| `template_id` | string | | |\n| `template_data` | object | | |\n| `draft` | boolean | | Leave true to save an unsent draft the member reviews. Pass false only to deliver the message now \u2014 delivery is irreversible. |\n| `file_ids` | string[] | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `message_id` | string | yes | The ID of the sent message or saved draft |\n| `subject` | string | yes | The subject as sent |\n| `html` | string | yes | The body as sent, rendered to HTML |\n| `markdown` | string | | The body as written in markdown; absent when a template rendered it |\n| `to` | string | yes | The recipients as sent, comma-separated |\n\n## instagram\n\n### instagram_create_post (workflow step)\n\n- Publish to the connected Instagram account.\n- Instagram has no text-only posts.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | |\n| `caption` | string | yes | |\n| `media_file_ids` | string[] | yes | One image, one video (published as a reel), or 2\u201310 images and videos as a carousel. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `post_id` | string | yes | |\n| `url` | string | yes | |\n\n## kiotviet\n\n### kiotviet_cancel_invoice (workflow step)\n\n- Cancel a KiotViet sales invoice by id, returning its stock.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `id` | number | yes | |\n| `void_payment` | boolean | | Also void payments recorded on the invoice |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `cancelled` | true | yes | |\n\n### kiotviet_cancel_order (workflow step)\n\n- Cancel a KiotViet sales order by id, releasing the stock it reserved.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `id` | number | yes | |\n| `void_payment` | boolean | | Also void payments recorded on the order |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `cancelled` | true | yes | |\n\n### kiotviet_create_category (workflow step)\n\n- Create a KiotViet product group (nh\xF3m h\xE0ng), optionally under a parent group.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `name` | string | yes | |\n| `parent_id` | number | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `category` | object | yes | |\n\n### kiotviet_create_customer (workflow step)\n\n- Create a KiotViet customer (kh\xE1ch h\xE0ng).\n- Returns the customer as KiotViet stores it, with its id and code.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `name` | string | yes | |\n| `code` | string | | Customer code (m\xE3 kh\xE1ch h\xE0ng) |\n| `contact_number` | string | | |\n| `email` | string | | |\n| `address` | string | | |\n| `location_name` | string | | Province/district as KiotViet names it |\n| `ward_name` | string | | |\n| `gender` | boolean | | true for male, false for female |\n| `birth_date` | string | | yyyy-mm-dd |\n| `group_ids` | number[] | | Customer group ids |\n| `comments` | string | | |\n| `branch_id` | number | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `customer` | object | yes | |\n\n### kiotviet_create_invoice (workflow step)\n\n- Create a KiotViet sales invoice (h\xF3a \u0111\u01A1n), which deducts stock.\n- Pass order_id to invoice an existing order.\n- Returns the invoice as KiotViet stores it, with its id and code.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `branch_id` | number | yes | |\n| `customer_id` | number | | |\n| `sold_by_id` | number | yes | KiotViet user id of the seller |\n| `purchase_date` | string | | ISO datetime |\n| `description` | string | | |\n| `discount` | number | | Discount amount on the whole document |\n| `lines` | object[] | yes | |\n| `lines[].product_id` | number | yes | |\n| `lines[].quantity` | number | yes | |\n| `lines[].price` | number | | Unit price |\n| `lines[].discount` | number | | Discount amount on the line |\n| `lines[].note` | string | | |\n| `order_id` | number | | The sales order this invoice settles |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `invoice` | object | yes | |\n\n### kiotviet_create_order (workflow step)\n\n- Create a KiotViet sales order (\u0111\u1EB7t h\xE0ng) \u2014 the pre-invoice stage, which reserves stock.\n- Returns the order as KiotViet stores it, with its id and code.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `branch_id` | number | yes | |\n| `customer_id` | number | | |\n| `sold_by_id` | number | | KiotViet user id of the seller |\n| `purchase_date` | string | | ISO datetime |\n| `description` | string | | |\n| `discount` | number | | Discount amount on the whole document |\n| `lines` | object[] | yes | |\n| `lines[].product_id` | number | yes | |\n| `lines[].quantity` | number | yes | |\n| `lines[].price` | number | | Unit price |\n| `lines[].discount` | number | | Discount amount on the line |\n| `lines[].note` | string | | |\n| `make_invoice` | boolean | | Also issue the invoice at once |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `order` | object | yes | |\n\n### kiotviet_create_product (workflow step)\n\n- Create a KiotViet product (h\xE0ng h\xF3a), optionally with opening stock per branch.\n- Returns the product as KiotViet stores it, with its id and code.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `name` | string | yes | |\n| `code` | string | | Product code (m\xE3 h\xE0ng) |\n| `category_id` | number | yes | Product group id |\n| `base_price` | number | | Selling price |\n| `unit` | string | | |\n| `allows_sale` | boolean | | |\n| `is_active` | boolean | | |\n| `description` | string | | |\n| `weight` | number | | Grams |\n| `inventories` | object[] | | Stock per branch |\n| `inventories[].branch_id` | number | yes | |\n| `inventories[].on_hand` | number | yes | |\n| `inventories[].cost` | number | | Unit cost at this branch |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `product` | object | yes | |\n\n### kiotviet_delete_product (workflow step)\n\n- Delete a KiotViet product by id.\n- KiotViet refuses one that already appears on invoices.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `id` | number | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `deleted` | true | yes | |\n\n### kiotviet_get_customer (workflow step)\n\n- Get one KiotViet customer by id or by customer code (m\xE3 kh\xE1ch h\xE0ng).\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `id` | number | | |\n| `code` | string | | Customer code (m\xE3 kh\xE1ch h\xE0ng), e.g. KH000123 |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `customer` | object | yes | |\n\n### kiotviet_get_invoice (workflow step)\n\n- Get one KiotViet sales invoice by id or by invoice code (m\xE3 h\xF3a \u0111\u01A1n), with its line items and payments.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `id` | number | | |\n| `code` | string | | Invoice code (m\xE3 h\xF3a \u0111\u01A1n), e.g. HD000123 |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `invoice` | object | yes | |\n\n### kiotviet_get_product (workflow step)\n\n- Get one KiotViet product by id or by product code (m\xE3 h\xE0ng), with stock per branch in inventories[].\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `id` | number | | |\n| `code` | string | | Product code (m\xE3 h\xE0ng), e.g. SP000123 |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `product` | object | yes | |\n\n### kiotviet_list_branches (workflow step)\n\n- List the store\'s KiotViet branches (chi nh\xE1nh).\n- Branch ids scope inventory, invoices and orders.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `page_size` | number | | Rows per page, up to 100 |\n| `current_item` | number | | Zero-based offset of the first row |\n| `last_modified_from` | string | | ISO datetime; only rows modified at or after it |\n| `include_removed_ids` | boolean | | Also return removed_ids \u2014 rows deleted since last_modified_from |\n| `order_by` | string | | KiotViet field name to sort by |\n| `order_direction` | "Asc" \\\\| "Desc" | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `total` | number | | Rows matching the query across all pages |\n| `page_size` | number | | |\n| `items` | object[] | yes | Rows as KiotViet returns them |\n| `removed_ids` | number[] | | |\n\n### kiotviet_list_categories (workflow step)\n\n- List KiotViet product groups (nh\xF3m h\xE0ng).\n- Each row carries its parentId, so the tree can be rebuilt from the flat list.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `page_size` | number | | Rows per page, up to 100 |\n| `current_item` | number | | Zero-based offset of the first row |\n| `last_modified_from` | string | | ISO datetime; only rows modified at or after it |\n| `include_removed_ids` | boolean | | Also return removed_ids \u2014 rows deleted since last_modified_from |\n| `order_by` | string | | KiotViet field name to sort by |\n| `order_direction` | "Asc" \\\\| "Desc" | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `total` | number | | Rows matching the query across all pages |\n| `page_size` | number | | |\n| `items` | object[] | yes | Rows as KiotViet returns them |\n| `removed_ids` | number[] | | |\n\n### kiotviet_list_customers (workflow step)\n\n- List KiotViet customers (kh\xE1ch h\xE0ng) with their lifetime totals \u2014 totalInvoiced, totalRevenue, debt, totalPoint.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `page_size` | number | | Rows per page, up to 100 |\n| `current_item` | number | | Zero-based offset of the first row |\n| `last_modified_from` | string | | ISO datetime; only rows modified at or after it |\n| `include_removed_ids` | boolean | | Also return removed_ids \u2014 rows deleted since last_modified_from |\n| `order_by` | string | | KiotViet field name to sort by |\n| `order_direction` | "Asc" \\\\| "Desc" | | |\n| `code` | string | | Customer code (m\xE3 kh\xE1ch h\xE0ng) |\n| `name` | string | | Name search |\n| `contact_number` | string | | Phone number |\n| `group_id` | number | | Only customers in this customer group |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `total` | number | | Rows matching the query across all pages |\n| `page_size` | number | | |\n| `items` | object[] | yes | Rows as KiotViet returns them |\n| `removed_ids` | number[] | | |\n\n### kiotviet_list_invoices (workflow step)\n\n- List KiotViet sales invoices (h\xF3a \u0111\u01A1n) with their line items in invoiceDetails[] \u2014 productCode, productName, quantity, price, discount, subTotal.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `page_size` | number | | Rows per page, up to 100 |\n| `current_item` | number | | Zero-based offset of the first row |\n| `last_modified_from` | string | | ISO datetime; only rows modified at or after it |\n| `include_removed_ids` | boolean | | Also return removed_ids \u2014 rows deleted since last_modified_from |\n| `order_by` | string | | KiotViet field name to sort by |\n| `order_direction` | "Asc" \\\\| "Desc" | | |\n| `branch_ids` | number[] | | |\n| `customer_ids` | number[] | | |\n| `customer_code` | string | | Customer code (m\xE3 kh\xE1ch h\xE0ng) |\n| `status` | number[] | | KiotViet status codes; each row carries statusValue with the label |\n| `from_purchase_date` | string | | Date, yyyy-mm-dd |\n| `to_purchase_date` | string | | Date, yyyy-mm-dd |\n| `include_payment` | boolean | | Include payments[] on each row |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `total` | number | | Rows matching the query across all pages |\n| `page_size` | number | | |\n| `items` | object[] | yes | Rows as KiotViet returns them |\n| `removed_ids` | number[] | | |\n\n### kiotviet_list_orders (workflow step)\n\n- List KiotViet sales orders (\u0111\u1EB7t h\xE0ng) \u2014 the pre-invoice stage \u2014 with line items in orderDetails[].\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `page_size` | number | | Rows per page, up to 100 |\n| `current_item` | number | | Zero-based offset of the first row |\n| `last_modified_from` | string | | ISO datetime; only rows modified at or after it |\n| `include_removed_ids` | boolean | | Also return removed_ids \u2014 rows deleted since last_modified_from |\n| `order_by` | string | | KiotViet field name to sort by |\n| `order_direction` | "Asc" \\\\| "Desc" | | |\n| `branch_ids` | number[] | | |\n| `customer_ids` | number[] | | |\n| `customer_code` | string | | Customer code (m\xE3 kh\xE1ch h\xE0ng) |\n| `status` | number[] | | KiotViet status codes; each row carries statusValue with the label |\n| `from_purchase_date` | string | | Date, yyyy-mm-dd |\n| `to_purchase_date` | string | | Date, yyyy-mm-dd |\n| `include_payment` | boolean | | Include payments[] on each row |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `total` | number | | Rows matching the query across all pages |\n| `page_size` | number | | |\n| `items` | object[] | yes | Rows as KiotViet returns them |\n| `removed_ids` | number[] | | |\n\n### kiotviet_list_products (workflow step)\n\n- List KiotViet products (h\xE0ng h\xF3a) with stock per branch.\n- Each row\'s inventories[] carries branchId, onHand (t\u1ED3n kho), reserved (\u0111\u1EB7t h\xE0ng) and cost.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `page_size` | number | | Rows per page, up to 100 |\n| `current_item` | number | | Zero-based offset of the first row |\n| `last_modified_from` | string | | ISO datetime; only rows modified at or after it |\n| `include_removed_ids` | boolean | | Also return removed_ids \u2014 rows deleted since last_modified_from |\n| `order_by` | string | | KiotViet field name to sort by |\n| `order_direction` | "Asc" \\\\| "Desc" | | |\n| `category_id` | number | | Only products in this product group |\n| `is_active` | boolean | | Only products still on sale (true) or discontinued (false) |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `total` | number | | Rows matching the query across all pages |\n| `page_size` | number | | |\n| `items` | object[] | yes | Rows as KiotViet returns them |\n| `removed_ids` | number[] | | |\n\n### kiotviet_list_purchase_orders (workflow step)\n\n- List KiotViet purchase orders (phi\u1EBFu nh\u1EADp h\xE0ng) \u2014 goods received from suppliers \u2014 with line items in purchaseOrderDetails[].\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `page_size` | number | | Rows per page, up to 100 |\n| `current_item` | number | | Zero-based offset of the first row |\n| `last_modified_from` | string | | ISO datetime; only rows modified at or after it |\n| `include_removed_ids` | boolean | | Also return removed_ids \u2014 rows deleted since last_modified_from |\n| `order_by` | string | | KiotViet field name to sort by |\n| `order_direction` | "Asc" \\\\| "Desc" | | |\n| `branch_ids` | number[] | | |\n| `status` | number[] | | KiotViet status codes; each row carries statusValue with the label |\n| `from_purchase_date` | string | | Date, yyyy-mm-dd |\n| `to_purchase_date` | string | | Date, yyyy-mm-dd |\n| `include_payment` | boolean | | Include payments[] on each row |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `total` | number | | Rows matching the query across all pages |\n| `page_size` | number | | |\n| `items` | object[] | yes | Rows as KiotViet returns them |\n| `removed_ids` | number[] | | |\n\n### kiotviet_update_category (workflow step)\n\n- Rename a KiotViet product group or move it under another parent.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `id` | number | yes | |\n| `name` | string | | |\n| `parent_id` | number | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `category` | object | yes | |\n\n### kiotviet_update_customer (workflow step)\n\n- Update a KiotViet customer by id.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `id` | number | yes | |\n| `name` | string | | |\n| `code` | string | | Customer code (m\xE3 kh\xE1ch h\xE0ng) |\n| `contact_number` | string | | |\n| `email` | string | | |\n| `address` | string | | |\n| `location_name` | string | | Province/district as KiotViet names it |\n| `ward_name` | string | | |\n| `gender` | boolean | | true for male, false for female |\n| `birth_date` | string | | yyyy-mm-dd |\n| `group_ids` | number[] | | Customer group ids |\n| `comments` | string | | |\n| `branch_id` | number | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `customer` | object | yes | |\n\n### kiotviet_update_invoice (workflow step)\n\n- Update a KiotViet sales invoice by id.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `id` | number | yes | |\n| `branch_id` | number | | |\n| `customer_id` | number | | |\n| `sold_by_id` | number | | KiotViet user id of the seller |\n| `purchase_date` | string | | ISO datetime |\n| `description` | string | | |\n| `discount` | number | | Discount amount on the whole document |\n| `lines` | object[] | | |\n| `lines[].product_id` | number | yes | |\n| `lines[].quantity` | number | yes | |\n| `lines[].price` | number | | Unit price |\n| `lines[].discount` | number | | Discount amount on the line |\n| `lines[].note` | string | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `invoice` | object | yes | |\n\n### kiotviet_update_order (workflow step)\n\n- Update a KiotViet sales order by id.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `id` | number | yes | |\n| `branch_id` | number | | |\n| `customer_id` | number | | |\n| `sold_by_id` | number | | KiotViet user id of the seller |\n| `purchase_date` | string | | ISO datetime |\n| `description` | string | | |\n| `discount` | number | | Discount amount on the whole document |\n| `lines` | object[] | | |\n| `lines[].product_id` | number | yes | |\n| `lines[].quantity` | number | yes | |\n| `lines[].price` | number | | Unit price |\n| `lines[].discount` | number | | Discount amount on the line |\n| `lines[].note` | string | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `order` | object | yes | |\n\n### kiotviet_update_product (workflow step)\n\n- Update a KiotViet product by id; inventories set the stock level per branch.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | KiotViet connected account |\n| `id` | number | yes | |\n| `name` | string | | |\n| `code` | string | | Product code (m\xE3 h\xE0ng) |\n| `category_id` | number | | Product group id |\n| `base_price` | number | | Selling price |\n| `unit` | string | | |\n| `allows_sale` | boolean | | |\n| `is_active` | boolean | | |\n| `description` | string | | |\n| `weight` | number | | Grams |\n| `inventories` | object[] | | Stock per branch |\n| `inventories[].branch_id` | number | yes | |\n| `inventories[].on_hand` | number | yes | |\n| `inventories[].cost` | number | | Unit cost at this branch |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `product` | object | yes | |\n\n## lark\n\n### lark_create_records (workflow step)\n\n- Create one or many records in a Lark Base (Bitable) table (max 500 per call). fields are keyed by Lark field name.\n- Returns the new record ids.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Lark connected account |\n| `app_token` | string | yes | Lark Base app_token (the Base id) |\n| `table_id` | string | yes | Lark Bitable table id |\n| `records` | object[] | yes | |\n| `records[].fields` | object | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `created` | number | yes | |\n| `records` | object[] | yes | |\n| `records[].record_id` | string | yes | |\n| `records[].fields` | object | yes | |\n\n### lark_delete_records (workflow step)\n\n- Delete one or many records from a Lark Base (Bitable) table by record_id (max 500 per call).\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Lark connected account |\n| `app_token` | string | yes | Lark Base app_token (the Base id) |\n| `table_id` | string | yes | Lark Bitable table id |\n| `record_ids` | string[] | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `deleted` | number | yes | |\n| `record_ids` | string[] | yes | |\n\n### lark_get_record (workflow step)\n\n- Get one record from a Lark Base (Bitable) table by its record_id.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Lark connected account |\n| `app_token` | string | yes | Lark Base app_token (the Base id) |\n| `table_id` | string | yes | Lark Bitable table id |\n| `record_id` | string | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `record_id` | string | yes | |\n| `fields` | object | yes | |\n\n### lark_list_fields (workflow step)\n\n- List the fields (columns) of a Lark Base (Bitable) table \u2014 name, id, and type.\n- Use to discover the schema before reading or writing records.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Lark connected account |\n| `app_token` | string | yes | Lark Base app_token (the Base id) |\n| `table_id` | string | yes | Lark Bitable table id |\n| `page_size` | number | | |\n| `page_token` | string | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `fields` | object[] | yes | |\n| `fields[].field_id` | string | | |\n| `fields[].field_name` | string | | |\n| `fields[].type` | number | | |\n| `fields[].ui_type` | string | | |\n| `fields[].is_primary` | boolean | | |\n| `has_more` | boolean | yes | |\n| `page_token` | string | | |\n\n### lark_list_records (workflow step)\n\n- List records from a Lark Base (Bitable) table.\n- Returns each record\'s id and fields (keyed by Lark field name).\n- Optionally narrow with filter / sort / field_names / view_id; paginate with page_token.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Lark connected account |\n| `app_token` | string | yes | Lark Base app_token (the Base id) |\n| `table_id` | string | yes | Lark Bitable table id |\n| `filter` | object | | |\n| `filter.conjunction` | "and" \\\\| "or" | yes | |\n| `filter.conditions` | object[] | yes | |\n| `filter.conditions[].field_name` | string | yes | |\n| `filter.conditions[].operator` | string | yes | e.g. is, isNot, contains, isGreater, isEmpty |\n| `filter.conditions[].value` | string[] | | |\n| `sort` | object[] | | |\n| `sort[].field_name` | string | yes | |\n| `sort[].desc` | boolean | | |\n| `field_names` | string[] | | Restrict returned fields by name |\n| `view_id` | string | | |\n| `page_size` | number | | |\n| `page_token` | string | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `records` | object[] | yes | |\n| `records[].record_id` | string | yes | |\n| `records[].fields` | object | yes | |\n| `has_more` | boolean | yes | |\n| `page_token` | string | | |\n| `total` | number | | |\n\n### lark_list_tables (workflow step)\n\n- List the tables in a Lark Base (Bitable) \u2014 id and name.\n- Use to discover which table_id to read or write.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Lark connected account |\n| `app_token` | string | yes | Lark Base app_token (the Base id) |\n| `page_size` | number | | |\n| `page_token` | string | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `tables` | object[] | yes | |\n| `tables[].table_id` | string | | |\n| `tables[].name` | string | | |\n| `has_more` | boolean | yes | |\n| `page_token` | string | | |\n\n### lark_update_records (workflow step)\n\n- Update one or many existing records in a Lark Base (Bitable) table by record_id (max 500 per call). fields are keyed by Lark field name; only provided fields change.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Lark connected account |\n| `app_token` | string | yes | Lark Base app_token (the Base id) |\n| `table_id` | string | yes | Lark Bitable table id |\n| `records` | object[] | yes | |\n| `records[].record_id` | string | yes | |\n| `records[].fields` | object | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `updated` | number | yes | |\n| `records` | object[] | yes | |\n| `records[].record_id` | string | yes | |\n| `records[].fields` | object | yes | |\n\n## linkedin\n\n### linkedin_create_post (workflow step)\n\n- Publish a post to the connected LinkedIn member\'s profile.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | |\n| `text` | string | yes | |\n| `link` | string | | Shown as an article card; needs link_title. A post carries either a link or media. |\n| `link_title` | string | | |\n| `media_file_ids` | string[] | | Up to 20 images, or one video. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `post_id` | string | yes | |\n| `url` | string | yes | |\n\n## list\n\n### list_banks (workflow step)\n\n- List banks supported by generate_bank_qr_code. (workflow step, chat)\n- Returns the bank code (used as input to the generator), display name, and country.\n- Call this before generate_bank_qr_code to discover valid codes. (workflow step, chat)\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `country` | "VN" | | Filter to banks from a specific country. Omit to list all supported banks. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `banks` | object[] | yes | |\n| `banks[].country` | string | yes | |\n| `banks[].code` | string | yes | |\n| `banks[].bin` | string | yes | |\n| `banks[].short_name` | string | yes | |\n| `banks[].full_name` | string | yes | |\n\n## lock\n\n### lock_records (workflow step)\n\n- Lock records to prevent editing.\n- Returns `{ locked, record_ids }`.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `table_id` | string | yes | |\n| `record_ids` | string[] | | |\n| `filters` | any | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `locked` | number | yes | |\n| `record_ids` | string[] | yes | |\n\n## lookup\n\n### lookup_business (workflow step)\n\n- Look up business registration info by tax / registration code.\n- Defaults to Vietnam (country=\'VN\').\n- A VN registered name ending in "(NTNN)" marks a code for paying a foreign contractor\'s tax on the company\'s behalf, not the company\'s own code.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `tax_code` | string | yes | Business tax / registration code. Format varies by country; for VN this is a 10\u201313 digit m\xE3 s\u1ED1 thu\u1EBF. |\n| `country` | string | | ISO country code. Defaults to \'VN\' (Vietnam). Only \'VN\' is supported today. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `country` | string | yes | |\n| `tax_code` | string | yes | |\n| `name` | string | yes | |\n| `address` | string | yes | |\n| `representative` | string \\\\| null | yes | |\n| `status` | string \\\\| null | yes | |\n| `international_name` | string \\\\| null | yes | |\n| `short_name` | string \\\\| null | yes | |\n| `operating_since` | string \\\\| null | yes | |\n| `managed_by` | string \\\\| null | yes | |\n| `company_type` | string \\\\| null | yes | |\n| `primary_industry` | string \\\\| null | yes | |\n\n## misa\n\n### misa_get_dictionary (workflow step)\n\n- Read master-data records from MISA AMIS to look up codes (customer code, item code, warehouse code, etc.) before pushing a voucher.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | MISA connected account to read from |\n| `data_type` | 1 \\\\| 2 \\\\| 3 \\\\| 4 \\\\| 5 \\\\| 6 \\\\| 8 \\\\| 9 \\\\| 10 \\\\| 11 \\\\| 12 | yes | 1 objects (customers/suppliers/employees), 2 inventory items, 3 stocks, 4 units, 5 chart of accounts, 6 organization units, 8 bank accounts, 9 projects, 10 cost objects, 11 payment terms, 12 banks |\n| `skip` | integer | | |\n| `take` | integer | | Max 100 per page |\n| `last_sync_time` | string | | ISO timestamp \u2014 only return records changed since this time |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `success` | boolean | yes | |\n| `data` | object[] | yes | The dictionary records, each as MISA names its fields |\n| `last_sync_time` | string | | Cursor \u2014 pass as last_sync_time on the next call to fetch only newer changes |\n| `error_code` | string | | |\n| `error_message` | string | | |\n\n### misa_save_bank_voucher (workflow step)\n\n- Push a bank voucher (deposit / withdrawal / transfer) into MISA AMIS. voucher_type: 1 deposit (b\xE1o c\xF3), 3 withdrawal/debit-advice (b\xE1o n\u1EE3), 2 internal transfer. bank_account_id is the company-side bank account GUID \u2014 look it up with misa_get_dictionary (data_type 8). (workflow step, chat)\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `voucher_type` | 1 \\\\| 2 \\\\| 3 | yes | |\n| `reftype` | integer | | |\n| `org_refid` | string | yes | a UUID that stays the same for the document \u2014 `uuidFrom(record.id)` |\n| `org_refno` | string | | Source-system document number |\n| `refdate` | string | yes | Document date, ISO 8601 |\n| `posted_date` | string | yes | Accounting posting date, ISO 8601 |\n| `branch_id` | string | | MISA branch GUID, optional for single-branch tenants |\n| `currency_id` | string | | Currency code, default VND |\n| `exchange_rate` | number | | FX rate, default 1.0 |\n| `journal_memo` | string | | Voucher memo/notes |\n| `custom_field1` | string | | |\n| `custom_field2` | string | | |\n| `custom_field3` | string | | |\n| `custom_field4` | string | | |\n| `custom_field5` | string | | |\n| `bank_account_id` | string | yes | Bank account GUID in MISA \u2014 look up via misa_get_dictionary (workflow step, chat) |\n| `account_object_code` | string | | |\n| `account_object_name` | string | | |\n| `total_amount_oc` | number | yes | |\n| `total_amount` | number | yes | |\n| `detail` | object[] | yes | |\n| `detail[].description` | string | yes | |\n| `detail[].amount_oc` | number | yes | |\n| `detail[].amount` | number | yes | |\n| `detail[].debit_account` | string | yes | |\n| `detail[].credit_account` | string | yes | |\n| `detail[].sort_order` | integer | | |\n| `connected_account_id` | string | yes | MISA connected account to push to |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `queued` | boolean | yes | |\n| `org_refid` | string | yes | |\n| `error_code` | string | | |\n| `error_message` | string | | |\n\n### misa_save_cash_voucher (workflow step)\n\n- Push a cash voucher (cash receipt or cash payment) into MISA AMIS. voucher_type: 5 receipt (thu ti\u1EC1n), 4 payment (chi ti\u1EC1n). detail array carries the journal lines with debit_account/credit_account per Vietnamese chart-of-accounts.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `voucher_type` | 4 \\\\| 5 | yes | |\n| `reftype` | integer | | |\n| `org_refid` | string | yes | a UUID that stays the same for the document \u2014 `uuidFrom(record.id)` |\n| `org_refno` | string | | Source-system document number |\n| `refdate` | string | yes | Document date, ISO 8601 |\n| `posted_date` | string | yes | Accounting posting date, ISO 8601 |\n| `branch_id` | string | | MISA branch GUID, optional for single-branch tenants |\n| `currency_id` | string | | Currency code, default VND |\n| `exchange_rate` | number | | FX rate, default 1.0 |\n| `journal_memo` | string | | Voucher memo/notes |\n| `custom_field1` | string | | |\n| `custom_field2` | string | | |\n| `custom_field3` | string | | |\n| `custom_field4` | string | | |\n| `custom_field5` | string | | |\n| `account_object_code` | string | | Counterparty code (customer/supplier/employee) |\n| `account_object_name` | string | | |\n| `total_amount_oc` | number | yes | |\n| `total_amount` | number | yes | |\n| `detail` | object[] | yes | |\n| `detail[].description` | string | yes | |\n| `detail[].amount_oc` | number | yes | |\n| `detail[].amount` | number | yes | |\n| `detail[].debit_account` | string | yes | |\n| `detail[].credit_account` | string | yes | |\n| `detail[].sort_order` | integer | | |\n| `connected_account_id` | string | yes | MISA connected account to push to |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `queued` | boolean | yes | |\n| `org_refid` | string | yes | |\n| `error_code` | string | | |\n| `error_message` | string | | |\n\n### misa_save_dictionary (workflow step)\n\n- Create or update master-data records in MISA AMIS (customers, suppliers, items, warehouses, etc.).\n- Use this before pushing a voucher that references a code MISA doesn\'t yet know about.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | MISA connected account to push to |\n| `dictionary_type` | 1 \\\\| 2 \\\\| 3 \\\\| 4 \\\\| 5 \\\\| 6 \\\\| 7 \\\\| 8 \\\\| 9 \\\\| 10 \\\\| 12 | yes | 1 customers/suppliers/employees, 2 object groups, 3 inventory items, 4 item categories, 5 warehouses, 6 units, 7 bank accounts, 8 banks, 9 expense items, 10 revenue/expense categories, 12 cost allocation |\n| `items` | object[] | yes | Master-data records to create or update. 1\u2013200 per call. Each item\'s required fields depend on dictionary_type \u2014 see MISA Open API docs (chat, MCP, CLI) |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `queued` | boolean | yes | |\n| `count` | integer | yes | |\n| `error_code` | string | | |\n| `error_message` | string | | |\n\n### misa_save_purchase_voucher (workflow step)\n\n- Push a purchase voucher (purchase invoice / return / discount-debit-note-to-supplier / service / general purchase / purchase order) into MISA AMIS. voucher_type: 15 invoice, 18 voucher, 17 service, 16 return, 14 discount (debit note to supplier), 21 purchase order. account_object_code identifies the supplier in MISA \u2014 must already exist.\n- MISA sync ack only confirms queueing; final accept/reject arrives async.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `voucher_type` | 14 \\\\| 15 \\\\| 16 \\\\| 17 \\\\| 18 \\\\| 21 | yes | |\n| `reftype` | integer | | |\n| `org_refid` | string | yes | a UUID that stays the same for the document \u2014 `uuidFrom(record.id)` |\n| `org_refno` | string | | Source-system document number |\n| `refdate` | string | yes | Document date, ISO 8601 |\n| `posted_date` | string | yes | Accounting posting date, ISO 8601 |\n| `branch_id` | string | | MISA branch GUID, optional for single-branch tenants |\n| `currency_id` | string | | Currency code, default VND |\n| `exchange_rate` | number | | FX rate, default 1.0 |\n| `journal_memo` | string | | Voucher memo/notes |\n| `custom_field1` | string | | |\n| `custom_field2` | string | | |\n| `custom_field3` | string | | |\n| `custom_field4` | string | | |\n| `custom_field5` | string | | |\n| `account_object_code` | string | yes | Supplier code in MISA |\n| `account_object_name` | string | | |\n| `account_object_tax_code` | string | | |\n| `account_object_address` | string | | |\n| `total_amount_oc` | number | yes | |\n| `total_amount` | number | yes | |\n| `total_vat_amount_oc` | number | yes | |\n| `total_vat_amount` | number | yes | |\n| `detail` | object[] | yes | |\n| `detail[].inventory_item_code` | string | | Item/product code in MISA. Skip when is_description=true |\n| `detail[].inventory_item_name` | string | yes | Item/product display name |\n| `detail[].inventory_item_type` | 0 \\\\| 1 \\\\| 2 \\\\| 3 | | Item type \u2014 0 goods, 1 finished, 2 service, 3 raw material |\n| `detail[].description` | string | | Line description |\n| `detail[].is_description` | boolean | | Description-only line \u2014 when true, only `description` is required |\n| `detail[].stock_code` | string | | Warehouse code in MISA |\n| `detail[].unit_name` | string | | Unit of measure name |\n| `detail[].quantity` | number | yes | Line quantity |\n| `detail[].unit_price` | number | yes | Unit price (in currency_id of voucher) |\n| `detail[].amount_oc` | number | yes | Line total in original currency |\n| `detail[].amount` | number | yes | Line total in accounting currency (= amount_oc when VND) |\n| `detail[].discount_rate` | number | | Line discount percent |\n| `detail[].discount_amount_oc` | number | | Discount amount, original currency |\n| `detail[].discount_amount` | number | | Discount amount, accounting currency |\n| `detail[].vat_rate` | number | yes | VAT percent. 0/5/8/10 for standard, -1 exempt, -2 not creditable, -3 other (set other_vat_rate) |\n| `detail[].other_vat_rate` | number | | Custom VAT percent \u2014 required when vat_rate=-3 |\n| `detail[].vat_amount_oc` | number | yes | VAT amount, original currency |\n| `detail[].vat_amount` | number | yes | VAT amount, accounting currency |\n| `detail[].debit_account` | string | yes | Chart-of-accounts code on debit side, e.g. 131 |\n| `detail[].credit_account` | string | yes | Chart-of-accounts code on credit side, e.g. 511 |\n| `detail[].sale_account` | string | | |\n| `detail[].vat_account` | string | | |\n| `detail[].inventory_account` | string | | |\n| `detail[].sort_order` | integer | | |\n| `detail[].lot_no` | string | | |\n| `detail[].expiry_date` | string | | ISO date |\n| `detail[].organization_unit_code` | string | | Department/branch code |\n| `connected_account_id` | string | yes | MISA connected account to push to |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `queued` | boolean | yes | |\n| `org_refid` | string | yes | |\n| `error_code` | string | | |\n| `error_message` | string | | |\n\n### misa_save_sales_voucher (workflow step)\n\n- Push a sales voucher (invoice / sales return / discount-credit-note / sales order) into MISA AMIS. voucher_type: 11 invoice, 13 sales voucher, 12 return, 10 discount/credit note, 20 sales order. reftype refines the sub-type (e.g. 3530 unpaid sale, 3560 sales invoice, 3571 service cash). account_object_code identifies the customer in MISA \u2014 must already exist (use misa_save_dictionary first if not). (workflow step, chat)\n- MISA sync ack only confirms queueing; final accept/reject arrives async on the registered callback URL.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `voucher_type` | 10 \\\\| 11 \\\\| 12 \\\\| 13 \\\\| 20 | yes | |\n| `reftype` | integer | | Voucher sub-type code \u2014 MISA assigns a default when omitted |\n| `org_refid` | string | yes | a UUID that stays the same for the document \u2014 `uuidFrom(record.id)` |\n| `org_refno` | string | | Source-system document number |\n| `refdate` | string | yes | Document date, ISO 8601 |\n| `posted_date` | string | yes | Accounting posting date, ISO 8601 |\n| `branch_id` | string | | MISA branch GUID, optional for single-branch tenants |\n| `currency_id` | string | | Currency code, default VND |\n| `exchange_rate` | number | | FX rate, default 1.0 |\n| `journal_memo` | string | | Voucher memo/notes |\n| `custom_field1` | string | | |\n| `custom_field2` | string | | |\n| `custom_field3` | string | | |\n| `custom_field4` | string | | |\n| `custom_field5` | string | | |\n| `account_object_code` | string | yes | Customer code in MISA |\n| `account_object_name` | string | | |\n| `account_object_tax_code` | string | | |\n| `account_object_address` | string | | |\n| `employee_code` | string | | Salesperson code |\n| `employee_name` | string | | |\n| `total_sale_amount_oc` | number | yes | |\n| `total_sale_amount` | number | yes | |\n| `total_discount_amount_oc` | number | | |\n| `total_discount_amount` | number | | |\n| `total_vat_amount_oc` | number | yes | |\n| `total_vat_amount` | number | yes | |\n| `total_amount_oc` | number | yes | |\n| `total_amount` | number | yes | |\n| `is_sale_with_outward` | boolean | | Auto-generate stock-out slip |\n| `detail` | object[] | yes | |\n| `detail[].inventory_item_code` | string | | Item/product code in MISA. Skip when is_description=true |\n| `detail[].inventory_item_name` | string | yes | Item/product display name |\n| `detail[].inventory_item_type` | 0 \\\\| 1 \\\\| 2 \\\\| 3 | | Item type \u2014 0 goods, 1 finished, 2 service, 3 raw material |\n| `detail[].description` | string | | Line description |\n| `detail[].is_description` | boolean | | Description-only line \u2014 when true, only `description` is required |\n| `detail[].stock_code` | string | | Warehouse code in MISA |\n| `detail[].unit_name` | string | | Unit of measure name |\n| `detail[].quantity` | number | yes | Line quantity |\n| `detail[].unit_price` | number | yes | Unit price (in currency_id of voucher) |\n| `detail[].amount_oc` | number | yes | Line total in original currency |\n| `detail[].amount` | number | yes | Line total in accounting currency (= amount_oc when VND) |\n| `detail[].discount_rate` | number | | Line discount percent |\n| `detail[].discount_amount_oc` | number | | Discount amount, original currency |\n| `detail[].discount_amount` | number | | Discount amount, accounting currency |\n| `detail[].vat_rate` | number | yes | VAT percent. 0/5/8/10 for standard, -1 exempt, -2 not creditable, -3 other (set other_vat_rate) |\n| `detail[].other_vat_rate` | number | | Custom VAT percent \u2014 required when vat_rate=-3 |\n| `detail[].vat_amount_oc` | number | yes | VAT amount, original currency |\n| `detail[].vat_amount` | number | yes | VAT amount, accounting currency |\n| `detail[].debit_account` | string | yes | Chart-of-accounts code on debit side, e.g. 131 |\n| `detail[].credit_account` | string | yes | Chart-of-accounts code on credit side, e.g. 511 |\n| `detail[].sale_account` | string | | |\n| `detail[].vat_account` | string | | |\n| `detail[].inventory_account` | string | | |\n| `detail[].sort_order` | integer | | |\n| `detail[].lot_no` | string | | |\n| `detail[].expiry_date` | string | | ISO date |\n| `detail[].organization_unit_code` | string | | Department/branch code |\n| `connected_account_id` | string | yes | MISA connected account to push to |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `queued` | boolean | yes | |\n| `org_refid` | string | yes | |\n| `error_code` | string | | |\n| `error_message` | string | | |\n\n## outlook\n\n### outlook_count_emails (workflow step)\n\n- Count Outlook emails matching a filter or search query.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | The Lotics connected account ID (cac_xxx), not the Microsoft user ID |\n| `search` | string | | KQL expression |\n| `filter` | string | | OData expression |\n| `folder` | string | | Mail folder: well-known name or folder ID |\n| `user_id` | string | | Mailbox owner user ID. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `count` | number | yes | Number of matching emails |\n\n### outlook_query_emails (workflow step)\n\n- Search and filter Outlook emails.\n- Two modes: search (KQL keywords) or structured filters (from, to, subject, dates, etc.).\n- When search is provided, structured filters are ignored. ## KQL search syntax (for the search field) Bare keywords search across from, subject, and body.\n- Property restrictions (no space after colon): - People: from:, to:, cc:, bcc:, participants: (all people fields), recipients: (to+cc+bcc) - Content: subject:, body:, "exact phrase" - Attachments: hasAttachments:true, attachment:filename* - Dates: received:2024-01-01, received:2024-01-01..2024-01-31, received>=2024-01-01, received:today, received:"this week", sent:2024-06-01 - Size (bytes): size>1048576, size:1..10485760 - Status: importance:high, isRead:false, kind:email Combining (UPPERCASE required): AND, OR, NOT, - (exclude), () for grouping.\n- Prefix wildcard: subject:set* (end of word only, no *prefix or *mid*dle).\n- Examples: - from:john@contoso.com AND subject:"quarterly report" - participants:alice importance:high hasAttachments:true - body:contract AND received>=2024-01-01 AND received<=2024-06-30 - (from:legal OR from:compliance) AND subject:contract - attachment:annual* received:"this month"\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | The Lotics connected account ID (cac_xxx), not the Microsoft user ID |\n| `search` | string | | KQL search query \u2014 overrides all structured filter fields when provided |\n| `from` | string | | Sender email address exact match |\n| `to` | string | | Recipient email address exact match |\n| `subject` | string | | Subject starts with this text |\n| `after` | string | | ISO date \u2014 received on or after |\n| `before` | string | | ISO date \u2014 received before |\n| `is_read` | boolean | | |\n| `is_draft` | boolean | | |\n| `has_attachments` | boolean | | |\n| `importance` | "low" \\\\| "normal" \\\\| "high" | | |\n| `is_flagged` | boolean | | Whether the email is flagged for follow-up |\n| `classification` | "focused" \\\\| "other" | | Focused Inbox classification |\n| `category` | string | | Color category name |\n| `conversation_id` | string | | Outlook conversation ID \u2014 retrieves all messages in a thread |\n| `folder` | string | | Mail folder: well-known name (inbox, sentitems, drafts, deleteditems, junkemail, archive) or folder ID |\n| `skip` | number | | Number of results to skip for pagination. |\n| `max_result` | number | yes | Maximum number of emails to retrieve (1-50) |\n| `user_id` | string | | The ID of the user whose mailbox the email belongs to. If not provided, the connected account\'s user ID (me) will be used. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `messages` | object[] | yes | List of matching Outlook messages |\n| `messages[].id` | string | yes | Outlook message ID |\n| `messages[].date` | string | yes | Email date in the workspace timezone, with its offset |\n| `messages[].from` | string | yes | Sender email address |\n| `messages[].subject` | string | yes | Email subject |\n| `messages[].to` | string | yes | Recipient email address |\n| `messages[].cc` | string \\\\| null | yes | CC recipients |\n| `messages[].bcc` | string \\\\| null | yes | BCC recipients |\n| `messages[].snippet` | string | yes | Short plain-text preview of the email body (first ~255 chars) |\n| `messages[].conversationId` | string | | Outlook conversation ID |\n| `messages[].receivedDateTime` | string | | Received date-time in ISO format |\n| `messages[].hasAttachments` | boolean | | Whether the email has attachments |\n| `messages[].importance` | string | | Email importance level |\n| `messages[].isRead` | boolean | | Whether the email has been read |\n| `messages[].isDraft` | boolean | | Whether the email is a draft |\n| `messages[].flagStatus` | string | | Flag status: notFlagged, complete, or flagged |\n| `messages[].classification` | string | | Focused Inbox classification: focused or other |\n| `messages[].categories` | string[] | | Color categories assigned to the email |\n\n### outlook_query_folders (workflow step)\n\n- List mail folders in an Outlook mailbox.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | The Lotics connected account ID (cac_xxx), not the Microsoft user ID |\n| `parent_folder_id` | string | | Parent folder ID to list child folders. Omit for top-level folders. |\n| `name` | string | | Match folders by display name prefix. |\n| `include_hidden` | boolean | | Include hidden system folders |\n| `max_result` | number | | Maximum number of folders to return (1-100) |\n| `skip` | number | | Number of results to skip for pagination |\n| `user_id` | string | | The ID of the user whose mailbox to query. Defaults to the connected account owner. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `folders` | object[] | yes | List of mail folders |\n| `folders[].id` | string | yes | Folder ID |\n| `folders[].displayName` | string | yes | Folder display name |\n| `folders[].parentFolderId` | string | | Parent folder ID |\n| `folders[].childFolderCount` | number | yes | Number of child folders |\n| `folders[].totalItemCount` | number | yes | Total number of items in the folder |\n| `folders[].unreadItemCount` | number | yes | Number of unread items |\n| `folders[].isHidden` | boolean | yes | Whether the folder is hidden |\n\n### outlook_read_email (workflow step)\n\n- Fetch an Outlook email\'s body and the list of its attachments.\n- Attachments are stored as workspace files \u2014 the result names each one\'s file_id; read one with view_files, attach one to a record with update_records. (chat, MCP, CLI)\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | The Lotics connected account ID (cac_xxx), not the Microsoft user ID |\n| `message_id` | string | yes | The ID of the Outlook message to retrieve |\n| `user_id` | string | | The ID of the user whose mailbox the email belongs to. If not provided, the connected account\'s user ID (me) will be used. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `message` | object | yes | The full Outlook message |\n| `message.id` | string | | Outlook message ID |\n| `message.date` | string | yes | Email date in the workspace timezone, with its offset |\n| `message.from` | string | yes | Sender email address |\n| `message.subject` | string | yes | Email subject |\n| `message.to` | string | yes | Recipient email address |\n| `message.cc` | string \\\\| null | yes | CC recipients |\n| `message.bcc` | string \\\\| null | yes | BCC recipients |\n| `message.inReplyTo` | string \\\\| null | yes | In-Reply-To header |\n| `message.replyTo` | string \\\\| null | yes | Reply-To header |\n| `message.references` | string[] \\\\| null | yes | References header |\n| `message.conversationId` | string | | Outlook conversation ID |\n| `message.receivedDateTime` | string | | Received date-time in ISO format |\n| `message.hasAttachments` | boolean | | Whether the email has attachments |\n| `message.importance` | string | | Email importance level |\n| `message.isRead` | boolean | | Whether the email has been read |\n| `message.body` | object | yes | Email body |\n| `message.body.content` | string | yes | Body content |\n| `message.body.contentType` | "text" \\\\| "html" | yes | Body content type |\n| `message.attachments` | object[] | | Email attachments |\n| `message.attachments[].id` | string | yes | Outlook attachment ID |\n| `message.attachments[].fileName` | string | | Attachment filename as stored, which may differ from the sender\'s |\n| `message.attachments[].contentType` | string | | MIME type as stored, recovered from the filename when Graph declared a generic one |\n| `message.attachments[].size` | number | | Stored size in bytes |\n| `message.attachments[].file_id` | string | | Stored file ID \u2014 pass to view_files to read it, or to update_records to attach it (chat, MCP, CLI) |\n\n### outlook_reply_email (workflow step)\n\n- Draft or send a reply to an Outlook email.\n- Use reply_body (markdown) or template_id + template_data \u2014 not both.\n- Attach stored files by passing their file_ids.\n- Leaves an unsent draft unless draft is false.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | The Lotics connected account ID (cac_xxx), not the Microsoft user ID |\n| `original_message_id` | string | yes | |\n| `reply_body` | string | | Reply body (markdown). Mutually exclusive with template_id. |\n| `template_id` | string | | |\n| `template_data` | object | | |\n| `cc` | string | | CC recipients, comma-separated |\n| `bcc` | string | | BCC recipients, comma-separated |\n| `draft` | boolean | | Leave true to save an unsent draft the member reviews. Pass false only to deliver the message now \u2014 delivery is irreversible. |\n| `file_ids` | string[] | yes | |\n| `user_id` | string | | Mailbox user ID |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `message_id` | string | yes | The ID of the sent message or saved draft |\n| `subject` | string | yes | The subject as sent |\n| `html` | string | yes | The body as sent, rendered to HTML |\n| `markdown` | string | | The body as written in markdown; absent when a template rendered it |\n| `to` | string | yes | The original sender the reply went to |\n\n### outlook_send_email (workflow step)\n\n- Draft or send an Outlook email.\n- Use content (markdown) or template_id + template_data \u2014 not both.\n- Attach stored files by passing their file_ids.\n- Leaves an unsent draft unless draft is false, and while drafting \'to\' may be omitted to leave the recipient line for the member to fill in.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | The Lotics connected account ID (cac_xxx), not the Microsoft user ID |\n| `to` | string | | Recipient email(s), comma-separated. Required unless using a template. |\n| `subject` | string | | |\n| `cc` | string | | CC recipients, comma-separated |\n| `bcc` | string | | BCC recipients, comma-separated |\n| `content` | string | | Email body (markdown). Mutually exclusive with template_id. |\n| `template_id` | string | | |\n| `template_data` | object | | |\n| `draft` | boolean | | Leave true to save an unsent draft the member reviews. Pass false only to deliver the message now \u2014 delivery is irreversible. |\n| `file_ids` | string[] | yes | |\n| `user_id` | string | | Mailbox user ID |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `message_id` | string | yes | The ID of the sent message or saved draft |\n| `subject` | string | yes | The subject as sent |\n| `html` | string | yes | The body as sent, rendered to HTML |\n| `markdown` | string | | The body as written in markdown; absent when a template rendered it |\n| `to` | string \\\\| null | yes | The recipients as sent, comma-separated; null on a draft saved without recipients |\n\n## press\n\n### press_button (workflow step)\n\n- Run a button field\'s action against a record \u2014 equivalent to a user clicking the button in the UI.\n- Buttons are a legacy field type; the action must already be wired.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `table_id` | string | yes | |\n| `record_id` | string | yes | |\n| `field_key` | string | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `execution_id` | string | | |\n| `status` | "success" \\\\| "error" | | |\n| `message` | string | | |\n\n## rename\n\n### rename_file (workflow step)\n\n- Get a file under another name: a new file over the same bytes.\n- Write its file_id into the files field in place of the old one; every other place holding the old file keeps its name.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | |\n| `filename` | string | yes | The whole new name, keeping the file\'s extension exactly. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n## request\n\n### request_locked_record_change (workflow step)\n\n- Submit one change request to change locked field values on a record.\n- Include every blocked field in the same call \u2014 the approver accepts or rejects the change set as a whole.\n- Values are NOT changed immediately; an approver must accept the request first.\n- Returns `{ request_id, status }`.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `table_id` | string | yes | |\n| `record_id` | string | yes | |\n| `changes` | object | yes | Map of field_key to proposed new value. Every key must be locked on this record. |\n| `reason` | string | yes | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `request_id` | string | yes | |\n| `status` | "pending" | yes | |\n\n## save\n\n### save_file (workflow step)\n\n- Save a file from a URL to the workspace.\n- Max 20MB.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `url` | string | yes | Public URL to download the file from (https:// or http://). |\n| `filename` | string | | Filename with extension, e.g. \'report.pdf\'. Derived from URL if omitted. |\n| `mime_type` | string | | MIME type, e.g. \'application/pdf\'. Derived from URL response if omitted. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `id` | string | yes | File ID. |\n| `filename` | string | yes | |\n| `mime_type` | string | yes | |\n| `url` | string | yes | |\n\n### save_record (workflow step)\n\n- Save a record found by its identity, with its lines, all or nothing.\n- A call whose match is carried by no live record adds it; one carried by a record changes the cells of set that differ and appends add_to, so sending the same call twice writes nothing the second time. match holds the record\'s identity: field keys with their values, exactly the fields of one uniqueness its table declares (a unique field, or fields unique together). set holds its other cells. add_to lists items to append to a files, multi-select or many-link field, keeping what it holds. lines saves rows of other tables that link the record.\n- Each entry names the child table_id, its one-row link field to this table, match (the child fields that with link are one uniqueness of the child table) and rows, each stating every match field. link is set by the step and no row states it.\n- A line found by its match changes the cells that differ; one not found is added; a line not listed is left as it is.\n- Any refusal \u2014 a table check, a locked record, a value a field does not take, no write access to a table \u2014 saves nothing.\n- Returns { record_id, created, updated_field_keys, lines }: the cells changed on a record that existed, and per entry of lines the ids it added, changed and left unchanged.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `table_id` | string | yes | |\n| `match` | object | yes | |\n| `set` | object \\\\| null | | |\n| `add_to` | object \\\\| null | | |\n| `lines` | object[] \\\\| null | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `record_id` | string | yes | |\n| `created` | boolean | yes | |\n| `updated_field_keys` | string[] | yes | |\n| `lines` | object[] | yes | |\n| `lines[].table_id` | string | yes | |\n| `lines[].created_ids` | string[] | yes | |\n| `lines[].updated_ids` | string[] | yes | |\n| `lines[].unchanged_ids` | string[] | yes | |\n\n## send\n\n### send_notification (workflow step)\n\n- Notify workspace members.\n- Lotics shows it to each recipient and emails it to their own address, through no connection; a member who signs in with an identifier an admin issued has no mailbox and sees it in Lotics alone.\n- A member is named by the member_id get_workspace kind member lists. (chat, MCP, CLI)\n- In a workflow body, every member is { type: "organization", id: runtime.organization_id } and the member who started the run { type: "member", id: runtime.triggered_by_member_id }; a run a schedule, a webhook or an email starts was started by no member. blocks draw under the message: text, stat, chart, fields, link, and record (table_id and record_id; the card shows the record\'s own title, read as the sender can read it). actions are buttons: each runs workflow_id under its owner\'s access when pressed, and its owner or an admin may name it.\n- A workflow a card can run declares notification inputs. inputs are the values the sender fixes; asks are the values the presser answers, each ask key an input of the workflow that inputs does not fix; every required input of the workflow is fixed or asked as required. decision is "any" (one decision for all recipients: the first press decides it) or "each" (every recipient decides alone); it is required with actions and refused without.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `recipients` | any[] | yes | List of recipients. Each entry is a principal: { type: \'member\', id } \\| { type: \'member_group\', id } \\| { type: \'organization\', id } |\n| `title` | string | yes | |\n| `body` | string | yes | |\n| `blocks` | any[] | | |\n| `actions` | object[] | | |\n| `actions[].key` | string | yes | |\n| `actions[].label` | string | yes | |\n| `actions[].confirm` | string | | |\n| `actions[].outcome` | "negative" | | Pressing it declines what the card asks: the button is drawn after the others, and the decided card ends with a cross rather than a check |\n| `actions[].asks` | any[] | | |\n| `actions[].workflow_id` | string | yes | |\n| `actions[].inputs` | object | yes | |\n| `decision` | "any" \\\\| "each" | | |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `message` | string | yes | |\n| `recipients_count` | number | yes | |\n\n## telegram\n\n### telegram_list_chats (workflow step)\n\n- List the chats that messaged a Telegram bot, or added it, in the last 24 hours \u2014 where a chat id comes from.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Telegram connected account |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `chats` | object[] | yes | |\n| `chats[].chat_id` | string | yes | |\n| `chats[].type` | string | yes | private, group, supergroup or channel |\n| `chats[].name` | string | yes | |\n| `chats[].username` | string | | |\n| `chats[].last_seen_at` | string | yes | ISO timestamp of the chat\'s latest update |\n\n### telegram_send_document (workflow step)\n\n- Send a stored file from a Telegram bot to a chat, as a document with an optional caption.\n- The chat must have messaged the bot first.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Telegram connected account |\n| `chat_id` | string | yes | Numeric chat id, or the @username of a public channel or group |\n| `file_id` | string | yes | |\n| `caption` | string | | |\n| `parse_mode` | "HTML" \\\\| "MarkdownV2" | | How the text is formatted: Telegram\'s HTML tags or its MarkdownV2 syntax |\n| `disable_notification` | boolean | | Deliver without a notification sound |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `message_id` | number | yes | |\n| `chat_id` | string | yes | |\n| `sent_at` | string | yes | ISO timestamp |\n\n### telegram_send_message (workflow step)\n\n- Send a text message from a Telegram bot to a chat.\n- The chat must have messaged the bot first.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Telegram connected account |\n| `chat_id` | string | yes | Numeric chat id, or the @username of a public channel or group |\n| `text` | string | yes | |\n| `parse_mode` | "HTML" \\\\| "MarkdownV2" | | How the text is formatted: Telegram\'s HTML tags or its MarkdownV2 syntax |\n| `disable_notification` | boolean | | Deliver without a notification sound |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `message_id` | number | yes | |\n| `chat_id` | string | yes | |\n| `sent_at` | string | yes | ISO timestamp |\n\n## threads\n\n### threads_create_post (workflow step)\n\n- Publish a post to the connected Threads account.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | |\n| `text` | string | yes | |\n| `link` | string | | Shown as a link card. A post carries either a link or media. |\n| `media_file_ids` | string[] | | One image or video, or 2\u201320 images and videos as a carousel. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `post_id` | string | yes | |\n| `url` | string | yes | |\n\n## vietcombank\n\n### vietcombank_convert_currency (workflow step)\n\n- Convert between currencies using live Vietcombank exchange rates.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `from_currency` | string | yes | Source currency code (e.g., \'USD\', \'EUR\', \'JPY\') |\n| `to_currency` | string | yes | Target currency code (e.g., \'USD\', \'EUR\', \'JPY\') |\n| `amount` | number | yes | The amount to convert (must be positive) |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `converted_amount` | number | yes | The converted amount |\n| `exchange_rate` | number | yes | The exchange rate |\n\n## wininvoice\n\n### wininvoice_create_or_update_invoice (workflow step)\n\n- Create or update a Vietnamese e-invoice in WinInvoice. invRef identifies the invoice: a value that already has one resolves to that invoice rather than issuing a new one, and isExisting: 1 means it came back unchanged with nothing issued.\n- Derive invRef from what is being billed rather than from a record that may later describe something else.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `invName` | string | yes | Invoice sample name, ex: 1,2,6 |\n| `invSerial` | string | yes | Invoice sign, ex: C24TAA, K24TXX |\n| `invNumber` | string | yes | Invoice number |\n| `invDate` | string | yes | Invoice date (format: yyyy/mm/dd) |\n| `invCustomer` | 0 \\\\| 1 | | Customer is not company? Value 1\\|0 |\n| `invRef` | string | yes | 3rd party Bill-ID. Identifies the invoice: a value that already has an invoice resolves to that invoice instead of issuing a new one |\n| `invRefDate` | string | | Bill date (format: yyyy/mm/dd) |\n| `billNumber` | string | | Bill number - extend |\n| `buyerTax` | string | | Buyer tax-number |\n| `buyerCode` | string | | Buyer-id |\n| `buyerName` | string | yes | Buyer full name |\n| `buyerCompany` | string | | Buyer company/ organization name |\n| `buyerAddress` | string | | Buyer full address |\n| `buyerAcc` | string | | Buyer bank account number |\n| `buyerBank` | string | | Buyer bank name |\n| `buyerEmail` | string | | Buyer email |\n| `buyerPhone` | string | | Buyer phone number |\n| `buyerFax` | string | | Buyer fax number |\n| `buyerCitizenIDNumber` | string | | Citizen Identification Number |\n| `buyerPassportNumber` | string | | Passport Number |\n| `govUnitCode` | string | | Budget-related Unit Code |\n| `invSubTotal` | number | yes | Invoice Subtotal (not include VAT, not include discount) |\n| `invVatRate` | number | yes | VAT Rate: 0,5,8,10 (0%,5%,8%,10%), -1 (Not taxable), -2 (Not declare and pay taxes) |\n| `invVatAmount` | number | yes | VAT Amount |\n| `invTotalAmount` | number | yes | Invoice Total |\n| `invPayment` | string | | Payment method |\n| `invExchangeRate` | number | | Exchange rate (to VietNam \u0111\u1ED3ng) |\n| `invCurrency` | string | | Payment currency |\n| `note` | string | | Note for discount |\n| `invAutoSign` | 0 \\\\| 1 | | Request sign invoice immediately after create successful? Value 1\\|0 |\n| `privateCode` | string | | The UID string (10-12 chars), the buyer will use this code to lookup invoice (after invoice signed). If blank, WinInvoice will generate automatically |\n| `option` | 0 \\\\| 1 \\\\| 2 \\\\| 3 \\\\| 4 | | Invoice type: 0 (Normal invoice), 1 (Information-adjustment invoice), 2 (Increases-adjustment invoice), 3 (Decreases-adjustment invoice), 4 (Replacement invoice - original will be marked as deleted when signed) |\n| `invCodeOld` | string | | Original invoice number (required for adjustment/replacement invoices) |\n| `invNameOld` | string | | Original invoice sample name (required for adjustment/replacement invoices) |\n| `invSignOld` | string | | Original invoice sign (required for adjustment/replacement invoices) |\n| `create04SSHDDT` | 0 \\\\| 1 | | Auto create 04/SS-H\u0110\u0110T? Value 1\\|0 (default 1) |\n| `reason04SSHDDT` | string | | 04/SS-H\u0110\u0110T Reason |\n| `isDscnForSaleInv` | 0 \\\\| 1 | | Apply an 8% tax reduction to the sales invoice? Value 1\\|0 (default 0) |\n| `saleInvVATRate` | number | | Tax rate based on revenue (Only applicable when isDscnForSaleInv = 1) |\n| `saleInvDscnAmnt` | number | | The reduction amount determined based on revenue and corresponding tax rate (Only applicable when isDscnForSaleInv = 1) |\n| `privateNote` | string | | Used for internal notes |\n| `items` | object[] | yes | Array of item/product in this bill |\n| `items[].itemNo` | string | | Item number |\n| `items[].itemCode` | string | | Product/Item code |\n| `items[].itemName` | string | yes | Name of product |\n| `items[].itemPromo` | 0 \\\\| 1 | | Is promotional product (gift)? Value 1\\|0 (default 0) |\n| `items[].isDscnItem` | 0 \\\\| 1 | | Is the discount line? Value 1\\|0 (default 0) |\n| `items[].itemUnit` | string | | Product Unit |\n| `items[].itemQuantity` | number | yes | Product quantity |\n| `items[].itemPrice` | number | yes | Product unit price (not include VAT) |\n| `items[].itemVatRate` | number | | Product VAT rate |\n| `items[].itemVatAmnt` | number | | Product VAT Amount |\n| `items[].itemDscnAmnt` | number | | Product Discount Amount |\n| `items[].itemAmountNoVat` | number | | Product Amount (not include VAT)(not include item discount) |\n| `items[].adjustType` | "PRICE" \\\\| "QTTY" | | Type of adjustment: PRICE (Adjust unit price of item in original invoice), QTTY (Adjust quantity of item in original invoice). This field has effect when value of option field is 2 or 3 |\n| `items[].itemPack` | string | | Product Lot |\n| `items[].itemDate` | string | | Product expiration date |\n| `items[].itemNote` | string | | Product note |\n| `items[].specialGoodsType` | 0 \\\\| 1 \\\\| 2 \\\\| 3 | | Special category of goods: 0 (Normal item/good), 1 (Cars or motorcycles), 2 (Transportation service), 3 (Transportation services on digital and e-commerce platforms) |\n| `items[].specialGoodsInfo` | object | | Data requirements for specialized goods based on specialGoodsType |\n| `items[].specialGoodsInfo.chassisNumb` | string | | Chassis Number (for cars/motorcycles - specialGoodsType = 1) |\n| `items[].specialGoodsInfo.engineNumb` | string | | Engine Number (for cars/motorcycles - specialGoodsType = 1) |\n| `items[].specialGoodsInfo.licensePlate` | string | | License plate of the transport vehicle (for transportation service - specialGoodsType = 2) |\n| `items[].specialGoodsInfo.senderName` | string | | Sender\'s Name (for shipping service - specialGoodsType = 3) |\n| `items[].specialGoodsInfo.senderAddress` | string | | Sender\'s Address (for shipping service - specialGoodsType = 3) |\n| `items[].specialGoodsInfo.senderTaxCode` | string | | Sender\'s Tax Code (for shipping service - specialGoodsType = 3) |\n| `items[].specialGoodsInfo.senderCitizenIDNumber` | string | | Sender\'s Citizen Identification Number (for shipping service - specialGoodsType = 3) |\n| `items[].isNoteItem` | 0 \\\\| 1 | | Is the note line? Value 1\\|0 (default 0) |\n| `connected_account_id` | string | yes | The ID of the connected account |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `oid` | string | yes | WinInvoice\'s UID |\n| `invCode` | string | yes | Invoice number (is \'0000000\' if has not signed) |\n| `invRef` | string | yes | 3rd party Bill-ID |\n| `invSign` | string | yes | Invoice sign, (as invSerial) |\n| `invDate` | string | yes | Invoice date, format yyyy-mm-dd |\n| `invName` | string | yes | Full invoice sample (invName + invSign) |\n| `privateCode` | string | yes | Private lookup code for buyer |\n| `itemTotal` | number | | Count of products in invoice |\n| `itemError` | number | | Count of error-products in invoice |\n| `govTranfer` | number | yes | Invoice has transferred to GOV? 1\\|0 |\n| `govTranID` | string | yes | Transaction ID used to transfer invoice to GOV |\n| `govTranferErr` | number | yes | ansferred to GOV has FAIL? 1\\|0 |\n| `govTranText` | string | yes | Error message if transfer to GOV has FAIL |\n| `govCode` | string | yes | The UID string issue by GOV for this invoice |\n| `autoSign` | number | | Has request sign immediately ? 1\\|0 |\n| `isExisting` | 0 \\\\| 1 | | 1 when invRef already had an invoice and this call returned it unchanged \u2014 no invoice was issued |\n| `link` | string | yes | Link to view the invoice |\n\n## x\n\n### x_create_post (workflow step)\n\n- Publish a post to the connected X account.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | |\n| `text` | string | yes | |\n| `media_file_ids` | string[] | | Up to 4 images, or one GIF, or one video. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `post_id` | string | yes | |\n| `url` | string | yes | |\n\n## zip\n\n### zip_files (workflow step)\n\n- Bundle multiple files into a zip archive.\n- Max 100 files.\n- An item in file_ids is a file id \u2014 or `{ id, name }` to name that entry in the archive: a file name, never a path, carrying the stored extension.\n- A bare id keeps the stored filename.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_ids` | string \\\\| object[] | yes | |\n| `filename` | string | | Name for the zip file, without the .zip extension. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n';
|
|
1910
1910
|
|
|
1911
1911
|
// docs/app_bindings.md
|
|
1912
|
-
var app_bindings_default = "# App bindings \u2014 the queries and workflows an app calls\n\nA custom-code app reaches workspace data through two kinds of binding, each declared on the app\nunder an alias \u2014 a JS identifier (`/^[a-zA-Z_$][a-zA-Z0-9_$]*$/`):\n\n| Binding | Declared with | The app calls it with | An agent calls it with |\n|---|---|---|---|\n| Query | `set_app`, a `Query` node | `useQuery(\"<alias>\", params?)` | `run_app_query` |\n| Workflow | `set_workflow` | `useWorkflow(\"<alias>\")({ ...inputs })` | `run_app_workflow` |\n\nEach runs under the app's authority (`{ type: \"app\", app_id }`), the app owner's reach \u2014 never the\ncalling member's. Declaring one needs the app's owner or an admin. A write is live: the app's next\ncall uses it. `get_app` lists an app's aliases with their params and inputs.\n\nEach reader returns a fingerprint of what it read, and a write built on that read passes it back:\n`get_workflow`'s `version` as `set_workflow`'s `expected_version`, and `get_app`'s version as `set_app`'s\n`base_version_id`. The write is refused, and writes nothing, when it changed since; omit it for an unconditional write.\n\n## API apps\n\nAn API app is one a customer's own server calls. It holds only `Query` and `Workflow` nodes, so no address serves it, and it cannot be shared publicly.\n\n1. `set_app` with a tree of those nodes, naming the tables they read in `uses`. The answer carries the link where an admin creates its key, and `get_app` states it again.\n2. `set_workflow` sets each workflow's code.\n3. An admin opens the link and creates an app key (`lak_\u2026`). It reaches this app alone and only calls it; no other route and no tool answers it, and that can never be widened. Its secret is shown once, so it goes straight into the server's secrets, and no tool creates or reads one.\n4. To promise the shape to that server, an admin's `set_app` states `{ \"app_id\": \"\u2026\", \"api_published\": true }`: a numbered contract and an OpenAPI document, and a later write that would break it is refused.\n\nThe server sends `Authorization: Bearer lak_\u2026` to `POST /v1/apps/{app_id}/queries/{alias}` and `POST /v1/apps/{app_id}/workflows/{alias}/execute`. The answer holds what the app declares, with each row's own id and timestamps: no member's email, no field id, and a failed run a generic message beside its `execution_id`. A browser cannot call them, and a key never goes in a page.\n\nA `Query` node reads one table or List with `rows` or `list`. A wider read states the whole query as `ast`, below.\n\n## Queries\n\nA query declaration is `{ ast, params?, description?, templates? }`:\n\n- `ast` \u2014 a query template (a QueryNode, below). It fixes the tables, filters and columns the alias\n reads, so a caller cannot widen it.\n- `params` \u2014 the typed value holes the caller fills, each an input declaration (see **Inputs**),\n named in the ast as `{{params.<name>}}`. A param fills a VALUE position only \u2014 a filter value, a\n `search` \u2014 never a `table_id` or a field key. Every token the ast names is declared. An optional\n param left unset drops the conditions that read it; a required param that arrives empty is\n refused where a filter reads it.\n- `description` \u2014 one line saying what the query returns, for an agent choosing between aliases.\n- `templates` \u2014 the document templates an export of its rows may fill, by name:\n `{ <name>: { template_id: \"dtl_\u2026\", rows: \"<key the template lists the rows under>\" } }`.\n\nA save checks what a deploy checks: every table is in this workspace and within the owner's reach,\nevery projected, filtered and sorted field resolves, every param token is declared, and a key a\nnode's kind does not take (a stray `sort`, `limit`, `filter`, `search`) is refused by name.\n\n`set_app` states one as a `Query` node: `{ \"type\": \"Query\", \"key\": \"<alias>\", \"ast\": { \u2026 } }`, beside `params`,\n`description` and `templates`. On an app made from a tree it stands among the tree's `children`, and a `nodes` patch\nreplaces its `ast`, `params` or `templates` whole. On an app that serves\ncode, `nodes` takes `{ \"<alias>\": { \u2026 } }` and merges each: send only the fields you change, `null` clears `params`,\n`description` or `templates` (never `ast`), a new alias needs an `ast`, and an alias set to `null` is unbound. Its\n`children` state the list whole, each query entire, and an alias they omit is unbound. Any other field is refused by\nname, and `get_app`'s `body` reads them back by alias.\n\n### The query tree\n\nEvery node has a `kind`; all but `from_table` read the node under `from` (`join`: `left`/`right`,\n`union`: `sources`).\n\n| `kind` | Keys |\n|---|---|\n| `from_table` | `table_id`, `filter?`, `search?`, `sort?`, `limit?` |\n| `project` | `columns` \u2014 the output columns |\n| `filter` | `predicate` \u2014 a filter tree over the input's columns |\n| `join` | `left`, `right`, `on: { left_column, right_column }`, `type: \"inner\" \\| \"left\"` |\n| `union` | `sources` (at least two, columns aligned by name and type) |\n| `group` | `by` (columns, `{ bucket: { source, granularity, output } }`, or `{ band: { source, tiers, output } }`), `aggregates` |\n| `window` | `partition_by`, `order_by`, `frame?`, `aggregates?`, `functions?` |\n| `sort` | `by: [{ field_key, order }]` |\n| `limit` | `n`, `offset?` or `keyset?` |\n| `unpivot` | `passthrough`, `row_columns`, `rows` \u2014 one source row into several |\n| `unnest` | `source`, `output`, `display_output?`, `keep_empty?` \u2014 one row per element of a multi-value cell |\n\nFilters (`from_table.filter`, `filter.predicate`, an aggregate's `filter`) are the filter grammar \u2014 the\n`filters` reference \u2014 over the input's columns, taking `{{params.x}}` as values. `search` matches\nevery text-bearing field of the row, accent- and case-insensitive.\n\nA query names a table's fields by the alias its document states, wherever a node reads the table directly (a\n`from_table`'s filter and sort, the `project`, `filter`, `group`, `window`, `unnest` or `unpivot` over it) and a select\ncondition's values by the option's alias. A column a `project` writes answers under the alias it was written with; every\nname past a `project` or an aggregate is that column's own. A `union` whose arms read one alias from different tables\nprojects each arm's columns under one name first. The query is stored by key and read back by alias.\n\nA `project` column is a field's alias as a bare string (output name and type come from the field), or\n`{ output?, type?, source, writable_target?, limit? }` to rename, compute or bound one. A computed\n`source` is a field's alias, `{ literal }`, `{ eq: [a, b] }`, `{ neq: [a, b] }`, `{ isEmpty }`,\n`{ isNotEmpty }`, `{ coalesce: [...] }`, `{ concat: [...] }`, `{ record_id: true }`,\n`{ link: { source, field } }` (a field of the first linked record),\n`{ link_agg: { source, field, operation } }` (`sum`, `avg`, `min`, `max`, `count`, `string_agg`\nover every linked record), or `{ expression }`. A computed column states its `type`: `text`,\n`number`, `boolean`, `date`, `datetime`, `select`, `select_record_link`, `select_member`, `files`\nor `json`. `limit` (1\u201310) bounds a `files` column's entries per cell.\n\nAn aggregate column is `{ output, type, operation, input_column?, filter? }` \u2014 `string_agg` also\ntakes `separator`, `distinct` and `max_values`. A `window` function is\n`{ output, fn }` for `row_number`, `rank`, `dense_rank`, `percent_rank`, `cume_dist`, plus\n`buckets` for `ntile` and `input_column`, `offset?`, `default?` for `lag` / `lead`; functions need\na non-empty `order_by`.\n\n## Inputs\n\nA query's `params`, a workflow's `inputs` and an agent's `inputs` are one vocabulary: a map of\nname \u2192 `{ type, required?, description?, \u2026per type }`. An entry is required unless it states\n`required: false`.\n\n| `type` | Takes |\n|---|---|\n| `text`, `number`, `boolean`, `date`, `datetime`, `email` | \u2014 |\n| `record_link` | `table_id`; `multi?`; `max?` (with `multi`, the most ids one call carries) |\n| `select` | exactly one of `options: [{ label, value }]` or `field: \"<table id>.<alias>\"` (a select field whose CURRENT options back it); `multi?` |\n| `date_range` | `include_time?` |\n| `member` | `multi?`; `group?` (a member group the value must belong to) |\n| `file` | `multi?` \u2014 an uploaded `fil_\u2026` id, for a files field |\n| `json` | \u2014 any value |\n| `object` | `fields` \u2014 a nested map of entries |\n| `array` | `items` \u2014 one entry |\n\nNesting stops at depth 8. A `field`-form select tracks the field's options as they change; an\ninline `options` set is a fixed list. A query's select param takes an option by alias, label or key, each condition reading it by its own field's options, and a value that is none of them is refused naming the options.\n\n## Outputs\n\nA workflow's and an agent's `outputs` declare the structured data handed back: a map of\nname \u2192 `{ type, required?, description?, \u2026per type }`, every entry present unless it states\n`required: false`.\n\n| `type` | Takes |\n|---|---|\n| `text`, `number`, `boolean`, `date`, `datetime`, `email`, `json` | \u2014 |\n| `record_link` | `table_id`, `multi?` |\n| `select` | exactly one of `options: [{ label, value }]` or `field: \"<table id>.<alias>\"`; `multi?` |\n| `object` | `fields` |\n| `array` | `items` |\n\nThe returned value is checked against it, and the app reads it typed. An inline `options` set is\nalso enforced on the value returned, so the producer is told the legal keys; a `field`-form select\nkeeps the type tracking the live field.\n\n## Workflows\n\n`set_workflow` binds a workflow body to an alias: `{ workflow_id?, name?, description?, source }`, the `source`\nopening with `on({ type: \"app\", app_id, alias, inputs?, outputs? })`. Without a `workflow_id` it binds the alias; with\nthe one `get_app` lists for it, it replaces the body. On an app written as a tree the alias is one the tree names \u2014 a Workflow node's\n`key` or an Act's `workflow` \u2014 and the node states `inputs`, `outputs` and `description`\n(`reference/workflow-node`, whose value shapes differ from the **Inputs** below): a call stating any of\nthem for it is refused, and outputs the node leaves out are derived from the body. An alias the tree\nnames nowhere is archived by the next `set_app`. `set_app`'s `workflows` takes the same sources and saves them in the\nsame write as the tree: a change to what a workflow takes or hands back that its saved body no longer meets is refused\nunless the write carries the new body. A Workflow node runs only for someone who holds the\napp: on an app shared by a public link, a visitor's call of it is refused as an alias the app does\nnot have. This page's `inputs` and `outputs` are for a custom-code app.\n\n- `source` is the header, then the body; the app is the trigger. The body reads each declared\n input as `trigger.app_workflow.inputs.<name>`; no record is in scope, so it reads each one by id\n with `query_records` and `record_ids`.\n The body's steps are the `workflows` reference.\n- `inputs` in the header is the payload the call site passes (see **Inputs**). Omitted, an existing workflow keeps\n its inputs; on a first bind it takes an untyped payload. `{}` clears them.\n- `outputs` in the header is what `return({ data })` hands back (see **Outputs**). Usually omit it: the type is\n derived from the body's `return({ data })`, and the result echoes the bound `outputs`. Declared,\n the body does not save unless its return matches.\n- A save checks the body \u2014 parse, type-check against the declared inputs, names, lint, structure \u2014\n and answers with `[source/code] location: message` lines. `dry_run: true` makes every check\n and writes nothing. A call naming a live alias replaces its body in place, keeping its run history.\n- A call whose payload does not match `inputs` is refused before the body runs.\n\n`get_workflow` reads the source back; `set_workflow` with `dry_run` and `record_id` or `preview_inputs`\nrehearses a draft before binding; `set_workflow` with `delete: true` and the `workflow_id` unbinds it. An unbind is refused\nwhile the deployed version of the app calls the alias or an agent of the app declares it (`even_if_invoked` overrides it for a\nworkflow that has run, only when the caller that ran it is gone).\n";
|
|
1912
|
+
var app_bindings_default = "# App bindings \u2014 the queries and workflows an app calls\n\nA custom-code app reaches workspace data through two kinds of binding, each declared on the app\nunder an alias \u2014 a JS identifier (`/^[a-zA-Z_$][a-zA-Z0-9_$]*$/`):\n\n| Binding | Declared with | The app calls it with | An agent calls it with |\n|---|---|---|---|\n| Query | `set_app`, a `Query` node | `useQuery(\"<alias>\", params?)` | `run_app_query` |\n| Workflow | `set_workflow` | `useWorkflow(\"<alias>\")({ ...inputs })` | `run_app_workflow` |\n\nEach runs under the app's authority (`{ type: \"app\", app_id }`), the app owner's reach \u2014 never the\ncalling member's. Declaring one needs the app's owner or an admin. A write is live: the app's next\ncall uses it. `get_app` lists an app's aliases with their params and inputs.\n\nEach reader returns a fingerprint of what it read, and a write built on that read passes it back:\n`get_workflow`'s `version` as `set_workflow`'s `expected_version`, and `get_app`'s version as `set_app`'s\n`base_version_id`. The write is refused, and writes nothing, when it changed since; omit it for an unconditional write.\n\n## API apps\n\nAn API app is one a customer's own server calls. It holds only `Query` and `Workflow` nodes, so no address serves it, and it cannot be shared publicly.\n\n1. `set_app` with a tree of those nodes, naming the tables they read in `uses`. The answer carries the link where an admin creates its key, and `get_app` states it again.\n2. `set_workflow` sets each workflow's code.\n3. An admin opens the link and creates an app key (`lak_\u2026`). It reaches this app alone and only calls it; no other route and no tool answers it, and that can never be widened. Its secret is shown once, so it goes straight into the server's secrets, and no tool creates or reads one.\n4. To promise the shape to that server, an admin's `set_app` states `{ \"app_id\": \"\u2026\", \"api_published\": true }`: a numbered contract and an OpenAPI document, and a later write that would break it is refused.\n\nThe server sends `Authorization: Bearer lak_\u2026` to `POST /v1/apps/{app_id}/queries/{alias}` and `POST /v1/apps/{app_id}/workflows/{alias}/execute`. The answer holds what the app declares, with each row's own id and timestamps: no member's email, no field id, and a failed run a generic message beside its `execution_id`. A browser cannot call them, and a key never goes in a page.\n\nA `Query` node reads one table or List with `rows` or `list`. A wider read states the whole query as `ast`, below.\n\n## Queries\n\nA query declaration is `{ ast, params?, description?, templates? }`:\n\n- `ast` \u2014 a query template (a QueryNode, below). It fixes the tables, filters and columns the alias\n reads, so a caller cannot widen it.\n- `params` \u2014 the typed value holes the caller fills, each an input declaration (see **Inputs**),\n named in the ast as `{{params.<name>}}`. A param fills a VALUE position only \u2014 a filter value, a\n `search` \u2014 never a `table_id` or a field key. Every token the ast names is declared. An optional\n param left unset drops the conditions that read it; a required param that arrives empty is\n refused where a filter reads it.\n- `description` \u2014 one line saying what the query returns, for an agent choosing between aliases.\n- `templates` \u2014 the document templates an export of its rows may fill, by name:\n `{ <name>: { template_id: \"dtl_\u2026\", rows: \"<key the template lists the rows under>\" } }`.\n\nA save checks what a deploy checks: every table is in this workspace and within the owner's reach,\nevery projected, filtered and sorted field resolves, every param token is declared, and a key a\nnode's kind does not take (a stray `sort`, `limit`, `filter`, `search`) is refused by name.\n\n`set_app` states one as a `Query` node: `{ \"type\": \"Query\", \"key\": \"<alias>\", \"ast\": { \u2026 } }`, beside `params`,\n`description` and `templates`. On an app made from a tree it stands among the tree's `children`, and a `nodes` patch\nreplaces its `ast`, `params` or `templates` whole. On an app that serves\ncode, `nodes` takes `{ \"<alias>\": { \u2026 } }` and merges each: send only the fields you change, `null` clears `params`,\n`description` or `templates` (never `ast`), a new alias needs an `ast`, and an alias set to `null` is unbound. Its\n`children` state the list whole, each query entire, and an alias they omit is unbound. Any other field is refused by\nname, and `get_app`'s `body` reads them back by alias.\n\n### The query tree\n\nEvery node has a `kind`; all but `from_table` read the node under `from` (`join`: `left`/`right`,\n`union`: `sources`).\n\n| `kind` | Keys |\n|---|---|\n| `from_table` | `table_id`, `filter?`, `search?`, `sort?`, `limit?` |\n| `project` | `columns` \u2014 the output columns |\n| `filter` | `predicate` \u2014 a filter tree over the input's columns |\n| `join` | `left`, `right`, `on: { left_column, right_column }`, `type: \"inner\" \\| \"left\"` |\n| `union` | `sources` (at least two, columns aligned by name and type) |\n| `group` | `by` (columns, `{ bucket: { source, granularity, output } }`, or `{ band: { source, tiers, output } }`), `aggregates` |\n| `window` | `partition_by`, `order_by`, `frame?`, `aggregates?`, `functions?` |\n| `sort` | `by: [{ field_key, order }]` |\n| `limit` | `n`, `offset?` or `keyset?` |\n| `unpivot` | `passthrough`, `row_columns`, `rows` \u2014 one source row into several |\n| `unnest` | `source`, `output`, `display_output?`, `keep_empty?` \u2014 one row per element of a multi-value cell |\n\nFilters (`from_table.filter`, `filter.predicate`, an aggregate's `filter`) are the filter grammar \u2014 the\n`filters` reference \u2014 over the input's columns, taking `{{params.x}}` as values. `search` matches\nevery text-bearing field of the row, accent- and case-insensitive.\n\nA query names a table's fields by the alias its document states, wherever a node reads the table directly (a\n`from_table`'s filter and sort, the `project`, `filter`, `group`, `window`, `unnest` or `unpivot` over it) and a select\ncondition's values by the option's alias. A column a `project` writes answers under the alias it was written with; every\nname past a `project` or an aggregate is that column's own. A `union` whose arms read one alias from different tables\nprojects each arm's columns under one name first. The query is stored by key and read back by alias.\n\nA `project` column is a field's alias as a bare string (output name and type come from the field), or\n`{ output?, type?, source, writable_target?, limit? }` to rename, compute or bound one. A computed\n`source` is a field's alias, `{ literal }`, `{ eq: [a, b] }`, `{ neq: [a, b] }`, `{ isEmpty }`,\n`{ isNotEmpty }`, `{ coalesce: [...] }`, `{ concat: [...] }`, `{ record_id: true }`,\n`{ link: { source, field } }` (a field of the first linked record),\n`{ link_agg: { source, field, operation } }` (`sum`, `avg`, `min`, `max`, `count`, `string_agg`\nover every linked record), or `{ expression }`. A computed column states its `type`: `text`,\n`number`, `boolean`, `date`, `datetime`, `select`, `select_record_link`, `select_member`, `files`\nor `json`. `limit` (1\u201310) bounds a `files` column's entries per cell.\n\nAn aggregate column is `{ output, type, operation, input_column?, filter? }` \u2014 `string_agg` also\ntakes `separator`, `distinct` and `max_values`. A `window` function is\n`{ output, fn }` for `row_number`, `rank`, `dense_rank`, `percent_rank`, `cume_dist`, plus\n`buckets` for `ntile` and `input_column`, `offset?`, `default?` for `lag` / `lead`; functions need\na non-empty `order_by`.\n\n## Inputs\n\nA query's `params`, a workflow's `inputs` and an agent's `inputs` are one vocabulary: a map of\nname \u2192 `{ type, required?, description?, \u2026per type }`. An entry is required unless it states\n`required: false`.\n\n| `type` | Takes |\n|---|---|\n| `text`, `number`, `boolean`, `date`, `datetime`, `email` | \u2014 |\n| `record_link` | `table_id`; `multi?`; `max?` (with `multi`, the most ids one call carries) |\n| `select` | exactly one of `options: [{ label, value }]` or `field: \"<table id>.<alias>\"` (a select field whose CURRENT options back it); `multi?` |\n| `date_range` | `include_time?` |\n| `member` | `multi?`; `group?` (a member group the value must belong to) |\n| `file` | `multi?` \u2014 an uploaded `fil_\u2026` id, for a files field |\n| `json` | \u2014 any value |\n| `object` | `fields` \u2014 a nested map of entries |\n| `array` | `items` \u2014 one entry |\n\nA `record_link`'s `table_id`, in inputs and outputs, takes the table's id or alias and is stored as its id. Nesting stops at\ndepth 8. A `field`-form select tracks the field's options as they change; an\ninline `options` set is a fixed list. A query's select param takes an option by alias, label or key, each condition reading it by its own field's options, and a value that is none of them is refused naming the options.\n\n## Outputs\n\nA workflow's and an agent's `outputs` declare the structured data handed back: a map of\nname \u2192 `{ type, required?, description?, \u2026per type }`, every entry present unless it states\n`required: false`.\n\n| `type` | Takes |\n|---|---|\n| `text`, `number`, `boolean`, `date`, `datetime`, `email`, `json` | \u2014 |\n| `record_link` | `table_id`, `multi?` |\n| `select` | exactly one of `options: [{ label, value }]` or `field: \"<table id>.<alias>\"`; `multi?` |\n| `object` | `fields` |\n| `array` | `items` |\n\nThe returned value is checked against it, and the app reads it typed. An inline `options` set is\nalso enforced on the value returned, so the producer is told the legal keys; a `field`-form select\nkeeps the type tracking the live field.\n\n## Workflows\n\n`set_workflow` binds a workflow body to an alias: `{ workflow_id?, name?, description?, source }`, the `source`\nopening with `on({ type: \"app\", app_id, alias, inputs?, outputs? })`. Without a `workflow_id` it binds the alias; with\nthe one `get_app` lists for it, it replaces the body. On an app written as a tree the alias is one the tree names \u2014 a Workflow node's\n`key` or an Act's `workflow` \u2014 and the node states `inputs`, `outputs` and `description`\n(`reference/workflow-node`, whose value shapes differ from the **Inputs** below): a call stating any of\nthem for it is refused, and outputs the node leaves out are derived from the body. An alias the tree\nnames nowhere is archived by the next `set_app`. `set_app`'s `workflows` takes the same sources and saves them in the\nsame write as the tree: a change to what a workflow takes or hands back that its saved body no longer meets is refused\nunless the write carries the new body. A Workflow node runs only for someone who holds the\napp: on an app shared by a public link, a visitor's call of it is refused as an alias the app does\nnot have. This page's `inputs` and `outputs` are for a custom-code app.\n\n- `source` is the header, then the body; the app is the trigger. The body reads each declared\n input as `trigger.app_workflow.inputs.<name>`; no record is in scope, so it reads each one by id\n with `query_records` and `record_ids`.\n The body's steps are the `workflows` reference.\n- `inputs` in the header is the payload the call site passes (see **Inputs**). Omitted, an existing workflow keeps\n its inputs; on a first bind it takes an untyped payload. `{}` clears them.\n- `outputs` in the header is what `return({ data })` hands back (see **Outputs**). Usually omit it: the type is\n derived from the body's `return({ data })`, and the result echoes the bound `outputs`. Declared,\n the body does not save unless its return matches.\n- A save checks the body \u2014 parse, type-check against the declared inputs, names, lint, structure \u2014\n and answers with `[source/code] location: message` lines. `dry_run: true` makes every check\n and writes nothing. A call naming a live alias replaces its body in place, keeping its run history.\n- A call whose payload does not match `inputs` is refused before the body runs.\n\n`get_workflow` reads the source back; `set_workflow` with `dry_run` and `record_id` or `preview_inputs`\nrehearses a draft before binding; `set_workflow` with `delete: true` and the `workflow_id` unbinds it. An unbind is refused\nwhile the deployed version of the app calls the alias or an agent of the app declares it (`even_if_invoked` overrides it for a\nworkflow that has run, only when the caller that ran it is gone).\n";
|
|
1913
1913
|
|
|
1914
1914
|
// docs/document_templates.md
|
|
1915
1915
|
var document_templates_default = '# Document Templates\n\nTurn workspace data into finished documents \u2014 invoices, contracts, reports, letters,\nlabels, emails \u2014 by filling a reusable template instead of writing a file from scratch.\nYou register a template once, then generate a filled file (or a rendered email) from it as\nmany times as you like, feeding it data from records, a workflow, or an agent run.\n\nThis is a **capability + usage** guide. A tool\'s exact input schema is in its own description.\n\n## The five template types\n\n`set_template` writes all five. Its `type` names which one a new template is.\n\n| Type | What it fills | Output | `type` |\n|---|---|---|---|\n| `pdf-form` | fields overlaid on an **uploaded PDF** at fixed positions | PDF | `"pdf-form"` |\n| `html` (a PDF) | an **HTML + Handlebars** layout you write from scratch | PDF | `"html"` |\n| `excel` | an **uploaded `.xlsx` or `.xlsm`** with `{{marker}}` cells | `.xlsx` | `"excel"` |\n| `word` | an **uploaded `.docx`** with `{{marker}}`s | `.docx` | `"word"` |\n| `email` | an **inline HTML + Handlebars** body, rendered when the email is sent | email | `"email"` |\n\nTwo shapes underneath: **file-backed** (`pdf-form`, `excel`, `word`) clone an uploaded\noffice file and mark it up; **inline** (`html`, `email`) store the markup you author directly.\n\n## The lifecycle: create \u2192 generate \u2192 chain\n\n1. **Create** a template \u2014 register the file (or inline markup) and declare a `variables`\n map (the named slots the template fills). This returns a template id (`dtl_\u2026`).\n2. **Generate** a filled file \u2014 call `generate_document` with the\n template id, a `filename` (no extension), and a `data` map keyed by your variable names.\n It substitutes the markers and returns a **generated file** (with a `file_id`).\n3. **Chain** the result \u2014 generation only *produces* the file. Attaching it to a record,\n sending it, or saving it is a separate step: `update_records` with `add_to` on a files field\n files the `file_id` on a record (`remove_made`, a template id, takes out the paper that template\n made earlier); over MCP and on the CLI, `download_file` fetches it; inside a workflow, pass the `file_id` to the next\n step. A paper an app makes is its Act\'s `template`, which files it on the record itself\n (below).\n\nEmail is the exception: `generate_document` refuses an email template. An email template is\nrendered to a subject + body **at send time** from the template and the data the send step\nsupplies \u2014 so you author it with `set_template` and a workflow/app send step (or the\nweb composer) does the rendering and delivery. External agents send their own email directly.\n\n## Creating and changing a template\n\nA paper prints the owner\'s own terms only: the clauses, wording and fields of the sample they sent, never a term the owner did not state.\n\n`set_template` creates a template when it is given no `template_id`, and changes the named one\nwhen it is given one. Creating takes `type` and `name`, and the fields of its type; changing takes\n`expected_version` \u2014 the `current_version` that `get_template` returned, so a concurrent edit is\nrefused rather than overwritten \u2014 and only the fields to change. A field the type does not take is\nrefused rather than dropped. `description` (one line on what the template produces) is on every type. A change is\nbuilt into every app whose Acts make the template; one an app can no longer be built with is refused, naming the app and\nthe marker, and nothing is written.\n\n### Getting a file in\n\nA file-backed template starts from a file in the workspace: over MCP and on the CLI, `upload_file` takes a public URL,\nor bytes you hold, and returns a `file_id`. When the person has the file and your host shows you its content but not its\nbytes, `upload_file` with `person: true` returns a `drop_url` for them to open and a `ticket_id` per file; once they say\nthey dropped it, `upload_file` with that `ticket_id` returns the `file_id`.\n\nA new Word or Excel paper is a file you build yourself, in your own filesystem or sandbox, with its markers typed where\nthe values go, then, over MCP or on the CLI, send it with `upload_file` `files` and register with `set_template`. Where your sandbox cannot reach\nthis host, give the person the file and a `person` drop link.\n\n### By type\n\n- **`html`** \u2014 a full HTML document with inline CSS and `{{variable}}` placeholders, rendered to PDF; anything whose layout\n you control. `variables` are plain text, rich `html`, an auto-rendered `table` or a `list`; `format` (a named page size:\n A0\u2013A6, Letter, Legal, Tabloid, Ledger) and `orientation` are optional; any other size is the page\'s own CSS,\n `@page { size: 50mm 30mm }`. A change may send `patch_ops`, exact search-and-replace edits of the stored markup, in place\n of the whole `template`.\n- **`pdf-form`** \u2014 an existing PDF filled in place. `set_template` with the uploaded `template_file_id`\n answers `page_count` and `pages` (each page\'s `page_index`, unrotated MediaBox `width` and `height`, `origin_x`, `origin_y`\n and its `labels`, the text with its position and font size; `get_template` returns the same); `set_template` again with\n `expected_version` and the positioned `variables` (`text` / `checkbox` / `image`, each with a page and x/y/size). Data is one scalar per field. A field whose `page` is past `page_count`, or whose box lies outside that page\'s MediaBox,\n is refused. The answer holds at most 50 pages and 400 labels a page; `pages_omitted` and each page\'s `labels_omitted`\n count the rest, and `pages_unavailable` says why a template\'s pages could not be read.\n A positioned text field prints in Arimo, which covers Vietnamese; a PDF\'s own field keeps its font while its value is\n ASCII and switches to Arimo past it.\n- **`excel`** \u2014 a `.xlsx` or `.xlsm` with `{{marker}}`s in the cells to fill, and a `variables` map. `sheet` names the sheet\n that is the paper in a workbook holding others, and the template leaves the rest out; a formula reading a sheet left out\n is refused. A macro workbook is kept without its macros and the buttons that run them. Markers are validated at create\n time: a structural error blocks the save, and a declared variable with no marker comes back in `unmarked_variables`\n (skipped). `set_template` with `dry_run: true` runs every check and stores nothing; a refusal lists every error with its code and cell, and `warnings[]` (`severity`, `code`, `message`, `sheet_name?`, `cell?`) comes back with the answer. Pass\n raw numbers, ISO dates and booleans at generate time; the cell\'s number format shows them. A cell\'s format also decides\n what text becomes: text that reads as a number (`5%`) is written as one, unless the cell is formatted as text (`@`).\n- **`word`** \u2014 a `.docx` with `{{marker}}`s. `variables` is optional: every marker is derived (`{{name}}` string,\n `{{FOR \u2026 IN name}}` array, `{{IF name}}` boolean), and a marker you did not declare is still added\n (`derived_variables`). At generate time `data` needs a key for **every** marker, `""` for a blank one. A marker may run\n across formatting runs and is still read whole. In a table, the row holding `{{FOR line IN lines}}` and the row holding\n `{{END-FOR line}}` enclose the row that repeats. A newline in a value prints as a line break and a tab as a tab;\n a tab the paper prints only when a blank is empty is written `{{IF !name}}{{"\\t"}}\u2026\u2026{{END-IF}}`, since the\n form\'s own tab stays put inside an `{{IF}}` on the same line.\n- **`email`** \u2014 inline HTML + Handlebars, with `template` and `variables`; optionally a default `subject` (it takes\n `{{variable}}` too) and `default_to`, `default_cc`, `default_bcc`. Body and subject render from the data at send time.\n\n## Markers, at a usage level\n\nEvery type supports three shapes of substitution. The exact syntax differs per engine \u2014 read\nthe `set_template` description for the reference; here is the capability:\n\n- **Scalar** \u2014 a single value in one spot: `{{name}}`, `{{total}}`. Whole-cell scalars in\n Excel preserve their type via the cell\'s number format.\n- **Repeating rows / line items** \u2014 one template row rendered once per item in a list, for\n invoice lines, order rows, tables. Excel and the HTML/email engines use a Handlebars-style\n `{{#each items}}\u2026{{/each}}`; Word uses `{{FOR item IN items}}\u2026{{$item.field}}\u2026{{END-FOR item}}`. The HTML and email types\n also offer an auto-rendered `table` variable \u2014 declare its columns and pass an array, no\n hand-written loop. Excel marks the rows that repeat with `{{#each items}}` and `{{/each}}`, each alone in a row above and\n below them, or inline in the paper\'s own rows: `{{#each items}}` opens the first repeated row\'s first cell holding text\n and `{{/each}}` closes the last one\'s last (a formula cell is passed over), so a one-row body reads `{{#each lines}}{{@ordinal}}` \u2026 `{{amount}}{{/each}}`.\n (Excel has no auto-rendered `table` type; its variable types are string/number/date/boolean/array.) Inside a loop the row\'s number counted from 1\n is `{{@ordinal}}` (Excel, HTML, email) or `{{$ordinal}}` (Word), the innermost loop\'s: an STT column is a cell holding\n `{{@ordinal}}` beside the row\'s other markers. `{{@index}}` counts from 0.\n- **Columns across** \u2014 a column per item of a list, for a grid of rows by days or by kinds. HTML/email nest a\n `{{#each}}` inside a table row\'s; Excel repeats the columns between `{{#each-col columns}}` and `{{/each-col}}`, each\n marker alone in its column, and a row\'s cell under the column is `{{cells | lookup:@index}}`, its list\'s item at that\n column\'s place; Word repeats a table cell between a cell holding `{{FOR c IN columns}}` and one holding\n `{{END-FOR c}}`, and a row\'s cells the same way inside its loop, `{{FOR k IN $r.cells}}` `{{$k}}` `{{END-FOR k}}`.\n- **Conditional sections** \u2014 a block shown only when a condition holds (a "paid" stamp, an\n optional notes block). Excel/HTML/email use `{{#if}}\u2026{{else}}\u2026{{/if}}`; Word uses `{{IF name}}\u2026{{END-IF name}}`.\n\nThe `html` and `email` types print a raw value through a helper in the template\'s `locale` (`vi` or `en`; none prints in the organization\'s language): `{{money total "VND"}}`, `{{number qty}}`, `{{date issued_on}}`, `{{words total "USD"}}` (`reference/groups-and-templates` lists what each prints). `{{date (add_days issued_on -1)}}` prints the day before, `add_days` shifting a date by whole days. A value a helper cannot read fails the render, and a template calling a helper the engine lacks (`{{eq a b}}`) is refused when saved, naming the ones it has.\n\nA field can also print as a **QR code** or a **Code 128 barcode** (a picture a phone\'s camera or a scanner reads back): `{{qr link}}` or `{{code128 position 6}}` in html (never email: mail clients do not show the picture, and a save refuses it), `{{position | qr}}` or `{{position | code128:6}}` as a whole Excel cell (its row grows to the picture), `{{IMAGE qr(position)}}` or `{{IMAGE code128(position, 6)}}` in Word. The optional number is the picture\'s width in centimetres. Without it the width follows the value\'s length \u2014 each module prints 0.5 mm in a QR code and 0.33 mm in a barcode, so a longer value prints wider; a width that would shrink a module below what a scanner reads (0.3 mm, 0.19 mm) is refused, naming the least width that scans. An empty field draws nothing.\n\nA record\'s **photos** (a files field, an act\'s paper hands each as a file cell `{id, name, mime, url}`) print too, and only for a file whoever makes the paper may read \u2014 the same rule the file proxy applies; any other file is never drawn. html: `{{#each photos}}<img src="{{url}}">{{/each}}` (only the data\'s file cells are inlined; a url typed into a text field stays a link). Word: `{{IMAGE picture(cover, 8)}}`, and `{{FOR p IN photos}}{{IMAGE picture($p, 8)}}{{END-FOR p}}` for several. Excel: `{{cover | picture:6}}` as the whole cell, or `{{this | picture}}` inside `{{#each photos}}` (each row grows to its picture). The number is the width in centimetres (8, or 6 in Excel, by default). `picture` takes one image file: a list (loop over it), a file that is no image or one that cannot be read is refused by name. Photos are embedded at most 1600 pixels across, about 200 dpi at 20 cm.\n\nA Word command (`{{ \u2026 }}`) reads the data and calls, by name, a Word helper (`picture`, `qr`, `code128`) or one of these text\nand number functions: `trim`, `trimStart`, `trimEnd`, `lower`, `upper`, `capitalize`, `replace`, `replaceAll`, `removeChars`, `removeSpaces`,\n`startsWith`, `endsWith`, `contains`, `substring`, `padStart`, `padEnd`, `length`, `join`, `split`, `repeat`, `formatNumber`,\n`formatDecimal`, `numberToWords`. It holds no JavaScript method or regular-expression literal: `{{upper(name)}}`,\n`{{formatDecimal(total, 0, "vi-VN")}}`, and `{{removeSpaces(removeChars(cccd || "", ".\u2026"))}}` for the text without its dots,\nellipses and spaces. `removeChars(text, chars)` removes every character of `text` that occurs in `chars` (a set of characters,\nnever a pattern); `removeSpaces(text)` removes every whitespace character of `text`, anywhere in it, the set `trim` trims.\n\nA field named like a function is read as the field, and calling the function then fails.\n\n`set_template`\'s description holds each type\'s exact marker grammar and helper list.\n\n## Generating a filled file\n\n```\nget_template {"template_id": "dtl_\u2026"} # its declared variables\ngenerate_document {"document_template_id": "dtl_\u2026", "filename": "invoice-1042",\n "data": {"company_name": "Acme", "total": 1042, "items": [...]}}\n```\n\n- `data` is a map keyed by your variable names. Scalars for scalar/form fields; arrays for\n `table`/`list`/loop variables. `filename` excludes the extension (the type sets it). Pass a select, a\n member or a link as `query_records`\' `display` words, a number and a date raw.\n- `generate_document` renders the template\'s own type and returns a generated file object; take\n its `file_id` onward.\n- A PDF no template is wanted for takes `html`, a `filename` and its `data` in place of `document_template_id`: the markup is\n rendered as an `html` template is (the same markup rules, markers and helpers) and the PDF is stored as a workspace file. Name one of the two.\n- In a workflow, a **generate step** calls the same tool and hands the `file_id` to the next\n step (attach to a record, send as an attachment, etc.).\n\n## A template an app\'s Act makes\n\nAn Act with `template` (or `templates`) fills an `html`, `excel` or `word` template from its record and files the result\n(a PDF, an `.xlsx` or a `.docx`) in the record\'s files field `into`; `run_app_workflow` on `act_<key>` presses it. The Act hands the template the record\'s fields by their\nalias, so name each variable after one: `{{customer}}`, `{{total}}`. A select, a member and a link arrive as their words\n(a link as the linked row\'s title); a number and a date arrive raw, for `{{money total "VND"}}` and `{{date issued_on}}`.\nA loop over a link of the record whose partner the table pairs, or over the alias of a table that links to the record\nonce, receives those rows with their fields, read under the app\'s row rules:\n\n```html\n<h1>Quote {{code}}</h1>\n<p>{{customer}} \u2014 {{money total "VND"}}</p>\n{{#each lines}}<p>{{description}} \xD7 {{quantity}}</p>{{/each}}\n```\n\nHere `code`, `customer` and `total` are fields of the record and `lines` is its link to the child table, so\n`{{#each quote_line}}`, the child table\'s alias, fills as well; a Word template loops the same rows with `{{FOR line IN lines}}` \u2026\n`{{$line.description}}` \u2026 `{{END-FOR line}}`. A link whose partner is not paired reaches no rows from the record, and\na loop printing a field of each of its items is refused, naming `pair`.\n\nEvery List the record draws and the template names (an html template\'s variables, a Word template\'s markers) hands its\nrows, each List\'s `where` applied; a List the template does not name is not read. A List that only reads hands them under its\n`key` (the table\'s alias where it states none), and a List that sums a number hands the sums under `<name>_totals`, one\nentry per number the List draws as a column or as the table\'s figure. A `where` bound may be `{ "record": "<field>" }`,\na date or number the record itself holds, so a record can print a window of its own days. A service plan row (customer,\n`period_start`, `period_end`) draws the customer\'s visits within its period:\n\n```\n{ "type": "List", "key": "visits", "entity": "visit", "same": "customer", "label": "Visits", "columns": ["visited_on", "hours"],\n "where": { "visited_on": { "gte": { "record": "period_start" }, "lte": { "record": "period_end" } } } }\n```\n\n```html\n{{#each visits}}<p>{{visited_on}} \u2014 {{hours}} h</p>{{/each}}\n<p>Total {{visits_totals.hours}} h</p>\n```\n\nA bound the record leaves blank, or holds as anything but one whole day (`2026-05`) or one figure, keeps no row:\n`visits` is empty and `visits_totals.hours` is `0`. The sums add a number as the List\'s foot does: a cell holding a\nfigure adds it, any other cell (blank, an errored formula, a lookup\'s list) adds nothing. A Word template loops\n`{{FOR v IN visits}}` and prints `{{visits_totals.hours}}` the same way. A template that names a List narrowed to the\nreader (`"me"`) is refused, and so is a name a rows List and a `list` List both reach: give the `list` a `key`. A record\nbound narrows what is listed and is never an access bound; the table\'s row rules are.\n\nA List that reads by a path (`via: "<link>.<link>"`) hands its rows the same way. A List the screen draws as an outline (a record\'s own\nsub-rows, in a table whose rows nest, with no `where`, total, group, long-text column or other narrowing) hands every sub-row, depth first, each after the row it is filed under and its\nsiblings in the List\'s order, with its depth as `level` (1 for the rows filed under the record): `{{#each tasks}}{{level}} {{name}}{{/each}}`.\nA paper that lists an outline whose table has a field named `level` is refused. Inside a listed row a link arrives as the\ntitles of its rows (`{{#each marks}}{{this}}{{/each}}` prints them), so a loop there printing a field of each item is\nrefused, naming the key a List hands those rows under; so is one drawing a table cell per title, which lines up with no\ncolumn \u2014 a grid of rows by days is a roster\'s Export (below). A Word template is read for this when it is next saved.\n\nA paper over many rows (a client\'s month, a statement) is that: a record of the period whose List is windowed by its dates, made by the Act\'s `template`; or a List `Export` with `template` and `per` (`reference/export-node`).\n`reference/groups-and-templates` has the rest.\n\nA roster\'s `Export` (an html or Excel `template`) is handed its grid over the window in view: `columns`, the days\nholding a row in the file (with `expect`, every option), each a `label`, its `date` and `weekday`; and on each row (under the List\'s entity alias, `student` here)\n`cells`, a word per column \u2014 each of its rows\' mark, the option\'s `short` else its label (a row with no state, its title), joined by `, ` \u2014\n`counts`, how many of its rows stand at each option by alias (`held`, at none), and `total`, as the roster reads it (its owed or expected ratio, else the sum of the row\'s figure, else the count of the cells it holds):\n\n```html\n<tr><th>Student</th>{{#each columns}}<th>{{label}}</th>{{/each}}<th>Absent</th></tr>\n{{#each student}}<tr><td>{{name}}</td>{{#each cells}}<td>{{this}}</td>{{/each}}<td>{{counts.absent}}</td></tr>{{/each}}\n```\n\n| | A | B | C | D | E |\n|---|---|---|---|---|---|\n| 1 | Student | `{{#each-col columns}}` | `{{label}}` | `{{/each-col}}` | Absent |\n| 2 | `{{#each student}}` | | | | |\n| 3 | `{{name}}` | | `{{cells \\| lookup:@index}}` | | `{{counts.absent}}` |\n| 4 | `{{/each}}` | | | | |\n\n## Discovering and managing templates\n\nThese tools work across all five types:\n\n| Tool | Does |\n|---|---|\n| `get_workspace` | list the workspace\'s templates (`kind: "template"`), each with its id, type and one line |\n| `get_template` | one template\'s full definition, incl. the `variables` it expects and the `current_version` a change needs |\n| `set_template` | create a template, change one, delete it (`delete: true` with `template_id`) or bring it back (`restore: true`); `dry_run: true` checks the call and stores nothing; a copy is `get_template` then `set_template` |\n\nCall `get_template` before generating when you don\'t already know a template\'s variable names.\n';
|
|
@@ -25383,8 +25383,12 @@ function ownText(value) {
|
|
|
25383
25383
|
if (typeof value === "string") return value;
|
|
25384
25384
|
if (value instanceof Date) return Date.prototype.toString.call(value);
|
|
25385
25385
|
if (typeof value === "object" && value !== null) return Object.prototype.toString.call(value);
|
|
25386
|
+
if (typeof value === "number") return numberText(value);
|
|
25386
25387
|
return String(value);
|
|
25387
25388
|
}
|
|
25389
|
+
function numberText(value) {
|
|
25390
|
+
return Number.isInteger(value) ? String(value) : String(Number(value.toPrecision(15)));
|
|
25391
|
+
}
|
|
25388
25392
|
function walkJoined(array2, write) {
|
|
25389
25393
|
const joining = /* @__PURE__ */ new Set([array2]);
|
|
25390
25394
|
const stack = [{ array: array2, at: 0 }];
|
package/docs/app_bindings.md
CHANGED
|
@@ -119,7 +119,8 @@ name → `{ type, required?, description?, …per type }`. An entry is required
|
|
|
119
119
|
| `object` | `fields` — a nested map of entries |
|
|
120
120
|
| `array` | `items` — one entry |
|
|
121
121
|
|
|
122
|
-
|
|
122
|
+
A `record_link`'s `table_id`, in inputs and outputs, takes the table's id or alias and is stored as its id. Nesting stops at
|
|
123
|
+
depth 8. A `field`-form select tracks the field's options as they change; an
|
|
123
124
|
inline `options` set is a fixed list. A query's select param takes an option by alias, label or key, each condition reading it by its own field's options, and a value that is none of them is refused naming the options.
|
|
124
125
|
|
|
125
126
|
## Outputs
|
package/docs/design.md
CHANGED
|
@@ -31,7 +31,9 @@ or its entity is read-only (`edit: false`); a stepped status never is, since Act
|
|
|
31
31
|
- Every app states its tile's `color`, apart from the workspace's other apps where it can be.
|
|
32
32
|
- The paperwork is the proof of the work: a files field per purpose (what arrived, what was issued to the customer, the
|
|
33
33
|
carrier, the authority) in the Section where that work happens, and the source of a
|
|
34
|
-
figure (a screenshot, an email, a sheet) on its row. Every files field is drawn somewhere.
|
|
34
|
+
figure (a screenshot, an email, a sheet) on its row. Every files field is drawn somewhere. A paper a counterparty
|
|
35
|
+
sends (a supplier's invoice, a delivery receipt) is added on the record it arrives with — the order it is for — and
|
|
36
|
+
listed again where it is settled, never only in the counterparty's ledger.
|
|
35
37
|
|
|
36
38
|
<!-- generated:start words -->
|
|
37
39
|
|