@lotics/cli 0.321.117 → 0.321.118

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 CHANGED
@@ -1890,7 +1890,7 @@ async function saveAnswerFile(result, dir, timeoutMs) {
1890
1890
  }
1891
1891
 
1892
1892
  // src/version.ts
1893
- var VERSION = "0.321.117";
1893
+ var VERSION = "0.321.118";
1894
1894
 
1895
1895
  // src/cli_dispatch.ts
1896
1896
  import { spawn as spawn2 } from "node:child_process";
@@ -1899,7 +1899,7 @@ import { spawn as spawn2 } from "node:child_process";
1899
1899
  var getting_started_default = '# Getting started\n\nA workspace is where one business keeps what it knows and does its daily work. **Records** are what it tracks, one table per kind of thing and one row per entry. **Apps** are the screens a team works in, one per main kind of record, each given to everyone who works its rows. **Documents** are the quotes, invoices and slips it sends, each a template filled from a record, or from the many rows of a period or a statement. A paper is the workspace\'s once it is made from a template or uploaded and filed on its record; a file left on the host\'s own disk, the user\'s included, reaches no one in the workspace. A procedure or policy no table holds is a **knowledge doc**; a price list, a customer list or the open orders are rows.\n\nOpen the one page for the job. Pages are read with the `docs` tool (`docs path="design"`; `lotics docs design` on the CLI).\n\n- **Build a workspace, or add an app:** `docs path="build"`. A bakery built call by call: tables with a check, the paper, the app, what the owner will ask an agent, the owner\'s rows, then pressing it.\n- **Which apps a business needs, and who gets each:** `docs path="app_architecture"`.\n- **Judge what you built:** `docs path="design/the-rubric"`. Six questions, each answered by a call.\n- **Change an app:** `docs path="reference/changing-an-app"`. `get_app`, then `set_app` with `nodes` and `base_version_id`. A table is changed with `get_table`, then `set_tables` with its `table_id` (`data_model`).\n- **Enforce a rule on a table:** `docs path="workflows/table-checks"`. A condition no create, update or delete may meet, whoever makes it, and the language it is written in.\n- **Make a document:** `docs path="document_templates"`. A template, its slots and loops, and the act that files it on a record.\n- **Enter data, count, answer a question:** `docs path="working_in_a_workspace"`. The right tool for each job; the value each field takes is `field_values`, choosing rows is `filters`.\n- **Rows owed on a weekly pattern (a diary every weekday, a class every Tuesday):** `docs path="reference/cadence"` for a table\'s `records.cadence`; the Act that `makes` them is `reference/act-node`.\n- **Rows an act proposes for a person to tick (a statement matched to the notes it pays):** the workflow body is `docs path="workflows/a-reviewed-act"`, calling the act is `agent_surface/a-reviewed-act`.\n- **Reach a connected service, or do what a button cannot:** `docs path="workflows"`. Triggers, steps and expressions; each service step is in `workflow_steps`.\n- **Who can reach what, or why something was refused:** `docs path="permissions"`.\n\nHow each record is drawn is `design`; every key is in `reference`; each screen in a complete workspace is `examples`.\n';
1900
1900
 
1901
1901
  // docs/build.md
1902
- 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, and a paper or list that does not come with it is never waited for \u2014 build from your defaults now and say in your report which papers would sharpen it. 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, and so is what goes wrong on a row and needs someone to act: an issue (`design/issues`). 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": "\\"Pay by the pickup day, \\" + formatDate(record.due_on)"}}\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 composes the page every row opens, the add and the Delete, and stores them. State only the difference from what it composes.\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": "Steps", "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\n**How a status draws follows the work, never this example.** The order states `Steps` because its stages hold something of their own: the lines it bakes from, the slip its Act files. A status whose Acts only move the row on states no `Steps` and draws as a line of steps. One a person sets by hand, closing nothing or moved by no Act, draws as its select (`design`, Stages).\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>", "pages": [{}, {"record_id": "rec_\u2026"}]}\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';
1902
+ 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, and a paper or list that does not come with it is never waited for \u2014 build from your defaults now and say in your report which papers would sharpen it. 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, and so is what goes wrong on a row and needs someone to act: an issue (`design/issues`). 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": "\\"Pay by the pickup day, \\" + formatDate(record.due_on)"}}\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. A check refuses the write, a table workflow\'s too, so it states only what the business says must never happen; a fact going out of line (stock short of what lines take, totals that do not match) is an issue the row keeps (`design/issues`).\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 composes the page every row opens, the add and the Delete, and stores them. State only the difference from what it composes.\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": "Steps", "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\n**How a status draws follows the work, never this example.** The order states `Steps` because its stages hold something of their own: the lines it bakes from, the slip its Act files. A status whose Acts only move the row on states no `Steps` and draws as a line of steps. One a person sets by hand, closing nothing or moved by no Act, draws as its select (`design`, Stages).\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>", "pages": [{}, {"record_id": "rec_\u2026"}]}\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';
1903
1903
 
1904
1904
  // docs/design.md
1905
1905
  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. What a write stores, and the Section that follows the table: `reference/changing-an-app`. 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 is not, since Acts move it, unless its `row` states `status: { edit: true }`. 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 as an issue its table declares (`design/issues`): a derived flag is an issue, in the\n warning tone on the row\'s line (in the danger tone where a Check\'s `on` refuses an act the row offers); every other yes\n reads in the success tone. `records.mark` is a category\'s own mark, a select whose options carry a brand or glyph.\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. A row listed under its record is named by its\n subtitle\'s first part where its title only reads that record (a join row\'s lookup through the link back): title a join row by one side, its subtitle the other.\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- An option with a `color` draws its dot where its select is drawn; one without reads as its word. A `mark` where a\n brand or glyph names the option, on every option of a select read down a column (how it was paid, the channel).\n- Every app states its tile\'s `color` and `icon`, each apart from the workspace\'s other apps where it can be: an\n app stating no icon draws the one glyph every such app shares.\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 | list of alias (at least one)): A files field that pictures the row, or a one-row link to a table with a picture (or a lookup of one through a one-row link: a delivery led by its order\'s customer), 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) 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, drawn as a line of steps on a record page where no Section states `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 over a Query | 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, in this order, each drawn though no row holds it\n- `label` (text): The register\'s name in the app\'s lists and tab strip\n- `filters` (list of (alias | Tiered filter | Listed filter)): Fields the reader narrows by every day, beside the stage chips\n- `children` (list of (Tab | Reading | Act | List) (at least one)): Its Tabs, band Readings 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) | `false`): Fields the search box reads\n- `where` (narrowing): A fixed narrowing on the server, for every reader\n- `group` (alias | `false`): A field the rows stand grouped by, a gantt drawing the groups as its lanes, a lanes board of days its cards\' sub-headings inside each lane\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 (List over a Query in a Record | alias | Field | Fieldset | Section | Steps | Side | Outside | List | Reading | Statement | Comments | Act | Check) (at least one)): Parts (Section, Side, and one Steps holding the Sections that are its path), and the Fields, Fieldsets, Lists, Readings, Statements and Comments stated 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): The part\'s heading\n- `key` (alias): Unique among its siblings\n- `children` (list of (List over a Query in a Record | alias | Field | Fieldset | List | Reading | Statement | Comments | Act | Check) (at least one)): What the part draws, in reading order\n- `at` (list of alias (at least one)): The status options this part is the work of\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` | `"warnings"` | 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 issue 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## Issues\n\nA row takes what the person has, in the order it arrives \u2014 a supplier\'s paper after the delivery, a payment before its\ninvoice, a price filled in later. What is missing or out of order is an issue on the row, never a refusal of the write;\nrefusal is kept for what must never happen and for the step that cannot be taken without a fact, which names it (an\ninvoice made without the buyer\'s tax code).\n\nWhatever goes wrong on a row and needs a person to act \u2014 a line delivered short, a price missing, a customer over their\ncredit limit, a permit about to expire \u2014 is an issue its table declares in `records.issues`. A declared issue stands in\nevery app that draws its row, with no app stating it: first on the row\'s line (`+N` the others), in the record\'s callout (a count of child rows as pills on those rows), in the List\'s filter of what needs checking with how many rows hold it, and those rows first. It never makes an\napp draw a row it did not, and never shows on an `Outside` page. What needs no one\'s action is no issue: a stage is the\nstatus, a category a select. A record\'s callout says each issue by its label and what it means: a text issue\'s own sentence, a yes/no issue\'s field `description` \u2014 give a yes/no issue\'s field one, or its line shows the name alone.\n\nDeclare an issue only where the owner confirms each flagged case is a problem: a rule that flags rows nobody fixes trains\neveryone to ignore the colour, real issues included. Where a flagged row may be accepted as it is (a price agreed by\nexception), give the acceptance a field the formula reads, so accepting it clears the issue.\n\n- An issue is a formula of the row stating `output_type`: `"boolean"` stands while true; `"text"` stands while not empty,\n its words the sentence the reader sees \u2014 use it when the sentence must say what or how much ("Short 4 of 10").\n Its label is its name. Put the moment it matters in the formula, so it clears itself when the work is done.\n- The list is priority: an issue blocking the next step leads, then the earlier in the list.\n- `{ "rows": <link> }` on a parent rolls up every issue its child table declares, through a many-link paired to the\n child\'s one-row link back. The platform keeps a count on the parent per child issue, `<link>_<issue>`, labelled\n "<link label> \xB7 <issue label>"; never write it. The parent reads "2 rows left: Lines \xB7 Short".\n- A formula reading `now()` or `isToday()` (overdue, expiring within 30 days) is judged again every night, to the day.\n- An app\'s `Check` says what the issue does not: `on`, what it refuses in that app (`"update"`, `"all"`, or that\n entity\'s Acts), and `resolve`, the Act that clears it; one stating neither is refused, and one without `on` names a\n declared issue. A parent\'s Act is refused by a Check on the parent\'s count `on` that Act (never `"update"` or `"all"`: editing the rows clears it); the act then holds\n the parent while it runs, so its own `workflow` cannot send mail, notify, run an agent or wait \u2014 start that work from a\n workflow the act starts after.\n- A lock is a Check, not an issue: a yes/no such as paid in full refusing `"update"`, in no `records.issues`, since nothing\n is wrong with the row.\n- `get_table` reports each issue: rows holding it now, opened in the last 30 days, median days to clear.\n\nAn order whose lines can arrive short or unpriced, invoiced only when no line is short:\n\n```json5\n// order_line\n"fields": {\n "short": { "label": "Short", "type": "formula", "output_type": "text",\n "expression": "!isEmpty({delivered}) && {delivered} < {quantity} ? \\"Short \\" + toString({quantity} - {delivered}) + \\" of \\" + toString({quantity}) : \\"\\"" },\n "no_price": { "label": "No price", "type": "formula", "output_type": "boolean", "expression": "isEmpty({price})" }\n},\n"records": { "issues": ["short", "no_price"] }\n// order \u2014 `lines` is its many-link to order_line; the platform adds lines_short and lines_no_price\n"records": { "issues": [{ "rows": "lines" }] }\n// the order\'s Record in the app\n{ "type": "Check", "field": "lines_short", "on": ["invoice"] },\n{ "type": "Check", "field": "paid_in_full", "on": ["update"] }\n```\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: one Section is `/<record id>?section=<its title>`; `screen` for a later screen of a long one), up to six `pages` in one call \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. `set_app` with `app_id`, an empty `body` and `dry_run` answers what a write of the\nstored tree would be refused for now, 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`); one who cannot open the app is first invited (`set_members`) and given it (`set_access`) \u2014 an app nobody shares opens for admins alone.\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 exporting List\'s workbook made, those this kind of business sends unasked too, with no blank? Press each paper Act and read the file it files; prove a List\'s `export: true` with `run_app_query` and `export`.\n7. Can each row be recorded with what the person has now, its gap an issue, while only the step that needs the fact refuses? Is each thing that must never happen in this business (a step taken before its approval, stock below zero, a double booking) refused on every write? Prove each with a write sent `dry_run: true` that is refused (`workflows/table-checks`).\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; a stage that holds something of its own, a note included, is a Section inside `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 | a files field with `photo_places: true` keeps where the device stood for each photo shot through the camera; judge them in a text formula `distance({photos}, {site_lat}, {site_lon})` listed in `records.issues` | `reference/formula` |\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| A figure a record works out from its own figures (a payslip\'s net, an invoice\'s total) | a `Statement`: its lines in the order the arithmetic runs | `reference/statement-node` |\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`), or a lookup of one through a one-row link (a delivery\'s `customer`, through its order): the row leads with that row\'s picture, still titled by\nits own words \u2014 or several in order (`["product", "bundle"]`, a line linking either), the first that holds a picture leading the row. 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. The table\'s `records.image_shape` (`portrait`, `square`, `landscape`) states the shape the register\'s cards and tiles and such a List draw it at. 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 the one a write stores for you. A link\'s row shows 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 group of the workspace by its id, 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.\nWorked: `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), and without one a row moved on by mistake stays until an admin edits the table. What a\n`workflow` or a paper did stands, so a way back there is a correction of its own.\n\n#### Buttons\n\nPeople mostly work through agents, so an app draws no button by default: an Act is offered everywhere, and a record\'s\nheader \u22EF and a row\'s \u22EF list it. Rows never draw a button: every row act waits in its \u22EF, and where many rows are worked,\ntick them and state an act `on: "rows"`. An Act on a record or drawer states `button: true` only for a step a person\ndoes at that screen (a count received, a signed paper, an approval), never for work an agent does (an invoice made\nfrom delivered orders, a payment matched from a statement). Every other Act waits in the record\'s \u22EF.\n\n#### Stages\n\nWork the owner named no decider for has no status: the row saved is the fact (a goods receipt nobody approves moves\nstock as it is saved), and a stage, its owner or an approval enters with the person the owner said decides.\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 (a total a rollup sums or a yes/no a formula yields among them), 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\nA status draws one of three ways, by what the author states, never by habit. With nothing `closed` it is a condition a person sets: its select, no steps. With `closed` it is a path: one a person moves by hand (no Act moves it, or its `row` states `status: { edit: true }`) keeps its select alone, and one Acts move draws its stages as a line of steps across the page, each only moving the row on. Where a stage holds something of its own \u2014 fields, blocks, an act that asks or files a paper, a note \u2014 the Record states it as a Section inside `Steps`, and the path draws down the page, each step holding what its stage holds. A part that is the work at every open stage is no step and states no `at`; `when` shows a part only at some stages.\n\n#### Stage dates and history\n\nA step reads as done only where the row shows it was reached, by a stamped date or a history move: a finished row with neither ticks none of its earlier steps, so a path whose steps should read states `dates`. Who 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 that states no `Steps` draws it as a line of 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, titled by them ("Price (open)"). 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. A figure stated per party (owed, overdue, short) opens on the rows that make it,\nlisted on that party\'s page and adding up to it. Many Readings stand on several Sheets, each a View the reader picks. 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. Its parts stack, one scroll with each headed; state `parts: "tabs"`, or a `tab` on a Section, to show one part at a time, and Sections stating one `tab` share a tab. 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, and a stage that holds something of its own \u2014 fields, blocks, acts, a note \u2014 is a Section inside `Steps`, one `Steps` to a record. 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 stage that holds nothing needs no Section: the path draws it by 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; what only a stage\'s Act writes (an invoice\'s number,\na delivery\'s signature) stands empty before it, so it goes in that stage\'s Section inside `Steps`, never the Side. The status\nstands in the head or the Side, never a Section. `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 in a part come first, a Fieldset where they need a heading. Only where the arrangement itself is the need does the Fieldset state `Line`s \u2014 two weights and their difference on one line \u2014 and `heads` where several Lines repeat the same columns, a fee\'s amount, its payment and its invoice button per row (`reference/line-node`). A figure only that screen shows is a `Value`; one a list, a report or an export reads is a formula field of the table. 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, or\n`layout: {"gantt": \u2026}` where they are bars on a schedule. 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';
@@ -1938,7 +1938,7 @@ var filters_default = '# Filters \u2014 choosing records by their fields\n\nOne
1938
1938
  var field_values_default = '# Field values \u2014 what a write takes for each field type\n\nThe value `create_records` and `update_records` take for a field. A field is named by its alias, as `get_table` shows it, and a select option the same way. `dry_run: true` on `create_records`, `update_records` and `delete_records` runs the write in a transaction that is rolled back: every check, rule and stage owner is judged, no number is consumed, and the answer says what would be written or why it is refused. Every write meets the table\'s rules (`reference/write-rules`): a refusal lists every broken rule at once, and a locked record answers under `blocked` in `update_records`\' result.\n\n## Values by type\n\n| Type | Value |\n|---|---|\n| `text` | `"hello"` |\n| `time` | a `text` of this format: `"16:00"`, stored `HH:mm` on a 24-hour clock; `"8:00"` and `"08:00:00"` are stored `"08:00"`, any other text is refused |\n| `number` | `42` |\n| `boolean` | `true` |\n| `date` | `"2025-03-14"`, or a month `"2025-03"` or a year `"2025"`, stored as written and compared as its first day |\n| `month` | `"2025-03"`; a full date written to it keeps its month, a bare year is refused |\n| `datetime` | a `date` of this format: `"2025-03-14T09:00"`, never a month or a year |\n| `date_range` | a `date` of this format: `"2025-03-01/2025-03-15"`, both halves full dates |\n| `datetime_range` | a `date` of this format: `"2025-03-01T09:00/2025-03-15T17:00"`, both halves full |\n| `select` | `["open"]`, the option\'s alias |\n| `member` | `["mbr_\u2026"]` |\n| `link` | `["rec_\u2026"]` |\n| `files` | `["fil_\u2026"]`, ids of uploaded files |\n| `formula`, `rollup`, `lookup`, `autonumber`, a `date` with `derive_from` | none \u2014 the platform writes them, and a write naming one is refused |\n\n## Lists\n\n`select`, `member`, `link` and `files` store an ARRAY, even where the field holds\none value.\n\n- A single-select is a ONE-element array; a bare `"open"` is accepted and wrapped. A single\n `member` takes a bare `"mbr_\u2026"` the same way.\n- A single `link` takes a bare `"rec_\u2026"` the same way; a multi `link` and `files` take an array only.\n- A `files` id the write adds must name a live file of this workspace, or the whole write is refused;\n an id that cell already holds stays, though its file was archived since.\n- A file previews by its kind: an image zooms; a PDF scrolls, zooms sharp and turns by page, its text selectable; a DXF\n drawing shows read-only in 2D with a toggle per layer. A DWG stays a stored file with no preview; attach its plotted\n PDF beside it.\n- Two options on a single-select, two members on a single `member`, or two records on a single `link`, are refused.\n- `update_records`\' `add_to`, `remove_from` and `replace` take arrays of the same items: option aliases\n for a select, member ids for a `member`, record ids for a `link`, file ids for\n `files`.\n';
1939
1939
 
1940
1940
  // docs/workflows.md
1941
- var workflows_default = '# Workflows \u2014 the steps a workflow runs\n\nA workflow is written as a strict subset of JavaScript. The source is never run as JavaScript: a\nsave parses it into steps, type-checks it against what its trigger supplies, and stores the steps.\nOnly the forms below are accepted; anything else is refused at save with the line, the column and\nwhat to write instead. A save that succeeds may still return `warnings` \u2014 advisory hints such as a\nloop that may never end. Read them.\n\nA workflow changes records, calls integrations, notifies and makes papers. A tool for anything else \u2014 views, history,\ntables and apps, members, knowledge, skills, editing a file \u2014 is an agent\'s, and a body that\ncalls one is refused at save with that reason. One saved before is refused at run, before its first step.\n\nThe same grammar serves a table\'s workflow, an automation and an app\'s workflow, which `set_workflow` saves, and the\nexpressions of a table check.\n\n## Triggers\n\nEvery workflow\'s source opens with `on({ ... })`, which states what starts it. `set_workflow` saves the source, and\n`get_workflow` reads it back with whether it is on and how its latest runs ended. `get_workflow` without a\n`workflow_id` lists the workflows you may read, a page at a time (`limit` 1 to 100, `offset`, `total`), each with its\n`kind`, its trigger in a line, whether it is on and its failed runs of the last 7 days; `table_id` and `app_id` keep the\nones that follow or name them.\n\n| kind | header |\n|---|---|\n| table | `on({ type: "create" \\| "update" \\| "delete", table: "<alias>", changed?: ["<alias>", ...], when?: "<expression>" })` |\n| automation | `on({ type: "recurring_schedule", cron_expression })`, `receive_webhook`, `receive_gmail_email` or `receive_outlook_email` \u2014 see **Automations** |\n| app | `on({ type: "app", app_id, alias, inputs?, outputs? })` \u2014 `inputs` and `outputs` only for a custom-code app |\n| notification | `on({ type: "notification", inputs: { ... } })` \u2014 what a card\'s action hands the body |\n\nWhat starts a workflow is fixed once it is made: its kind, a table workflow\'s trigger type and table, an automation\'s\ntrigger type, an app workflow\'s app and alias. To change either, delete the workflow and make another. A replace states the whole trigger, so a key the\nheader leaves out is removed (an app workflow keeps the inputs it leaves out, and derives the outputs it leaves out from\nwhat the body returns). `expected_version` refuses a replace when the workflow has moved since the `version` you read.\n`dry_run` checks the source and stores nothing; given the trial inputs its trigger supplies, it also walks the steps once\nand returns the calls planned, the return value, the failures and the papers rendered. A table trigger takes `record_id`,\n`prev_data` and `changes`; a webhook or email trigger `trigger_payload`; an app trigger `record_id` and `preview_inputs`; a\ntable or automation trigger also `live_reads` (an app\'s rehearsal always reads real data). A trial input its trigger does\nnot supply is refused, naming the ones it takes. A rehearsal needs write scope: a key that reads data alone cannot make one.\nA rehearsal\'s answer cuts a long list or text where it stands and says how much it kept; each step\'s output follows the\ncalls and the return value, cut to its first rows.\n\nA stored workflow is changed without sending it whole: `edits` with its `workflow_id` are anchored replacements in the\nsource `get_workflow` returns (`[{ old_string, new_string }]`; `op` inserts before or after an anchor, or appends), and the\nwrite is refused if the workflow moved since the version they were made against. A source not stored yet rides a file:\n`source_file_id` takes it from a stored text file in place of `source`; write the source where you work, upload it with\n`upload_file` (`files`) and pass the `file_id`.\n\n`delete: true` with a `workflow_id` removes a workflow, and is the one call that asks for approval; a replace asks for none,\na step it drops included. `even_if_invoked` and `acknowledge_breaking_api_change` belong to an app workflow and are\nrefused for another kind.\n\nA notification workflow is run by the action of a notification card under its owner\'s access; the press only triggers it. It declares `inputs` as an app workflow does, reads them as `inputs.<name>` (or `trigger.notification_action.inputs.<name>`), cannot `wait` or `wait_for_event`, and is bound to no table, automation, button or app. Its owner or an admin reads, replaces and deletes it and puts it on a card, and it still runs as its owner; it has one owner for life and is archived with them when they leave (its open cards close), never handed on. Its writes are judged and attributed as its owner. Its runs are read by its owner and admins, and are never retried: pressing the card again is the retry. A step that sends a card names each action\'s `workflow_id` as a literal. Only a workflow sends a card; an `agent` step writes the title and body it sends.\n\nAn app workflow reads its call as `trigger.app_workflow.inputs.<name>`, or `inputs.<name>`, which is the same read. A Workflow node receives the inputs it declares;\nan Act\'s `workflow` receives `record_id` (`record_ids` on an act over several rows) and what the Act asks.\n\n### Automations\n\nAn automation answers an event outside the records: a schedule, a webhook, an inbound email. `set_workflow` saves one\nfrom its source \u2014 the `on({...})` declaration, then its steps \u2014 and, given its `workflow_id`, replaces it: the\ntrigger config is the one the header states, a key it leaves out removed, and steps left as it runs them are checked again\nonly when the call turns it on (`enabled`), so one a later rule refuses can still be switched off. An admin names the owner at creation with\n`owner_member_id`. It runs with its owner\'s current permissions, a connected service it names is its owner\'s account, and only its\nowner or an admin reads, changes or deletes it.\n\n```\non({ type: "recurring_schedule", cron_expression: "0 9 * * MON" });\n```\n\nEvery source below is typed, so a misspelled member is refused at save rather than read as nothing.\nAll three carry `trigger.trigger_id`.\n\n| trigger | required config | what the body reads |\n|---|---|---|\n| `recurring_schedule` | `cron_expression` | `runtime.timezone`; the current time is `now()` |\n| `receive_webhook` | `secret`? | `trigger.method`, `trigger.headers[...]`, `trigger.query[...]`, `trigger.body` (any JSON, or raw text when the request is not JSON), `trigger.received_at` |\n| `receive_gmail_email` / `receive_outlook_email` | `connected_account_id`, `filter` | `trigger.email_id`, `trigger.from`, `trigger.to`, `trigger.cc`, `trigger.bcc`, `trigger.subject`, `trigger.date`, `trigger.body` (plain text), `trigger.reply_to`, `trigger.in_reply_to`, `trigger.attachments` (file refs \u2014 assign them straight to a files field). One type serves both providers, so `labels`, `thread_id`, `importance` and `conversation_id` are not readable. |\n\n## Steps\n\n| step | syntax |\n|---|---|\n| tool call, kept | `const <id> = await <tool>({ ...inputs });` \u2014 also `let x = await \u2026` and `x = await \u2026` |\n| tool call | `await <tool>({ ...inputs });` \u2014 the platform\'s own steps (`send_notification`, `generate_document`, \u2026) and a connection\'s tools, each a workflow step (`bkav_submit_invoices`, `kiotviet_create_order`, \u2026); a step that fails ends the run with its reason unless a `try`/`catch` around it handles it |\n| agent | `const <id> = await agent({ instructions, input, model, output });` \u2014 see **An agent step** |\n| app agent | `const <id> = await app_agent({ alias: "<agent alias>", input: { ... } });` \u2014 runs one of the app\'s declared agents, in an app workflow only, and resolves to its declared outputs or its final text. `wait: false` only starts the run and resolves to `{ run_id }`; the run\'s failure is then its own, not the workflow\'s. Refused in a run an agent started. |\n| bind | `const <id> = <expression>;` \u2014 evaluated once; later steps read `<id>`. Bind any expression used twice. |\n| if / else | `if (<expr>) { ... } else { ... }` \u2014 `else` optional, `else if` chains allowed |\n| switch | `switch (<expr>) { case "X": { ... } default: { ... } }` \u2014 string cases only, no fallthrough |\n| for | `for (const <name> of <expr>) { ... }` |\n| wait | `await wait({ duration_in_minutes: 5 });` |\n| wait for an event | `await wait_for_event({ event_type: "webhook", event_ref: <expr>, timeout_in_minutes: 60 });` |\n| return | `return({ status: "success" \\| "error", message: <expr>, field_errors: { ... }?, data: { ... }? });` \u2014 `data` holds the outputs a Workflow node declares \u2014 a body whose steps only read and write the workspace\'s rows and make papers runs as one transaction: a return of `error`, a failed `validate`, a table\'s refusal or a failure takes back every write of the run, and a run too long to hold one starts again step by step; a body that also calls out (a send, a connected service, an import of rows, another workflow), waits or runs an agent runs step by step: each step\'s writes stand as they land and a return of `error` undoes none, so its refusals stand before its first write; an Act\'s own write (`set`, asks, signature) and its papers land after the body, before each `success` return and where the body ends, so a refusal leaves the row as it stood, and the body\'s `row` and any read of the row in the body see it as the press found it |\n| validate | `validate({ checks: [{ fail_when: <expr>, field_key: "...", message: <expr> }, ...] });` |\n\nA delayed run is never cancelled from a workflow: after a `wait`, it reads the row\'s state and acts only if it still holds.\n\nA tool\'s inputs and answer are in its own description; the steps only a body runs \u2014 a connection\'s, a mail\'s \u2014 are each\nan entry of `workflow_steps`. An admin connects a service in Lotics under Settings \u2192 Connections; a step names that\nconnection by its `connected_account_id`, which `get_workspace` with `kind: "connection"` lists for the connections the\ncaller can use. The app\'s owner must be able to use that connection, so a\n`connected_account_id` is a literal, a constant bound to one, or a choice among them: every possible value is judged at\nsave, and one read from an input, a record or a call is refused. A template may come from data; a run refuses one its\nowner cannot use.\n\nIn a workflow, the step `send_notification` reaches a member of the workspace: the member sees it in their Lotics\ninbox, and it is mailed only to a member who has chosen email for their notifications. Its recipients are members by\n`member_id` (`get_workspace` with `kind: "member"` lists them), member groups or the whole organization. Mail that\nmust arrive, to a member or anyone else, goes from a\nconnected Gmail or Outlook (`gmail_send_email`, `outlook_send_email`), which leaves an unsent draft unless `draft` is\n`false`.\n\n`return` is a call, not a JavaScript `return` statement. A `success` may leave out `message`, and a bare\n`return;` is that success; an `error` states its `message`. `validate` ends the workflow with an error\nwhen a check\'s `fail_when` is truthy; the check\'s `field_key` names the control its message lands on \u2014\nin an app workflow a declared input, or the alias of a field on a table the body names; in an\nautomation it is not checked.\n\nThe name in `const x = await tool({...})` is the step\'s id; later expressions read its output as\n`x.records`, `x.id` and so on. A `// id: my_step` comment directly above a statement sets an explicit\nid; any other `//` comment there becomes the step\'s description.\n\nA run reads a repeated identical record read once, until the run writes; a loop that waits for a row to change needs a `wait` step, or each pass sees the same rows.\n\nA `query_records` with no `limit` returns the first 50 rows, and `has_more` says whether there are more. `all: true` returns every row the call matches, up to 32 MiB of them; a call past that is refused, with no rows. `all` does not combine with `limit`, `offset`, `page_size`, `pagination`, `record_ids`, `aggregate`, `tables` or `comments`, and a workflow\'s read takes no `as_file`.\n\n`sort` of a records read also takes `__created_at` and `__updated_at`, a row\'s creation and last-update time (`{ field_key: "__created_at", order: "desc" }` is newest-created first); with `include_timestamps: true` each row carries `created_at` and `updated_at`, read as `r.created_at`.\n\n**`await` inside a statement** runs the call as its own step first, then reads its output where it is\nwritten: `size((await query_records({...})).records)`, an `if` test, a `return` value, a `for-of`\niterable, a tool input. `const x = c ? await t({...}) : null;` is stored as the `if` it means. An\n`await` that would run on some paths only \u2014 inside `&&`, `||`, `??`, `?.`, a nested ternary, a loop\ntest, a `validate` check \u2014 is refused; write the `if`.\n\n**Names are block-scoped, as in JavaScript** \u2014 `const`, `let`, loop items and `catch (e)`: sibling\nblocks may reuse a name and an inner block may shadow an outer one. A local may take a helper\'s name\n(`const size = 3;`), but calling `size(...)` while it is in scope is refused. The names of the tools a\nworkflow calls, the reserved roots, `linked` and `_s` followed by digits cannot be bound.\n\n### An agent step\n\n`const x = await agent({ instructions, input, model, output });` runs a model as one step \u2014 read a paper, classify,\ndraft text. It calls no tool: the workflow\'s own steps write, send and notify with what it returns, and a step that\nstates `tools` is refused.\n\n- `instructions` \u2014 a fixed string.\n- `input` \u2014 an object literal; its fields are expressions, evaluated and handed to the model (`{}` for\n none). It is the ONLY workflow data the agent sees: read the trigger, prior steps, `runtime` or the loop\n item here, never inside `instructions`, which is a fixed literal and reads no binding. A field holding a file, or a\n list of files (a files field, a mail\'s attachments), hands the agent the files themselves: a picture or a PDF it\n sees, any other paper read into text.\n- `model` \u2014 optional; omit it to follow the platform\'s default model.\n- `output` \u2014 `{ mode: "text" }` resolves to a string; `{ mode: "object", schema }` to a typed object.\n\nOnly `x` comes back: in text mode `x` is the string itself, in object mode `x.field` reads a field the\n`schema` declares.\n\n## Naming tables and templates\n\nA body names a table or document template by its alias (`query_records({ table_id: "orders" })`); ids still work. `get_workflow` shows aliases. An app\'s workflow reaches only the tables the app uses.\n\n## Fields and options\n\n1. **A body names a table\'s fields and select options by alias**, the names the table\'s document states: a field reads\n as `record["status"]`, an option as `"done"`, a linked field as `linked(record["customer"])[0]["name"]`, in the\n body of a Workflow node, of an Act\'s own `workflow`, of an automation and of a table\'s workflow (`set_workflow`). It is stored by key and `get_workflow` shows it by alias\n again. A field\'s key is accepted where its alias is and is kept as written; an option\'s key is read as that option\'s\n alias, and one that two tables\' options share with different aliases is refused where it is read, naming both. A\n display name is refused with the aliases there are, and a row that names one field by both its alias and its key is refused. A row written to a table is\n stored by field key wherever the save can follow it to the record tool that writes it: a row or list written in the call,\n a conditional of them, a name holding them, pushed to a `let`, and through `map`, `flatMap`, `concat`, `filter`, `sortBy`,\n `slice` and `reverse`. A field of such rows is read by alias as well (`picks.toSorted((a, b) => a.quantity - b.quantity)`,\n `sortBy(picks, "quantity")`, `rows[0].note`) and stored by key. A body that cannot be stored by key is refused at save,\n naming the statement.\n2. **An Act\'s own `workflow`** has the app\'s guards placed at the top of the body, between `<lotics:guards>` tags,\n replaced on every save: a save that leaves them out or edits them gets the app\'s again, at the top wherever the tags\n sat, so the act\'s row rule, `when`, `requires`, checks and locks always run first.\n3. **A value is read as the record tools store it.** A single select reads as its option\'s alias and a member as its id;\n an option is written by its alias wherever it meets a select \u2014 compared, listed, switched on, written \u2014 also beside a\n name set from the field (`const s = record.status; s == "done"`) or in a list that search runs over\n (`includes(filter(record.tags, \u2026), "hot")`). A select value handed on whole (returned for a declared select, written to a\n select field or a filter) is resolved to the option\'s key where it leaves the body; one handed to a text, a message or a\n template carries the alias. A link reads as the list of its row ids, a\n one-row link too: `first(record.customer)` is the one id, and `record.customer` used as one id is refused at save,\n naming `first(record.customer)`. A one-row link is written with its one id or a list of one; a many-row link with a list. A lookup reads as one flat list of the values it looks up: `includes(record.owner,\n me)`; a looked-up link, as the ids of its rows, which `query_records` takes as `record_ids`. A select\'s value is one of another select\'s options where the two state the same alias for it; two selects that\n state no alias in common never hold one value, and a save that compares them or copies one into the other is refused.\n A row that takes its parent\'s option gets it from `default_from`, and a lookup shows it.\n A grouped aggregate\'s `key` reads as the option\'s alias, and `get(row.data, "<field>")` as `row.data.<field>` (an empty cell takes the default).\n4. **What an app sends takes an option by alias or key.** An input or output drawn from a field (`field`, written\n `<table id>.<alias>`) compares and returns by alias in the body, and the run hands it on as the option\'s key. A\n refusal\'s `field_errors` and a `validate` check\'s `field_key` name a declared input or a field\'s alias.\n5. **`==` against a multi-select means "includes".** `record["tags"] == "urgent"` on a multi-select is stored as\n `includes(record["tags"], "urgent")`; either spelling works.\n6. **`option("<field>", "<option>")` names an option where no select is beside it** (a name set once and compared later,\n a list of options, a value handed to a tool). It reads as the option, typed as that select\'s, and is stored as its alias. The field is a select or a formula that states `options`.\n The field is looked up among the tables the body reaches; a field or option that does not exist is refused naming both, and\n a field alias that two tables state with different keys for that option is refused naming each table, as is one printed\n (rule 7) where the tables label that option differently. An option\n key written out reads as its alias, but write `option()`: a key is a value no one can read. `options("<field>")` lists\n the field\'s options in its order, each `{ alias, label }`, found and refused as `option()`\'s field is\n (`options("status").map((o) => o.label)`); it is read when the run reads it, so a reorder or a relabel shows at once.\n7. **Text renders labels.** Inside a template, `text(...)` or a text tool input, a select, member or link value renders its display\n text: `` `${record["status"]}` `` writes "Done", not `done`, and `` `${record["status"] ?? ""}` `` writes it too. A\n card\'s action inputs and the option keys its ask offer take the alias, a field\'s value included. `option("status", "done")`\n and a select input read as `inputs.stage` print a label only in a template, `text(...)` or a document\'s data: the label\n its field, or the workflow\'s declared input, states when the run prints it; a multi-select\'s labels print as a field\'s\n do. Handed to any other tool input, compared, written or filtered on, each is the option\'s alias: `title: inputs.stage`\n is the alias, `` title: `Stage ${inputs.stage}` `` prints the label. A name bound to the value (`const s = inputs.stage`,\n `const o = option("status", "done")`, `const v = record.status`) prints the value. A formula stating `options` (a computed category) is read as the single select it is drawn as:\n compared by option, rendered by label.\n\n## What an expression reads\n\n- `record`, `prev_record`, `changes` \u2014 in a table check, the write it checks (see **Table checks**).\n `changes` is a PARTIAL map: `changes["x"]?.next_value` and `?.prev_value`, the `?.` required.\n- `trigger` \u2014 what the trigger carries (see **Triggers**).\n- a loop\'s item name, and `index`, the iteration\'s 0-based index.\n- `<step id>` \u2014 an earlier step\'s output (`dup.records`).\n- `runtime.timezone`, `runtime.workflow_id`, `runtime.execution_id`, `runtime.workspace_id`,\n `runtime.organization_id`, `runtime.change_origin`, `runtime.triggered_by_member_id`. The current\n time is `now()`.\n\n## Paths\n\n- `record.x` and `record["x"]` read a field; `[n]` reads a list\'s n-th item.\n- A path may start at any expression: an awaited call `(await query_records({ table_id: "orders", record_ids: [id] })).records[0].data["x"]`, a helper\'s\n result `first(found.records).id`, a filter `rows.filter((r) => r.ok)[0].n`, a `(a ?? b).c`. `?.` reads\n through a null as usual, except on a value drawn at random (`sample(xs)?.id` is refused: bind it first).\n- A record reads in its declared shape wherever it comes from \u2014 the trigger, a tool result, a `let`, a\n callback parameter: a single select as its option alias or null, a member as its id, a link as its ids. A property read\n by alias (`x.order.quantity`, `xs[0]["quantity"]`, `y.quantity`) also names the record\'s field when the record is held in an\n object, a list or a spread (`{ order: record }`, `[record]`, `{ ...record }`). A field is named by alias wherever the\n row\'s table is known: also through `map`, `push`, a conditional or `??`, where a row\'s data is held on its own\n (`{ item: row.data }`, read `p.item.state`), and where it is destructured (`const { state } = p.item.data`). It is not\n known for rows of two tables, for rows of a call whose `table_id` is not written out, for `linked()` over a link read off\n such a held row (read the link while the row is in hand), and a helper\'s field-path text reads the rows of a records\n tool and a loop over them only (over rows held in objects, pass a callback). (The record tools called outside a workflow return the stored arrays instead.)\n- `linked(record["link"])[n]["x"]` fetches the n-th linked row and reads a field of it; bare\n `linked(record["link"])` is every linked row, one fetch per row. Its argument is a path ending on\n a link field and carries the guard: `linked(record?.["link"])[0]`.\n- `changes["link"]?.next_value` is the same list of ids; `linked()` over a change is refused \u2014\n read `linked(record["link"])` or `linked(prev_record["link"])`.\n\n## Operators and statements\n\nOperators in JavaScript precedence: `? :`, `||`, `??`, `&&`, `== != === !==`, `< <= > >=`, `+ -`, `* / %`,\nprefix `! -`.\n\n- Arithmetic is exact decimal (`0.1 + 0.2` is `0.3`). A result computed from a division that does not end\n is the short decimal it reads as (`1 / 3 * 3` is `1`), and stands as computed where it reads long\n (`1 / 3 * 100` is `33.33333333333333`). A comparison between two numbers reads both at 15 significant\n digits. `round` and `formatNumber` round the decimal, a half away from zero: `round(-2.5)` is `-3`. A\n table filter compares stored values exactly.\n- `??` is `coalesce(left, right)`; `?.` reads through a null (`a?.b`, `a?.[0]`, and `s?.trim()` for the\n method names listed under **Helpers**). `x?.()` is refused: helpers and tools are not values.\n- Templates use backticks and `${...}`. `get_workflow` shows a template as `text(\u2026)`, which writes its parts in order as the template does: `text("Missing: ", join(names, ", "), ".")`. A request whose body holds a template\'s `${\u2026}` can be refused before it reaches Lotics, a 403 page rather than an answer; write that text with `text(\u2026)`.\n- Destructuring \u2014 `const { status, name } = record;` binds each name. Renames\n (`{ status: s }`), quoted keys (`{ "ref": ref }`), array patterns with holes\n (`const [first, , third] = xs;`) and defaults (`{ note = "" }`, which apply on null too) work on\n `const`, `let`, `for (const { id } of rows)` and a `const` inside a block. A tool result destructures directly:\n `const { records } = await query_records({...});`. `const a = 1, b = 2;` declares both. Nested\n patterns and rest are refused.\n- Spread \u2014 `[...a, b]` and `{ ...a, b: 1 }` (later keys win), in a tool input\'s values too (`records: [{ a: 1, ...extra }]`).\n At the top of a tool input each input is named, so a spread there reads a `const` bound to an object written in the\n body (`const common = { table_id: "orders" }; await update_records({ ...common, set: { ... } });`); any other spread\n there is refused.\n- Shorthand \u2014 `{ table_id }` is `{ table_id: table_id }`.\n- `xs.push(a, b);` appends, also on a key (`o.items.push(v)`); `o.a.b = v;` sets a nested key;\n `x ??= v`, `x ||= v` and `x &&= v` assign. A `const` may be pushed to or have a key set, as in\n JavaScript; a loop item is read-only.\n- `undefined` reads as `null`, so `x === undefined` is `isNull(x)` and `x !== undefined` is `isNotNull(x)`;\n a key set to null and a key never sent are not told apart (`"k" in o` tells a key that is there). A write\n tells them apart: a field given `undefined` is left as it is (Writing a field: null and undefined).\n- `typeof x` answers JavaScript\'s words, and a null (a missing value too) is `"object"`. `k in o` tests an\n object\'s own keys, or a list\'s indexes and `length`.\n- A filter node may leave out `node_type` when its keys say which it is: `field_key` / `operator` /\n `value` a condition, `logic` / `children` a group, `path` / `condition` a traversal.\n- `function name(p = <default>) { ... }` or `const name = (p = <default>) => ...` \u2014 top level only, expanded at\n every call (a call may come before a `function`; a `const` is declared above the statement that first calls it).\n A parameter takes its type from a default or an annotation (`p: number`). The body is an expression, or a block of\n `const`, `if`/`else` and `return`, reading only its parameters, helpers and the reserved roots \u2014 never the caller\'s\n names, nor `index`. A parameter and a block\'s `const` are written out where they are read: a value read on no path\n is not computed, a `const` nothing reads is refused, and a value from `now()` or a random helper is read once\n (bind it in a `const` before the call to read it more). No recursion; a function never called is refused. A body\n read back shows the expression at each call, not the function.\n- `(() => { ... })()` \u2014 an arrow called where it is written, with no parameters: its block is expanded in place the\n same way, and reads the names in scope there.\n\n**try / catch.** `try { ... } catch (e) { ... }` catches a tool error or an expression error inside the\nbody; `e` is `{ message, type, step_id?, detail? }`. A failed `validate` and a `return` are not\nerrors \u2014 they end the workflow \u2014 and a step that runs after a wait inside the `try` is outside it.\n`finally` is refused: put always-run steps after the `try`.\n\n**Loops.** `for-of`, `while (cond) { ... }`, `do { ... } while (cond);` and\n`for (let i = 0; i < n; i++) { ... }`, each capped at 10,000 iterations. `break;` and `continue;` act\non the innermost loop; labels and `for-in` are refused.\n\n**`let`.** `let x = <expr>;` declares a block-scoped variable; the initializer is required\n(`let x = null;`). Reassign with `=`, `+=`, `-=`, `*=`, `/=`, `%=`, `??=`, `++` and `--`. Re-declaring in\nthe same block is refused; shadowing in a nested block is allowed. A `let` keeps its value across a\n`wait` or `wait_for_event`.\n\n**Refused, each because a save must know what runs and a run must give the same answer twice:** regex\n(unbounded matching: use the string methods), `Math.random`, `Date.now()` and `new Date()` (use `now()` and\n`parseDate`), a tool or helper as a value or a computed callee (callees are named), `new` of anything,\n`instanceof`, `delete`, `void`, rest elements, computed keys, classes, `throw`, `finally`, `import`,\n`export`, `eval`, labels, and a function as a value anywhere but a top-level `const` (pass the arrow to the helper\nthat takes it). `xs.sort(...)` on a name or path is refused too, since a value is never changed in place:\nwrite `xs.toSorted(...)` or `[...xs].sort(...)`. Inside a block a loop, `let` and a reassignment are refused: use a\nhelper, or compute the value before the callback.\n\n## Typing\n\n- The body is type-checked as TypeScript before it is read: annotations, `as`, `satisfies` and a non-null `!`\n are accepted and erased, and the checker is strict about null. The stored body keeps none of them and is checked again as\n stored, by field key, as every later change to its app or tables checks it: a body that types only through one of them is\n refused at save.\n- Narrow what is not typed (a connector\'s JSON is `unknown`) with `typeof`, `in`, `Array.isArray` and `isNull`.\n- `first(xs)` may be undefined; `requireFirst(xs)` is the list\'s first item or an error. A test of `first(xs)` covers no second `first(xs)`: bind it once (`const id = first(xs)`), then test `id`.\n- `obj[key]` needs `key` to be a key of `obj`, or `obj` to be a record with a string index.\n\n## Helpers\n\nOrdinary JavaScript works \u2014 the standard library below, the array and string methods, `Math`, `JSON`,\n`Object`, `Array`, `Number`, `parseInt` \u2014 and means what it means in JavaScript, with the differences\nlisted here. Where JavaScript answers NaN, Infinity or undefined, a workflow has none of them and the\nanswer is `null`.\n\n- Standard library: `Math.abs/ceil/floor/trunc/sign/min/max/pow/sqrt`, `Number(x)`, `String(x)`,\n `Boolean(x)`, `parseInt(s, radix?)`, `parseFloat(s)`, `Number.isFinite/isInteger`,\n `Object.keys/values/entries/fromEntries`, `Array.isArray/from` (a list, text, or `{ length: n }`),\n `JSON.parse/stringify`.\n- Arrays: `length, map, filter, find, findIndex, findLast, some, every, reduce, includes, indexOf, join,\n slice, concat, flat, flatMap, at, reverse, toReversed, toSorted` and `[...xs].sort(compare?)`.\n- Strings: `length, toLowerCase, toUpperCase, trim, trimStart, trimEnd, startsWith, endsWith, includes,\n indexOf, slice, substring, split, replace, replaceAll, padStart, padEnd, repeat, charAt, at,\n localeCompare` (en-US order, wherever it runs). Numbers: `toFixed, toString`.\n- Differences from JavaScript: `Math.round` is the engine\'s `round` (a half goes away from zero:\n `Math.round(-2.5)` is `-3`); `Number(x)` and `parseFloat(x)` are `toNumber`, which refuses text that is no\n number; `String(null)` is `""`; `join` writes a null item as `null`; `concat` skips a null; `toFixed`\n rounds the decimal, not the binary double; `replaceAll` writes the replacement as text\n (`$&` stays as typed), while `replace` expands `$&`, `$$`, `` $` `` and `$\'` in it as JavaScript does; `split` takes no limit; `sort` without a comparator orders by text, as JavaScript does. `==`, `!=`, `===` and `!==` between two list values (files, a multi-select, a link of any cardinality, a lookup) are refused at save, since a list compares by identity, not by its items: `!isNull(changes.<field>)` asks whether one changed.\n\nThe same work can be written with the helpers below, which are additions to JavaScript. They are called as\n`size(arr)`; the method form works only where the name is also a JavaScript method \u2014\n`x.trim()`, `arr.includes(v)`, `arr.at(-1)`, `arr.map(fn)`, `s.split(",")`; `arr.size()` is refused.\n\n- **Null and type**: `isNull`, `isNotNull`, `isEmpty`, `isString`, `isNumber`, `isBoolean`, `isArray`,\n `isObject`, `coalesce`, `get`, `toNumber`, `toFigure`, `toString` (a text, number, yes/no or date; a record, file or list is refused at save, an object at run), `typeOf`, `parseJson`, `toJson`. `isNull` is strict (`null` and `undefined` only), but on a list field of the record (a link, files, a multi-select) it asks whether the list holds nothing, since a cleared list is `[]`: `!isNull(record.vehicle)` reads as `!isEmpty(record.vehicle)`. `isNull(changes.<field>)` stays strict: null there means unchanged\n- **Lists**: `size`, `first`, `requireFirst` (the first item, refusing an empty list \u2014 after a\n `validate` on the size it saves an `if`), `last`, `nth`, `at` (`at(arr, -1)` counts from the end),\n `includes`, `filter`, `find`, `some`, `every`, `pluck`, `sortBy`, `groupBy`, `countBy`, `unique`,\n `uniqueBy`, `compact` (drops falsy items), `flatten`, `reverse`, `slice`, `concat`, `difference`,\n `differenceBy`, `intersection`, `intersectionBy`, `list`, `reduce(arr, (acc, x) => ..., initial)`,\n `range(end)` / `range(start, end)`\n- **Math**: `sum`, `sumBy`, `mean`, `meanBy`, `minBy`, `maxBy`, `round`, `ceil`, `floor`, `min`, `max`,\n `abs`, `mod`, `pow`, `sqrt`, `clamp`, `percentage`, `distance(lat1, lon1, lat2, lon2)` (metres along the earth between two places in degrees; null when an argument is empty)\n- **Text**: `upper`, `lower`, `capitalize`, `trim`, `contains`, `startsWith`, `endsWith`, `replace`,\n `replaceAll`, `removeChars(str, chars)` (without every character that occurs in `chars`),\n `removeSpaces(str)` (without any whitespace; a Word template command calls both too), `substring`, `length`, `split`, `join`, `padStart(str, length, char)`,\n `padEnd(str, length, char)`, `formatNumber(x, decimals)` (ungrouped; rounds the decimal, a half away\n from zero: `formatNumber(1.005, 2)` is `1.01`),\n `formatDecimal(x, decimals, locale)` (grouped: `formatDecimal(151000, 0, "vi-VN")` is `151.000`),\n `numberToWords(x, lang?)` (an integer in words: Vietnamese, or English with `"en"`),\n `uuidFrom(text)` (the same UUID for the same text, refusing null and empty text: `uuidFrom(record.id)`)\n- **Objects**: `keys`, `values`, `entries`, `nonNullKeys`, `pick`, `omit`, `merge`\n- **Dates**, in the workspace\'s timezone: `now`, `formatDate`, `parseDate`, `addDays`, `subDays`,\n `addHours`, `subHours`, `addMinutes`, `subMinutes`, `startOfDay`, `endOfDay`, `startOfMonth`, `endOfMonth`,\n `addMonths` (a day past the target month\'s end lands on its last day), `differenceInCalendarDays`, `differenceInHours`, `differenceInMinutes`, `isBefore`, `isAfter`,\n `isSameDay`, `isToday`, `isWithinRange`, `datesOn(from, until, days)` (the days from `from` to `until`, both included, falling on weekdays named `mon` to `sun`), `meetsBounds`. A date beside a moment compares by day, so `<=` means\n through that day; `startOfMonth` and `endOfMonth` of a date answer a day\n- **Options**: `option(field, option)` and `options(field)` (see **Fields and options**)\n- **Other**: `formatCurrency(amount, locale, currency)`, `randomNumber(len)`,\n `randomAlphaNumeric(len)`, `sample(items)` (a random item)\n\nOver a null or empty list `mean`, `meanBy`, `min`, `max`, `minBy` and `maxBy` answer null, while `sum`\nand `sumBy` answer 0: `maxBy(pieces, "reach")?.Name` prints a blank for a month with no pieces.\n\nA date helper given a null or empty date returns null, so guard its result before comparing or\nwriting it: `differenceInCalendarDays(a, b) ?? 0`.\n\n`filter`, `find`, `some`, `every`, `sortBy`, `pluck`, `sumBy`, `meanBy`, `minBy`, `maxBy`, `groupBy`,\n`countBy`, `uniqueBy`, `differenceBy` and `intersectionBy` take a path string\n(`filter(record.items, "Status", "open")`) or a callback\n(`filter(record.items, x => x.Status == "open" && x.Amount > 100)`); `reduce` takes a callback and an\ninitial value. A callback gets `(item, idx)` (`reduce`: `(acc, item, idx)`) and reads `record`,\n`runtime`, the names in scope, loop items and an enclosing callback\'s parameters. Its body is one\nexpression \u2014 `(x) => <expr>` \u2014 or a block of `const` declarations, `if`/`else` and `return`, every path\nending in `return <expr>;` (`(x) => { \u2026 }` or `function (x) { \u2026 }`):\n\n```js\nconst orders = await query_records({ table_id: "orders", all: true });\nconst customers = await query_records({ table_id: "customers", all: true });\nconst rows = orders.records.map((o) => {\n const c = find(customers.records, (x) => x.id == o.data.customer[0]);\n if (c == null) { return null; }\n return { name: c.data.name, total: o.data.qty * o.data.price };\n});\nreturn({ status: "success", message: text(rows.length) });\n```\n\nA block\'s `const` behaves as a top-level `const` does, and destructures as one (`const { qty, price } = o.data;`).\nInside a block a loop, `let`, a reassignment, `switch` and `try` are refused: use a helper (`map`, `filter`, `find`,\n`reduce`) or compute the value before the callback. A declared function and an arrow called where it is written take\nthe same block; a table check takes none. `async` and named function expressions are refused.\n\nLook a row up by key rather than filtering for it: a `filter` inside a callback walks its whole list again\nfor every item, so a thousand items against a few hundred rows is hundreds of thousands of calls. Group the\nrows once, then read each group by its key. `groupBy` answers an object of lists, and `byCode[code] ?? []`\nis the group a code names, or an empty list:\n\n```\nconst parties = await query_records({ table_id: "parties", all: true });\nconst lines = await query_records({ table_id: "sheet_lines", all: true });\nconst byCode = groupBy(parties.records, (p) => p.data["code"] ?? "");\nconst holders = lines.records.map((line) => ({\n line: line.id,\n parties: (byCode[line.data["code"] ?? ""] ?? []).map((p) => p.id),\n}));\n```\n\nA key is read exactly: a code holding a dot, a slash or a bracket reads its own group, and a name every\nobject inherits (`constructor`) reads nothing unless a row made a group of that name. `get(o, "a.b")`\nfollows a dotted path instead, so a key that holds a dot is read with `o[key]`.\n\n## Writing a field: null and undefined\n\nIn `update_records`\' `set`, `create_records`\' `records` and the workflow step `save_record`\'s `set` and line rows:\n\n- `null` clears the field.\n- `undefined`, or leaving the key out, leaves the field as it is.\n\nSo passing a read that may be null (`record["x"]`) keeps a value when there is one and clears the\nfield when there is none. Use `coalesce(x, fallback)` only for a real fallback value.\n\nA body is refused at save when a `create_records` whose table and rows are written out leaves a required field of that\ntable unset in a row. The platform fills a `default`, an autonumber, a derived date and a computed field; a copied field\n(`default_from`) fills only when the row sets its link. A required date counts as set when the row enters a stage whose\ndate it is: the stage the create states, or the status field\'s `default` when it states none.\n\n## Examples\n\nCompare a link by id. Display text is not unique, and a link reads as a list of ids \u2014 `==` against a\nstring is a type error:\n\n```\nconst found = await query_records({\n table_id: "customers",\n filters: { node_type: "condition", field_key: "name", operator: "equals", value: "ACME Corp" },\n});\nconst customer = first(found.records);\nconst order = (await query_records({ table_id: "orders", record_ids: [trigger.app_workflow.inputs.order_id] })).records[0];\n\nif (customer && includes(order.data["customer"], customer.id)) {\n // \u2026\n}\n```\n\nRead an uploaded sheet and add the rows a table lacks. `excel_get_rows`, a workflow step, answers every\nrow of an `.xlsx`, `.xls` or `.csv` sheet in one call, each an object keyed by the header row\'s text. A cell is a number,\n`true` or `false`, text, a date as ISO text, or null when blank, so `row["Header"]` is typed\n`string | number | boolean | null` and a helper narrows it: `toString` for text, `toNumber` for a number,\n`isString` before a date. Every cell of a `.csv` is text. `columns` keeps only the ones the body reads.\nA sheet past what one call reads is refused with its size, never cut short: the step\'s entry in\n`workflow_steps` states the bounds.\n\nA sheet\'s rows are written with `save_record`, a workflow step, once per row. `match` is the row\'s identity,\n`{ code: <the row\'s code> }`, and must be a uniqueness its table declares: the field is `unique`. A live row carrying\nthe key is found and only the cells of `set` that differ are written; none is found and the row is added. Run the same\nfile twice and the second run writes nothing new. A cell the row has no value for is left out of `set`, and `null` is an\nempty cell, which differs from a filled one as any other value does. A row the body should not write is skipped and\ncounted in what the workflow returns, so the person who ran it is told; the step holds nothing back on its own, and a\nrow a table check or a lock refuses fails the call, naming the row.\n\nA link cell takes the record id of the row it links. To find that row by the text a sheet holds, `query_records` the\nlinked table once, `groupBy` its key, and read the id from the group. A body that does not find the row skips the\nsheet\'s row and counts it.\n\n```\nconst sheet = await excel_get_rows({ // a workflow step\n file_id: trigger.app_workflow.inputs.file,\n columns: ["Code", "Name", "Price"],\n});\n\nconst kept = await create_records({\n table_id: "price_sheets",\n records: [{ file: [trigger.app_workflow.inputs.file], run: runtime.execution_id }],\n});\nconst sheet_id = kept.record_ids[0];\n\nlet added = 0;\nlet changed = 0;\nlet skipped = 0;\nfor (let at = 0; at < size(sheet.rows); at += 1) {\n const row = sheet.rows[at];\n if (isNull(row["Price"])) {\n skipped += 1;\n await create_records({\n table_id: "sheet_lines",\n records: [{ sheet: [sheet_id], line: at + 2, outcome: "skipped", why: "The sheet states no price", code: toString(row["Code"]) }],\n });\n } else {\n const saved = await save_record({ // a workflow step\n table_id: "plants",\n match: { code: toString(row["Code"]) },\n set: { name: toString(row["Name"]), price: toNumber(row["Price"]) },\n });\n added += saved.created ? 1 : 0;\n changed += !saved.created && size(saved.updated_field_keys) > 0 ? 1 : 0;\n }\n}\n\nreturn({ status: "success", message: `${added} added, ${changed} changed, ${skipped} skipped` });\n```\n\nOne `save_record`, a workflow step, per row writes about a hundred rows a second on a table of thirty fields with a link, a lookup and a\nformula: a thousand rows took ten seconds. A run whose writes finish within twenty seconds lands all or nothing; a\nlonger one starts again, each row written as it is reached, and three thousand rows took seventy of the ninety seconds\nan awaited call gives a run. A sheet of up to about a thousand rows loops; a larger one is written in batches.\n\nThe batched form reads the table\'s keys once and writes in calls of up to a thousand rows. `query_records` the table\nin pages (a call reads 50 rows unless it states a `limit`, and 1000 at most), `groupBy` the key, split the sheet\'s rows into those with no row yet and those whose cells differ, then\n`create_records` the first and `update_records` the second in its per-record form (`field_keys` and one `rows` entry per\n`record_ids` entry). Ten thousand rows took about seven seconds, a repeat with nothing changed under three, and the\nwhole of it is one transaction at that size. The body does the comparison, so it writes only what differs:\n\n```\nconst inputs = trigger.app_workflow.inputs;\n\nconst sheet = await excel_get_rows({ // a workflow step\n file_id: inputs.file,\n columns: ["Code", "Name", "Price"],\n});\nconst rows = sheet.rows.map((row) => ({ code: toString(row["Code"]), name: toString(row["Name"]), price: toNumber(row["Price"]) }));\n\nlet held = (await query_records({ table_id: "plants", field_keys: ["code", "name", "price"], pagination: { offset: 0, limit: 1000 } })).records\n .map((one) => ({ id: one.id, code: toString(one.data["code"]), name: toString(one.data["name"]), price: toNumber(one.data["price"]) }));\nfor (let start = 1000; start < inputs.row_count; start += 1000) {\n const page = await query_records({ table_id: "plants", field_keys: ["code", "name", "price"], pagination: { offset: start, limit: 1000 } });\n held = concat(held, page.records.map((one) => ({ id: one.id, code: toString(one.data["code"]), name: toString(one.data["name"]), price: toNumber(one.data["price"]) })));\n}\nconst byCode = groupBy(held, (one) => one.code);\n\nconst fresh = filter(rows, (row) => size(byCode[row.code] ?? []) == 0);\nconst changed = filter(rows, (row) =>\n size(byCode[row.code] ?? []) > 0 &&\n (requireFirst(byCode[row.code] ?? []).name != row.name || requireFirst(byCode[row.code] ?? []).price != row.price));\n\nfor (let at = 0; at < size(fresh); at += 1000) {\n await create_records({ table_id: "plants", records: slice(fresh, at, at + 1000) });\n}\nfor (let at = 0; at < size(changed); at += 1000) {\n const part = slice(changed, at, at + 1000);\n await update_records({\n table_id: "plants",\n record_ids: part.map((row) => requireFirst(byCode[row.code] ?? []).id),\n field_keys: ["name", "price"],\n rows: part.map((row) => [row.name, row.price]),\n });\n}\n\nreturn({ status: "success", message: `${size(fresh)} added, ${size(changed)} changed` });\n```\n\n`inputs.row_count` is a number the act asks beside the file. A key the table keeps `unique` refuses a second row with\nit, so a sheet that carries one key twice fails the `create_records` call, naming it, before any row of that call is\nwritten.\n\nA workflow does not put a run\'s writes back: that reads the history of what the run wrote, which a member\'s agent reads\nunder the member\'s own access to the table and no workflow does. A member\'s agent puts them back with\n`update_records`: `query_audit_logs` on the table shows what the run wrote \u2014 the run is what `runtime.execution_id` held in\nit, which a body keeps on a row of its own \u2014 and each field\'s value before it, `update_records` writes that value back as\nthe member\'s own write, `update_records` with `restore: true` brings back a row the run moved to the trash, and\n`delete_records` removes a row the run created. Write a field back only where the row still holds what the run wrote.\n\nWhat a business keeps of a sheet \u2014 the file, its counts, the lines waiting for a person \u2014 is rows of its own tables,\nwritten by the workflow that ran. A garden centre brings its grower\'s price sheet into its plants, and keeps each sheet\nand the lines it skipped. These tables are shown beside the plants, in the same app: the sheets as a List beside the\nplants\' (a second List at the root, `reference/app-node`), a sheet\'s lines on the page it opens. A line keeping what a\ncell held and what it holds now in two fields reads one against the other (`compare`, `reference/list-node`).\n\nA skipped line is applied by the act on it, whose workflow reads the line and saves the plant from it. A cell the line\nholds none of is left out, so a skipped line never empties a cell of the plant:\n\n```\nconst line = (await query_records({ table_id: "sheet_lines", record_ids: [trigger.app_workflow.inputs.record_id] })).records[0];\nconst values = {\n ...(isEmpty(line.data["name"]) ? {} : { name: line.data["name"] }),\n ...(isNull(line.data["price"]) ? {} : { price: line.data["price"] }),\n};\n\nawait save_record({ // a workflow step\n table_id: "plants",\n match: { code: line.data["code"] },\n set: values,\n});\n\nawait update_records({ table_id: "sheet_lines", record_ids: [line.id], set: { outcome: "applied" } });\nreturn({ status: "success", message: "Applied." });\n```\n\n### A reviewed act\n\nA shop matches a bank statement to the notes it is owed by an act that states `review`. That act\'s workflow only\nproposes: its body calls steps that read and no other, and runs no agent \u2014 either is refused when the body is saved \u2014\nand returns in `data.review` one changeset of the act\'s table, which the platform writes the approved rows of. Called\nwith what the act asks, it answers the proposal and nothing is written; called again with\n`approved: { creates: [{ key, sha }], updates?: [{ record_id, sha }] }` (absent `updates` means none), the body runs again and the platform writes\nthose rows as this second run proposes them, so the body never reads `approved`. The platform adds a `sha` to every row\nof the proposal it answers \u2014 the body states none, and one it states is dropped \u2014 and the caller echoes the `sha` of\neach row it approves. A row the second run proposes with other values than the `sha` was read from is left unwritten\n(`changed`), so the body must propose the same for the same inputs and the rows it reads.\nAn update is of a record the act is run over (`record_id`, or one of `record_ids`): one of any other record is left\nunwritten. An act over every row in view is handed no rows: its body reads the rows it may change, and any of them may\nbe proposed. A create carries a `key`, a text of the body\'s own that names the same line on every run\n(`key: toString(line["Reference"])`), unique among the creates; where a confirm repeated must not add a second row,\nthe body also writes the key into a field the table keeps unique, so the repeat\'s create is left as a `conflict`.\nEach row\'s `data` holds only stored fields that change \u2014 never one the platform computes or stamps, nor a file \u2014 with\na `note` and a `ticked` the reader starts from, and `unplaced` lists what was read and matched nothing. Every approved\nrow is checked against its fields before any is written, and they are written in one transaction, so a flawed one\nwrites none. The status history of every row written that moved, or was made holding a status, is recorded in the\nsame run. The answer\'s `applied.previous` holds what each updated record\'s written fields held before, so one `update_records` of it puts the values back, and `delete_records` of a `created` record takes that row away. A body that stops proposing a row once it is\nwritten \u2014 it matches against what the rows hold now \u2014 makes approving twice write once.\n\n```\nconst inputs = trigger.app_workflow.inputs;\n\nconst sheet = await excel_get_rows({ // a workflow step\n file_id: inputs.statement,\n columns: ["Reference", "Amount", "Paid on"],\n});\nconst unpaid = await query_records({\n table_id: "notes",\n filters: { field_key: "paid_on", operator: "is_empty" },\n pagination: { offset: 0, limit: 500 },\n});\nconst acted = groupBy(inputs.record_ids, (id) => toString(id));\nconst owed = filter(unpaid.records, (one) => size(acted[toString(one.id)] ?? []) > 0);\nconst byRef = groupBy(owed, (one) => toString(one.data["ref"]));\n\nconst lines = sheet.rows.map((line) => ({\n line,\n note: first(byRef[toString(line["Reference"])] ?? []),\n}));\nconst updates = filter(lines, (one) => !isNull(one.note)).map((one) => ({\n record_id: toString(one.note?.id),\n note: `Transfer of ${toString(one.line["Amount"])}`,\n ticked: toNumber(one.line["Amount"]) == sumBy(filter(owed, (owing) => owing.id == one.note?.id), (owing) => coalesce(owing.data["amount"], 0)),\n data: { paid_on: toString(one.line["Paid on"]) },\n}));\nconst unplaced = filter(lines, (one) => isNull(one.note)).map((one) => ({\n title: `${toString(one.line["Reference"])}: ${toString(one.line["Amount"])}`,\n note: "Matches no unpaid note",\n}));\n\nreturn({\n status: "success",\n message: `${size(updates)} of ${size(lines)} transfers match a note`,\n data: { review: { version: 1, table_id: "notes", creates: [], updates, unplaced } },\n});\n```\n\n### Saving a record with its lines\n\n`save_record`, a workflow step, saves one record and the rows of other tables that hang off it, all or\nnothing, and recognises what exists by the identity the input carries \u2014 so a call sent twice updates and\nadds nothing. `match` is the record\'s identity, `{ field_key: value }`, and must be exactly a uniqueness\nits table declares: one field marked `unique`, or the fields of one of the table\'s `unique` sets together\n(text, number, date, single select and one-row link fields). A `match` that is no declared uniqueness is\nrefused, naming what the table does declare: where the body is saved when its table and fields are written\nout, at run otherwise. A table cannot lose a uniqueness a stored `save_record` matches on: declare the new\none beside it, move the workflows to it, then take the old one away. A live record carrying the match is found and only the cells\nof `set` that differ are written; none is found and it is added with `match` and `set`. `add_to` appends\nto a files, multi-select or many-link field and keeps what it holds.\n\n`lines` saves rows of other tables that link the record. Each entry names the child `table_id`, its\n`link` \u2014 a field of the child holding one row of this table, which the step fills and no row states \u2014\nthe child fields that, with `link`, are one uniqueness of the child table (`match`), and `rows`, each\nstating every `match` field. A line found by its match changes only the cells that differ, one not found\nis added, and a line the call does not list is left as it is: the step deletes nothing. Two rows of one\nentry cannot share a match.\n\nEverything is checked before the first write, and everything is written in one transaction: a table check\nthat refuses one line, a locked record or line the call would change, a value a field does not take, or a\ntable the run may not write refuses the call and saves nothing, naming the row. Two calls of one identity\ntake turns, so the second finds what the first saved. The answer is `record_id`, `created`,\n`updated_field_keys` (the cells changed on a record that existed) and, per entry of `lines`, the ids it\nadded, changed and left unchanged; these ids are typed for their tables, so a declared `record_link`\noutput or a follow-up write links straight to them.\n\n```\nconst inputs = trigger.app_workflow.inputs;\n\nconst sheet = await excel_get_rows({ // a workflow step\n file_id: inputs.release_order,\n columns: ["Size", "Quantity"],\n});\n\nconst saved = await save_record({ // a workflow step\n table_id: "release_orders",\n match: { number: inputs.number },\n set: { note: "Read from the paper" },\n lines: [{\n table_id: "release_lines",\n link: "order",\n match: ["size"],\n rows: sheet.rows.map((row) => ({\n size: toString(row["Size"]),\n quantity: toNumber(row["Quantity"]),\n })),\n }],\n});\n\nreturn({\n status: "success",\n message: `${size(saved.lines[0].created_ids)} lines added`,\n data: { record_id: saved.record_id },\n});\n```\n\n### Numbering a row at a moment\n\nA number given when a row is signed or issued is an editable number field the workflow fills with the table\'s highest plus one,\nonly while the row has none, so a second press keeps its number. The field carries a one-field `unique` set on its table, so two\nruns that read the same highest are refused, not doubled; the refused run reads the highest again, for three attempts in all, and\na run still refused after the third fails with that refusal. The last attempt stands outside the `try`, since a `catch` takes any\ntool error, not the unique refusal alone. A sequence per series or year filters the query on it and states a two-field `unique`.\n\n```\nif (isNull(record.no)) {\n let numbered = false;\n for (let attempt = 0; attempt < 2 && !numbered; attempt++) {\n const top = await query_records({ table_id: "contracts", sort: [{ field_key: "no", order: "desc" }], limit: 1 });\n try {\n await update_records({ table_id: "contracts", record_ids: [record.id], set: { no: coalesce(first(top.records)?.data["no"], 0) + 1 } });\n numbered = true;\n } catch (e) {\n numbered = false;\n }\n }\n if (!numbered) {\n const last = await query_records({ table_id: "contracts", sort: [{ field_key: "no", order: "desc" }], limit: 1 });\n await update_records({ table_id: "contracts", record_ids: [record.id], set: { no: coalesce(first(last.records)?.data["no"], 0) + 1 } });\n }\n}\n```\n\n## Schedules\n\nA weekly pattern made into dated rows is a parent\'s `records.cadence` and an Act `makes` it\n(`reference/record-places-pins-and-cadence`), no body; pressed again it also moves the rows the pattern now makes otherwise that no one has touched. The rest of a timetable is a rule or a short body.\n\n**A student in two places.** An enrolment reads its span and its days off its course, so one meeting at the same\ntime on a shared weekday as the student\'s other course is refused at save:\n\n```json\n"no_overlap": { "from": "course.starts", "to": "course.ends", "by": ["student", "course.days"], "while": { "state": ["active"] } }\n```\n\n**A swap.** One Act on a shift runs a `workflow` asking the other shift (an input `other` of `type: "link"`, `entity` the shifts) and writes both people in one call:\n\n```\nconst inputs = trigger.app_workflow.inputs;\nconst both = (await query_records({ table_id: "shifts", record_ids: [inputs.record_id, inputs.other] })).records;\nconst mine = requireFirst(filter(both, (one) => one.id == inputs.record_id));\nconst theirs = requireFirst(filter(both, (one) => one.id == inputs.other));\nawait update_records({\n table_id: "shifts",\n record_ids: [mine.id, theirs.id],\n field_keys: ["person"],\n rows: [[theirs.data["person"]], [mine.data["person"]]],\n});\nreturn({ status: "success", message: "Swapped." });\n```\n\n**A rotation.** A pattern that turns over the days (teams taking nights in turn) is a body: `datesOn(from, until,\ndays)` lists the days of a range falling on the weekdays named.\n\n```\nconst inputs = trigger.app_workflow.inputs;\nconst days = datesOn(inputs.from, inputs.until, ["mon", "tue", "wed", "thu", "fri"]);\nconst teams = (await query_records({ table_id: "teams", record_ids: inputs.record_ids })).records;\nconst rows = days.flatMap((day, at) => teams.map((team, place) => ({ team: [team.id], day, kind: (at + place) % 2 == 0 ? "day" : "night" })));\nfor (let at = 0; at < size(rows); at += 1000) {\n await create_records({ table_id: "shifts", records: slice(rows, at, at + 1000) });\n}\nreturn({ status: "success", message: `${size(rows)} shifts` });\n```\n\n**Pay at the rate taught, and a month closed.** A lesson copies its teacher\'s rate when it is made (`"default_from":\n"teacher.rate"`), so a rise later leaves the lessons already made alone; a formula multiplies it by the lesson\'s hours,\nand a Tab\'s `totals` sums each teacher\'s month. A pay period is a row with its first and last day and a status; a check\non the lessons refuses every write inside a closed one:\n\n```json\n"checks": { "month_closed": {\n "on": ["create", "update", "delete"],\n "lookups": { "period": { "table": "pay_periods", "limit": 1, "filter": { "node_type": "group", "logic": "and", "children": [\n { "node_type": "condition", "field_key": "first_day", "operator": "on_or_before", "value": { "$expr": "record.starts_at" } },\n { "node_type": "condition", "field_key": "last_day", "operator": "on_or_after", "value": { "$expr": "record.starts_at" } },\n { "node_type": "condition", "field_key": "status", "operator": "has_any_of", "value": ["closed"] } ] } } },\n "fail_when": "size(lookups.period) > 0",\n "message": "\\"This month\'s pay is closed.\\""\n} }\n```\n\n## Reaching a connected service\n\nA service is reached only by a workflow step, and a step is called inside an app\'s workflow or an automation. From\nnothing to an app\'s run:\n\n1. `get_workspace` with `kind: "connection"` lists each `connected_account_id`.\n2. `set_app` declares a Workflow node that states what a call takes and hands back:\n\n```json\n{\n "type": "Workflow",\n "key": "invoice_order",\n "description": "Issues the KiotViet invoice for a confirmed order and hands back its code.",\n "inputs": { "order": { "type": "record_link", "entity": "order" } },\n "outputs": { "invoice_code": { "type": "text" } }\n}\n```\n\n3. `set_workflow` with a `source` that opens with `on({ type: "app", app_id: "app_\u2026", alias: "invoice_order" });` and this body (the step\'s entry is in `workflow_steps`):\n\n```\nconst order = (await query_records({ table_id: "orders", record_ids: [trigger.app_workflow.inputs.order] })).records[0];\nconst made = await kiotviet_create_invoice({ // a workflow step\n connected_account_id: "cac_\u2026",\n branch_id: 1,\n sold_by_id: 7,\n lines: [{ product_id: 42, quantity: toNumber(order.data["quantity"]), price: toNumber(order.data["price"]) }],\n});\nreturn({ status: "success", message: "Invoiced", data: { invoice_code: made.invoice.code } });\n```\n\n4. `run_app_workflow` with `dry_run: true`, then the same call without it.\n\nTo change later what it takes or hands back, send the node\'s change and the new body in one `set_app`, the body under\n`workflows`.\n\nA step wants the provider\'s own ids (`branch_id`, `sold_by_id`, `product_id`) and no tool lists them: declare a Workflow\nwhose body calls the provider\'s `list_*` workflow step (`kiotviet_list_branches`), run it, and read the ids from its answer.\nNo step lists KiotViet\'s users: read `sold_by_id` off a row `kiotviet_list_invoices` returns (KiotViet\'s `soldById`), or ask the owner.\n\n## Table checks\n\nA table check is one condition its table\'s record writes must not meet, declared beside the table\'s\n`unique`. It is not a workflow: it reads the write and a few lookups and answers yes or no, so it\ncannot change data. It runs inside the write, on every create, update or delete it is `on`, whichever\nsurface makes it \u2014 a person, the API, the CLI, an agent, a workflow. A refusal writes nothing and\nanswers with the check\'s message, under its field when the check names one, and names the check.\n\nA check is stated in its table\'s document, under `checks`, each under an alias of its own, and\n`set_tables` writes it with the rest of the table: a merge patch edits one, `null` removes it, and a\ncall that makes a table can state its checks, a lookup naming another table of the call by its `ref`.\n`get_table` states a table\'s checks in its document.\n\n| part | what it holds |\n|---|---|\n| `on` | the writes it checks: any of `create`, `update`, `delete` |\n| `when` | optional expression; the check runs only on a write where it is truthy. It cannot read lookups. |\n| `lookups` | optional, by name, the rows to read: `{ table, filter, limit }`, `table` an id or the `ref` of a table of the call, the filter as `query_records` takes it with fields and select options named by alias (`id` matches a row by its own record id), `limit` from 1 to 50 (50 when left out). A filter value that reads the record is `{ "$expr": "record.code" }`. |\n| `fail_when` | expression; truthy refuses the write |\n| `message` | expression for the refusal\'s text \u2014 a fixed text is a quoted string |\n| `field` | optional; the alias of the field the refusal is shown under |\n| `enabled` | `false` keeps the check without deciding writes; absent, it decides |\n\nEvery expression is written in the grammar above, names a table\'s fields and select options by\nalias (`record.status == "closed"`), and reads:\n\n- `record` \u2014 the record as it will be stored; on a delete, the record being deleted.\n- `prev_record` \u2014 on an update or a delete, the record before.\n- `changes` \u2014 on an update, the fields it changes. `!isNull(changes.photos)` asks whether a field changed.\n- `lookups.<name>` \u2014 in `fail_when` and `message`, the rows that lookup read. A row reads as `record` does: its fields by alias beside `id` (`row.start_on`), and a lookup field as the flat list of what it looks up (`first(row.booking_start)` through a one-row link). A lookup over the written table never returns the row being checked, and finds its other rows as the write leaves them, this call\'s other rows included. A field given to a helper as text names it by alias too (`sumBy(lookups.paid, "amount")`); text that names no field of the rows\' table is refused when the check is saved.\n- `runtime.timezone`, `runtime.workspace_id`, `runtime.organization_id`, `runtime.change_origin` (the\n write\'s origin), `runtime.triggered_by_member_id` (the member writing; null for a write no member\n made), `now()`, and `member_of("grp_\u2026")` \u2014 true when the member writing belongs to the group.\n\nIn a check a select reads as its one value (`record.kind == "retail"`), and a link (a one-row link too) and a lookup read as lists (`first(record.customer)`).\n\nA check on several operations reads only what all of them carry, so one on creates and updates reads\nneither `prev_record` nor `changes`.\n\nA write that recomputes another table\'s rows (a rollup over lines, a lookup or a formula over a parent) judges each recomputed row as an update, by the checks `on` `update` that read a field the recompute changed; `changes` is what the recompute changed. A check that refuses on `changes` or on a status the row holds can therefore refuse the write that moved the parent, so it is gated on the field it means (`!isNull(changes.status)`).\n\nA lookup reads with the access of the member who last saved the check, so saving one requires reading\nevery table its lookups read. A check\'s reads wait on the writes they depend on: the rows its links name are locked before it reads, and any other lookup takes a lock per check, so two writes at the same moment can\'t both pass a check the other would fail. Values no two rows may share are the table\'s `unique`.\n\nA `when`, a lookup or a `fail_when` that cannot decide \u2014 it fails, or the write\'s time runs out \u2014\nrefuses the write, naming the part it was reading and, for an expression or a filter, what it met\n(`lookups.clash: Filter on "start_on": date \'before\' value \u2026 is not a date`). A draft is checked when it is submitted, as a create; its edits before that are\nnot. A restored record is checked as a create. Cloning a table copies its checks to the member who\nclones it, and is refused when that member cannot read a table a check\'s lookup reads.\n\nOne open order per reference, a row never counting against itself:\n\n```json\n{\n "tables": [\n {\n "ref": "orders",\n "label": "Orders",\n "fields": {\n "reference": { "type": "text", "label": "Reference" },\n "closed_at": { "type": "date", "label": "Closed at" }\n },\n "checks": {\n "one_open_order_per_reference": {\n "on": ["create", "update"],\n "when": "isNull(record.closed_at)",\n "lookups": {\n "same_ref": {\n "table": "orders",\n "filter": {\n "node_type": "group",\n "logic": "and",\n "children": [\n { "node_type": "condition", "field_key": "reference", "operator": "equals", "value": { "$expr": "record.reference" } },\n { "node_type": "condition", "field_key": "closed_at", "operator": "is_empty" }\n ]\n },\n "limit": 2\n }\n },\n "fail_when": "some(lookups.same_ref, (r) => r.id != record.id)",\n "message": "\\"An open order already has this reference.\\"",\n "field": "reference"\n }\n }\n }\n ]\n}\n```\n\n## Table workflows\n\nA table workflow is what follows every committed write of a table\'s rows, whoever makes it: the grid, an import, an agent or\nany app. An effect that must hold for all of them belongs to the table. A button on one screen is that app\'s act, a value fixed\nwhen a row is made is `default_from`, and a rule that refuses a write is a check; a table workflow runs after the write has\ncommitted and cannot refuse it.\n\n`set_workflow` writes it: the `source` opens with `on({ type, table, ... })` and carries the steps, and `enabled: false`\nkeeps the workflow without running it (absent, it runs). `get_table` lists a table\'s workflows to whoever manages the\ntable \u2014 `workflow_id`, name, trigger, whether it is on and its failed runs of the last 7 days \u2014 and `get_workflow` reads one\nback. The table and the trigger type (`create`, `update` or `delete`) are fixed once the workflow is made: to change\neither, delete it and make another. A replace that changes only the gate, the trigger config or `enabled` moves the\nworkflow\'s version. `dry_run` with a `record_id` (and, for an update, `prev_data` and `changes`, each changed field as `{ prev_value, next_value }`) says what the workflow would\nwrite on that row; reads are real and nothing is written.\n\n| part of the header | what it holds |\n|---|---|\n| `type` | the write it follows: `create`, `update` or `delete`; a `delete` workflow runs once, when the row is deleted; deleting it for good from the trash runs none |\n| `table` | the table\'s alias |\n| `when` | optional expression over `record`, `prev_record` and `changes`; the workflow runs only after a write where it is truthy |\n| `changed` | optional, with `type: "update"`: field aliases; the workflow runs only after an update that changes any one of them |\n\n```\non({ type: "update", table: "repairs", changed: ["status"], when: "record.status == \\"fixed\\"" });\n\nawait update_records({ table_id: "repairs", record_ids: [trigger.record_id], set: { fixed_on: formatDate(now(), "yyyy-MM-dd") } });\n```\n\nThe body names the table\'s fields, select options and other tables by alias, and reads the write as `record`,\n`prev_record` and `changes`, the row\'s id as `trigger.record_id`, and the member who made the write as\n`runtime.triggered_by_member_id` (null for a write no member made). It operates on records and integrations: a body\nthat calls a tool changing a table, an app or any other structure is refused when it is saved. It runs as the table\'s owner, so\nit reaches the tables the owner reaches, and its writes meet the table\'s checks like any other write; a write refused by a\ncheck fails that run and leaves the row as it was. A body names a field by alias where it can tell which table\'s field it is: a\nread of `record`, `prev_record` or `changes`, a row from `query_records` called with a literal `table_id`,\na row `find`, `first`, `at` or an index picks from such rows, and a loop or callback over them, each also when held in an\nobject or a list written out, or a spread. A row read through `map` or `push`, or picked by a conditional or `??`, is not\ntied to its table: read its fields where the row itself is in hand (`rows.map((r) => ({ state: r.data.state, n: 1 }))`). A name it cannot tie to a table, and an option compared to a value of unknown type (not a read of a field, and\nnot a text, number or other value the type proves holds no option), are refused with what to change. A link reads as the list of the row ids it holds, a one-row link too: compare `first(record.customer) == id`. A lookup reads as one flat list of what it looks up: `record.x != prev_record.x` on one is refused, so compare `first(record.x)` with `first(prev_record.x)`. A single member, a single select, a number or a text reads as the value itself: `first(record.technician)` is refused at save, naming the read.\n\nA write the workflow itself makes sets off the workflows of its table in turn, and a chain of them stops after five. A workflow\nthat writes the row it follows is gated by a `changed` or a `when` that its own write does not satisfy. One run is queued for a\nrow and a workflow at a time, so a burst of writes to one row runs it once more after the run in flight. A field a workflow\nreads cannot be deleted or retyped until the workflow is changed or deleted with `set_workflow` before. Cloning a table copies its\nworkflows for whoever manages it (`include_workflows: false` leaves them), each with a body of its own, and is refused when a\nbody names a table the cloner cannot reach. A workflow runs as the table\'s owner, so whoever saves or rehearses one must manage the\ntable and read every table it reads in full: the body\'s, the gate\'s links\', the written table. An option is written where\nit is compared to, listed against or set on its field; a constant holding one is refused.\n\nA lock is the table\'s: a table workflow locks a row with `update_records` and `locked: true` (an app\'s act may too), and every door then refuses\nthe row\'s writes until whoever manages the table unlocks it with `update_records` and `locked: false` \u2014 in an app\'s run, judged as the member who pressed.\nA locked row reads locked in every app. An app\'s own Check or `edit: false` only makes a row read-only in that app.\n\n## Runs\n\nEach start of a workflow is a run: an app\'s workflow or act, a table workflow, a button, an automation. A call through an\napp\'s API to a workflow that only reads is kept as a run only when it fails or returns an error, unless its body reads\n`runtime.execution_id` or `runtime.change_origin`. An agent finds, reads, retries and stops runs. A run is read by whoever manages what its workflow belongs to: its\nautomation or its table, and for an app\'s workflow the app\'s owner or an admin, never a manager of the app.\n\n- **Find.** `query_workflow_executions` lists one workflow\'s runs (`workflow_id`), every run started for one row\n (`record_id`) \u2014 a table workflow\'s written row, a pressed button\'s row, an app run\'s `record_id` input \u2014 or both, newest\n first, a page at a time (`next_cursor`). A listing naming no workflow and no row covers every workflow whose runs the caller may read. Each run names its workflow and kind, what started it, its row and how it ended:\n for a failure, the step that threw, its tool and the error; for a waiting run, when it wakes, or the payment. A run started before runs recorded their row carries no `record_id`.\n- **Read.** `get_workflow_execution` gives one run\'s steps in order with each one\'s tool, input, output and error, what it\n returned, how many rows it wrote (a row\'s own history is in `query_audit_logs`) and the runs its writes started. Ninety days\n after a run starts, its trigger and its steps\' input and output are pruned; the read says so and gives the rest.\n `run_app_workflow` answers each run it makes with its `execution_id`.\n- **Retry.** `set_workflow_execution` with `action: "retry"` runs a failed, refused or cancelled run again as a new run linked to the first\n (`retry_of`): the first run\'s trigger and row, the workflow\'s current steps and its owner\'s current access, with the\n member who retries it as the one who started it. A run is retried once; a retry that fails is retried in turn. It asks\n first when the run, or a run it retried, already wrote rows or called a service no delete reverses. An automation\'s or a\n table workflow\'s retry runs in the background, as its runs do, and answers `queued`; a button\'s and an app\'s run while\n the call waits. An app\'s call is checked again against the workflow\'s current inputs. A pruned run, a run of a workflow\n that is off, a reviewed act\'s run (call the act again) and a recording\'s filing (the recording retries its delivery)\n are not run again.\n- **Stop.** `set_workflow_execution` with `action: "cancel"` stops a waiting run. Both answer\n `execution_id`, `action`, `status`, `retry_of`, `error` and, for a retry, `original_wrote`: the rows and the irreversible\n calls the first run wrote, which the retry makes again.\n\nOff means off: a waiting run whose workflow was turned off, deleted, or taken off its automation, table, button or app ends\n`cancelled` when it would resume, saying why, and runs no further step.\n\nA waiting run keeps its version: when it resumes, it runs the steps of the version it started with, so an edit saved while it\nwaited changes later runs only. When that version is gone, the run ends failed and says why.\n';
1941
+ var workflows_default = '# Workflows \u2014 the steps a workflow runs\n\nA workflow is written as a strict subset of JavaScript. The source is never run as JavaScript: a\nsave parses it into steps, type-checks it against what its trigger supplies, and stores the steps.\nOnly the forms below are accepted; anything else is refused at save with the line, the column and\nwhat to write instead. A save that succeeds may still return `warnings` \u2014 advisory hints such as a\nloop that may never end. Read them.\n\nA workflow changes records, calls integrations, notifies and makes papers. A tool for anything else \u2014 views, history,\ntables and apps, members, knowledge, skills, editing a file \u2014 is an agent\'s, and a body that\ncalls one is refused at save with that reason. One saved before is refused at run, before its first step.\n\nThe same grammar serves a table\'s workflow, an automation and an app\'s workflow, which `set_workflow` saves, and the\nexpressions of a table check.\n\n## Triggers\n\nEvery workflow\'s source opens with `on({ ... })`, which states what starts it. `set_workflow` saves the source, and\n`get_workflow` reads it back with whether it is on and how its latest runs ended. `get_workflow` without a\n`workflow_id` lists the workflows you may read, a page at a time (`limit` 1 to 100, `offset`, `total`), each with its\n`kind`, its trigger in a line, whether it is on and its failed runs of the last 7 days; `table_id` and `app_id` keep the\nones that follow or name them.\n\n| kind | header |\n|---|---|\n| table | `on({ type: "create" \\| "update" \\| "delete", table: "<alias>", changed?: ["<alias>", ...], when?: "<expression>" })` |\n| automation | `on({ type: "recurring_schedule", cron_expression })`, `receive_webhook`, `receive_gmail_email` or `receive_outlook_email` \u2014 see **Automations** |\n| app | `on({ type: "app", app_id, alias, inputs?, outputs? })` \u2014 `inputs` and `outputs` only for a custom-code app |\n| notification | `on({ type: "notification", inputs: { ... } })` \u2014 what a card\'s action hands the body |\n\nWhat starts a workflow is fixed once it is made: its kind, a table workflow\'s trigger type and table, an automation\'s\ntrigger type, an app workflow\'s app and alias. To change either, delete the workflow and make another. A replace states the whole trigger, so a key the\nheader leaves out is removed (an app workflow keeps the inputs it leaves out, and derives the outputs it leaves out from\nwhat the body returns). `expected_version` refuses a replace when the workflow has moved since the `version` you read.\n`dry_run` checks the source and stores nothing; given the trial inputs its trigger supplies, it also walks the steps once\nand returns the calls planned, the return value, the failures and the papers rendered. A table trigger takes `record_id`,\n`prev_data` and `changes`; a webhook or email trigger `trigger_payload`; an app trigger `record_id` and `preview_inputs`; a\ntable or automation trigger also `live_reads` (an app\'s rehearsal always reads real data). A trial input its trigger does\nnot supply is refused, naming the ones it takes. A rehearsal needs write scope: a key that reads data alone cannot make one.\nA rehearsal\'s answer cuts a long list or text where it stands and says how much it kept; each step\'s output follows the\ncalls and the return value, cut to its first rows.\n\nA stored workflow is changed without sending it whole: `edits` with its `workflow_id` are anchored replacements in the\nsource `get_workflow` returns (`[{ old_string, new_string }]`; `op` inserts before or after an anchor, or appends), and the\nwrite is refused if the workflow moved since the version they were made against. A source not stored yet rides a file:\n`source_file_id` takes it from a stored text file in place of `source`; write the source where you work, upload it with\n`upload_file` (`files`) and pass the `file_id`.\n\n`delete: true` with a `workflow_id` removes a workflow, and is the one call that asks for approval; a replace asks for none,\na step it drops included. `even_if_invoked` and `acknowledge_breaking_api_change` belong to an app workflow and are\nrefused for another kind.\n\nA notification workflow is run by the action of a notification card under its owner\'s access; the press only triggers it. It declares `inputs` as an app workflow does, reads them as `inputs.<name>` (or `trigger.notification_action.inputs.<name>`), cannot `wait` or `wait_for_event`, and is bound to no table, automation, button or app. Its owner or an admin reads, replaces and deletes it and puts it on a card, and it still runs as its owner; it has one owner for life and is archived with them when they leave (its open cards close), never handed on. Its writes are judged and attributed as its owner. Its runs are read by its owner and admins, and are never retried: pressing the card again is the retry. A step that sends a card names each action\'s `workflow_id` as a literal. Only a workflow sends a card; an `agent` step writes the title and body it sends.\n\nAn app workflow reads its call as `trigger.app_workflow.inputs.<name>`, or `inputs.<name>`, which is the same read. A Workflow node receives the inputs it declares;\nan Act\'s `workflow` receives `record_id` (`record_ids` on an act over several rows) and what the Act asks.\n\n### Automations\n\nAn automation answers an event outside the records: a schedule, a webhook, an inbound email. `set_workflow` saves one\nfrom its source \u2014 the `on({...})` declaration, then its steps \u2014 and, given its `workflow_id`, replaces it: the\ntrigger config is the one the header states, a key it leaves out removed, and steps left as it runs them are checked again\nonly when the call turns it on (`enabled`), so one a later rule refuses can still be switched off. An admin names the owner at creation with\n`owner_member_id`. It runs with its owner\'s current permissions, a connected service it names is its owner\'s account, and only its\nowner or an admin reads, changes or deletes it.\n\n```\non({ type: "recurring_schedule", cron_expression: "0 9 * * MON" });\n```\n\nEvery source below is typed, so a misspelled member is refused at save rather than read as nothing.\nAll three carry `trigger.trigger_id`.\n\n| trigger | required config | what the body reads |\n|---|---|---|\n| `recurring_schedule` | `cron_expression` | `runtime.timezone`; the current time is `now()` |\n| `receive_webhook` | `secret`? | `trigger.method`, `trigger.headers[...]`, `trigger.query[...]`, `trigger.body` (any JSON, or raw text when the request is not JSON), `trigger.received_at` |\n| `receive_gmail_email` / `receive_outlook_email` | `connected_account_id`, `filter` | `trigger.email_id`, `trigger.from`, `trigger.to`, `trigger.cc`, `trigger.bcc`, `trigger.subject`, `trigger.date`, `trigger.body` (plain text), `trigger.reply_to`, `trigger.in_reply_to`, `trigger.attachments` (file refs \u2014 assign them straight to a files field). One type serves both providers, so `labels`, `thread_id`, `importance` and `conversation_id` are not readable. |\n\n## Steps\n\n| step | syntax |\n|---|---|\n| tool call, kept | `const <id> = await <tool>({ ...inputs });` \u2014 also `let x = await \u2026` and `x = await \u2026` |\n| tool call | `await <tool>({ ...inputs });` \u2014 the platform\'s own steps (`send_notification`, `generate_document`, \u2026) and a connection\'s tools, each a workflow step (`bkav_submit_invoices`, `kiotviet_create_order`, \u2026); a step that fails ends the run with its reason unless a `try`/`catch` around it handles it |\n| agent | `const <id> = await agent({ instructions, input, model, output });` \u2014 see **An agent step** |\n| app agent | `const <id> = await app_agent({ alias: "<agent alias>", input: { ... } });` \u2014 runs one of the app\'s declared agents, in an app workflow only, and resolves to its declared outputs or its final text. `wait: false` only starts the run and resolves to `{ run_id }`; the run\'s failure is then its own, not the workflow\'s. Refused in a run an agent started. |\n| bind | `const <id> = <expression>;` \u2014 evaluated once; later steps read `<id>`. Bind any expression used twice. |\n| if / else | `if (<expr>) { ... } else { ... }` \u2014 `else` optional, `else if` chains allowed |\n| switch | `switch (<expr>) { case "X": { ... } default: { ... } }` \u2014 string cases only, no fallthrough |\n| for | `for (const <name> of <expr>) { ... }` |\n| wait | `await wait({ duration_in_minutes: 5 });` |\n| wait for an event | `await wait_for_event({ event_type: "webhook", event_ref: <expr>, timeout_in_minutes: 60 });` |\n| return | `return({ status: "success" \\| "error", message: <expr>, field_errors: { ... }?, data: { ... }? });` \u2014 `data` holds the outputs a Workflow node declares \u2014 a body whose steps only read and write the workspace\'s rows and make papers runs as one transaction: a return of `error`, a failed `validate`, a table\'s refusal or a failure takes back every write of the run, and a run too long to hold one starts again step by step; a body that also calls out (a send, a connected service, an import of rows, another workflow), waits or runs an agent runs step by step: each step\'s writes stand as they land and a return of `error` undoes none, so its refusals stand before its first write; an Act\'s own write (`set`, asks, signature) and its papers land after the body, before each `success` return and where the body ends, so a refusal leaves the row as it stood, and the body\'s `row` and any read of the row in the body see it as the press found it |\n| validate | `validate({ checks: [{ fail_when: <expr>, field_key: "...", message: <expr> }, ...] });` |\n\nA delayed run is never cancelled from a workflow: after a `wait`, it reads the row\'s state and acts only if it still holds.\n\nA tool\'s inputs and answer are in its own description; the steps only a body runs \u2014 a connection\'s, a mail\'s \u2014 are each\nan entry of `workflow_steps`. An admin connects a service in Lotics under Settings \u2192 Connections; a step names that\nconnection by its `connected_account_id`, which `get_workspace` with `kind: "connection"` lists for the connections the\ncaller can use. The app\'s owner must be able to use that connection, so a\n`connected_account_id` is a literal, a constant bound to one, or a choice among them: every possible value is judged at\nsave, and one read from an input, a record or a call is refused. A template may come from data; a run refuses one its\nowner cannot use.\n\nIn a workflow, the step `send_notification` reaches a member of the workspace: the member sees it in their Lotics\ninbox, and it is mailed only to a member who has chosen email for their notifications. Its recipients are members by\n`member_id` (`get_workspace` with `kind: "member"` lists them), member groups or the whole organization. Mail that\nmust arrive, to a member or anyone else, goes from a\nconnected Gmail or Outlook (`gmail_send_email`, `outlook_send_email`), which leaves an unsent draft unless `draft` is\n`false`.\n\n`return` is a call, not a JavaScript `return` statement. A `success` may leave out `message`, and a bare\n`return;` is that success; an `error` states its `message`. `validate` ends the workflow with an error\nwhen a check\'s `fail_when` is truthy; the check\'s `field_key` names the control its message lands on \u2014\nin an app workflow a declared input, or the alias of a field on a table the body names; in an\nautomation it is not checked.\n\nThe name in `const x = await tool({...})` is the step\'s id; later expressions read its output as\n`x.records`, `x.id` and so on. A `// id: my_step` comment directly above a statement sets an explicit\nid; any other `//` comment there becomes the step\'s description.\n\nA run reads a repeated identical record read once, until the run writes; a loop that waits for a row to change needs a `wait` step, or each pass sees the same rows.\n\nA `query_records` with no `limit` returns the first 50 rows, and `has_more` says whether there are more. `all: true` returns every row the call matches, up to 32 MiB of them; a call past that is refused, with no rows. `all` does not combine with `limit`, `offset`, `page_size`, `pagination`, `record_ids`, `aggregate`, `tables` or `comments`, and a workflow\'s read takes no `as_file`.\n\n`sort` of a records read also takes `__created_at` and `__updated_at`, a row\'s creation and last-update time (`{ field_key: "__created_at", order: "desc" }` is newest-created first); with `include_timestamps: true` each row carries `created_at` and `updated_at`, read as `r.created_at`.\n\n**`await` inside a statement** runs the call as its own step first, then reads its output where it is\nwritten: `size((await query_records({...})).records)`, an `if` test, a `return` value, a `for-of`\niterable, a tool input. `const x = c ? await t({...}) : null;` is stored as the `if` it means. An\n`await` that would run on some paths only \u2014 inside `&&`, `||`, `??`, `?.`, a nested ternary, a loop\ntest, a `validate` check \u2014 is refused; write the `if`.\n\n**Names are block-scoped, as in JavaScript** \u2014 `const`, `let`, loop items and `catch (e)`: sibling\nblocks may reuse a name and an inner block may shadow an outer one. A local may take a helper\'s name\n(`const size = 3;`), but calling `size(...)` while it is in scope is refused. The names of the tools a\nworkflow calls, the reserved roots, `linked` and `_s` followed by digits cannot be bound.\n\n### An agent step\n\n`const x = await agent({ instructions, input, model, output });` runs a model as one step \u2014 read a paper, classify,\ndraft text. It calls no tool: the workflow\'s own steps write, send and notify with what it returns, and a step that\nstates `tools` is refused.\n\n- `instructions` \u2014 a fixed string.\n- `input` \u2014 an object literal; its fields are expressions, evaluated and handed to the model (`{}` for\n none). It is the ONLY workflow data the agent sees: read the trigger, prior steps, `runtime` or the loop\n item here, never inside `instructions`, which is a fixed literal and reads no binding. A field holding a file, or a\n list of files (a files field, a mail\'s attachments), hands the agent the files themselves: a picture or a PDF it\n sees, any other paper read into text.\n- `model` \u2014 optional; omit it to follow the platform\'s default model.\n- `output` \u2014 `{ mode: "text" }` resolves to a string; `{ mode: "object", schema }` to a typed object.\n\nOnly `x` comes back: in text mode `x` is the string itself, in object mode `x.field` reads a field the\n`schema` declares.\n\n## Naming tables and templates\n\nA body names a table or document template by its alias (`query_records({ table_id: "orders" })`); ids still work. `get_workflow` shows aliases. An app\'s workflow reaches only the tables the app uses.\n\n## Fields and options\n\n1. **A body names a table\'s fields and select options by alias**, the names the table\'s document states: a field reads\n as `record["status"]`, an option as `"done"`, a linked field as `linked(record["customer"])[0]["name"]`, in the\n body of a Workflow node, of an Act\'s own `workflow`, of an automation and of a table\'s workflow (`set_workflow`). It is stored by key and `get_workflow` shows it by alias\n again. A field\'s key is accepted where its alias is and is kept as written; an option\'s key is read as that option\'s\n alias, and one that two tables\' options share with different aliases is refused where it is read, naming both. A\n display name is refused with the aliases there are, and a row that names one field by both its alias and its key is refused. A row written to a table is\n stored by field key wherever the save can follow it to the record tool that writes it: a row or list written in the call,\n a conditional of them, a name holding them, pushed to a `let`, and through `map`, `flatMap`, `concat`, `filter`, `sortBy`,\n `slice` and `reverse`. A field of such rows is read by alias as well (`picks.toSorted((a, b) => a.quantity - b.quantity)`,\n `sortBy(picks, "quantity")`, `rows[0].note`) and stored by key. A body that cannot be stored by key is refused at save,\n naming the statement.\n2. **An Act\'s own `workflow`** has the app\'s guards placed at the top of the body, between `<lotics:guards>` tags,\n replaced on every save: a save that leaves them out or edits them gets the app\'s again, at the top wherever the tags\n sat, so the act\'s row rule, `when`, `requires`, checks and locks always run first.\n3. **A value is read as the record tools store it.** A single select reads as its option\'s alias and a member as its id;\n an option is written by its alias wherever it meets a select \u2014 compared, listed, switched on, written \u2014 also beside a\n name set from the field (`const s = record.status; s == "done"`) or in a list that search runs over\n (`includes(filter(record.tags, \u2026), "hot")`). A select value handed on whole (returned for a declared select, written to a\n select field or a filter) is resolved to the option\'s key where it leaves the body; one handed to a text, a message or a\n template carries the alias. A link reads as the list of its row ids, a\n one-row link too: `first(record.customer)` is the one id, and `record.customer` used as one id is refused at save,\n naming `first(record.customer)`. A one-row link is written with its one id or a list of one; a many-row link with a list. A lookup reads as one flat list of the values it looks up: `includes(record.owner,\n me)`; a looked-up link, as the ids of its rows, which `query_records` takes as `record_ids`. A select\'s value is one of another select\'s options where the two state the same alias for it; two selects that\n state no alias in common never hold one value, and a save that compares them or copies one into the other is refused.\n A row that takes its parent\'s option gets it from `default_from`, and a lookup shows it.\n A grouped aggregate\'s `key` reads as the option\'s alias, and `get(row.data, "<field>")` as `row.data.<field>` (an empty cell takes the default).\n4. **What an app sends takes an option by alias or key.** An input or output drawn from a field (`field`, written\n `<table id>.<alias>`) compares and returns by alias in the body, and the run hands it on as the option\'s key. A\n refusal\'s `field_errors` and a `validate` check\'s `field_key` name a declared input or a field\'s alias.\n5. **`==` against a multi-select means "includes".** `record["tags"] == "urgent"` on a multi-select is stored as\n `includes(record["tags"], "urgent")`; either spelling works.\n6. **`option("<field>", "<option>")` names an option where no select is beside it** (a name set once and compared later,\n a list of options, a value handed to a tool). It reads as the option, typed as that select\'s, and is stored as its alias. The field is a select or a formula that states `options`.\n The field is looked up among the tables the body reaches; a field or option that does not exist is refused naming both, and\n a field alias that two tables state with different keys for that option is refused naming each table, as is one printed\n (rule 7) where the tables label that option differently. An option\n key written out reads as its alias, but write `option()`: a key is a value no one can read. `options("<field>")` lists\n the field\'s options in its order, each `{ alias, label }`, found and refused as `option()`\'s field is\n (`options("status").map((o) => o.label)`); it is read when the run reads it, so a reorder or a relabel shows at once.\n7. **Text renders labels.** Inside a template, `text(...)` or a text tool input, a select, member or link value renders its display\n text: `` `${record["status"]}` `` writes "Done", not `done`, and `` `${record["status"] ?? ""}` `` writes it too. A\n card\'s action inputs and the option keys its ask offer take the alias, a field\'s value included. `option("status", "done")`\n and a select input read as `inputs.stage` print a label only in a template, `text(...)` or a document\'s data: the label\n its field, or the workflow\'s declared input, states when the run prints it; a multi-select\'s labels print as a field\'s\n do. Handed to any other tool input, compared, written or filtered on, each is the option\'s alias: `title: inputs.stage`\n is the alias, `` title: `Stage ${inputs.stage}` `` prints the label. A name bound to the value (`const s = inputs.stage`,\n `const o = option("status", "done")`, `const v = record.status`) prints the value. A formula stating `options` (a computed category) is read as the single select it is drawn as:\n compared by option, rendered by label.\n\n## What an expression reads\n\n- `record`, `prev_record`, `changes` \u2014 in a table check, the write it checks (see **Table checks**).\n `changes` is a PARTIAL map: `changes["x"]?.next_value` and `?.prev_value`, the `?.` required.\n- `trigger` \u2014 what the trigger carries (see **Triggers**).\n- a loop\'s item name, and `index`, the iteration\'s 0-based index.\n- `<step id>` \u2014 an earlier step\'s output (`dup.records`).\n- `runtime.timezone`, `runtime.workflow_id`, `runtime.execution_id`, `runtime.workspace_id`,\n `runtime.organization_id`, `runtime.change_origin`, `runtime.triggered_by_member_id`. The current\n time is `now()`.\n\n## Paths\n\n- `record.x` and `record["x"]` read a field; `[n]` reads a list\'s n-th item.\n- A path may start at any expression: an awaited call `(await query_records({ table_id: "orders", record_ids: [id] })).records[0].data["x"]`, a helper\'s\n result `first(found.records).id`, a filter `rows.filter((r) => r.ok)[0].n`, a `(a ?? b).c`. `?.` reads\n through a null as usual, except on a value drawn at random (`sample(xs)?.id` is refused: bind it first).\n- A record reads in its declared shape wherever it comes from \u2014 the trigger, a tool result, a `let`, a\n callback parameter: a single select as its option alias or null, a member as its id, a link as its ids. A property read\n by alias (`x.order.quantity`, `xs[0]["quantity"]`, `y.quantity`) also names the record\'s field when the record is held in an\n object, a list or a spread (`{ order: record }`, `[record]`, `{ ...record }`). A field is named by alias wherever the\n row\'s table is known: also through `map`, `push`, a conditional or `??`, where a row\'s data is held on its own\n (`{ item: row.data }`, read `p.item.state`), and where it is destructured (`const { state } = p.item.data`). It is not\n known for rows of two tables, for rows of a call whose `table_id` is not written out, for `linked()` over a link read off\n such a held row (read the link while the row is in hand), and a helper\'s field-path text reads the rows of a records\n tool and a loop over them only (over rows held in objects, pass a callback). (The record tools called outside a workflow return the stored arrays instead.)\n- `linked(record["link"])[n]["x"]` fetches the n-th linked row and reads a field of it; bare\n `linked(record["link"])` is every linked row, one fetch per row. Its argument is a path ending on\n a link field and carries the guard: `linked(record?.["link"])[0]`.\n- `changes["link"]?.next_value` is the same list of ids; `linked()` over a change is refused \u2014\n read `linked(record["link"])` or `linked(prev_record["link"])`.\n\n## Operators and statements\n\nOperators in JavaScript precedence: `? :`, `||`, `??`, `&&`, `== != === !==`, `< <= > >=`, `+ -`, `* / %`,\nprefix `! -`.\n\n- Arithmetic is exact decimal (`0.1 + 0.2` is `0.3`). A result computed from a division that does not end\n is the short decimal it reads as (`1 / 3 * 3` is `1`), and stands as computed where it reads long\n (`1 / 3 * 100` is `33.33333333333333`). A comparison between two numbers reads both at 15 significant\n digits. `round` and `formatNumber` round the decimal, a half away from zero: `round(-2.5)` is `-3`. A\n table filter compares stored values exactly.\n- `??` is `coalesce(left, right)`; `?.` reads through a null (`a?.b`, `a?.[0]`, and `s?.trim()` for the\n method names listed under **Helpers**). `x?.()` is refused: helpers and tools are not values.\n- Templates use backticks and `${...}`. `get_workflow` shows a template as `text(\u2026)`, which writes its parts in order as the template does: `text("Missing: ", join(names, ", "), ".")`. A request whose body holds a template\'s `${\u2026}` can be refused before it reaches Lotics, a 403 page rather than an answer; write that text with `text(\u2026)`.\n- Destructuring \u2014 `const { status, name } = record;` binds each name. Renames\n (`{ status: s }`), quoted keys (`{ "ref": ref }`), array patterns with holes\n (`const [first, , third] = xs;`) and defaults (`{ note = "" }`, which apply on null too) work on\n `const`, `let`, `for (const { id } of rows)` and a `const` inside a block. A tool result destructures directly:\n `const { records } = await query_records({...});`. `const a = 1, b = 2;` declares both. Nested\n patterns and rest are refused.\n- Spread \u2014 `[...a, b]` and `{ ...a, b: 1 }` (later keys win), in a tool input\'s values too (`records: [{ a: 1, ...extra }]`).\n At the top of a tool input each input is named, so a spread there reads a `const` bound to an object written in the\n body (`const common = { table_id: "orders" }; await update_records({ ...common, set: { ... } });`); any other spread\n there is refused.\n- Shorthand \u2014 `{ table_id }` is `{ table_id: table_id }`.\n- `xs.push(a, b);` appends, also on a key (`o.items.push(v)`); `o.a.b = v;` sets a nested key;\n `x ??= v`, `x ||= v` and `x &&= v` assign. A `const` may be pushed to or have a key set, as in\n JavaScript; a loop item is read-only.\n- `undefined` reads as `null`, so `x === undefined` is `isNull(x)` and `x !== undefined` is `isNotNull(x)`;\n a key set to null and a key never sent are not told apart (`"k" in o` tells a key that is there). A write\n tells them apart: a field given `undefined` is left as it is (Writing a field: null and undefined).\n- `typeof x` answers JavaScript\'s words, and a null (a missing value too) is `"object"`. `k in o` tests an\n object\'s own keys, or a list\'s indexes and `length`.\n- A filter node may leave out `node_type` when its keys say which it is: `field_key` / `operator` /\n `value` a condition, `logic` / `children` a group, `path` / `condition` a traversal.\n- `function name(p = <default>) { ... }` or `const name = (p = <default>) => ...` \u2014 top level only, expanded at\n every call (a call may come before a `function`; a `const` is declared above the statement that first calls it).\n A parameter takes its type from a default or an annotation (`p: number`). The body is an expression, or a block of\n `const`, `if`/`else` and `return`, reading only its parameters, helpers and the reserved roots \u2014 never the caller\'s\n names, nor `index`. A parameter and a block\'s `const` are written out where they are read: a value read on no path\n is not computed, a `const` nothing reads is refused, and a value from `now()` or a random helper is read once\n (bind it in a `const` before the call to read it more). No recursion; a function never called is refused. A body\n read back shows the expression at each call, not the function.\n- `(() => { ... })()` \u2014 an arrow called where it is written, with no parameters: its block is expanded in place the\n same way, and reads the names in scope there.\n\n**try / catch.** `try { ... } catch (e) { ... }` catches a tool error or an expression error inside the\nbody; `e` is `{ message, type, step_id?, detail? }`. A failed `validate` and a `return` are not\nerrors \u2014 they end the workflow \u2014 and a step that runs after a wait inside the `try` is outside it.\n`finally` is refused: put always-run steps after the `try`.\n\n**Loops.** `for-of`, `while (cond) { ... }`, `do { ... } while (cond);` and\n`for (let i = 0; i < n; i++) { ... }`, each capped at 10,000 iterations. `break;` and `continue;` act\non the innermost loop; labels and `for-in` are refused.\n\n**`let`.** `let x = <expr>;` declares a block-scoped variable; the initializer is required\n(`let x = null;`). Reassign with `=`, `+=`, `-=`, `*=`, `/=`, `%=`, `??=`, `++` and `--`. Re-declaring in\nthe same block is refused; shadowing in a nested block is allowed. A `let` keeps its value across a\n`wait` or `wait_for_event`.\n\n**Refused, each because a save must know what runs and a run must give the same answer twice:** regex\n(unbounded matching: use the string methods), `Math.random`, `Date.now()` and `new Date()` (use `now()` and\n`parseDate`), a tool or helper as a value or a computed callee (callees are named), `new` of anything,\n`instanceof`, `delete`, `void`, rest elements, computed keys, classes, `throw`, `finally`, `import`,\n`export`, `eval`, labels, and a function as a value anywhere but a top-level `const` (pass the arrow to the helper\nthat takes it). `xs.sort(...)` on a name or path is refused too, since a value is never changed in place:\nwrite `xs.toSorted(...)` or `[...xs].sort(...)`. Inside a block a loop, `let` and a reassignment are refused: use a\nhelper, or compute the value before the callback.\n\n## Typing\n\n- The body is type-checked as TypeScript before it is read: annotations, `as`, `satisfies` and a non-null `!`\n are accepted and erased, and the checker is strict about null. The stored body keeps none of them and is checked again as\n stored, by field key, as every later change to its app or tables checks it: a body that types only through one of them is\n refused at save.\n- Narrow what is not typed (a connector\'s JSON is `unknown`) with `typeof`, `in`, `Array.isArray` and `isNull`.\n- `first(xs)` may be undefined; `requireFirst(xs)` is the list\'s first item or an error. A test of `first(xs)` covers no second `first(xs)`: bind it once (`const id = first(xs)`), then test `id`.\n- `obj[key]` needs `key` to be a key of `obj`, or `obj` to be a record with a string index.\n\n## Helpers\n\nOrdinary JavaScript works \u2014 the standard library below, the array and string methods, `Math`, `JSON`,\n`Object`, `Array`, `Number`, `parseInt` \u2014 and means what it means in JavaScript, with the differences\nlisted here. Where JavaScript answers NaN, Infinity or undefined, a workflow has none of them and the\nanswer is `null`.\n\n- Standard library: `Math.abs/ceil/floor/trunc/sign/min/max/pow/sqrt`, `Number(x)`, `String(x)`,\n `Boolean(x)`, `parseInt(s, radix?)`, `parseFloat(s)`, `Number.isFinite/isInteger`,\n `Object.keys/values/entries/fromEntries`, `Array.isArray/from` (a list, text, or `{ length: n }`),\n `JSON.parse/stringify`.\n- Arrays: `length, map, filter, find, findIndex, findLast, some, every, reduce, includes, indexOf, join,\n slice, concat, flat, flatMap, at, reverse, toReversed, toSorted` and `[...xs].sort(compare?)`.\n- Strings: `length, toLowerCase, toUpperCase, trim, trimStart, trimEnd, startsWith, endsWith, includes,\n indexOf, slice, substring, split, replace, replaceAll, padStart, padEnd, repeat, charAt, at,\n localeCompare` (en-US order, wherever it runs). Numbers: `toFixed, toString`.\n- Differences from JavaScript: `Math.round` is the engine\'s `round` (a half goes away from zero:\n `Math.round(-2.5)` is `-3`); `Number(x)` and `parseFloat(x)` are `toNumber`, which refuses text that is no\n number; `String(null)` is `""`; `join` writes a null item as `null`; `concat` skips a null; `toFixed`\n rounds the decimal, not the binary double; `replaceAll` writes the replacement as text\n (`$&` stays as typed), while `replace` expands `$&`, `$$`, `` $` `` and `$\'` in it as JavaScript does; `split` takes no limit; `sort` without a comparator orders by text, as JavaScript does. `==`, `!=`, `===` and `!==` between two list values (files, a multi-select, a link of any cardinality, a lookup) are refused at save, since a list compares by identity, not by its items: `!isNull(changes.<field>)` asks whether one changed.\n\nThe same work can be written with the helpers below, which are additions to JavaScript. They are called as\n`size(arr)`; the method form works only where the name is also a JavaScript method \u2014\n`x.trim()`, `arr.includes(v)`, `arr.at(-1)`, `arr.map(fn)`, `s.split(",")`; `arr.size()` is refused.\n\n- **Null and type**: `isNull`, `isNotNull`, `isEmpty`, `isString`, `isNumber`, `isBoolean`, `isArray`,\n `isObject`, `coalesce`, `get`, `toNumber`, `toFigure`, `toString` (a text, number, yes/no or date; a record, file or list is refused at save, an object at run), `typeOf`, `parseJson`, `toJson`. `isNull` is strict (`null` and `undefined` only), but on a list field of the record (a link, files, a multi-select) it asks whether the list holds nothing, since a cleared list is `[]`: `!isNull(record.vehicle)` reads as `!isEmpty(record.vehicle)`. `isNull(changes.<field>)` stays strict: null there means unchanged\n- **Lists**: `size`, `first`, `requireFirst` (the first item, refusing an empty list \u2014 after a\n `validate` on the size it saves an `if`), `last`, `nth`, `at` (`at(arr, -1)` counts from the end),\n `includes`, `filter`, `find`, `some`, `every`, `pluck`, `sortBy`, `groupBy`, `countBy`, `unique`,\n `uniqueBy`, `compact` (drops falsy items), `flatten`, `reverse`, `slice`, `concat`, `difference`,\n `differenceBy`, `intersection`, `intersectionBy`, `list`, `reduce(arr, (acc, x) => ..., initial)`,\n `range(end)` / `range(start, end)`\n- **Math**: `sum`, `sumBy`, `mean`, `meanBy`, `minBy`, `maxBy`, `round`, `ceil`, `floor`, `min`, `max`,\n `abs`, `mod`, `pow`, `sqrt`, `clamp`, `percentage`, `distance(lat1, lon1, lat2, lon2)` (metres along the earth between two places in degrees; null when an argument is empty)\n- **Text**: `upper`, `lower`, `capitalize`, `trim`, `contains`, `startsWith`, `endsWith`, `replace`,\n `replaceAll`, `removeChars(str, chars)` (without every character that occurs in `chars`),\n `removeSpaces(str)` (without any whitespace; a Word template command calls both too), `substring`, `length`, `split`, `join`, `padStart(str, length, char)`,\n `padEnd(str, length, char)`, `formatNumber(x, decimals)` (ungrouped; rounds the decimal, a half away\n from zero: `formatNumber(1.005, 2)` is `1.01`),\n `formatDecimal(x, decimals, locale)` (grouped: `formatDecimal(151000, 0, "vi-VN")` is `151.000`),\n `numberToWords(x, lang?)` (an integer in words: Vietnamese, or English with `"en"`),\n `uuidFrom(text)` (the same UUID for the same text, refusing null and empty text: `uuidFrom(record.id)`)\n- **Objects**: `keys`, `values`, `entries`, `nonNullKeys`, `pick`, `omit`, `merge`\n- **Dates**, in the workspace\'s timezone: `now`, `formatDate`, `parseDate`, `addDays`, `subDays`,\n `addHours`, `subHours`, `addMinutes`, `subMinutes`, `startOfDay`, `endOfDay`, `startOfMonth`, `endOfMonth`,\n `addMonths` (a day past the target month\'s end lands on its last day), `differenceInCalendarDays`, `differenceInHours`, `differenceInMinutes`, `isBefore`, `isAfter`,\n `isSameDay`, `isToday`, `isWithinRange`, `datesOn(from, until, days)` (the days from `from` to `until`, both included, falling on weekdays named `mon` to `sun`), `meetsBounds`. A date beside a moment compares by day, so `<=` means\n through that day; `startOfMonth` and `endOfMonth` of a date answer a day\n- **Options**: `option(field, option)` and `options(field)` (see **Fields and options**)\n- **Other**: `formatCurrency(amount, locale, currency)`, `randomNumber(len)`,\n `randomAlphaNumeric(len)`, `sample(items)` (a random item)\n\nOver a null or empty list `mean`, `meanBy`, `min`, `max`, `minBy` and `maxBy` answer null, while `sum`\nand `sumBy` answer 0: `maxBy(pieces, "reach")?.Name` prints a blank for a month with no pieces.\n\nA date helper given a null or empty date returns null, so guard its result before comparing or\nwriting it: `differenceInCalendarDays(a, b) ?? 0`.\n\n`filter`, `find`, `some`, `every`, `sortBy`, `pluck`, `sumBy`, `meanBy`, `minBy`, `maxBy`, `groupBy`,\n`countBy`, `uniqueBy`, `differenceBy` and `intersectionBy` take a path string\n(`filter(record.items, "Status", "open")`) or a callback\n(`filter(record.items, x => x.Status == "open" && x.Amount > 100)`); `reduce` takes a callback and an\ninitial value. A callback gets `(item, idx)` (`reduce`: `(acc, item, idx)`) and reads `record`,\n`runtime`, the names in scope, loop items and an enclosing callback\'s parameters. Its body is one\nexpression \u2014 `(x) => <expr>` \u2014 or a block of `const` declarations, `if`/`else` and `return`, every path\nending in `return <expr>;` (`(x) => { \u2026 }` or `function (x) { \u2026 }`):\n\n```js\nconst orders = await query_records({ table_id: "orders", all: true });\nconst customers = await query_records({ table_id: "customers", all: true });\nconst rows = orders.records.map((o) => {\n const c = find(customers.records, (x) => x.id == o.data.customer[0]);\n if (c == null) { return null; }\n return { name: c.data.name, total: o.data.qty * o.data.price };\n});\nreturn({ status: "success", message: text(rows.length) });\n```\n\nA block\'s `const` behaves as a top-level `const` does, and destructures as one (`const { qty, price } = o.data;`).\nInside a block a loop, `let`, a reassignment, `switch` and `try` are refused: use a helper (`map`, `filter`, `find`,\n`reduce`) or compute the value before the callback. A declared function and an arrow called where it is written take\nthe same block; a table check takes none. `async` and named function expressions are refused.\n\nLook a row up by key rather than filtering for it: a `filter` inside a callback walks its whole list again\nfor every item, so a thousand items against a few hundred rows is hundreds of thousands of calls. Group the\nrows once, then read each group by its key. `groupBy` answers an object of lists, and `byCode[code] ?? []`\nis the group a code names, or an empty list:\n\n```\nconst parties = await query_records({ table_id: "parties", all: true });\nconst lines = await query_records({ table_id: "sheet_lines", all: true });\nconst byCode = groupBy(parties.records, (p) => p.data["code"] ?? "");\nconst holders = lines.records.map((line) => ({\n line: line.id,\n parties: (byCode[line.data["code"] ?? ""] ?? []).map((p) => p.id),\n}));\n```\n\nA key is read exactly: a code holding a dot, a slash or a bracket reads its own group, and a name every\nobject inherits (`constructor`) reads nothing unless a row made a group of that name. `get(o, "a.b")`\nfollows a dotted path instead, so a key that holds a dot is read with `o[key]`.\n\n## Writing a field: null and undefined\n\nIn `update_records`\' `set`, `create_records`\' `records` and the workflow step `save_record`\'s `set` and line rows:\n\n- `null` clears the field.\n- `undefined`, or leaving the key out, leaves the field as it is.\n\nSo passing a read that may be null (`record["x"]`) keeps a value when there is one and clears the\nfield when there is none. Use `coalesce(x, fallback)` only for a real fallback value.\n\nA body is refused at save when a `create_records` whose table and rows are written out leaves a required field of that\ntable unset in a row. The platform fills a `default`, an autonumber, a derived date and a computed field; a copied field\n(`default_from`) fills only when the row sets its link. A required date counts as set when the row enters a stage whose\ndate it is: the stage the create states, or the status field\'s `default` when it states none.\n\n## Examples\n\nCompare a link by id. Display text is not unique, and a link reads as a list of ids \u2014 `==` against a\nstring is a type error:\n\n```\nconst found = await query_records({\n table_id: "customers",\n filters: { node_type: "condition", field_key: "name", operator: "equals", value: "ACME Corp" },\n});\nconst customer = first(found.records);\nconst order = (await query_records({ table_id: "orders", record_ids: [trigger.app_workflow.inputs.order_id] })).records[0];\n\nif (customer && includes(order.data["customer"], customer.id)) {\n // \u2026\n}\n```\n\nRead an uploaded sheet and add the rows a table lacks. `excel_get_rows`, a workflow step, answers every\nrow of an `.xlsx`, `.xls` or `.csv` sheet in one call, each an object keyed by the header row\'s text. A cell is a number,\n`true` or `false`, text, a date as ISO text, or null when blank, so `row["Header"]` is typed\n`string | number | boolean | null` and a helper narrows it: `toString` for text, `toNumber` for a number,\n`isString` before a date. Every cell of a `.csv` is text. `columns` keeps only the ones the body reads.\nA sheet past what one call reads is refused with its size, never cut short: the step\'s entry in\n`workflow_steps` states the bounds.\n\nA sheet\'s rows are written with `save_record`, a workflow step, once per row. `match` is the row\'s identity,\n`{ code: <the row\'s code> }`, and must be a uniqueness its table declares: the field is `unique`. A live row carrying\nthe key is found and only the cells of `set` that differ are written; none is found and the row is added. Run the same\nfile twice and the second run writes nothing new. A cell the row has no value for is left out of `set`, and `null` is an\nempty cell, which differs from a filled one as any other value does. A row the body should not write is skipped and\ncounted in what the workflow returns, so the person who ran it is told; the step holds nothing back on its own, and a\nrow a table check or a lock refuses fails the call, naming the row.\n\nA link cell takes the record id of the row it links. To find that row by the text a sheet holds, `query_records` the\nlinked table once, `groupBy` its key, and read the id from the group. A body that does not find the row skips the\nsheet\'s row and counts it.\n\n```\nconst sheet = await excel_get_rows({ // a workflow step\n file_id: trigger.app_workflow.inputs.file,\n columns: ["Code", "Name", "Price"],\n});\n\nconst kept = await create_records({\n table_id: "price_sheets",\n records: [{ file: [trigger.app_workflow.inputs.file], run: runtime.execution_id }],\n});\nconst sheet_id = kept.record_ids[0];\n\nlet added = 0;\nlet changed = 0;\nlet skipped = 0;\nfor (let at = 0; at < size(sheet.rows); at += 1) {\n const row = sheet.rows[at];\n if (isNull(row["Price"])) {\n skipped += 1;\n await create_records({\n table_id: "sheet_lines",\n records: [{ sheet: [sheet_id], line: at + 2, outcome: "skipped", why: "The sheet states no price", code: toString(row["Code"]) }],\n });\n } else {\n const saved = await save_record({ // a workflow step\n table_id: "plants",\n match: { code: toString(row["Code"]) },\n set: { name: toString(row["Name"]), price: toNumber(row["Price"]) },\n });\n added += saved.created ? 1 : 0;\n changed += !saved.created && size(saved.updated_field_keys) > 0 ? 1 : 0;\n }\n}\n\nreturn({ status: "success", message: `${added} added, ${changed} changed, ${skipped} skipped` });\n```\n\nOne `save_record`, a workflow step, per row writes about a hundred rows a second on a table of thirty fields with a link, a lookup and a\nformula: a thousand rows took ten seconds. A run whose writes finish within twenty seconds lands all or nothing; a\nlonger one starts again, each row written as it is reached, and three thousand rows took seventy of the ninety seconds\nan awaited call gives a run. A sheet of up to about a thousand rows loops; a larger one is written in batches.\n\nThe batched form reads the table\'s keys once and writes in calls of up to a thousand rows. `query_records` the table\nin pages (a call reads 50 rows unless it states a `limit`, and 1000 at most), `groupBy` the key, split the sheet\'s rows into those with no row yet and those whose cells differ, then\n`create_records` the first and `update_records` the second in its per-record form (`field_keys` and one `rows` entry per\n`record_ids` entry). Ten thousand rows took about seven seconds, a repeat with nothing changed under three, and the\nwhole of it is one transaction at that size. The body does the comparison, so it writes only what differs:\n\n```\nconst inputs = trigger.app_workflow.inputs;\n\nconst sheet = await excel_get_rows({ // a workflow step\n file_id: inputs.file,\n columns: ["Code", "Name", "Price"],\n});\nconst rows = sheet.rows.map((row) => ({ code: toString(row["Code"]), name: toString(row["Name"]), price: toNumber(row["Price"]) }));\n\nlet held = (await query_records({ table_id: "plants", field_keys: ["code", "name", "price"], pagination: { offset: 0, limit: 1000 } })).records\n .map((one) => ({ id: one.id, code: toString(one.data["code"]), name: toString(one.data["name"]), price: toNumber(one.data["price"]) }));\nfor (let start = 1000; start < inputs.row_count; start += 1000) {\n const page = await query_records({ table_id: "plants", field_keys: ["code", "name", "price"], pagination: { offset: start, limit: 1000 } });\n held = concat(held, page.records.map((one) => ({ id: one.id, code: toString(one.data["code"]), name: toString(one.data["name"]), price: toNumber(one.data["price"]) })));\n}\nconst byCode = groupBy(held, (one) => one.code);\n\nconst fresh = filter(rows, (row) => size(byCode[row.code] ?? []) == 0);\nconst changed = filter(rows, (row) =>\n size(byCode[row.code] ?? []) > 0 &&\n (requireFirst(byCode[row.code] ?? []).name != row.name || requireFirst(byCode[row.code] ?? []).price != row.price));\n\nfor (let at = 0; at < size(fresh); at += 1000) {\n await create_records({ table_id: "plants", records: slice(fresh, at, at + 1000) });\n}\nfor (let at = 0; at < size(changed); at += 1000) {\n const part = slice(changed, at, at + 1000);\n await update_records({\n table_id: "plants",\n record_ids: part.map((row) => requireFirst(byCode[row.code] ?? []).id),\n field_keys: ["name", "price"],\n rows: part.map((row) => [row.name, row.price]),\n });\n}\n\nreturn({ status: "success", message: `${size(fresh)} added, ${size(changed)} changed` });\n```\n\n`inputs.row_count` is a number the act asks beside the file. A key the table keeps `unique` refuses a second row with\nit, so a sheet that carries one key twice fails the `create_records` call, naming it, before any row of that call is\nwritten.\n\nA workflow does not put a run\'s writes back: that reads the history of what the run wrote, which a member\'s agent reads\nunder the member\'s own access to the table and no workflow does. A member\'s agent puts them back with\n`update_records`: `query_audit_logs` on the table shows what the run wrote \u2014 the run is what `runtime.execution_id` held in\nit, which a body keeps on a row of its own \u2014 and each field\'s value before it, `update_records` writes that value back as\nthe member\'s own write, `update_records` with `restore: true` brings back a row the run moved to the trash, and\n`delete_records` removes a row the run created. Write a field back only where the row still holds what the run wrote.\n\nWhat a business keeps of a sheet \u2014 the file, its counts, the lines waiting for a person \u2014 is rows of its own tables,\nwritten by the workflow that ran. A garden centre brings its grower\'s price sheet into its plants, and keeps each sheet\nand the lines it skipped. These tables are shown beside the plants, in the same app: the sheets as a List beside the\nplants\' (a second List at the root, `reference/app-node`), a sheet\'s lines on the page it opens. A line keeping what a\ncell held and what it holds now in two fields reads one against the other (`compare`, `reference/list-node`).\n\nA skipped line is applied by the act on it, whose workflow reads the line and saves the plant from it. A cell the line\nholds none of is left out, so a skipped line never empties a cell of the plant:\n\n```\nconst line = (await query_records({ table_id: "sheet_lines", record_ids: [trigger.app_workflow.inputs.record_id] })).records[0];\nconst values = {\n ...(isEmpty(line.data["name"]) ? {} : { name: line.data["name"] }),\n ...(isNull(line.data["price"]) ? {} : { price: line.data["price"] }),\n};\n\nawait save_record({ // a workflow step\n table_id: "plants",\n match: { code: line.data["code"] },\n set: values,\n});\n\nawait update_records({ table_id: "sheet_lines", record_ids: [line.id], set: { outcome: "applied" } });\nreturn({ status: "success", message: "Applied." });\n```\n\n### A reviewed act\n\nA shop matches a bank statement to the notes it is owed by an act that states `review`. That act\'s workflow only\nproposes: its body calls steps that read and no other, and runs no agent \u2014 either is refused when the body is saved \u2014\nand returns in `data.review` one changeset of the act\'s table, which the platform writes the approved rows of. Called\nwith what the act asks, it answers the proposal and nothing is written; called again with\n`approved: { creates: [{ key, sha }], updates?: [{ record_id, sha }] }` (absent `updates` means none), the body runs again and the platform writes\nthose rows as this second run proposes them, so the body never reads `approved`. The platform adds a `sha` to every row\nof the proposal it answers \u2014 the body states none, and one it states is dropped \u2014 and the caller echoes the `sha` of\neach row it approves. A row the second run proposes with other values than the `sha` was read from is left unwritten\n(`changed`), so the body must propose the same for the same inputs and the rows it reads.\nAn update is of a record the act is run over (`record_id`, or one of `record_ids`): one of any other record is left\nunwritten. An act over every row in view is handed no rows: its body reads the rows it may change, and any of them may\nbe proposed. A create carries a `key`, a text of the body\'s own that names the same line on every run\n(`key: toString(line["Reference"])`), unique among the creates; where a confirm repeated must not add a second row,\nthe body also writes the key into a field the table keeps unique, so the repeat\'s create is left as a `conflict`.\nEach row\'s `data` holds only stored fields that change \u2014 never one the platform computes or stamps, nor a file \u2014 with\na `note` and a `ticked` the reader starts from, and `unplaced` lists what was read and matched nothing. Every approved\nrow is checked against its fields before any is written, and they are written in one transaction, so a flawed one\nwrites none. The status history of every row written that moved, or was made holding a status, is recorded in the\nsame run. The answer\'s `applied.previous` holds what each updated record\'s written fields held before, so one `update_records` of it puts the values back, and `delete_records` of a `created` record takes that row away. A body that stops proposing a row once it is\nwritten \u2014 it matches against what the rows hold now \u2014 makes approving twice write once.\n\n```\nconst inputs = trigger.app_workflow.inputs;\n\nconst sheet = await excel_get_rows({ // a workflow step\n file_id: inputs.statement,\n columns: ["Reference", "Amount", "Paid on"],\n});\nconst unpaid = await query_records({\n table_id: "notes",\n filters: { field_key: "paid_on", operator: "is_empty" },\n pagination: { offset: 0, limit: 500 },\n});\nconst acted = groupBy(inputs.record_ids, (id) => toString(id));\nconst owed = filter(unpaid.records, (one) => size(acted[toString(one.id)] ?? []) > 0);\nconst byRef = groupBy(owed, (one) => toString(one.data["ref"]));\n\nconst lines = sheet.rows.map((line) => ({\n line,\n note: first(byRef[toString(line["Reference"])] ?? []),\n}));\nconst updates = filter(lines, (one) => !isNull(one.note)).map((one) => ({\n record_id: toString(one.note?.id),\n note: `Transfer of ${toString(one.line["Amount"])}`,\n ticked: toNumber(one.line["Amount"]) == sumBy(filter(owed, (owing) => owing.id == one.note?.id), (owing) => coalesce(owing.data["amount"], 0)),\n data: { paid_on: toString(one.line["Paid on"]) },\n}));\nconst unplaced = filter(lines, (one) => isNull(one.note)).map((one) => ({\n title: `${toString(one.line["Reference"])}: ${toString(one.line["Amount"])}`,\n note: "Matches no unpaid note",\n}));\n\nreturn({\n status: "success",\n message: `${size(updates)} of ${size(lines)} transfers match a note`,\n data: { review: { version: 1, table_id: "notes", creates: [], updates, unplaced } },\n});\n```\n\n### Saving a record with its lines\n\n`save_record`, a workflow step, saves one record and the rows of other tables that hang off it, all or\nnothing, and recognises what exists by the identity the input carries \u2014 so a call sent twice updates and\nadds nothing. `match` is the record\'s identity, `{ field_key: value }`, and must be exactly a uniqueness\nits table declares: one field marked `unique`, or the fields of one of the table\'s `unique` sets together\n(text, number, date, single select and one-row link fields). A `match` that is no declared uniqueness is\nrefused, naming what the table does declare: where the body is saved when its table and fields are written\nout, at run otherwise. A table cannot lose a uniqueness a stored `save_record` matches on: declare the new\none beside it, move the workflows to it, then take the old one away. A live record carrying the match is found and only the cells\nof `set` that differ are written; none is found and it is added with `match` and `set`. `add_to` appends\nto a files, multi-select or many-link field and keeps what it holds.\n\n`lines` saves rows of other tables that link the record. Each entry names the child `table_id`, its\n`link` \u2014 a field of the child holding one row of this table, which the step fills and no row states \u2014\nthe child fields that, with `link`, are one uniqueness of the child table (`match`), and `rows`, each\nstating every `match` field. A line found by its match changes only the cells that differ, one not found\nis added, and a line the call does not list is left as it is: the step deletes nothing. Two rows of one\nentry cannot share a match.\n\nEverything is checked before the first write, and everything is written in one transaction: a table check\nthat refuses one line, a locked record or line the call would change, a value a field does not take, or a\ntable the run may not write refuses the call and saves nothing, naming the row. Two calls of one identity\ntake turns, so the second finds what the first saved. The answer is `record_id`, `created`,\n`updated_field_keys` (the cells changed on a record that existed) and, per entry of `lines`, the ids it\nadded, changed and left unchanged; these ids are typed for their tables, so a declared `record_link`\noutput or a follow-up write links straight to them.\n\n```\nconst inputs = trigger.app_workflow.inputs;\n\nconst sheet = await excel_get_rows({ // a workflow step\n file_id: inputs.release_order,\n columns: ["Size", "Quantity"],\n});\n\nconst saved = await save_record({ // a workflow step\n table_id: "release_orders",\n match: { number: inputs.number },\n set: { note: "Read from the paper" },\n lines: [{\n table_id: "release_lines",\n link: "order",\n match: ["size"],\n rows: sheet.rows.map((row) => ({\n size: toString(row["Size"]),\n quantity: toNumber(row["Quantity"]),\n })),\n }],\n});\n\nreturn({\n status: "success",\n message: `${size(saved.lines[0].created_ids)} lines added`,\n data: { record_id: saved.record_id },\n});\n```\n\n### Numbering a row at a moment\n\nA number given when a row is signed or issued is an editable number field the workflow fills with the table\'s highest plus one,\nonly while the row has none, so a second press keeps its number. The field carries a one-field `unique` set on its table, so two\nruns that read the same highest are refused, not doubled; the refused run reads the highest again, for three attempts in all, and\na run still refused after the third fails with that refusal. The last attempt stands outside the `try`, since a `catch` takes any\ntool error, not the unique refusal alone. A sequence per series or year filters the query on it and states a two-field `unique`.\n\n```\nif (isNull(record.no)) {\n let numbered = false;\n for (let attempt = 0; attempt < 2 && !numbered; attempt++) {\n const top = await query_records({ table_id: "contracts", sort: [{ field_key: "no", order: "desc" }], limit: 1 });\n try {\n await update_records({ table_id: "contracts", record_ids: [record.id], set: { no: coalesce(first(top.records)?.data["no"], 0) + 1 } });\n numbered = true;\n } catch (e) {\n numbered = false;\n }\n }\n if (!numbered) {\n const last = await query_records({ table_id: "contracts", sort: [{ field_key: "no", order: "desc" }], limit: 1 });\n await update_records({ table_id: "contracts", record_ids: [record.id], set: { no: coalesce(first(last.records)?.data["no"], 0) + 1 } });\n }\n}\n```\n\n## Schedules\n\nA weekly pattern made into dated rows is a parent\'s `records.cadence` and an Act `makes` it\n(`reference/record-places-pins-and-cadence`), no body; pressed again it also moves the rows the pattern now makes otherwise that no one has touched. The rest of a timetable is a rule or a short body.\n\n**A student in two places.** An enrolment reads its span and its days off its course, so one meeting at the same\ntime on a shared weekday as the student\'s other course is refused at save:\n\n```json\n"no_overlap": { "from": "course.starts", "to": "course.ends", "by": ["student", "course.days"], "while": { "state": ["active"] } }\n```\n\n**A swap.** One Act on a shift runs a `workflow` asking the other shift (an input `other` of `type: "link"`, `entity` the shifts) and writes both people in one call:\n\n```\nconst inputs = trigger.app_workflow.inputs;\nconst both = (await query_records({ table_id: "shifts", record_ids: [inputs.record_id, inputs.other] })).records;\nconst mine = requireFirst(filter(both, (one) => one.id == inputs.record_id));\nconst theirs = requireFirst(filter(both, (one) => one.id == inputs.other));\nawait update_records({\n table_id: "shifts",\n record_ids: [mine.id, theirs.id],\n field_keys: ["person"],\n rows: [[theirs.data["person"]], [mine.data["person"]]],\n});\nreturn({ status: "success", message: "Swapped." });\n```\n\n**A rotation.** A pattern that turns over the days (teams taking nights in turn) is a body: `datesOn(from, until,\ndays)` lists the days of a range falling on the weekdays named.\n\n```\nconst inputs = trigger.app_workflow.inputs;\nconst days = datesOn(inputs.from, inputs.until, ["mon", "tue", "wed", "thu", "fri"]);\nconst teams = (await query_records({ table_id: "teams", record_ids: inputs.record_ids })).records;\nconst rows = days.flatMap((day, at) => teams.map((team, place) => ({ team: [team.id], day, kind: (at + place) % 2 == 0 ? "day" : "night" })));\nfor (let at = 0; at < size(rows); at += 1000) {\n await create_records({ table_id: "shifts", records: slice(rows, at, at + 1000) });\n}\nreturn({ status: "success", message: `${size(rows)} shifts` });\n```\n\n**Pay at the rate taught, and a month closed.** A lesson copies its teacher\'s rate when it is made (`"default_from":\n"teacher.rate"`), so a rise later leaves the lessons already made alone; a formula multiplies it by the lesson\'s hours,\nand a Tab\'s `totals` sums each teacher\'s month. A pay period is a row with its first and last day and a status; a check\non the lessons refuses every write inside a closed one:\n\n```json\n"checks": { "month_closed": {\n "on": ["create", "update", "delete"],\n "lookups": { "period": { "table": "pay_periods", "limit": 1, "filter": { "node_type": "group", "logic": "and", "children": [\n { "node_type": "condition", "field_key": "first_day", "operator": "on_or_before", "value": { "$expr": "record.starts_at" } },\n { "node_type": "condition", "field_key": "last_day", "operator": "on_or_after", "value": { "$expr": "record.starts_at" } },\n { "node_type": "condition", "field_key": "status", "operator": "has_any_of", "value": ["closed"] } ] } } },\n "fail_when": "size(lookups.period) > 0",\n "message": "\\"This month\'s pay is closed.\\""\n} }\n```\n\n## Reaching a connected service\n\nA service is reached only by a workflow step, and a step is called inside an app\'s workflow or an automation. From\nnothing to an app\'s run:\n\n1. `get_workspace` with `kind: "connection"` lists each `connected_account_id`.\n2. `set_app` declares a Workflow node that states what a call takes and hands back:\n\n```json\n{\n "type": "Workflow",\n "key": "invoice_order",\n "description": "Issues the KiotViet invoice for a confirmed order and hands back its code.",\n "inputs": { "order": { "type": "record_link", "entity": "order" } },\n "outputs": { "invoice_code": { "type": "text" } }\n}\n```\n\n3. `set_workflow` with a `source` that opens with `on({ type: "app", app_id: "app_\u2026", alias: "invoice_order" });` and this body (the step\'s entry is in `workflow_steps`):\n\n```\nconst order = (await query_records({ table_id: "orders", record_ids: [trigger.app_workflow.inputs.order] })).records[0];\nconst made = await kiotviet_create_invoice({ // a workflow step\n connected_account_id: "cac_\u2026",\n branch_id: 1,\n sold_by_id: 7,\n lines: [{ product_id: 42, quantity: toNumber(order.data["quantity"]), price: toNumber(order.data["price"]) }],\n});\nreturn({ status: "success", message: "Invoiced", data: { invoice_code: made.invoice.code } });\n```\n\n4. `run_app_workflow` with `dry_run: true`, then the same call without it.\n\nTo change later what it takes or hands back, send the node\'s change and the new body in one `set_app`, the body under\n`workflows`.\n\nA step wants the provider\'s own ids (`branch_id`, `sold_by_id`, `product_id`) and no tool lists them: declare a Workflow\nwhose body calls the provider\'s `list_*` workflow step (`kiotviet_list_branches`), run it, and read the ids from its answer.\nNo step lists KiotViet\'s users: read `sold_by_id` off a row `kiotviet_list_invoices` returns (KiotViet\'s `soldById`), or ask the owner.\n\n## Table checks\n\nA table check is one condition its table\'s record writes must not meet, declared beside the table\'s\n`unique`. It is not a workflow: it reads the write and a few lookups and answers yes or no, so it\ncannot change data. It runs inside the write, on every create, update or delete it is `on`, whichever\nsurface makes it \u2014 a person, the API, the CLI, an agent, a workflow. A refusal writes nothing and\nanswers with the check\'s message, under its field when the check names one, and names the check.\n\nA check is stated in its table\'s document, under `checks`, each under an alias of its own, and\n`set_tables` writes it with the rest of the table: a merge patch edits one, `null` removes it, and a\ncall that makes a table can state its checks, a lookup naming another table of the call by its `ref`.\n`get_table` states a table\'s checks in its document.\n\n| part | what it holds |\n|---|---|\n| `on` | the writes it checks: any of `create`, `update`, `delete` |\n| `when` | optional expression; the check runs only on a write where it is truthy. It cannot read lookups. |\n| `lookups` | optional, by name, the rows to read: `{ table, filter, limit }`, `table` an id or the `ref` of a table of the call, the filter as `query_records` takes it with fields and select options named by alias (`id` matches a row by its own record id), `limit` from 1 to 50 (50 when left out). A filter value that reads the record is `{ "$expr": "record.code" }`. |\n| `fail_when` | expression; truthy refuses the write |\n| `message` | expression for the refusal\'s text \u2014 a fixed text is a quoted string |\n| `field` | optional; the alias of the field the refusal is shown under |\n| `enabled` | `false` keeps the check without deciding writes; absent, it decides |\n\nEvery expression is written in the grammar above, names a table\'s fields and select options by\nalias (`record.status == "closed"`), and reads:\n\n- `record` \u2014 the record as it will be stored; on a delete, the record being deleted.\n- `prev_record` \u2014 on an update or a delete, the record before.\n- `changes` \u2014 on an update, the fields it changes. `!isNull(changes.photos)` asks whether a field changed.\n- `lookups.<name>` \u2014 in `fail_when` and `message`, the rows that lookup read. A row reads as `record` does: its fields by alias beside `id` (`row.start_on`), and a lookup field as the flat list of what it looks up (`first(row.booking_start)` through a one-row link). A lookup over the written table never returns the row being checked, and finds its other rows as the write leaves them, this call\'s other rows included. A field given to a helper as text names it by alias too (`sumBy(lookups.paid, "amount")`); text that names no field of the rows\' table is refused when the check is saved.\n- `runtime.timezone`, `runtime.workspace_id`, `runtime.organization_id`, `runtime.change_origin` (the\n write\'s origin), `runtime.triggered_by_member_id` (the member writing; null for a write no member\n made), `now()`, and `member_of("grp_\u2026")` \u2014 true when the member writing belongs to the group.\n\nIn a check a select reads as its one value (`record.kind == "retail"`), and a link (a one-row link too) and a lookup read as lists (`first(record.customer)`).\n\nA check on several operations reads only what all of them carry, so one on creates and updates reads\nneither `prev_record` nor `changes`.\n\nA write that recomputes another table\'s rows (a rollup over lines, a lookup or a formula over a parent) judges each recomputed row as an update, by the checks `on` `update` that read a field the recompute changed; `changes` is what the recompute changed. A check that refuses on `changes` or on a status the row holds can therefore refuse the write that moved the parent, so it is gated on the field it means (`!isNull(changes.status)`).\n\nA lookup reads with the access of the member who last saved the check, so saving one requires reading\nevery table its lookups read. A check\'s reads wait on the writes they depend on: the rows its links name are locked before it reads, and any other lookup takes a lock per check, so two writes at the same moment can\'t both pass a check the other would fail. Values no two rows may share are the table\'s `unique`.\n\nA `when`, a lookup or a `fail_when` that cannot decide \u2014 it fails, or the write\'s time runs out \u2014\nrefuses the write, naming the part it was reading and, for an expression or a filter, what it met\n(`lookups.clash: Filter on "start_on": date \'before\' value \u2026 is not a date`). A draft is checked when it is submitted, as a create; its edits before that are\nnot. A restored record is checked as a create. Cloning a table copies its checks to the member who\nclones it, and is refused when that member cannot read a table a check\'s lookup reads.\n\nOne open order per reference, a row never counting against itself:\n\n```json\n{\n "tables": [\n {\n "ref": "orders",\n "label": "Orders",\n "fields": {\n "reference": { "type": "text", "label": "Reference" },\n "closed_at": { "type": "date", "label": "Closed at" }\n },\n "checks": {\n "one_open_order_per_reference": {\n "on": ["create", "update"],\n "when": "isNull(record.closed_at)",\n "lookups": {\n "same_ref": {\n "table": "orders",\n "filter": {\n "node_type": "group",\n "logic": "and",\n "children": [\n { "node_type": "condition", "field_key": "reference", "operator": "equals", "value": { "$expr": "record.reference" } },\n { "node_type": "condition", "field_key": "closed_at", "operator": "is_empty" }\n ]\n },\n "limit": 2\n }\n },\n "fail_when": "some(lookups.same_ref, (r) => r.id != record.id)",\n "message": "\\"An open order already has this reference.\\"",\n "field": "reference"\n }\n }\n }\n ]\n}\n```\n\n## Table workflows\n\nA table workflow is what follows every committed write of a table\'s rows, whoever makes it: the grid, an import, an agent or\nany app. An effect that must hold for all of them belongs to the table. A button on one screen is that app\'s act, a value fixed\nwhen a row is made is `default_from`, and a rule that refuses a write is a check; a table workflow runs after the write has\ncommitted and cannot refuse it. An agent\'s write waits for the runs it set off, while they run and at most 10 seconds, and\nits answer names each that failed or had not ended.\n\n`set_workflow` writes it: the `source` opens with `on({ type, table, ... })` and carries the steps, and `enabled: false`\nkeeps the workflow without running it (absent, it runs). `get_table` lists a table\'s workflows to whoever manages the\ntable \u2014 `workflow_id`, name, trigger, whether it is on and its failed runs of the last 7 days \u2014 and `get_workflow` reads one\nback. The table and the trigger type (`create`, `update` or `delete`) are fixed once the workflow is made: to change\neither, delete it and make another. A replace that changes only the gate, the trigger config or `enabled` moves the\nworkflow\'s version. `dry_run` with a `record_id` (and, for an update, `prev_data` and `changes`, each changed field as `{ prev_value, next_value }`) says what the workflow would\nwrite on that row; reads are real and nothing is written.\n\n| part of the header | what it holds |\n|---|---|\n| `type` | the write it follows: `create`, `update` or `delete`; a `delete` workflow runs once, when the row is deleted; deleting it for good from the trash runs none |\n| `table` | the table\'s alias |\n| `when` | optional expression over `record`, `prev_record` and `changes`; the workflow runs only after a write where it is truthy |\n| `changed` | optional, with `type: "update"`: field aliases; the workflow runs only after an update that changes any one of them |\n\n```\non({ type: "update", table: "repairs", changed: ["status"], when: "record.status == \\"fixed\\"" });\n\nawait update_records({ table_id: "repairs", record_ids: [trigger.record_id], set: { fixed_on: formatDate(now(), "yyyy-MM-dd") } });\n```\n\nThe body names the table\'s fields, select options and other tables by alias, and reads the write as `record`,\n`prev_record` and `changes`, the row\'s id as `trigger.record_id`, and the member who made the write as\n`runtime.triggered_by_member_id` (null for a write no member made). It operates on records and integrations: a body\nthat calls a tool changing a table, an app or any other structure is refused when it is saved. It runs as the table\'s owner, so\nit reaches the tables the owner reaches, and its writes meet the table\'s checks like any other write; a write refused by a\ncheck fails that run and leaves the row as it was. A body names a field by alias where it can tell which table\'s field it is: a\nread of `record`, `prev_record` or `changes`, a row from `query_records` called with a literal `table_id`,\na row `find`, `first`, `at` or an index picks from such rows, and a loop or callback over them, each also when held in an\nobject or a list written out, or a spread. A row read through `map` or `push`, or picked by a conditional or `??`, is not\ntied to its table: read its fields where the row itself is in hand (`rows.map((r) => ({ state: r.data.state, n: 1 }))`). A name it cannot tie to a table, and an option compared to a value of unknown type (not a read of a field, and\nnot a text, number or other value the type proves holds no option), are refused with what to change. A link reads as the list of the row ids it holds, a one-row link too: compare `first(record.customer) == id`. A lookup reads as one flat list of what it looks up: `record.x != prev_record.x` on one is refused, so compare `first(record.x)` with `first(prev_record.x)`. A single member, a single select, a number or a text reads as the value itself: `first(record.technician)` is refused at save, naming the read.\n\nA write the workflow itself makes sets off the workflows of its table in turn, and a chain of them stops after five. A workflow\nthat writes the row it follows is gated by a `changed` or a `when` that its own write does not satisfy. One run is queued for a\nrow and a workflow at a time, so a burst of writes to one row runs it once more after the run in flight. A field a workflow\nreads cannot be deleted or retyped until the workflow is changed or deleted with `set_workflow` before. Cloning a table copies its\nworkflows for whoever manages it (`include_workflows: false` leaves them), each with a body of its own, and is refused when a\nbody names a table the cloner cannot reach. A workflow runs as the table\'s owner, so whoever saves or rehearses one must manage the\ntable and read every table it reads in full: the body\'s, the gate\'s links\', the written table. An option is written where\nit is compared to, listed against or set on its field; a constant holding one is refused.\n\nA lock is the table\'s: a table workflow locks a row with `update_records` and `locked: true` (an app\'s act may too), and every door then refuses\nthe row\'s writes until whoever manages the table unlocks it with `update_records` and `locked: false` \u2014 in an app\'s run, judged as the member who pressed.\nA locked row reads locked in every app. An app\'s own Check or `edit: false` only makes a row read-only in that app.\n\n## Runs\n\nEach start of a workflow is a run: an app\'s workflow or act, a table workflow, a button, an automation. A call through an\napp\'s API to a workflow that only reads is kept as a run only when it fails or returns an error, unless its body reads\n`runtime.execution_id` or `runtime.change_origin`. An agent finds, reads, retries and stops runs. A run is read by whoever manages what its workflow belongs to: its\nautomation or its table, and for an app\'s workflow the app\'s owner or an admin, never a manager of the app.\n\n- **Find.** `query_workflow_executions` lists one workflow\'s runs (`workflow_id`), every run started for one row\n (`record_id`) \u2014 a table workflow\'s written row, a pressed button\'s row, an app run\'s `record_id` input \u2014 or both, newest\n first, a page at a time (`next_cursor`). A listing naming no workflow and no row covers every workflow whose runs the caller may read. Each run names its workflow and kind, what started it, its row and how it ended:\n for a failure, the step that threw, its tool and the error; for a waiting run, when it wakes, or the payment. A run started before runs recorded their row carries no `record_id`.\n- **Read.** `get_workflow_execution` gives one run\'s steps in order with each one\'s tool, input, output and error, what it\n returned, how many rows it wrote (a row\'s own history is in `query_audit_logs`) and the runs its writes started. Ninety days\n after a run starts, its trigger and its steps\' input and output are pruned; the read says so and gives the rest.\n `run_app_workflow` answers each run it makes with its `execution_id`.\n- **Retry.** `set_workflow_execution` with `action: "retry"` runs a failed, refused or cancelled run again as a new run linked to the first\n (`retry_of`): the first run\'s trigger and row, the workflow\'s current steps and its owner\'s current access, with the\n member who retries it as the one who started it. A run is retried once; a retry that fails is retried in turn. It asks\n first when the run, or a run it retried, already wrote rows or called a service no delete reverses. An automation\'s or a\n table workflow\'s retry runs in the background, as its runs do, and answers `queued`; a button\'s and an app\'s run while\n the call waits. An app\'s call is checked again against the workflow\'s current inputs. A pruned run, a run of a workflow\n that is off, a reviewed act\'s run (call the act again) and a recording\'s filing (the recording retries its delivery)\n are not run again.\n- **Stop.** `set_workflow_execution` with `action: "cancel"` stops a waiting run. Both answer\n `execution_id`, `action`, `status`, `retry_of`, `error` and, for a retry, `original_wrote`: the rows and the irreversible\n calls the first run wrote, which the retry makes again.\n\nOff means off: a waiting run whose workflow was turned off, deleted, or taken off its automation, table, button or app ends\n`cancelled` when it would resume, saying why, and runs no further step.\n\nA waiting run keeps its version: when it resumes, it runs the steps of the version it started with, so an edit saved while it\nwaited changes later runs only. When that version is gone, the run ends failed and says why.\n';
1942
1942
 
1943
1943
  // docs/workflow_steps.md
1944
1944
  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 an organization owner: 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| `status` | object | yes | |\n| `status.BkavStatus` | number | yes | InvoiceStatusID: 1 m\u1EDBi t\u1EA1o, 2 \u0111\xE3 ph\xE1t h\xE0nh, 3 \u0111\xE3 hu\u1EF7, \u2026 |\n| `status.TaxStatus` | number | yes | 32 waiting, 33 accepted, 34\u201339 returned or failed |\n| `status.TaxAuthorityCode` | string \\\\| null | yes | M\xE3 c\u1EE7a C\u01A1 quan thu\u1EBF, once granted |\n| `status.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)\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) |\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); a workflow body\'s read carries `display`, `links`, `comment_count` and `units` only when the body reads them.\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 an organization owner: 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| `table_id` | string | yes | |\n| `data` | object | yes | |\n| `display` | object | | Human-readable display values for select, member, and record link fields. Omitted from a workflow read whose body never looks at it. |\n| `links` | object | | Each link field\'s linked rows with the title the cell carries, by field alias; `data` holds their ids. |\n| `issues` | object[] | | What the workspace marks as needing a person\'s action on this row, in its priority order, whatever fields were asked for; absent where the row holds none. |\n| `issues[].issue` | string | yes | |\n| `issues[].name` | string | yes | |\n| `issues[].says` | string | yes | |\n| `locked` | boolean | | |\n| `comment_count` | number | | How many comments the record holds. Omitted from a workflow read whose body never looks at it. |\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)\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) |\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)\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) |\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 to locked field values on a record, with its reason.\n- Include every blocked field in the same call \u2014 the change set is accepted or rejected as a whole.\n- The people who manage the table decide it before any value changes (`status: "pending"`, with `request_id`); a table whose `locked_change` is `tell` writes it at once and tells them (`status: "applied"`).\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 | | |\n| `status` | "pending" \\\\| "applied" | 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- Each recipient sees it in their Lotics inbox; it is also mailed to a recipient who has chosen email for their notifications, and to no other.\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; the card and its email name the member who started the run. 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';
package/docs/build.md CHANGED
@@ -62,7 +62,7 @@ Linked tables go in one call, since they name each other by `ref`; `records` and
62
62
  }
63
63
  ```
64
64
 
65
- `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.
65
+ `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. A check refuses the write, a table workflow's too, so it states only what the business says must never happen; a fact going out of line (stock short of what lines take, totals that do not match) is an issue the row keeps (`design/issues`).
66
66
 
67
67
  A `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`).
68
68
 
package/docs/workflows.md CHANGED
@@ -941,7 +941,8 @@ One open order per reference, a row never counting against itself:
941
941
  A table workflow is what follows every committed write of a table's rows, whoever makes it: the grid, an import, an agent or
942
942
  any app. An effect that must hold for all of them belongs to the table. A button on one screen is that app's act, a value fixed
943
943
  when a row is made is `default_from`, and a rule that refuses a write is a check; a table workflow runs after the write has
944
- committed and cannot refuse it.
944
+ committed and cannot refuse it. An agent's write waits for the runs it set off, while they run and at most 10 seconds, and
945
+ its answer names each that failed or had not ended.
945
946
 
946
947
  `set_workflow` writes it: the `source` opens with `on({ type, table, ... })` and carries the steps, and `enabled: false`
947
948
  keeps the workflow without running it (absent, it runs). `get_table` lists a table's workflows to whoever manages the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lotics/cli",
3
- "version": "0.321.117",
3
+ "version": "0.321.118",
4
4
  "description": "Lotics SDK and CLI for AI agents",
5
5
  "type": "module",
6
6
  "bin": {