npm - @lotics/cli - Versions diffs - 0.313.5 → 0.315.0 - Mend

@lotics/cli 0.313.5 → 0.315.0

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.

Files changed (5) hide show

package/dist/src/cli.js CHANGED Viewed

@@ -35506,7 +35506,7 @@ function computedTypeFindings(entities) {
 }
 // ../shared/src/schemas/app_spec_version.ts
-var APP_SPEC_VERSION = 21;
+var APP_SPEC_VERSION = 22;
 // ../shared/src/schemas/app_compose.ts
 var fieldAlias = contractAliasSchema.describe("A field alias of the record's entity");
@@ -46614,8 +46614,8 @@ async function saveSignedLinks(links, dir) {
 }
 // src/version.ts
-var VERSION = "0.313.5";
-var APP_SDK_VERSION = "0.123.4";
+var VERSION = "0.315.0";
+var APP_SDK_VERSION = "0.123.5";
 // src/timezone.ts
 function machineTimezone() {
@@ -46640,7 +46640,7 @@ var model_reference_default = '# The Lotics workspace model (`model.json`)\n\nOn
 var examples_default = '# Worked examples\n\nEach section is one treatment, cut from a complete model of an invented business: the job, the keys to\nread, where the treatment is wrong, and the excerpt \u2014 an app the check passes with no finding, as stated;\nthe `records` of every entity it draws; those entities\' fields it names, by what each holds and how it is\ndrawn; and the templates it makes. Left out: labels, descriptions, `required`, `unique`, `default`, a link\'s\npairing, how a computed field computes, and template contents. Choosing among them: the `design` reference.\nEvery key: the `model` reference, at the pages each section names under **Keys**.\n\n## Calendar\n\n**The job.** Book visits on the days they happen, and see a week\'s work at a glance.\n\n**Read.** `register.layout: "calendar"`; each visit stands over its span because its `records` line holds two dates (`scheduled_for`, `ends_at`).\n\n**Keys.** `model/calendar`\n\n**Not when.** Rows booked on a resource that two may not share at once \u2014 that is `lanes`. Rows with a date nobody plans by (an invoice\'s date) stay a table.\n\n```json\n{\n  "entities": [\n    {\n      "alias": "service_visit",\n      "fields": [\n        {"alias": "customer", "type": "select_record_link", "target_entity": "customer", "cardinality": "one"},\n        {"alias": "scheduled_for", "type": "date", "format": "datetime"},\n        {"alias": "ends_at", "type": "date", "format": "datetime"},\n        {"alias": "engineer", "type": "select_record_link", "target_entity": "engineer", "cardinality": "one"},\n        {\n          "alias": "job",\n          "type": "select",\n          "options": [{"alias": "inspection", "color": "sky"}, {"alias": "repair", "color": "orange"}]\n        },\n        {"alias": "booked_on", "type": "date"},\n        {"alias": "parts_ready_on", "type": "date"},\n        {"alias": "arrived_on", "type": "date"},\n        {"alias": "hours", "type": "number", "notation": {"style": "unit", "unit": "h"}},\n        {"alias": "report", "type": "text", "format": "markdown"},\n        {"alias": "completed_on", "type": "date"}\n      ]\n    }\n  ],\n  "records": {\n    "service_visit": {\n      "title": "customer",\n      "subtitle": ["scheduled_for", "ends_at"],\n      "status": {\n        "milestones": ["booked_on", {"field": "parts_ready_on", "when": {"job": ["repair"]}}, "arrived_on", "completed_on"],\n        "closed": ["completed_on"]\n      },\n      "figure": "hours",\n      "due": ["scheduled_for"]\n    }\n  },\n  "apps": [\n    {\n      "alias": "visits",\n      "name": "Service visits",\n      "icon": "calendar",\n      "theme": {"color": "emerald"},\n      "entity": "service_visit",\n      "register": {\n        "columns": ["engineer", "job"],\n        "filters": ["customer"],\n        "sort": {"field": "scheduled_for"},\n        "layout": "calendar",\n        "create": ["customer", "job", "scheduled_for", "ends_at", "engineer"],\n        "readings": [\n          {"metric": "service_visit", "where": {"job": ["repair"]}, "label": "Repairs"},\n          {"breakdown": "service_visit", "by": "engineer", "value": "hours"}\n        ]\n      },\n      "record": {\n        "sections": [\n          {"title": "Visit", "at": ["booked_on", "parts_ready_on"], "fields": ["job"], "acts": ["reschedule"]},\n          {"title": "Report", "at": ["arrived_on"], "fields": ["engineer", "report"], "acts": ["complete"]}\n        ]\n      },\n      "acts": [\n        {\n          "alias": "complete",\n          "label": "Complete visit",\n          "requires": ["engineer"],\n          "asks": ["hours", {"input": "summary", "label": "What was done", "type": "long_text", "required": true}],\n          "set": {"report": "input:summary", "completed_on": "now"}\n        },\n        {"alias": "reschedule", "label": "Reschedule", "asks": ["scheduled_for", "ends_at"]}\n      ]\n    }\n  ]\n}\n```\n\n## Lanes\n\n**The job.** Put each service visit on an engineer\'s day by the hour, and see at once who is free between visits.\n\n**Read.** `register.layout: "lanes"` with `lanes` naming the one-row link to the resource (the engineer); every engineer stands as a lane, empty or not.\n\n**Keys.** `model/lanes`\n\n**Not when.** The resource is not a row of the model (a free-text room name), or rows never compete for one \u2014 a `calendar` reads them by day.\n\n```json\n{\n  "entities": [\n    {\n      "alias": "service_visit",\n      "fields": [\n        {"alias": "customer", "type": "select_record_link", "target_entity": "customer", "cardinality": "one"},\n        {"alias": "scheduled_for", "type": "date", "format": "datetime"},\n        {"alias": "ends_at", "type": "date", "format": "datetime"},\n        {"alias": "engineer", "type": "select_record_link", "target_entity": "engineer", "cardinality": "one"},\n        {\n          "alias": "job",\n          "type": "select",\n          "options": [{"alias": "inspection", "color": "sky"}, {"alias": "repair", "color": "orange"}]\n        },\n        {"alias": "booked_on", "type": "date"},\n        {"alias": "parts_ready_on", "type": "date"},\n        {"alias": "arrived_on", "type": "date"},\n        {"alias": "hours", "type": "number", "notation": {"style": "unit", "unit": "h"}},\n        {"alias": "completed_on", "type": "date"}\n      ]\n    },\n    {\n      "alias": "engineer",\n      "fields": [\n        {"alias": "name", "type": "text"},\n        {"alias": "base", "type": "select_record_link", "target_entity": "warehouse", "cardinality": "one"}\n      ]\n    }\n  ],\n  "records": {\n    "service_visit": {\n      "title": "customer",\n      "subtitle": ["scheduled_for", "ends_at"],\n      "status": {\n        "milestones": ["booked_on", {"field": "parts_ready_on", "when": {"job": ["repair"]}}, "arrived_on", "completed_on"],\n        "closed": ["completed_on"]\n      },\n      "figure": "hours",\n      "due": ["scheduled_for"]\n    },\n    "engineer": {"title": "name", "subtitle": ["base"], "party": "person"}\n  },\n  "apps": [\n    {\n      "alias": "dispatch",\n      "name": "Dispatch",\n      "icon": "wrench",\n      "theme": {"color": "sky"},\n      "entity": "service_visit",\n      "register": {\n        "columns": ["job"],\n        "search": ["customer"],\n        "layout": "lanes",\n        "lanes": "engineer",\n        "create": ["customer", "job"]\n      },\n      "record": {"door": "drawer", "sections": [{"title": "Booking", "fields": ["engineer", "job"]}]}\n    }\n  ]\n}\n```\n\n## Gantt\n\n**The job.** Read every hire as a bar from the day the machine goes out to the day it is due back, against today.\n\n**Read.** `register.layout: "gantt"` and `register.gantt.start`; with no end stated, the bar ends at the entity\'s first `due`.\n\n**Keys.** `model/gantt`\n\n**Not when.** Rows that last a day or less (a visit, a shift) \u2014 `calendar` or `lanes`; a plan with no dates set yet.\n\n```json\n{\n  "entities": [\n    {\n      "alias": "phieu_thue",\n      "fields": [\n        {\n          "alias": "khach_hang",\n          "type": "select_record_link",\n          "target_entity": "khach_hang",\n          "cardinality": "one"\n        },\n        {"alias": "so_phieu", "type": "text"},\n        {\n          "alias": "trang_thai",\n          "type": "select",\n          "options": [\n            {"alias": "moi", "color": "slate"},\n            {"alias": "dang_thue", "color": "blue"},\n            {"alias": "da_tra", "color": "green"},\n            {"alias": "huy", "color": "gray"}\n          ]\n        },\n        {"alias": "phu_trach", "type": "select_member"},\n        {"alias": "ngay_giao", "type": "date"},\n        {"alias": "han_tra", "type": "date"},\n        {"alias": "ngay_tra", "type": "date"},\n        {\n          "alias": "tinh_trang_tra",\n          "type": "select",\n          "options": [\n            {"alias": "tot", "color": "green"},\n            {"alias": "tray_xuoc", "color": "amber"},\n            {"alias": "hu_hong", "color": "red"}\n          ]\n        },\n        {"alias": "so_ngay", "type": "formula"},\n        {"alias": "tong_tien", "type": "rollup"}\n      ]\n    }\n  ],\n  "records": {\n    "phieu_thue": {\n      "title": "khach_hang",\n      "subtitle": ["so_phieu"],\n      "status": {"field": "trang_thai", "closed": ["da_tra", "huy"], "history": "lich_su_phieu"},\n      "figure": "tong_tien",\n      "due": ["han_tra"]\n    }\n  },\n  "apps": [\n    {\n      "alias": "tien_do_thue",\n      "name": "Ti\u1EBFn \u0111\u1ED9 cho thu\xEA",\n      "icon": "calendar-range",\n      "theme": {"color": "teal"},\n      "entity": "phieu_thue",\n      "register": {\n        "columns": ["phu_trach"],\n        "filters": ["phu_trach", "khach_hang"],\n        "layout": "gantt",\n        "gantt": {"start": "ngay_giao"},\n        "remove": false,\n        "create": false,\n        "readings": [\n          {"metric": "phieu_thue", "where": {"trang_thai": ["dang_thue"]}, "label": "Phi\u1EBFu \u0111ang cho thu\xEA"},\n          {\n            "metric": "phieu_thue",\n            "value": "tong_tien",\n            "where": {"trang_thai": ["dang_thue"]},\n            "label": "Ti\u1EC1n thu\xEA \u0111ang ch\u1EA1y"\n          }\n        ]\n      },\n      "record": {\n        "sections": [\n          {"title": "Phi\u1EBFu thu\xEA", "fields": ["ngay_giao", "han_tra"]},\n          {"title": "\u0110ang thu\xEA", "at": ["dang_thue"], "fields": ["so_ngay", "ngay_tra"], "acts": ["nhan_tra"]}\n        ]\n      },\n      "acts": [\n        {\n          "alias": "nhan_tra",\n          "label": "Nh\u1EADn m\xE1y tr\u1EA3",\n          "when": {"trang_thai": ["dang_thue"]},\n          "asks": ["tinh_trang_tra"],\n          "set": {"trang_thai": "da_tra", "ngay_tra": "now"},\n          "confirm": true\n        }\n      ]\n    }\n  ]\n}\n```\n\n## Roster\n\n**The job.** See who works which shift on each day of the week or the month.\n\n**Read.** `register.layout: "roster"` over the people; `register.roster` names the child whose rows fill the days \u2014 one link back and a date on its line.\n\n**Keys.** `model/roster`\n\n**Not when.** Rows that are themselves the bookings (a stay over several days) \u2014 a `calendar` or `lanes` draws them; a roster\'s row is what the days are filled for.\n\n```json\n{\n  "entities": [\n    {\n      "alias": "nha_si",\n      "fields": [\n        {"alias": "ho_ten", "type": "text"},\n        {\n          "alias": "chuyen_mon",\n          "type": "select",\n          "options": [\n            {"alias": "tong_quat", "color": "blue"},\n            {"alias": "chinh_nha", "color": "purple"},\n            {"alias": "nha_chu", "color": "green"},\n            {"alias": "phuc_hinh", "color": "orange"}\n          ]\n        },\n        {"alias": "dien_thoai", "type": "text"}\n      ]\n    },\n    {\n      "alias": "lich_truc",\n      "fields": [\n        {"alias": "nha_si", "type": "select_record_link", "target_entity": "nha_si", "cardinality": "one"},\n        {\n          "alias": "ca",\n          "type": "select",\n          "options": [\n            {"alias": "sang", "color": "blue"},\n            {"alias": "chieu", "color": "purple"},\n            {"alias": "ca_ngay", "color": "green"},\n            {"alias": "nghi", "color": "gray"}\n          ]\n        },\n        {"alias": "ngay", "type": "date"},\n        {"alias": "ghe", "type": "select_record_link", "target_entity": "ghe", "cardinality": "one"}\n      ]\n    }\n  ],\n  "records": {\n    "nha_si": {"title": "ho_ten", "subtitle": ["chuyen_mon"], "party": "person"},\n    "lich_truc": {"title": "ca", "subtitle": ["ngay", "ghe"]}\n  },\n  "apps": [\n    {\n      "alias": "lich_truc",\n      "name": "L\u1ECBch tr\u1EF1c",\n      "icon": "users",\n      "theme": {"color": "indigo"},\n      "entity": "nha_si",\n      "register": {\n        "filters": ["chuyen_mon"],\n        "layout": "roster",\n        "roster": "lich_truc",\n        "create": ["ho_ten", "chuyen_mon", "dien_thoai"]\n      }\n    }\n  ]\n}\n```\n\n## Cards\n\n**The job.** Find an item by its picture, and count what the shelf holds.\n\n**Read.** `register.layout: "cards"` over rows whose `records.image` is a photo; `scope` keeps the app inside one warehouse at a time.\n\n**Keys.** `model/cards`, `model/records`, `model/apps`\n\n**Not when.** Rows with no picture \u2014 cards of words are a table drawn worse.\n\n```json\n{\n  "entities": [\n    {\n      "alias": "stock_item",\n      "fields": [\n        {"alias": "name", "type": "text"},\n        {\n          "alias": "warehouse",\n          "type": "select_record_link",\n          "target_entity": "warehouse",\n          "cardinality": "one"\n        },\n        {"alias": "photo", "type": "files"},\n        {"alias": "sku", "type": "text"},\n        {\n          "alias": "category",\n          "type": "select",\n          "options": [\n            {"alias": "pumps", "color": "blue"},\n            {"alias": "valves", "color": "teal"},\n            {"alias": "seals", "color": "amber"},\n            {"alias": "motors", "color": "violet"}\n          ]\n        },\n        {"alias": "on_hand", "type": "number"},\n        {"alias": "minimum", "type": "number"},\n        {"alias": "price", "type": "number", "notation": {"style": "currency", "currency": "USD"}},\n        {"alias": "supplier_page", "type": "text", "format": "link"},\n        {"alias": "last_counted", "type": "date"},\n        {"alias": "counted_by", "type": "select_member"},\n        {"alias": "count_note", "type": "text"}\n      ]\n    },\n    {\n      "alias": "order_line",\n      "fields": [\n        {"alias": "item", "type": "select_record_link", "target_entity": "stock_item", "cardinality": "one"},\n        {"alias": "order", "type": "select_record_link", "target_entity": "order", "cardinality": "one"},\n        {"alias": "quantity", "type": "number"},\n        {"alias": "shipped", "type": "number"},\n        {"alias": "picked", "type": "number"},\n        {"alias": "unit_price", "type": "number", "notation": {"style": "currency", "currency": "USD"}},\n        {"alias": "amount", "type": "formula"},\n        {"alias": "category", "type": "lookup"}\n      ]\n    }\n  ],\n  "records": {\n    "stock_item": {\n      "title": "name",\n      "subtitle": ["sku", "category"],\n      "image": "photo",\n      "figure": "on_hand",\n      "limits": {"on_hand": 400},\n      "gates": {"on_hand": "minimum"}\n    },\n    "order_line": {\n      "title": "item",\n      "subtitle": ["order", "unit_price"],\n      "figure": "amount",\n      "limits": {"shipped": "quantity", "picked": "quantity"}\n    }\n  },\n  "apps": [\n    {\n      "alias": "stock",\n      "name": "Stock",\n      "icon": "boxes",\n      "theme": {"color": "teal"},\n      "entity": "stock_item",\n      "scope": "warehouse",\n      "register": {\n        "columns": ["price"],\n        "filters": ["on_hand"],\n        "search": ["name", "sku"],\n        "layout": "cards",\n        "create": false,\n        "export": true,\n        "readings": [{"breakdown": "stock_item", "by": "category", "value": "on_hand"}]\n      },\n      "record": {\n        "sections": [\n          {"title": "Item", "fields": ["price", "minimum", "supplier_page"]},\n          {"title": "Last count", "fields": ["last_counted", "counted_by", "count_note"], "acts": ["count"]},\n          {"title": "On order", "blocks": [{"rows": "order_line", "columns": ["quantity"]}]}\n        ]\n      },\n      "acts": [\n        {\n          "alias": "count",\n          "label": "Count stock",\n          "asks": [\n            {"input": "counted", "label": "Units on the shelf", "type": "number", "required": true},\n            {"input": "remark", "label": "Remark", "type": "long_text"}\n          ],\n          "set": {\n            "on_hand": "input:counted",\n            "last_counted": "now",\n            "counted_by": "me",\n            "count_note": "input:remark"\n          }\n        }\n      ]\n    }\n  ]\n}\n```\n\n## Party\n\n**The job.** Keep each customer account \u2014 who they are, what they ordered, what was said to them.\n\n**Read.** `records.customer.party: "organization"` and its `image` (the logo); a `timeline` of touches, a `trend` of its orders, and its papers `expect`ed by kind.\n\n**Keys.** `model/records`, `model/timeline-and-agenda`, `model/blocks`, `model/reading-blocks`\n\n**Not when.** A list of customers is not a job by itself: the customer is a link on the desk whose rows name it, unless the job is the account itself.\n\n```json\n{\n  "entities": [\n    {\n      "alias": "customer",\n      "fields": [\n        {"alias": "name", "type": "text"},\n        {"alias": "logo", "type": "files"},\n        {"alias": "code", "type": "text"},\n        {\n          "alias": "tier",\n          "type": "select",\n          "options": [\n            {"alias": "key", "color": "violet"},\n            {"alias": "standard", "color": "sky"},\n            {"alias": "lapsed", "color": "gray"}\n          ]\n        },\n        {"alias": "phone", "type": "text"},\n        {"alias": "website", "type": "text", "format": "link"},\n        {"alias": "account_manager", "type": "select_member"},\n        {"alias": "credit_limit", "type": "number", "notation": {"style": "currency", "currency": "USD"}},\n        {"alias": "outstanding", "type": "rollup"},\n        {"alias": "over_limit", "type": "formula"},\n        {\n          "alias": "papers_needed",\n          "type": "select",\n          "options": [\n            {"alias": "credit_application", "color": "blue"},\n            {"alias": "trade_reference", "color": "violet"},\n            {"alias": "vat_certificate", "color": "teal"}\n          ],\n          "multi": true\n        },\n        {"alias": "notes", "type": "text", "format": "markdown"}\n      ]\n    },\n    {\n      "alias": "order",\n      "fields": [\n        {"alias": "customer", "type": "select_record_link", "target_entity": "customer", "cardinality": "one"},\n        {"alias": "reference", "type": "text"},\n        {\n          "alias": "stage",\n          "type": "select",\n          "options": [\n            {"alias": "draft", "color": "slate"},\n            {"alias": "confirmed", "color": "blue"},\n            {"alias": "picking", "color": "amber"},\n            {"alias": "shipped", "color": "indigo"},\n            {"alias": "delivered", "color": "green"},\n            {"alias": "cancelled", "color": "rose"}\n          ]\n        },\n        {"alias": "placed", "type": "date"},\n        {"alias": "due_date", "type": "date"},\n        {"alias": "total", "type": "rollup"},\n        {"alias": "balance", "type": "formula"},\n        {"alias": "units_ordered", "type": "rollup"},\n        {"alias": "units_shipped", "type": "rollup"},\n        {"alias": "units_picked", "type": "rollup"},\n        {"alias": "notes", "type": "text", "format": "markdown"},\n        {"alias": "paid_in_full", "type": "formula"}\n      ]\n    },\n    {\n      "alias": "customer_paper",\n      "fields": [\n        {\n          "alias": "kind",\n          "type": "select",\n          "options": [\n            {"alias": "credit_application", "color": "blue"},\n            {"alias": "trade_reference", "color": "violet"},\n            {"alias": "vat_certificate", "color": "teal"}\n          ]\n        },\n        {"alias": "customer", "type": "select_record_link", "target_entity": "customer", "cardinality": "one"},\n        {"alias": "received_on", "type": "date"},\n        {"alias": "file", "type": "files"}\n      ]\n    },\n    {\n      "alias": "touch",\n      "fields": [\n        {"alias": "said", "type": "text"},\n        {"alias": "customer", "type": "select_record_link", "target_entity": "customer", "cardinality": "one"},\n        {"alias": "by", "type": "select_member"}\n      ]\n    }\n  ],\n  "records": {\n    "customer": {\n      "title": "name",\n      "subtitle": ["tier"],\n      "image": "logo",\n      "party": "organization",\n      "figure": "outstanding",\n      "limits": {"outstanding": "credit_limit"}\n    },\n    "order": {\n      "title": "reference",\n      "subtitle": ["customer", "placed"],\n      "status": {"field": "stage", "closed": ["delivered", "cancelled"], "history": "order_stage"},\n      "figure": "total",\n      "limits": {"units_shipped": "units_ordered", "units_picked": "units_ordered"},\n      "due": ["due_date"]\n    },\n    "customer_paper": {"title": "kind", "image": "file"},\n    "touch": {"title": "said"}\n  },\n  "apps": [\n    {\n      "alias": "customers",\n      "name": "Customers",\n      "icon": "users",\n      "theme": {"color": "violet"},\n      "entity": "customer",\n      "reads": "shared",\n      "register": {\n        "columns": ["phone", "account_manager"],\n        "filters": ["account_manager"],\n        "sort": {"field": "name"},\n        "opens": {"tier": ["key", "standard"]},\n        "create": ["name", "code", "credit_limit"],\n        "readings": [\n          {"breakdown": "customer", "by": "tier", "value": "outstanding"},\n          {"breakdown": "customer", "by": "account_manager", "value": "outstanding"}\n        ]\n      },\n      "record": {\n        "door": "drawer",\n        "sections": [\n          {"title": "Contact", "fields": ["phone", "website"]},\n          {\n            "title": "Account",\n            "fields": ["code", "account_manager", "credit_limit"],\n            "acts": ["reassign", "lapse", "reinstate"]\n          },\n          {\n            "title": "Orders",\n            "blocks": [\n              {\n                "trend": "order",\n                "over": "placed",\n                "value": "total",\n                "where": {"stage": ["confirmed", "picking", "shipped", "delivered"]},\n                "label": "Order value"\n              },\n              {\n                "rows": "order",\n                "via": "customer",\n                "title": "Open orders",\n                "columns": ["due_date"],\n                "create": false,\n                "where": {"stage": ["draft", "confirmed", "picking", "shipped"]}\n              },\n              {\n                "rows": "order",\n                "via": "customer",\n                "title": "Shipped, still owed",\n                "columns": ["balance"],\n                "create": false,\n                "where": {"stage": ["shipped", "delivered"], "paid_in_full": false}\n              },\n              {\n                "list": "service_visit",\n                "columns": ["engineer", "job"],\n                "app": "visits",\n                "label": "Service visits"\n              }\n            ]\n          },\n          {\n            "title": "Account papers",\n            "blocks": [\n              {\n                "rows": "customer_paper",\n                "via": "customer",\n                "columns": ["received_on"],\n                "expect": "kind",\n                "of": "papers_needed"\n              }\n            ]\n          },\n          {"title": "Contact log", "blocks": [{"timeline": "touch", "via": "customer"}]},\n          {"title": "Notes", "blocks": [{"text": "notes"}]}\n        ]\n      },\n      "acts": [\n        {\n          "alias": "lapse",\n          "label": "Mark lapsed",\n          "when": {"tier": ["key", "standard"]},\n          "set": {"tier": "lapsed"},\n          "confirm": true\n        },\n        {\n          "alias": "reinstate",\n          "label": "Reinstate",\n          "when": {"tier": ["lapsed"]},\n          "asks": [\n            {\n              "input": "back_to",\n              "label": "Back to",\n              "type": "select",\n              "options": [\n                {"alias": "key", "label": "Key account", "color": "violet"},\n                {"alias": "standard", "label": "Standard", "color": "sky"}\n              ],\n              "required": true\n            }\n          ],\n          "set": {"tier": "input:back_to"}\n        },\n        {\n          "alias": "reassign",\n          "label": "Reassign",\n          "asks": [{"input": "to", "label": "Account manager", "type": "member", "required": true}],\n          "set": {"account_manager": "input:to"}\n        }\n      ],\n      "checks": [{"field": "over_limit"}]\n    }\n  ]\n}\n```\n\n## Case\n\n**The job.** Gather an applicant\'s papers into one case, make the forms it needs, and file it on time.\n\n**Read.** `expect` blocks for the papers brought (one line per kind, the missing ones empty), an act\'s `templates` for the forms made (ticked and made at once, kept in `into`), and `intake` reading the papers brought.\n\n**Keys.** `model/blocks`, `model/papers-and-recordings`\n\n**Not when.** A record that needs no papers, or one paper made once \u2014 a single `template` act.\n\n```json\n{\n  "entities": [\n    {\n      "alias": "ho_so",\n      "fields": [\n        {\n          "alias": "khach_hang",\n          "type": "select_record_link",\n          "target_entity": "khach_hang",\n          "cardinality": "one"\n        },\n        {"alias": "du_an", "type": "select_record_link", "target_entity": "du_an", "cardinality": "one"},\n        {"alias": "ma_ho_so", "type": "autonumber"},\n        {\n          "alias": "dich_vu",\n          "type": "select",\n          "options": [{"alias": "tron_goi", "color": "blue"}, {"alias": "lam_ho_so", "color": "violet"}]\n        },\n        {\n          "alias": "doi_tuong",\n          "type": "select",\n          "options": [\n            {"alias": "thu_nhap_thap", "color": "sky"},\n            {"alias": "cong_nhan", "color": "teal"},\n            {"alias": "can_bo", "color": "indigo"},\n            {"alias": "luc_luong", "color": "green"},\n            {"alias": "ho_ngheo", "color": "amber"},\n            {"alias": "nguoi_co_cong", "color": "rose"}\n          ]\n        },\n        {\n          "alias": "tinh_trang_nha_o",\n          "type": "select",\n          "options": [{"alias": "chua_co_nha", "color": "gray"}, {"alias": "nha_chat", "color": "orange"}]\n        },\n        {"alias": "giay_chung_nhan_so", "type": "text"},\n        {"alias": "dien_tich_nha", "type": "number"},\n        {"alias": "sale", "type": "select_member"},\n        {"alias": "xu_ly", "type": "select_member"},\n        {"alias": "can_bo_sung", "type": "boolean"},\n        {"alias": "phi_dich_vu", "type": "number", "notation": {"style": "currency", "currency": "VND"}},\n        {\n          "alias": "loai_can",\n          "type": "select",\n          "options": [\n            {"alias": "studio", "color": "sky"},\n            {"alias": "mot_pn", "color": "blue"},\n            {"alias": "hai_pn", "color": "indigo"},\n            {"alias": "ba_pn", "color": "violet"}\n          ]\n        },\n        {"alias": "khoi", "type": "select_record_link", "target_entity": "khoi_nha", "cardinality": "one"},\n        {"alias": "can_so", "type": "number"},\n        {"alias": "tang", "type": "number"},\n        {"alias": "hoa_hong_sale", "type": "number", "notation": {"style": "currency", "currency": "VND"}},\n        {"alias": "ngay_thu_phi", "type": "date"},\n        {"alias": "ngay_nhan_giay_to", "type": "date"},\n        {"alias": "ngay_lap_ho_so", "type": "date"},\n        {"alias": "ngay_nop_cdt", "type": "date"},\n        {"alias": "ngay_cdt_duyet", "type": "date"},\n        {"alias": "ngay_so_xd_duyet", "type": "date"},\n        {"alias": "ngay_boc_tham", "type": "date"},\n        {"alias": "ngay_ky_hdmb", "type": "date"},\n        {"alias": "ngay_ban_giao", "type": "date"},\n        {"alias": "bo_ho_so", "type": "files"},\n        {"alias": "hop_dong_mua_ban", "type": "files"},\n        {"alias": "giay_to", "type": "select_record_link", "target_entity": "giay_to", "cardinality": "many"},\n        {\n          "alias": "thanh_vien",\n          "type": "select_record_link",\n          "target_entity": "thanh_vien",\n          "cardinality": "many"\n        },\n        {\n          "alias": "phieu_thu",\n          "type": "select_record_link",\n          "target_entity": "phieu_thu",\n          "cardinality": "many"\n        },\n        {"alias": "dien_thoai", "type": "lookup"},\n        {"alias": "cccd", "type": "lookup"},\n        {"alias": "ngay_sinh", "type": "lookup"},\n        {"alias": "dia_chi", "type": "lookup"},\n        {"alias": "da_thu", "type": "rollup"},\n        {"alias": "chua_thu_phi", "type": "formula"},\n        {"alias": "con_no_phi", "type": "formula"},\n        {"alias": "vuot_thu_nhap", "type": "formula"},\n        {"alias": "da_hoan_tat", "type": "formula"}\n      ]\n    },\n    {\n      "alias": "thanh_vien",\n      "fields": [\n        {"alias": "ho_ten", "type": "text"},\n        {"alias": "ho_so", "type": "select_record_link", "target_entity": "ho_so", "cardinality": "one"},\n        {\n          "alias": "quan_he",\n          "type": "select",\n          "options": [\n            {"alias": "nguoi_dung_don", "color": "blue"},\n            {"alias": "vo_chong", "color": "violet"},\n            {"alias": "con", "color": "teal"},\n            {"alias": "bo_me", "color": "amber"},\n            {"alias": "khac", "color": "gray"}\n          ]\n        },\n        {"alias": "ngay_sinh", "type": "date"},\n        {"alias": "cccd", "type": "text"},\n        {"alias": "thu_nhap", "type": "number", "notation": {"style": "currency", "currency": "VND"}}\n      ]\n    },\n    {\n      "alias": "giay_to",\n      "fields": [\n        {\n          "alias": "loai",\n          "type": "select",\n          "options": [\n            {"alias": "don_dang_ky", "color": "blue"},\n            {"alias": "can_cuoc", "color": "sky"},\n            {"alias": "giay_doi_tuong", "color": "violet"},\n            {"alias": "xac_nhan_nha_o", "color": "teal"},\n            {"alias": "xac_nhan_thu_nhap", "color": "amber"},\n            {"alias": "hon_nhan", "color": "indigo"}\n          ]\n        },\n        {"alias": "ho_so", "type": "select_record_link", "target_entity": "ho_so", "cardinality": "one"},\n        {"alias": "ngay_nhan", "type": "date"},\n        {"alias": "can_sua", "type": "text"},\n        {"alias": "tep", "type": "files"},\n        {"alias": "phai_sua", "type": "formula"}\n      ]\n    },\n    {\n      "alias": "phieu_thu",\n      "fields": [\n        {\n          "alias": "khoan",\n          "type": "select",\n          "options": [\n            {"alias": "dat_coc", "color": "blue"},\n            {"alias": "tat_toan", "color": "indigo"},\n            {"alias": "phi_ho_so", "color": "violet"}\n          ]\n        },\n        {"alias": "ho_so", "type": "select_record_link", "target_entity": "ho_so", "cardinality": "one"},\n        {"alias": "so_tien", "type": "number", "notation": {"style": "currency", "currency": "VND"}},\n        {\n          "alias": "hinh_thuc",\n          "type": "select",\n          "options": [\n            {"alias": "tien_mat", "color": "green", "mark": {"kind": "icon", "name": "banknote"}},\n            {"alias": "chuyen_khoan", "color": "blue", "mark": {"kind": "icon", "name": "arrow-right-left"}}\n          ]\n        },\n        {\n          "alias": "trang_thai",\n          "type": "select",\n          "options": [\n            {"alias": "cho_thu", "color": "amber"},\n            {"alias": "da_thu", "color": "green"},\n            {"alias": "huy", "color": "gray"}\n          ]\n        },\n        {"alias": "ngay_thu", "type": "date"},\n        {"alias": "nguoi_thu", "type": "select_member"},\n        {"alias": "da_chot", "type": "formula"}\n      ]\n    }\n  ],\n  "records": {\n    "ho_so": {\n      "title": "khach_hang",\n      "subtitle": ["dich_vu"],\n      "status": {\n        "milestones": [\n          {"field": "ngay_thu_phi", "when": {"dich_vu": ["lam_ho_so"]}},\n          "ngay_nhan_giay_to",\n          {"field": "ngay_lap_ho_so", "when": {"dich_vu": ["tron_goi"]}},\n          {"field": "ngay_nop_cdt", "when": {"dich_vu": ["tron_goi"]}},\n          {"field": "ngay_cdt_duyet", "when": {"dich_vu": ["tron_goi"]}},\n          {"field": "ngay_so_xd_duyet", "when": {"dich_vu": ["tron_goi"]}},\n          {"field": "ngay_boc_tham", "when": {"dich_vu": ["tron_goi"]}},\n          {"field": "ngay_ky_hdmb", "when": {"dich_vu": ["tron_goi"]}},\n          {"field": "ngay_ban_giao", "when": {"dich_vu": ["lam_ho_so"]}}\n        ],\n        "closed": ["ngay_ky_hdmb", "ngay_ban_giao"]\n      },\n      "figure": "phi_dich_vu"\n    },\n    "thanh_vien": {"title": "ho_ten", "subtitle": ["quan_he", "cccd"], "party": "person", "figure": "thu_nhap"},\n    "giay_to": {"title": "loai", "image": "tep", "starts": {"ngay_nhan": "today"}},\n    "phieu_thu": {\n      "title": "khoan",\n      "subtitle": ["hinh_thuc", "ngay_thu"],\n      "status": {"field": "trang_thai", "closed": ["da_thu", "huy"]},\n      "figure": "so_tien"\n    }\n  },\n  "templates": [\n    {"alias": "don_dang_ky", "type": "html", "label": "\u0110\u01A1n \u0111\u0103ng k\xFD mua nh\xE0 \u1EDF x\xE3 h\u1ED9i"},\n    {"alias": "mau_02_chua_co_nha", "type": "html", "label": "M\u1EABu 02 \u2014 X\xE1c nh\u1EADn ch\u01B0a c\xF3 nh\xE0 \u1EDF"},\n    {"alias": "mau_03_nha_chat", "type": "html", "label": "M\u1EABu 03 \u2014 X\xE1c nh\u1EADn nh\xE0 \u1EDF d\u01B0\u1EDBi 15 m\xB2/ng\u01B0\u1EDDi"},\n    {"alias": "mau_05_thu_nhap", "type": "html", "label": "M\u1EABu 05 \u2014 X\xE1c nh\u1EADn thu nh\u1EADp"},\n    {"alias": "danh_sach_nop", "type": "html", "label": "Danh s\xE1ch h\u1ED3 s\u01A1 n\u1ED9p ch\u1EE7 \u0111\u1EA7u t\u01B0"}\n  ],\n  "apps": [\n    {\n      "alias": "ho_so",\n      "name": "H\u1ED3 s\u01A1 nh\xE0 \u1EDF x\xE3 h\u1ED9i",\n      "icon": "folder-open",\n      "theme": {"color": "blue"},\n      "entity": "ho_so",\n      "scope": "du_an",\n      "register": {\n        "columns": ["xu_ly", "can_bo_sung", "doi_tuong"],\n        "filters": ["xu_ly", "can_bo_sung"],\n        "search": ["khach_hang", "ma_ho_so", "dien_thoai"],\n        "create": ["khach_hang", "dich_vu", "doi_tuong", "tinh_trang_nha_o", "loai_can", "phi_dich_vu", "sale"],\n        "export": true,\n        "readings": [\n          {"metric": "ho_so", "where": {"can_bo_sung": true}, "label": "Ch\u1EDD kh\xE1ch b\u1ED5 sung"},\n          {"metric": "ho_so", "value": "da_thu", "over": "ngay_nhan_giay_to", "label": "Ph\xED \u0111\xE3 thu"},\n          {"breakdown": "ho_so", "by": "doi_tuong"}\n        ]\n      },\n      "record": {\n        "sections": [\n          {\n            "title": "Ng\u01B0\u1EDDi \u0111\u1EE9ng \u0111\u01A1n",\n            "fields": [\n              "ma_ho_so",\n              "dien_thoai",\n              "cccd",\n              "ngay_sinh",\n              "dia_chi",\n              "doi_tuong",\n              "tinh_trang_nha_o",\n              "sale",\n              "xu_ly",\n              "can_bo_sung"\n            ],\n            "blocks": [\n              {\n                "rows": "thanh_vien",\n                "title": "H\u1ED9 gia \u0111\xECnh",\n                "columns": ["ngay_sinh"],\n                "create": ["ho_ten", "quan_he", "ngay_sinh", "cccd", "thu_nhap"]\n              },\n              {\n                "rows": "giay_to",\n                "title": "Gi\u1EA5y t\u1EDD c\xE1 nh\xE2n",\n                "columns": ["ngay_nhan"],\n                "expect": "loai",\n                "only": ["can_cuoc", "hon_nhan"]\n              }\n            ],\n            "acts": ["doc_giay_to", "giao_xu_ly", "chuyen_du_an"]\n          },\n          {\n            "title": "Nh\xE0 hi\u1EC7n c\xF3",\n            "fields": ["giay_chung_nhan_so", "dien_tich_nha"],\n            "when": {"tinh_trang_nha_o": ["nha_chat"]}\n          },\n          {\n            "title": "Ph\xED d\u1ECBch v\u1EE5",\n            "blocks": [\n              {\n                "rows": "phieu_thu",\n                "title": "Phi\u1EBFu thu",\n                "columns": ["so_tien"],\n                "create": ["khoan", "so_tien", "hinh_thuc"],\n                "where": {"khoan": ["dat_coc", "tat_toan"]},\n                "expect": "khoan",\n                "when": {"dich_vu": ["tron_goi"]}\n              },\n              {\n                "rows": "phieu_thu",\n                "title": "Phi\u1EBFu thu",\n                "columns": ["so_tien"],\n                "create": ["khoan", "so_tien", "hinh_thuc"],\n                "where": {"khoan": ["phi_ho_so"]},\n                "expect": "khoan",\n                "when": {"dich_vu": ["lam_ho_so"]}\n              }\n            ]\n          },\n          {\n            "title": "Gi\u1EA5y t\u1EDD",\n            "at": ["ngay_thu_phi"],\n            "blocks": [\n              {\n                "rows": "giay_to",\n                "title": "Gi\u1EA5y t\u1EDD",\n                "columns": ["ngay_nhan"],\n                "create": ["loai", "ngay_nhan", "can_sua", "tep"],\n                "expect": "loai",\n                "only": ["don_dang_ky", "giay_doi_tuong", "xac_nhan_nha_o", "xac_nhan_thu_nhap"]\n              }\n            ]\n          },\n          {\n            "title": "B\u1ED9 h\u1ED3 s\u01A1",\n            "at": ["ngay_nhan_giay_to", "ngay_lap_ho_so"],\n            "acts": ["tao_giay_to", "nop_cdt"]\n          },\n          {\n            "title": "Ch\u1EE7 \u0111\u1EA7u t\u01B0",\n            "at": ["ngay_nop_cdt", "ngay_cdt_duyet", "ngay_so_xd_duyet"],\n            "fields": ["loai_can"],\n            "when": {"dich_vu": ["tron_goi"]}\n          },\n          {\n            "title": "C\u0103n h\u1ED9",\n            "at": ["ngay_boc_tham"],\n            "fields": ["khoi", "can_so", "tang", "hoa_hong_sale"],\n            "blocks": [{"files": ["hop_dong_mua_ban"]}],\n            "when": {"dich_vu": ["tron_goi"]}\n          }\n        ]\n      },\n      "acts": [\n        {\n          "alias": "doc_giay_to",\n          "label": "\u0110\u1ECDc gi\u1EA5y t\u1EDD",\n          "intake": "giay_to",\n          "fills": [\n            "doi_tuong",\n            "tinh_trang_nha_o",\n            "giay_chung_nhan_so",\n            "dien_tich_nha",\n            "khach_hang.ho_ten",\n            "khach_hang.cccd",\n            "khach_hang.ngay_sinh",\n            "khach_hang.dia_chi",\n            "thanh_vien"\n          ]\n        },\n        {\n          "alias": "tao_giay_to",\n          "label": "T\u1EA1o gi\u1EA5y t\u1EDD",\n          "templates": [\n            {"template": "don_dang_ky"},\n            {"template": "mau_02_chua_co_nha", "when": {"tinh_trang_nha_o": ["chua_co_nha"]}},\n            {"template": "mau_03_nha_chat", "when": {"tinh_trang_nha_o": ["nha_chat"]}},\n            {"template": "mau_05_thu_nhap", "when": {"doi_tuong": ["thu_nhap_thap"]}}\n          ],\n          "into": "bo_ho_so"\n        },\n        {\n          "alias": "nop_cdt",\n          "label": "N\u1ED9p ch\u1EE7 \u0111\u1EA7u t\u01B0",\n          "when": {"dich_vu": ["tron_goi"]},\n          "requires": ["bo_ho_so", "loai_can"],\n          "asks": ["loai_can"],\n          "set": {"ngay_nop_cdt": "now"},\n          "confirm": true\n        },\n        {\n          "alias": "giao_xu_ly",\n          "label": "Giao ng\u01B0\u1EDDi x\u1EED l\xFD",\n          "asks": [{"input": "nguoi", "label": "Ng\u01B0\u1EDDi x\u1EED l\xFD", "type": "member", "required": true}],\n          "set": {"xu_ly": "input:nguoi"}\n        },\n        {\n          "alias": "chuyen_du_an",\n          "label": "Chuy\u1EC3n d\u1EF1 \xE1n",\n          "asks": [{"input": "du_an_moi", "label": "Sang d\u1EF1 \xE1n", "type": "link", "entity": "du_an", "required": true}],\n          "set": {"du_an": "input:du_an_moi"},\n          "confirm": true\n        },\n        {\n          "alias": "in_danh_sach",\n          "label": "In danh s\xE1ch n\u1ED9p ch\u1EE7 \u0111\u1EA7u t\u01B0",\n          "on": "view",\n          "template": "danh_sach_nop"\n        },\n        {\n          "alias": "xac_nhan_thu",\n          "label": "X\xE1c nh\u1EADn \u0111\xE3 thu",\n          "of": "phieu_thu",\n          "when": {"trang_thai": ["cho_thu"]},\n          "asks": ["hinh_thuc"],\n          "set": {"trang_thai": "da_thu", "ngay_thu": "now", "nguoi_thu": "me"},\n          "confirm": true\n        },\n        {\n          "alias": "huy_phieu",\n          "label": "H\u1EE7y phi\u1EBFu",\n          "of": "phieu_thu",\n          "when": {"trang_thai": ["cho_thu"]},\n          "set": {"trang_thai": "huy"},\n          "danger": true\n        }\n      ],\n      "checks": [\n        {"field": "chua_thu_phi", "blocks": ["nop_cdt"]},\n        {"field": "con_no_phi"},\n        {"field": "vuot_thu_nhap"},\n        {"field": "da_hoan_tat", "blocks": ["delete", "doc_giay_to"]},\n        {"field": "da_chot", "of": "phieu_thu", "blocks": ["edit"]},\n        {"field": "phai_sua", "of": "giay_to"}\n      ]\n    }\n  ]\n}\n```\n\n## Calls\n\n**The job.** Call a lead from their record, and keep what was said as a touch on its timeline.\n\n**Read.** An act\'s `record` (into the `timeline` child: audio, transcript, when and who) and `fills` (the touch\'s fields an agent fills from the transcript).\n\n**Keys.** `model/papers-and-recordings`, `model/timeline-and-agenda`\n\n**Not when.** Calls made and logged elsewhere \u2014 a `timeline` with its own add keeps the note.\n\n```json\n{\n  "entities": [\n    {\n      "alias": "khach_tiem_nang",\n      "fields": [\n        {"alias": "ho_ten", "type": "text"},\n        {"alias": "ten_cong_ty", "type": "text"},\n        {\n          "alias": "vai_tro",\n          "type": "select",\n          "options": [\n            {"alias": "chu_doanh_nghiep", "color": "emerald"},\n            {"alias": "ke_toan_truong", "color": "blue"},\n            {"alias": "quan_ly", "color": "teal"},\n            {"alias": "nhan_vien", "color": "sky"},\n            {"alias": "chua_ro", "color": "zinc"}\n          ]\n        },\n        {\n          "alias": "loai_hinh",\n          "type": "select",\n          "options": [\n            {"alias": "thuong_mai", "color": "blue"},\n            {"alias": "san_xuat", "color": "amber"},\n            {"alias": "dich_vu", "color": "violet"},\n            {"alias": "xay_dung", "color": "orange"},\n            {"alias": "ho_kinh_doanh", "color": "teal"},\n            {"alias": "chua_ro", "color": "zinc"}\n          ]\n        },\n        {\n          "alias": "quy_mo",\n          "type": "select",\n          "options": [\n            {"alias": "q_1_10", "color": "sky"},\n            {"alias": "q_11_50", "color": "blue"},\n            {"alias": "q_51_200", "color": "indigo"},\n            {"alias": "q_200", "color": "violet"},\n            {"alias": "chua_ro", "color": "zinc"}\n          ]\n        },\n        {"alias": "so_dien_thoai", "type": "text"},\n        {"alias": "zalo", "type": "text"},\n        {"alias": "email", "type": "text"},\n        {"alias": "trang_ca_nhan", "type": "text", "format": "link"},\n        {"alias": "anh", "type": "files"},\n        {\n          "alias": "trang_thai",\n          "type": "select",\n          "options": [\n            {"alias": "moi", "color": "gray"},\n            {"alias": "du_dieu_kien", "color": "blue"},\n            {"alias": "da_lien_he", "color": "amber"},\n            {"alias": "da_chuyen_doi", "color": "emerald"},\n            {"alias": "loai", "color": "red"}\n          ]\n        },\n        {\n          "alias": "ly_do_loai",\n          "type": "select",\n          "options": [\n            {"alias": "khong_phu_hop", "color": "orange"},\n            {"alias": "qua_nho", "color": "amber"},\n            {"alias": "chua_co_ngan_sach", "color": "yellow"},\n            {"alias": "sai_nguoi", "color": "blue"},\n            {"alias": "yeu_cau_dung", "color": "red"},\n            {"alias": "trung", "color": "zinc"}\n          ]\n        },\n        {"alias": "vi_sao_du_dieu_kien", "type": "text"},\n        {"alias": "phu_trach", "type": "select_member"},\n        {"alias": "nguon", "type": "select_record_link", "target_entity": "kenh", "cardinality": "one"},\n        {"alias": "lien_he", "type": "select_record_link", "target_entity": "lien_he", "cardinality": "one"},\n        {"alias": "cong_ty", "type": "select_record_link", "target_entity": "cong_ty", "cardinality": "one"},\n        {"alias": "ngay_chuyen_doi", "type": "date", "format": "datetime", "timezone": "Asia/Ho_Chi_Minh"},\n        {"alias": "ghi_chu", "type": "text", "format": "markdown"},\n        {"alias": "tin_hieu", "type": "select_record_link", "target_entity": "tin_hieu"},\n        {"alias": "buoc_tiep", "type": "select_record_link", "target_entity": "buoc_tiep"},\n        {"alias": "tuong_tac", "type": "select_record_link", "target_entity": "tuong_tac"},\n        {"alias": "do_nong", "type": "formula"},\n        {"alias": "han_buoc_tiep", "type": "rollup"},\n        {"alias": "khong_lien_he", "type": "formula"}\n      ]\n    },\n    {\n      "alias": "tin_hieu",\n      "fields": [\n        {"alias": "tom_tat", "type": "text"},\n        {"alias": "noi_dung", "type": "text", "format": "markdown"},\n        {"alias": "anh_chup", "type": "files"},\n        {"alias": "lien_ket", "type": "text", "format": "link"},\n        {"alias": "kenh", "type": "select_record_link", "target_entity": "kenh", "cardinality": "one"},\n        {\n          "alias": "loai",\n          "type": "select",\n          "options": [\n            {"alias": "hoi_dich_vu", "color": "emerald"},\n            {"alias": "than_phien", "color": "blue"},\n            {"alias": "tuyen_ke_toan", "color": "amber"},\n            {"alias": "moi_thanh_lap", "color": "violet"},\n            {"alias": "gioi_thieu", "color": "teal"},\n            {"alias": "danh_ba", "color": "zinc"},\n            {"alias": "nhieu", "color": "stone"}\n          ]\n        },\n        {"alias": "ngay_dang", "type": "date", "timezone": "Asia/Ho_Chi_Minh"},\n        {"alias": "ngay_xay_ra", "type": "formula"}\n      ]\n    },\n    {\n      "alias": "buoc_tiep",\n      "fields": [\n        {"alias": "vi_sao_luc_nay", "type": "text"},\n        {\n          "alias": "viec",\n          "type": "select",\n          "options": [\n            {"alias": "binh_luan", "color": "blue", "mark": {"kind": "icon", "name": "message-square"}},\n            {"alias": "nhan_facebook", "color": "violet", "mark": {"kind": "brand", "name": "facebook"}},\n            {"alias": "nhan_zalo", "color": "sky", "mark": {"kind": "brand", "name": "zalo"}},\n            {"alias": "goi_dien", "color": "teal", "mark": {"kind": "icon", "name": "phone"}},\n            {"alias": "gui_email", "color": "indigo", "mark": {"kind": "icon", "name": "mail"}},\n            {"alias": "gui_bang_gia", "color": "amber", "mark": {"kind": "icon", "name": "receipt"}}\n          ]\n        },\n        {"alias": "ban_nhap", "type": "text", "format": "markdown"},\n        {"alias": "han", "type": "date", "format": "datetime", "timezone": "Asia/Ho_Chi_Minh"},\n        {\n          "alias": "tinh_trang",\n          "type": "select",\n          "options": [\n            {"alias": "cho", "color": "blue"},\n            {"alias": "xong", "color": "emerald"},\n            {"alias": "bo_qua", "color": "zinc"}\n          ]\n        }\n      ]\n    },\n    {\n      "alias": "tuong_tac",\n      "fields": [\n        {"alias": "tom_tat", "type": "text"},\n        {"alias": "thoi_diem", "type": "date", "format": "datetime", "timezone": "Asia/Ho_Chi_Minh"},\n        {\n          "alias": "qua",\n          "type": "select",\n          "options": [\n            {"alias": "goi_dien", "color": "teal", "mark": {"kind": "icon", "name": "phone"}},\n            {"alias": "zalo", "color": "sky", "mark": {"kind": "brand", "name": "zalo"}},\n            {"alias": "facebook", "color": "blue", "mark": {"kind": "brand", "name": "facebook"}},\n            {"alias": "email", "color": "indigo", "mark": {"kind": "icon", "name": "mail"}},\n            {"alias": "gap_truc_tiep", "color": "emerald", "mark": {"kind": "icon", "name": "users"}},\n            {"alias": "khac", "color": "zinc", "mark": {"kind": "icon", "name": "ellipsis"}}\n          ]\n        },\n        {\n          "alias": "phan_hoi",\n          "type": "select",\n          "options": [\n            {"alias": "dang_cho", "color": "blue"},\n            {"alias": "da_tra_loi", "color": "green"},\n            {"alias": "quan_tam", "color": "amber"},\n            {"alias": "khong_phu_hop", "color": "red"},\n            {"alias": "khong_phan_hoi", "color": "zinc"},\n            {"alias": "sai_so", "color": "stone"}\n          ]\n        },\n        {"alias": "ghi_am", "type": "files"},\n        {"alias": "nguyen_van", "type": "text", "format": "markdown"},\n        {"alias": "hen_lai", "type": "date", "timezone": "Asia/Ho_Chi_Minh"},\n        {"alias": "nguoi_thuc_hien", "type": "select_member"}\n      ]\n    }\n  ],\n  "records": {\n    "khach_tiem_nang": {\n      "title": "ho_ten",\n      "subtitle": ["ten_cong_ty"],\n      "image": "anh",\n      "party": "person",\n      "status": {"field": "trang_thai", "closed": ["da_chuyen_doi", "loai"], "history": "lich_su_trang_thai"},\n      "due": ["han_buoc_tiep"]\n    },\n    "tin_hieu": {"title": "tom_tat", "subtitle": ["kenh", "ngay_xay_ra"], "image": "anh_chup"},\n    "buoc_tiep": {\n      "title": "vi_sao_luc_nay",\n      "subtitle": ["viec"],\n      "mark": "viec",\n      "status": {"field": "tinh_trang", "closed": ["xong", "bo_qua"]},\n      "due": ["han"]\n    },\n    "tuong_tac": {"title": "tom_tat", "subtitle": ["qua", "phan_hoi"]}\n  },\n  "apps": [\n    {\n      "alias": "khach_tiem_nang",\n      "name": "Kh\xE1ch ti\u1EC1m n\u0103ng",\n      "icon": "radar",\n      "theme": {"color": "violet"},\n      "entity": "khach_tiem_nang",\n      "register": {\n        "columns": ["phu_trach", "han_buoc_tiep"],\n        "filters": ["phu_trach"],\n        "create": ["ho_ten", "trang_ca_nhan", "so_dien_thoai", "ten_cong_ty", "nguon"],\n        "readings": [\n          {"breakdown": "khach_tiem_nang", "by": "phu_trach"},\n          {"trend": "khach_tiem_nang", "over": "ngay_chuyen_doi", "label": "Kh\xE1ch chuy\u1EC3n \u0111\u1ED5i"}\n        ]\n      },\n      "record": {\n        "sections": [\n          {\n            "title": "\u0110\xE1nh gi\xE1",\n            "at": ["moi"],\n            "fields": ["vai_tro", "loai_hinh", "quy_mo", "vi_sao_du_dieu_kien", "do_nong"],\n            "blocks": [\n              {\n                "rows": "tin_hieu",\n                "title": "T\xEDn hi\u1EC7u",\n                "columns": ["loai", "noi_dung"],\n                "create": ["tom_tat", "anh_chup", "loai", "noi_dung", "kenh", "lien_ket", "ngay_dang"]\n              }\n            ],\n            "acts": ["danh_gia_dat"]\n          },\n          {\n            "title": "Li\xEAn h\u1EC7",\n            "at": ["du_dieu_kien"],\n            "fields": ["so_dien_thoai", "phu_trach", "trang_ca_nhan", "zalo", "email", "ghi_chu"],\n            "blocks": [\n              {\n                "rows": "buoc_tiep",\n                "title": "B\u01B0\u1EDBc ti\u1EBFp theo",\n                "columns": ["ban_nhap"],\n                "create": ["vi_sao_luc_nay", "viec", "han", "ban_nhap"]\n              },\n              {\n                "timeline": "tuong_tac",\n                "title": "T\u01B0\u01A1ng t\xE1c",\n                "create": ["tom_tat", "qua", "phan_hoi", "thoi_diem", "hen_lai"]\n              }\n            ],\n            "acts": ["ghi_cuoc_goi", "da_lien_he"]\n          },\n          {\n            "title": "Chuy\u1EC3n \u0111\u1ED5i",\n            "at": ["da_lien_he"],\n            "fields": ["nguon", "lien_he", "cong_ty"],\n            "acts": ["chuyen_doi"]\n          },\n          {"title": "Lo\u1EA1i", "at": ["loai"], "fields": ["ly_do_loai"], "acts": ["loai"]}\n        ]\n      },\n      "acts": [\n        {\n          "alias": "danh_gia_dat",\n          "label": "\u0110\u1EE7 \u0111i\u1EC1u ki\u1EC7n",\n          "when": {"trang_thai": ["moi"]},\n          "requires": ["vi_sao_du_dieu_kien"],\n          "set": {"trang_thai": "du_dieu_kien"}\n        },\n        {\n          "alias": "ghi_cuoc_goi",\n          "label": "Ghi \xE2m cu\u1ED9c g\u1ECDi",\n          "when": {"trang_thai": ["du_dieu_kien"]},\n          "record": {\n            "into": "tuong_tac",\n            "audio": "ghi_am",\n            "transcript": "nguyen_van",\n            "at": "thoi_diem",\n            "by": "nguoi_thuc_hien"\n          },\n          "fills": ["tom_tat", "phan_hoi"]\n        },\n        {\n          "alias": "da_lien_he",\n          "label": "\u0110\xE1nh d\u1EA5u \u0111\xE3 li\xEAn h\u1EC7",\n          "when": {"trang_thai": ["du_dieu_kien"]},\n          "set": {"trang_thai": "da_lien_he"}\n        },\n        {\n          "alias": "chuyen_doi",\n          "label": "Chuy\u1EC3n \u0111\u1ED5i",\n          "when": {"trang_thai": ["da_lien_he"]},\n          "workflow": "chuyen_doi_khach",\n          "writes": ["lien_he", "cong_ty"],\n          "confirm": true\n        },\n        {\n          "alias": "loai",\n          "label": "Lo\u1EA1i",\n          "when": {"trang_thai": ["moi", "du_dieu_kien", "da_lien_he"]},\n          "asks": ["ly_do_loai"],\n          "set": {"trang_thai": "loai"},\n          "danger": true\n        },\n        {\n          "alias": "lam_xong",\n          "label": "\u0110\xE3 l\xE0m",\n          "of": "buoc_tiep",\n          "when": {"tinh_trang": ["cho"]},\n          "set": {"tinh_trang": "xong"}\n        }\n      ],\n      "checks": [{"field": "khong_lien_he", "resolve": "da_lien_he"}]\n    }\n  ]\n}\n```\n\n## Approval\n\n**The job.** Raise a payment request, see it through approval, and read what is waiting at the top of the list.\n\n**Read.** `records.de_nghi.status` with its `history` (each move: when and who), sections staged by `at`, and `register.readings` leading with the headline number.\n\n**Keys.** `model/status`, `model/record-page`, `model/readings`\n\n**Not when.** Rows that never move \u2014 a reference list (a price list, a catalog) has no status and no headline number.\n\n```json\n{\n  "entities": [\n    {\n      "alias": "de_nghi",\n      "fields": [\n        {"alias": "noi_dung", "type": "text"},\n        {"alias": "so_de_nghi", "type": "text"},\n        {\n          "alias": "loai",\n          "type": "select",\n          "options": [\n            {"alias": "thanh_toan_ncc", "color": "violet"},\n            {"alias": "nhan_cong", "color": "indigo"},\n            {"alias": "chi_phi_cong_truong", "color": "sky"},\n            {"alias": "tam_ung", "color": "amber"},\n            {"alias": "hoan_ung", "color": "teal"}\n          ]\n        },\n        {"alias": "du_an", "type": "select_record_link", "target_entity": "du_an", "cardinality": "one"},\n        {\n          "alias": "nha_cung_cap",\n          "type": "select_record_link",\n          "target_entity": "nha_cung_cap",\n          "cardinality": "one"\n        },\n        {"alias": "so_tien", "type": "number", "notation": {"style": "currency", "currency": "VND"}},\n        {"alias": "han_thanh_toan", "type": "date"},\n        {\n          "alias": "trang_thai",\n          "type": "select",\n          "options": [\n            {"alias": "nhap", "color": "slate"},\n            {"alias": "cho_duyet", "color": "amber"},\n            {"alias": "cho_chu_tich", "color": "violet"},\n            {"alias": "da_duyet", "color": "blue"},\n            {"alias": "da_chi", "color": "green"},\n            {"alias": "tu_choi", "color": "rose"}\n          ]\n        },\n        {"alias": "nguoi_de_nghi", "type": "select_member"},\n        {"alias": "chung_tu", "type": "files"},\n        {"alias": "nguoi_duyet", "type": "select_member"},\n        {"alias": "duyet_luc", "type": "date", "format": "datetime"},\n        {"alias": "ly_do_tu_choi", "type": "text"},\n        {"alias": "phieu_chi", "type": "files"},\n        {"alias": "ngan_sach_du_an", "type": "lookup"},\n        {"alias": "da_duyet_du_an", "type": "lookup"},\n        {"alias": "vuot_ngan_sach", "type": "formula"},\n        {"alias": "sat_ngan_sach", "type": "formula"},\n        {"alias": "da_gui", "type": "formula"}\n      ]\n    }\n  ],\n  "records": {\n    "de_nghi": {\n      "title": "noi_dung",\n      "subtitle": ["du_an"],\n      "status": {\n        "field": "trang_thai",\n        "closed": ["da_chi", "tu_choi"],\n        "history": "lich_su_duyet",\n        "stages": {\n          "nhap": {"owner": "nguoi_de_nghi"},\n          "cho_duyet": {"owner": {"role": "giam_doc"}, "within": 1},\n          "cho_chu_tich": {"owner": {"role": "chu_tich"}, "within": 2},\n          "da_duyet": {"owner": {"role": "ke_toan"}, "within": 2}\n        }\n      },\n      "figure": "so_tien",\n      "limits": {"da_duyet_du_an": "ngan_sach_du_an"},\n      "due": ["han_thanh_toan"],\n      "starts": {"nguoi_de_nghi": "me"}\n    }\n  },\n  "apps": [\n    {\n      "alias": "de_nghi_chi",\n      "name": "\u0110\u1EC1 ngh\u1ECB thanh to\xE1n",\n      "icon": "hand-coins",\n      "theme": {"color": "amber"},\n      "entity": "de_nghi",\n      "register": {\n        "columns": ["nguoi_de_nghi"],\n        "filters": ["nguoi_de_nghi", "du_an"],\n        "group": "du_an",\n        "create": ["noi_dung", "loai", "du_an", "nha_cung_cap", "so_tien", "han_thanh_toan", "nguoi_de_nghi"],\n        "readings": [\n          {\n            "metric": "de_nghi",\n            "value": "so_tien",\n            "where": {"trang_thai": ["da_duyet"]},\n            "label": "\u0110\xE3 duy\u1EC7t, ch\u1EDD chi"\n          },\n          {"trend": "de_nghi", "over": "han_thanh_toan", "value": "so_tien"}\n        ]\n      },\n      "record": {\n        "door": "drawer",\n        "sections": [\n          {\n            "title": "\u0110\u1EC1 ngh\u1ECB",\n            "at": ["nhap"],\n            "fields": ["so_de_nghi", "loai", "nha_cung_cap", "han_thanh_toan", "nguoi_de_nghi"],\n            "blocks": [{"files": ["chung_tu"], "title": "Ch\u1EE9ng t\u1EEB k\xE8m"}],\n            "acts": ["gui_duyet"]\n          },\n          {\n            "title": "Duy\u1EC7t",\n            "at": ["cho_duyet", "cho_chu_tich"],\n            "fields": ["nguoi_duyet", "duyet_luc", "ly_do_tu_choi"],\n            "acts": ["rut_lai"]\n          },\n          {"title": "\u0110\xE3 chi", "at": ["da_chi"], "blocks": [{"files": ["phieu_chi"], "title": "Phi\u1EBFu chi"}]}\n        ]\n      },\n      "acts": [\n        {\n          "alias": "gui_duyet",\n          "label": "G\u1EEDi duy\u1EC7t",\n          "when": {"trang_thai": ["nhap"]},\n          "requires": ["chung_tu", "nguoi_de_nghi"],\n          "set": {"trang_thai": "cho_duyet"}\n        },\n        {\n          "alias": "rut_lai",\n          "label": "R\xFAt l\u1EA1i",\n          "when": {"trang_thai": ["cho_duyet", "cho_chu_tich"]},\n          "set": {"trang_thai": "nhap"},\n          "confirm": true\n        }\n      ],\n      "checks": [{"field": "da_gui", "blocks": ["edit"]}, {"field": "vuot_ngan_sach"}, {"field": "sat_ngan_sach"}]\n    }\n  ]\n}\n```\n\n## Dashboard\n\n**The job.** The owner\'s question \u2014 what came in, what went out, where it went, and what is still unmatched \u2014 answered over one period.\n\n**Read.** `dashboard`: `metric`s with `over` (the period windows them), a `trend`, `breakdown`s, and a `list` of rows to act on opening in their app.\n\n**Keys.** `model/dashboards`, `model/readings`\n\n**Not when.** One job\'s headline numbers \u2014 those lead that job\'s register as its `readings`.\n\n```json\n{\n  "entities": [\n    {\n      "alias": "giao_dich",\n      "fields": [\n        {"alias": "noi_dung", "type": "text"},\n        {"alias": "ngay", "type": "date"},\n        {\n          "alias": "loai",\n          "type": "select",\n          "options": [{"alias": "thu", "color": "green"}, {"alias": "chi", "color": "rose"}]\n        },\n        {"alias": "so_tien", "type": "number", "notation": {"style": "currency", "currency": "VND"}},\n        {"alias": "bien_dong", "type": "formula"},\n        {\n          "alias": "doi_tuong",\n          "type": "select_record_link",\n          "target_entity": "doi_tuong",\n          "cardinality": "one"\n        },\n        {\n          "alias": "danh_muc",\n          "type": "select",\n          "options": [\n            {"alias": "doanh_thu", "color": "green"},\n            {"alias": "hang_hoa", "color": "blue"},\n            {"alias": "van_chuyen", "color": "indigo"},\n            {"alias": "nhan_su", "color": "violet"},\n            {"alias": "van_phong", "color": "sky"},\n            {"alias": "thue_phi", "color": "slate"},\n            {"alias": "ngan_hang", "color": "teal"},\n            {"alias": "khac", "color": "gray"}\n          ]\n        },\n        {"alias": "sao_ke", "type": "select_record_link", "target_entity": "sao_ke", "cardinality": "one"},\n        {"alias": "hoa_don", "type": "select_record_link", "target_entity": "hoa_don", "cardinality": "many"},\n        {\n          "alias": "trang_thai",\n          "type": "select",\n          "options": [\n            {"alias": "chua_khop", "color": "amber"},\n            {"alias": "da_khop", "color": "green"},\n            {"alias": "khong_can_hd", "color": "slate"}\n          ]\n        }\n      ]\n    },\n    {\n      "alias": "hoa_don",\n      "fields": [\n        {\n          "alias": "doi_tuong",\n          "type": "select_record_link",\n          "target_entity": "doi_tuong",\n          "cardinality": "one"\n        },\n        {"alias": "so_hoa_don", "type": "text"},\n        {"alias": "ngay_hoa_don", "type": "date"},\n        {"alias": "so_ngay_qua_han", "type": "formula"},\n        {\n          "alias": "chieu",\n          "type": "select",\n          "options": [{"alias": "ban_ra", "color": "green"}, {"alias": "mua_vao", "color": "violet"}]\n        },\n        {"alias": "tong_cong", "type": "formula"},\n        {"alias": "thue_suat", "type": "formula"},\n        {"alias": "tep", "type": "files"},\n        {\n          "alias": "giao_dich",\n          "type": "select_record_link",\n          "target_entity": "giao_dich",\n          "cardinality": "many"\n        }\n      ]\n    }\n  ],\n  "records": {\n    "giao_dich": {\n      "title": "noi_dung",\n      "subtitle": ["ngay"],\n      "status": {"field": "trang_thai", "closed": ["da_khop", "khong_can_hd"], "history": "lich_su_khop"},\n      "figure": "bien_dong"\n    },\n    "hoa_don": {"title": "doi_tuong", "subtitle": ["so_hoa_don", "ngay_hoa_don"], "image": "tep", "figure": "tong_cong"}\n  },\n  "apps": [\n    {\n      "alias": "dong_tien",\n      "name": "D\xF2ng ti\u1EC1n",\n      "icon": "chart-line",\n      "theme": {"color": "emerald"},\n      "dashboard": [\n        {\n          "metric": "giao_dich",\n          "value": "so_tien",\n          "where": {"loai": ["thu"]},\n          "over": "ngay",\n          "label": "Ti\u1EC1n v\xE0o"\n        },\n        {\n          "metric": "giao_dich",\n          "value": "so_tien",\n          "where": {"loai": ["chi"]},\n          "over": "ngay",\n          "better": "down",\n          "label": "Ti\u1EC1n ra"\n        },\n        {"trend": "giao_dich", "over": "ngay", "value": "bien_dong", "label": "D\xF2ng ti\u1EC1n r\xF2ng"},\n        {\n          "breakdown": "giao_dich",\n          "by": "danh_muc",\n          "value": "so_tien",\n          "where": {"loai": ["chi"]},\n          "over": "ngay",\n          "label": "Chi theo danh m\u1EE5c"\n        },\n        {\n          "breakdown": "giao_dich",\n          "by": "doi_tuong",\n          "value": "so_tien",\n          "where": {"loai": ["thu"]},\n          "over": "ngay",\n          "label": "Thu theo kh\xE1ch h\xE0ng"\n        },\n        {\n          "pivot": "hoa_don",\n          "rows": "doi_tuong",\n          "columns": {"field": "so_ngay_qua_han", "tiers": [1, 8, 16, 31]},\n          "value": "tong_cong",\n          "where": {"chieu": ["ban_ra"]},\n          "label": "C\xF4ng n\u1EE3 b\xE1n ra theo tu\u1ED5i n\u1EE3"\n        },\n        {\n          "metric": "hoa_don",\n          "value": "so_ngay_qua_han",\n          "average": true,\n          "where": {"chieu": ["ban_ra"]},\n          "label": "S\u1ED1 ng\xE0y qu\xE1 h\u1EA1n b\xECnh qu\xE2n"\n        },\n        {"metric": "hoa_don", "value": "thue_suat", "average": true, "label": "Thu\u1EBF su\u1EA5t b\xECnh qu\xE2n"},\n        {\n          "list": "giao_dich",\n          "where": {"trang_thai": ["chua_khop"]},\n          "columns": ["sao_ke"],\n          "app": "doi_chieu",\n          "label": "D\xF2ng ch\u01B0a kh\u1EDBp"\n        }\n      ]\n    }\n  ]\n}\n```\n';
 // docs/agent_surface.md
-var agent_surface_default = '# An app\'s agent surface\n\nEverything a person reads or does in an app, an agent reads or does through that app\'s **queries** and\n**workflows** \u2014 the same ones its screen runs, under the same permissions and the same rules. Three tools\nreach them, over MCP and as `lotics run <tool>`:\n\n| Tool | Answers |\n|---|---|\n| `get_app_capabilities` | The app\'s queries and workflows by alias: each one\'s description, its params or inputs with their types and legal values, and under a query\'s line its output columns (`returns`) \u2014 beside what each table they name holds, in its owner\'s words |\n| `run_app_query` | The rows, a count or the groups of one query \u2014 or of several in one call |\n| `run_app_workflow` | One write \u2014 or several in order \u2014 or a preview of it that writes nothing |\n\nAn app stated in a model generates this surface from the model; the model declares what the screen never\nasks (\xA7 Declaring more). An app\'s logs (`logs`) are part of it: a log\'s list, its rows by id, its record\'s\nblocks and its acts are queries and workflows of the same app, named by the log\'s entity as the register\'s\nare by its own \u2014 `get_app_capabilities` lists them in the one roster, and nothing of a log is another app\'s. What only a log reads or runs answers the organization\'s own members alone, never a caller through the app\'s public link. A custom-code app\'s surface is the queries and workflows bound on it\n(`lotics docs app_bindings`).\n\n## What every app generates\n\nA name in angle brackets is the model\'s alias for that thing. `get_app_capabilities` lists the ones a given\napp has.\n\n### Queries\n\n<!-- generated:start queries -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `<entity>_list` | Every row of <entity> the reader may see. | `search`?; `<scope entity>_id` where the app states `scope`; `<filter>_is`? per `register.filters` field holding one value \u2014 a select, a one-row link, a member, a yes/no; `<filter>_from`? / `<filter>_to`? per date filter \u2014 none for a date holding a span; `<filter>_min`? / `<filter>_max`? per number filter \u2014 none over `books`, none for a looked-up link or member, none for a number read in each row\'s own unit or currency | every entity the app draws; the filter params on the app\'s own entity alone |\n| `<entity>_list_<tab>` | The <entity> rows of the tab "<tab>". | the list\'s; `from`? / `to`? on a tab dated `in` a period; `to` on a tab of rows `open` on a day | each of `register.tabs`; none over `books`, none for a tab whose period reads a date holding a span |\n| `<entity>_record` | One row of <entity> by its id. | `<entity>_id` | every entity the app draws |\n| `<child>_by_<link>` | The <child> rows under one <entity>, through "<link>". | `<entity>_id` | each block of child rows on the record; one narrowed by `where` or ordered by `sort` adds `_<field>_<option>` and `_sorted_<field>` to its name |\n| `<child>_by_<link>_days` | The <child> rows of the <entity> rows handed in whose "<day>" falls from one day to another. | `<entity>_ids`; `from`; `to` | `register.roster` |\n| `<entity>_<link>_pick` | The <target> rows "<link>" may point at, narrowed by what the reader typed. | `search`?; `same_<link>` per `same` link | a written link a write rule narrows (`options_where`, `same`) |\n| `<child>_by_<link>_picks` | The <child> rows no <entity> holds through "<link>" yet, that one <entity> may pick, narrowed by what the reader typed. | `search`?; `same_<link>` per `same` link | a block that picks existing rows into the record |\n| `register_reading_<n>` | <label>: how many <entity> rows there are. Each row carries `__count`. | the list\'s; `from`? / `to`? where the reading states `over`, or its `tab` is dated `in` a period; `to` where its `tab` is of rows `open` on a day | each of `register.readings` by its place among them, counted from 0 \u2014 but the work against its plan (`progress`), which reads the list\'s own rows; none over `books`. A reading stating `alias` is called by it |\n| `dashboard_reading_<n>` | <label>: how many <entity> rows there are. Each row carries `__count`. | `from`? / `to`? where the reading states `over` | each of a dashboard\'s readings, counted from 0; a reading stating `alias` is called by it |\n| `block_reading_<n>` | <label>: how many <child> rows there are. Each row carries `__count`. | `<entity>_id`; `same_<field>` where it is a list stating `same` | each reading, list or funnel block of the record, by its place among the record\'s blocks, counted from 0; a reading stating `alias` is called by it |\n| `<entity>_register_reading_<n>` | <label>: how many <entity> rows there are. Each row carries `__count`. | the list\'s; `from`? / `to`? where the reading states `over` | each of a log\'s `register.readings` by its place among them, counted from 0, named by the log\'s entity; a reading stating `alias` is called `<entity>_<alias>` |\n| `<entity>_block_reading_<n>` | <label>: how many <child> rows there are. Each row carries `__count`. | `<entity>_id`; `same_<field>` where it is a list stating `same` | each reading, list or funnel block of the record a row of a book or of a log opens, by its place among that record\'s blocks, counted from 0, named by the book\'s or the log\'s entity |\n| `<reading>_bound` | <label> / <bound>: the sum of "<bound>" over the <entity> rows. Each row carries `__count`, `__sum`. | its reading\'s | a metric whose value `records.limits` bounds: the bound\'s sum, beside the reading\'s own |\n| `<entity>_export_rows` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list\'s | a `register.export` that fills a template |\n| `<entity>_export_rows_of_<book>` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list\'s | a report of some of an app\'s `books`: their rows alone, each book named in turn |\n| `<entity>_moves` | Each move in <history> of the <entity> rows handed in: the status it went to, when and by whom, earliest first. | `<entity>_ids` | an entity whose status keeps a history (`records.status.history`) |\n| `<entity>_plan_load` | How many <entity> rows each <place> holds, over every table the register reads \u2014 the rows with no <place> counted apart. |  | a `plan` register: its places\' counts of present rows |\n\n<!-- generated:end queries -->\n\nA reading\'s query returns groups, never the rows it read: one row for all of them, or one per value it\nsplits by, or per day. Each row carries the alias of each field it splits by, `__day` where it splits by\nday, `__count`, and `__sum` where it sums a number; its description states which. An average is `__sum`\nover `__count`, both over the rows holding a value.\n\nA reading that states no `alias` is called by its place, so moving it in the model changes the name it is\ncalled by. A place that generates no query keeps its number, so the names may skip one. A reading an agent\nor a published API calls states its `alias` (`lotics docs model/readings`). A log\'s reading is called by the\nlog\'s entity before either name: `<entity>_register_reading_<n>`, or `<entity>_<alias>`.\n\nA register reading\'s query reads the rows it names, whatever a screen has open: the rows of its `tab` where\nit states one, every tab\'s where it states none \u2014 its description says which. One placed in time (`over`)\nreads every day unless the call states `from` or `to`.\n\n### Queries the screen runs for itself\n\nThey run like any other, and `get_app_capabilities` leaves them out: each feeds one control, and takes ids\nthe screen already holds.\n\n<!-- generated:start screen-queries -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `<child>_<link>_target` | One <entity> row by its id, where a <child> row\'s "<link>" may point at it. | `<entity>_id` | a picking block whose link a write rule narrows |\n| `<entity>_<field>_values` | Each "<field>" the <entity> rows hold, once, most held first, narrowed by what the reader typed. | `search`? | a text field a write rule offers values to (`suggest`) |\n| `<entity>_pictures` | The picture and name of each <entity> row among the ids handed in. | `<entity>_ids` | a link to several pictured rows |\n| `<entity>_count_by_<scope>` | How many <entity> rows each <scope entity> holds. |  | an app stating `scope` |\n| `<task>_progress_by_<link>` | How many <task> rows each <entity> row handed in holds, at each status. | `<entity>_ids` | rows whose task rows are counted done |\n| `<rows>_measured_by_<link>` | The share of each <entity> row handed in its <rows> rows add, day by day. | `<entity>_ids` | a `progress` reading stating `measured` |\n| `<lane>_lanes` | The <lane> rows of one <scope entity>, each a lane of the board. | `<scope entity>_id` | a lanes board inside an app stating `scope` |\n| `<entity>_same_<link>` | The <entity> rows naming one "<link>". | `same`; `before` where its line reads rows before a moment | a statement line that carries rows (`parts`) |\n\n<!-- generated:end screen-queries -->\n\n### Workflows\n\n<!-- generated:start workflows -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `create_<entity>` | Opens one row of <entity>. | every field the add asks, and the link it files the row under | an entity the app adds rows of |\n| `update_<entity>` | Changes one row of <entity>; every input but the row is optional, and one left out is left as it is. | `record_id`, and each field a person edits \u2014 a files field or a link to several rows as `<field>_added` / `<field>_removed` | an entity the app edits |\n| `remove_<entity>` | Removes one row of <entity>. | `record_id` | an entity the app removes rows of |\n| `act_<act>` | <label> \u2014 on one row of <entity>, refused where its conditions do not hold. | `record_id` \u2014 `record_ids` on an act over several rows \u2014 and what the act asks | each of `acts` that names no workflow of its own |\n| `archive_<act>` | Hands back every file of <label> on one row of <entity> as one archive. | `record_id` | an act making a set of papers (`templates`) |\n| `record_activity` | Lists one record\'s activity, newest first: each save with its fields before and after and who made it, and whether the caller may put it back. `next` is the `after` of the next page. | `record_id`; `after`? | every register app, unless `record.activity` is `false` |\n| `record_activity_undo` | Puts back one change entry of a record\'s activity, as the caller\'s own save, each field where the record still holds what the entry wrote. The fields kept are handed back with why. | `record_id`; `entry_id` | every register app, unless `record.activity` is `false`, where the app edits that entity |\n| `<workflow>_<book>` | The workflow of that name as one of the app\'s `books`, or a log of it, runs it, where its own table or page makes it differ. | that workflow\'s | an app stating `books` or `logs` |\n\n<!-- generated:end workflows -->\n\nA workflow the model declares (`workflows`) and an act that names its own are called by the alias the model\ngives them.\n\n## Calling a query\n\n```\nlotics run get_app_capabilities \'{"app_id":"app_\u2026"}\'\nlotics run run_app_query \'{"app_id":"app_\u2026","alias":"hire_list","params":{"status_is":"opt_\u2026","due_back_to":"2031-03-14"}}\'\n```\n\n| Argument | Does |\n|---|---|\n| `params` | The query\'s declared params. A required one is always sent; an optional one left out narrows nothing. A select takes an option\'s value, a link a record id, a member a member id, a date `yyyy-mm-dd` |\n| `filters` | Narrows the result further, by the query\'s output columns (`lotics docs filters`) |\n| `fields` | The output columns to return, in place of all of them; each row then holds them and the id of the record it is |\n| `sort` | An order in place of the query\'s own: `[{ "field_key": "<column>", "order": "asc" }]`, `asc` or `desc`, each `field_key` an output column\'s name |\n| `count` | `true`: `total`, the number of rows, in place of the rows; with `count_by`, `counts` per value of one column, keyed by an option\'s label, a member\'s name or a linked row\'s display; with `count_where` \u2014 a map of name \u2192 filter, never beside `count_by` \u2014 `counts` per name. Never with `fields`, `sort`, `limit` or `cursor` |\n| `aggregate` | Groups of the result in place of its rows, one row per group: `by` (up to 3 columns), or `day` (a date column, answered as `__day`), and `sum` (a number column, answered as `__sum`), each group with its `__count`. Sent with `params` and `filters` alone |\n| `limit`, `cursor` | A page \u2014 200 rows at most, 50 where no `limit` is stated \u2014 and the `next_cursor` of the page before it; `truncated` says more rows matched than `rows` holds |\n| `runs` | Several reads in one call, 20 at most, each with its own `alias` and arguments, answered in order under `runs`. Never beside an `alias` of the call\'s own |\n\nA query that states its own `limit` lists at most that many rows: `truncated` is `true` where more match, and `total` is\nthe rows the filtered query matches without it. A `count`, `count_by`, `count_where` and an `aggregate` are over every row\nthe query matches, never over the rows its `limit` lists.\n\nThe rows of one call, across its reads, total at most 262,144 bytes: a read past that is refused, naming\n`fields` and `limit` as what narrows it. The names `filters`, `fields`, `sort`, `count_by` and `aggregate`\ntake are the ones on the query\'s `returns` line.\n\nA list\'s params are how a person narrows that register: `search`, the row\'s id on an app that works inside\none row (`scope`), and a param for each filter the register states that one value or a range narrows. A\nfilter with no param \u2014 on a looked-up link or member, on a number read in each row\'s own unit or currency,\non a date holding a span, or on a register of several tables (`books`) \u2014 is narrowed by `filters`, where a\nnumber condition names the unit its value is in as `unit_option`, an option of the figure\'s select by label\nor key. Each tab of a register is a query of its own, taking the list\'s params and the period its rows are\nread over.\n\n## Calling a workflow\n\n```\nlotics run run_app_workflow \'{"app_id":"app_\u2026","alias":"act_check_out","inputs":{"record_id":"rec_\u2026"},"preview":true}\'\nlotics run run_app_workflow \'{"app_id":"app_\u2026","alias":"act_check_out","inputs":{"record_id":"rec_\u2026"}}\'\n```\n\n| Argument | Does |\n|---|---|\n| `inputs` | The workflow\'s declared inputs. An update takes the record and only the fields that change |\n| `preview` | `true`: nothing is written, and the answer is what the run would return, with the calls it would make \u2014 or `status: "not_previewed"` where the workflow cannot be previewed (\xA7 A preview) |\n| `runs` | Several runs in one call, 50 at most, in order, each its own write, answered under `runs`. The first one refused, failed or not previewed ends the call. An input `{"from_run": 0, "path": "data.record_id"}` is an earlier run\'s answer at that path. A run states its own `preview`, or takes the call\'s |\n\n```\nlotics run run_app_workflow \'{"app_id":"app_\u2026","runs":[\n  {"alias":"create_hire","inputs":{"customer":"rec_\u2026","machine":"rec_\u2026","due_back":"2031-03-14"}},\n  {"alias":"act_check_out","inputs":{"record_id":{"from_run":0,"path":"data.record_id"}}}\n]}\'\n```\n\n## A preview\n\nA previewed run makes every read the run would make and none of its writes. Its answer carries `status`,\n`message`, `field_errors` and `data` as the run would return them, and under `preview`:\n\n| Key | Holds |\n|---|---|\n| `available` | `true` |\n| `writes` | The calls the run would make that are not reads, in order. The app\'s owner and an admin, who may read the workflow\'s body, read each call\'s `step_id`, `tool_name` and `input`. Another member reads each step that would write once: its `step_id` and `tool_name`, and where the step states them outright, the `table_id` it names and how many `records` it lists |\n| `unpredicted` | The parts of the answer left out \u2014 `message`, `field_errors`, `data` \u2014 because each reads what a call the preview did not make would answer |\n\nA preview says nothing of a call its target refuses when it is made \u2014 a locked record, a required field, a\npermission \u2014 nor of what a write sets off in turn: a table\'s own workflows, its computed fields.\n\nA workflow is not previewed where its body reads the answer of a call the preview does not make, to branch,\nloop, check or feed another call, where it reads a linked record after such a call, where it runs an agent,\nwhere it waits, where a step cannot be evaluated or sends its call an input the call refuses, and where the\nrun is past what one preview walks \u2014 its steps, the passes of a loop, its reads or the time it takes. The\nanswer is then `status: "not_previewed"` with\n`preview: { "available": false, "reason" }`, and nothing ran \u2014 within `runs`, it ends the call. The same\nanswers a caller outside the app\'s organization.\n\n## A reviewed act\n\nAn act that states `review` runs a workflow that only proposes: call it with the inputs the act asks and it answers,\nwriting nothing, the changeset its body proposes in `data.review` \u2014 `table_id`, `creates` (each with its `key`) and\n`updates` (each with its `record_id`), each row\'s `data` holding only the fields that change, by field key, with an\noptional `note` and `ticked` (`false` where the body leaves it for a person to choose), and `unplaced`, what was read\nand matched nothing; the platform adds a `sha` to every row. Call it again with the same inputs and `approved`,\n`{ "updates": [{ "record_id", "sha" }], "creates": [{ "key", "sha" }] }`, listing the rows to write with the `sha` each\ncarries in the proposal, copied as it came \u2014 never computed \u2014 and the platform writes those rows as that second call\nproposes them, each only where it proposes the values read:\n\n```\nlotics run run_app_workflow \'{"app_id":"app_\u2026","alias":"match_statement","inputs":{"record_ids":["rec_\u2026"],"statement":"fil_\u2026"}}\'\nlotics run run_app_workflow \'{"app_id":"app_\u2026","alias":"match_statement","inputs":{"record_ids":["rec_\u2026"],"statement":"fil_\u2026","approved":{"updates":[{"record_id":"rec_\u2026","sha":"9f2c\u2026"}],"creates":[{"key":"line-4","sha":"41d0\u2026"}]}}}\'\n```\n\nThe answer\'s `data.applied` names the run (`execution_id`), the records `updated`, each `created` record by its key,\nand each approved row `left` with its `reason`: `not_proposed` (the second call no longer proposes it), `not_acted`\n(an update of a record the act was not run on), `changed` (the second call proposes other values than were read \u2014 read\nthe proposal again), `empty` (an update changing no field), `missing`, `locked` or `conflict`. Every approved row is\nchecked before any is written, and all are written in one transaction or none; the status history of each row written\nthat moved is recorded by the same run, so the workflow step `undo_record_changes` with that `execution_id` as its `workflow_execution_id` takes back both. An act over every\nrow in view takes no `record_ids`. A `file` input takes the id of a file uploaded to the workspace.\n\n## A refusal\n\nA workflow re-checks on the server every rule the screen shows: what an act requires, a bound, a duplicate,\nwhose step it is, a row the caller may not see. A run that is refused writes nothing and answers\n`status: "error"` with the sentence a person would read as `message`, and under `field_errors` the sentence\nfor each input it was refused over. A value of the wrong type, a missing required input and an unknown\nalias are refused before the body runs: the call itself fails with the sentence, and `field_errors` where\nan input is at fault \u2014 within `runs`, a run refused for its inputs answers `status: "error"` in its place,\nand the runs before it stand. A refused read fails the same way, naming the param or the column; within\n`runs`, it answers its `error` and the other reads are still answered.\n\n## Declaring more\n\nWhat a person would ask an agent in the app, and no screen draws, is stated in the model beside the app\'s\nacts. Both are checked by `check_model` and compiled by `apply_model` (`lotics docs model/queries`, `lotics docs model/workflows`).\n\n**A query** \u2014 the rows of one entity, or one figure of them, in the model\'s own aliases:\n\n```jsonc\n"queries": {\n  "hires_overdue": {\n    "description": "A customer\'s hires still out past the day they were due back, longest overdue first.",\n    "params": {\n      "customer": { "type": "record_link", "entity": "customer", "required": false, "description": "Only this customer\'s hires." },\n      "as_of": { "type": "date", "description": "The day a hire is overdue on: due back before it." }\n    },\n    "rows": "hire",\n    "fields": ["customer", "machine", "due_back", "daily_rate"],\n    "where": { "status": ["out"], "customer": { "param": "customer" }, "due_back": { "to": { "param": "as_of" } } },\n    "sort": { "field": "due_back" }\n  }\n}\n```\n\nIt reads under the entity\'s read scope and, on the app\'s own entity, exactly the rows its list reads \u2014\nso never the entity of an app that states `books`, whose list reads several tables. A condition reading an\noptional param narrows nothing when the call leaves it out; no param compares a number read in each row\'s\nown unit or currency, or a date holding a span. `"reading"` in place of `"fields"` returns a count or a sum \u2014\n`{ "value": "daily_rate", "by": "machine" }` \u2014 as a reading does. A declared query, a declared workflow and\na reading\'s `alias` take no name the app generates (`lotics docs model/app.generated-name`).\n\n**A workflow** \u2014 a write no act of the record makes, typed in the model and its body set on the app:\n\n```jsonc\n"workflows": {\n  "import_bookings": {\n    "description": "Books every hire a booking sheet lists, reusing a hire the sheet already booked.",\n    "inputs": {\n      "sheet": { "type": "file", "description": "The booking sheet, one hire per row." },\n      "booked_by": { "type": "member", "required": false, "description": "Who the hires are booked by; absent, the caller." }\n    },\n    "outputs": { "added": { "type": "number" }, "reused": { "type": "number" } }\n  }\n}\n```\n\n`lotics run set_app_workflow` sets its body (`lotics docs workflows`). A query set on a model\'s app outside\nthe model (`set_app_queries`, on the CLI or in chat) is removed by the next apply, whose plan and answer note it; declared under\nits alias in `queries`, it is the model\'s. A caller sees the description and\neach input\'s `description` and nothing else, so each says what the value is and what leaving it out means;\n`check_model` notes one that says nothing.\n\n**Shape each for a caller that is not looking at a screen.** Take a list where one job covers many records.\nMake a write survive running twice. Return the ids of what was written under `outputs`, so the next run can\nread them. Gate what cannot be undone behind an approval step.\n\n## Prove an app as an agent\n\nRun on a throwaway record.\n\n1. `get_app_capabilities` \u2014 every job the app\'s `description` names has an alias that does it or reads it.\n2. `run_app_query` the list with no param, then with each param a person would narrow by; `count: true`\n   answers how many without the rows.\n3. `run_app_query` `<entity>_record` with one row\'s id, and each `<child>_by_<link>` under it.\n4. `run_app_workflow` an act with `preview: true`, then without.\n5. `run_app_workflow` an act its record is not ready for: the answer is `status: "error"` with the sentence\n   the screen would show.\n6. `run_app_workflow` `record_activity` for the record, then `record_activity_undo` with the entry the act\n   wrote: each field the act changed reads as it did before step 4, but one written since, which `kept`\n   names. A row the act added under the record and a file it made stay.\n';
+var agent_surface_default = '# An app\'s agent surface\n\nEverything a person reads or does in an app, an agent reads or does through that app\'s **queries** and\n**workflows** \u2014 the same ones its screen runs, under the same permissions and the same rules. Three tools\nreach them, over MCP and as `lotics run <tool>`:\n\n| Tool | Answers |\n|---|---|\n| `get_app_capabilities` | The app\'s queries and workflows by alias: each one\'s description, its params or inputs with their types and legal values, and under a query\'s line its output columns (`returns`) \u2014 beside what each table they name holds, in its owner\'s words |\n| `run_app_query` | The rows, a count or the groups of one query \u2014 or of several in one call |\n| `run_app_workflow` | One write \u2014 or several in order \u2014 or a preview of it that writes nothing |\n\nAn app stated in a model generates this surface from the model; the model declares what the screen never\nasks (\xA7 Declaring more). An app\'s logs (`logs`) are part of it: a log\'s list, its rows by id, its record\'s\nblocks and its acts are queries and workflows of the same app, named by the log\'s entity as the register\'s\nare by its own \u2014 `get_app_capabilities` lists them in the one roster, and nothing of a log is another app\'s. What only a log reads or runs answers the organization\'s own members alone, never a caller through the app\'s public link. A custom-code app\'s surface is the queries and workflows bound on it\n(`lotics docs app_bindings`).\n\n## What every app generates\n\nA name in angle brackets is the model\'s alias for that thing. `get_app_capabilities` lists the ones a given\napp has.\n\n### Queries\n\n<!-- generated:start queries -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `<entity>_list` | Every row of <entity> the reader may see. | `search`?; `<scope entity>_id` where the app states `scope`; `<filter>_is`? per `register.filters` field holding one value \u2014 a select, a one-row link, a member, a yes/no; `<filter>_from`? / `<filter>_to`? per date filter \u2014 none for a date holding a span; `<filter>_min`? / `<filter>_max`? per number filter \u2014 none over `books`, none for a looked-up link or member, none for a number read in each row\'s own unit or currency | every entity the app draws; the filter params on the app\'s own entity alone |\n| `<entity>_list_<tab>` | The <entity> rows of the tab "<tab>". | the list\'s; `from`? / `to`? on a tab dated `in` a period; `to` on a tab of rows `open` on a day | each of `register.tabs`; none over `books`, none for a tab whose period reads a date holding a span |\n| `<entity>_record` | One row of <entity> by its id. | `<entity>_id` | every entity the app draws |\n| `<child>_by_<link>` | The <child> rows under one <entity>, through "<link>". | `<entity>_id` | each block of child rows on the record; one narrowed by `where` or ordered by `sort` adds `_<field>_<option>` and `_sorted_<field>` to its name |\n| `<child>_by_<link>_days` | The <child> rows of the <entity> rows handed in whose "<day>" falls from one day to another. | `<entity>_ids`; `from`; `to` | `register.roster` |\n| `<entity>_<link>_pick` | The <target> rows "<link>" may point at, narrowed by what the reader typed. | `search`?; `same_<link>` per `same` link | a written link a write rule narrows (`options_where`, `same`) |\n| `<child>_by_<link>_picks` | The <child> rows no <entity> holds through "<link>" yet, that one <entity> may pick, narrowed by what the reader typed. | `search`?; `same_<link>` per `same` link | a block that picks existing rows into the record |\n| `register_reading_<n>` | <label>: how many <entity> rows there are. Each row carries `__count`. | the list\'s; `from`? / `to`? where the reading states `over`, or its `tab` is dated `in` a period; `to` where its `tab` is of rows `open` on a day | each of `register.readings` by its place among them, counted from 0 \u2014 but the work against its plan (`progress`), which reads the list\'s own rows; none over `books`. A reading stating `alias` is called by it |\n| `dashboard_reading_<n>` | <label>: how many <entity> rows there are. Each row carries `__count`. | `from`? / `to`? where the reading states `over` | each of a dashboard\'s readings, counted from 0; a reading stating `alias` is called by it |\n| `block_reading_<n>` | <label>: how many <child> rows there are. Each row carries `__count`. | `<entity>_id`; `same_<field>` where it is a list stating `same` | each reading, list or funnel block of the record, by its place among the record\'s blocks, counted from 0; a reading stating `alias` is called by it |\n| `<entity>_register_reading_<n>` | <label>: how many <entity> rows there are. Each row carries `__count`. | the list\'s; `from`? / `to`? where the reading states `over` | each of a log\'s `register.readings` by its place among them, counted from 0, named by the log\'s entity; a reading stating `alias` is called `<entity>_<alias>` |\n| `<entity>_block_reading_<n>` | <label>: how many <child> rows there are. Each row carries `__count`. | `<entity>_id`; `same_<field>` where it is a list stating `same` | each reading, list or funnel block of the record a row of a book or of a log opens, by its place among that record\'s blocks, counted from 0, named by the book\'s or the log\'s entity |\n| `<reading>_bound` | <label> / <bound>: the sum of "<bound>" over the <entity> rows. Each row carries `__count`, `__sum`. | its reading\'s | a metric whose value `records.limits` bounds: the bound\'s sum, beside the reading\'s own |\n| `<entity>_export_rows` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list\'s | a `register.export` that fills a template |\n| `<entity>_export_rows_of_<book>` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list\'s | a report of some of an app\'s `books`: their rows alone, each book named in turn |\n| `<entity>_moves` | Each move in <history> of the <entity> rows handed in: the status it went to, when and by whom, earliest first. | `<entity>_ids` | an entity whose status keeps a history (`records.status.history`) |\n| `<entity>_plan_load` | How many <entity> rows each <place> holds, over every table the register reads \u2014 the rows with no <place> counted apart. |  | a `plan` register: its places\' counts of present rows |\n\n<!-- generated:end queries -->\n\nA reading\'s query returns groups, never the rows it read: one row for all of them, or one per value it\nsplits by, or per day. Each row carries the alias of each field it splits by, `__day` where it splits by\nday, `__count`, and `__sum` where it sums a number; its description states which. An average is `__sum`\nover `__count`, both over the rows holding a value.\n\nA reading that states no `alias` is called by its place, so moving it in the model changes the name it is\ncalled by. A place that generates no query keeps its number, so the names may skip one. A reading an agent\nor a published API calls states its `alias` (`lotics docs model/readings`). A log\'s reading is called by the\nlog\'s entity before either name: `<entity>_register_reading_<n>`, or `<entity>_<alias>`.\n\nA register reading\'s query reads the rows it names, whatever a screen has open: the rows of its `tab` where\nit states one, every tab\'s where it states none \u2014 its description says which. One placed in time (`over`)\nreads every day unless the call states `from` or `to`.\n\n### Queries the screen runs for itself\n\nThey run like any other, and `get_app_capabilities` leaves them out: each feeds one control, and takes ids\nthe screen already holds.\n\n<!-- generated:start screen-queries -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `<child>_<link>_target` | One <entity> row by its id, where a <child> row\'s "<link>" may point at it. | `<entity>_id` | a picking block whose link a write rule narrows |\n| `<entity>_<field>_values` | Each "<field>" the <entity> rows hold, once, most held first, narrowed by what the reader typed. | `search`? | a text field a write rule offers values to (`suggest`) |\n| `<entity>_pictures` | The picture and name of each <entity> row among the ids handed in. | `<entity>_ids` | a link to several pictured rows |\n| `<entity>_count_by_<scope>` | How many <entity> rows each <scope entity> holds. |  | an app stating `scope` |\n| `<task>_progress_by_<link>` | How many <task> rows each <entity> row handed in holds, at each status. | `<entity>_ids` | rows whose task rows are counted done |\n| `<rows>_measured_by_<link>` | The share of each <entity> row handed in its <rows> rows add, day by day. | `<entity>_ids` | a `progress` reading stating `measured` |\n| `<lane>_lanes` | The <lane> rows of one <scope entity>, each a lane of the board. | `<scope entity>_id` | a lanes board inside an app stating `scope` |\n| `<entity>_same_<link>` | The <entity> rows naming one "<link>". | `same`; `before` where its line reads rows before a moment | a statement line that carries rows (`parts`) |\n\n<!-- generated:end screen-queries -->\n\n### Workflows\n\n<!-- generated:start workflows -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `create_<entity>` | Opens one row of <entity>. | every field the add asks, and the link it files the row under | an entity the app adds rows of |\n| `update_<entity>` | Changes one row of <entity>; every input but the row is optional, and one left out is left as it is. | `record_id`, and each field a person edits \u2014 a files field or a link to several rows as `<field>_added` / `<field>_removed` | an entity the app edits |\n| `remove_<entity>` | Removes one row of <entity>. | `record_id` | an entity the app removes rows of |\n| `act_<act>` | <label> \u2014 on one row of <entity>, refused where its conditions do not hold. | `record_id` \u2014 `record_ids` on an act over several rows \u2014 and what the act asks | each of `acts` that names no workflow of its own |\n| `archive_<act>` | Hands back every file of <label> on one row of <entity> as one archive. | `record_id` | an act making a set of papers (`templates`) |\n| `record_activity` | Lists one record\'s activity, newest first: each save with its fields before and after and who made it, and whether the caller may put it back. `next` is the `after` of the next page. | `record_id`; `after`? | every register app, unless `record.activity` is `false` |\n| `record_activity_undo` | Puts back one change entry of a record\'s activity, as the caller\'s own save, each field where the record still holds what the entry wrote. The fields kept are handed back with why. | `record_id`; `entry_id` | every register app, unless `record.activity` is `false`, where the app edits that entity |\n| `<workflow>_<book>` | The workflow of that name as one of the app\'s `books`, or a log of it, runs it, where its own table or page makes it differ. | that workflow\'s | an app stating `books` or `logs` |\n\n<!-- generated:end workflows -->\n\nA workflow the model declares (`workflows`) and an act that names its own are called by the alias the model\ngives them.\n\n## Calling a query\n\n```\nlotics run get_app_capabilities \'{"app_id":"app_\u2026"}\'\nlotics run run_app_query \'{"app_id":"app_\u2026","alias":"hire_list","params":{"status_is":"opt_\u2026","due_back_to":"2031-03-14"}}\'\n```\n\n| Argument | Does |\n|---|---|\n| `params` | The query\'s declared params. A required one is always sent; an optional one left out narrows nothing. A select takes an option\'s value, a link a record id, a member a member id, a date `yyyy-mm-dd` |\n| `filters` | Narrows the result further, by the query\'s output columns (`lotics docs filters`) |\n| `fields` | The output columns to return, in place of all of them; each row then holds them and the id of the record it is |\n| `sort` | An order in place of the query\'s own: `[{ "field_key": "<column>", "order": "asc" }]`, `asc` or `desc`, each `field_key` an output column\'s name |\n| `count` | `true`: `total`, the number of rows, in place of the rows; with `count_by`, `counts` per value of one column, keyed by an option\'s label, a member\'s name or a linked row\'s display; with `count_where` \u2014 a map of name \u2192 filter, never beside `count_by` \u2014 `counts` per name. Never with `fields`, `sort`, `limit` or `cursor` |\n| `aggregate` | Groups of the result in place of its rows, one row per group: `by` (up to 3 columns), or `day` (a date column, answered as `__day`), and `sum` (a number column, answered as `__sum`), each group with its `__count`. Sent with `params` and `filters` alone |\n| `limit`, `cursor` | A page \u2014 200 rows at most, 50 where no `limit` is stated \u2014 and the `next_cursor` of the page before it; `truncated` says more rows matched than `rows` holds |\n| `runs` | Several reads in one call, 20 at most, each with its own `alias` and arguments, answered in order under `runs`. Never beside an `alias` of the call\'s own |\n\nA query that states its own `limit` lists at most that many rows: `truncated` is `true` where more match, and `total` is\nthe rows the filtered query matches without it. A `count`, `count_by`, `count_where` and an `aggregate` are over every row\nthe query matches, never over the rows its `limit` lists.\n\nThe rows of one call, across its reads, total at most 262,144 bytes: a read past that is refused, naming\n`fields` and `limit` as what narrows it. The names `filters`, `fields`, `sort`, `count_by` and `aggregate`\ntake are the ones on the query\'s `returns` line.\n\nA list\'s params are how a person narrows that register: `search`, the row\'s id on an app that works inside\none row (`scope`), and a param for each filter the register states that one value or a range narrows. A\nfilter with no param \u2014 on a looked-up link or member, on a number read in each row\'s own unit or currency,\non a date holding a span, or on a register of several tables (`books`) \u2014 is narrowed by `filters`, where a\nnumber condition names the unit its value is in as `unit_option`, an option of the figure\'s select by label\nor key. Each tab of a register is a query of its own, taking the list\'s params and the period its rows are\nread over.\n\n## Calling a workflow\n\n```\nlotics run run_app_workflow \'{"app_id":"app_\u2026","alias":"act_check_out","inputs":{"record_id":"rec_\u2026"},"preview":true}\'\nlotics run run_app_workflow \'{"app_id":"app_\u2026","alias":"act_check_out","inputs":{"record_id":"rec_\u2026"}}\'\n```\n\n| Argument | Does |\n|---|---|\n| `inputs` | The workflow\'s declared inputs. An update takes the record and only the fields that change |\n| `preview` | `true`: nothing is written, and the answer is what the run would return, with the calls it would make \u2014 or `status: "not_previewed"` where the workflow cannot be previewed (\xA7 A preview) |\n| `runs` | Several runs in one call, 50 at most, in order, each its own write, answered under `runs`. The first one refused, failed or not previewed ends the call. An input `{"from_run": 0, "path": "data.record_id"}` is an earlier run\'s answer at that path. A run states its own `preview`, or takes the call\'s |\n\n```\nlotics run run_app_workflow \'{"app_id":"app_\u2026","runs":[\n  {"alias":"create_hire","inputs":{"customer":"rec_\u2026","machine":"rec_\u2026","due_back":"2031-03-14"}},\n  {"alias":"act_check_out","inputs":{"record_id":{"from_run":0,"path":"data.record_id"}}}\n]}\'\n```\n\n## A preview\n\nA previewed run makes every read the run would make and none of its writes. Its answer carries `status`,\n`message`, `field_errors` and `data` as the run would return them, and under `preview`:\n\n| Key | Holds |\n|---|---|\n| `available` | `true` |\n| `writes` | The calls the run would make that are not reads, in order. The app\'s owner and an admin, who may read the workflow\'s body, read each call\'s `step_id`, `tool_name` and `input`. Another member reads each step that would write once: its `step_id` and `tool_name`, and where the step states them outright, the `table_id` it names and how many `records` it lists |\n| `unpredicted` | The parts of the answer left out \u2014 `message`, `field_errors`, `data` \u2014 because each reads what a call the preview did not make would answer |\n\nA preview says nothing of a call its target refuses when it is made \u2014 a locked record, a required field, a\npermission \u2014 nor of what a write sets off in turn: a table\'s own workflows, its computed fields.\n\nA workflow is not previewed where its body reads the answer of a call the preview does not make, to branch,\nloop, check or feed another call, where it reads a linked record after such a call, where it runs an agent,\nwhere it waits, where a step cannot be evaluated or sends its call an input the call refuses, and where the\nrun is past what one preview walks \u2014 its steps, the passes of a loop, its reads or the time it takes. The\nanswer is then `status: "not_previewed"` with\n`preview: { "available": false, "reason" }`, and nothing ran \u2014 within `runs`, it ends the call. The same\nanswers a caller outside the app\'s organization.\n\n## A reviewed act\n\nAn act that states `review` runs a workflow that only proposes: call it with the inputs the act asks and it answers,\nwriting nothing, the changeset its body proposes in `data.review` \u2014 `table_id`, `creates` (each with its `key`) and\n`updates` (each with its `record_id`), each row\'s `data` holding only the fields that change, by field key, with an\noptional `note` and `ticked` (`false` where the body leaves it for a person to choose), and `unplaced`, what was read\nand matched nothing; the platform adds a `sha` to every row. Call it again with the same inputs and `approved`,\n`{ "updates": [{ "record_id", "sha" }], "creates": [{ "key", "sha" }] }`, listing the rows to write with the `sha` each\ncarries in the proposal, copied as it came \u2014 never computed \u2014 and the platform writes those rows as that second call\nproposes them, each only where it proposes the values read:\n\n```\nlotics run run_app_workflow \'{"app_id":"app_\u2026","alias":"match_statement","inputs":{"record_ids":["rec_\u2026"],"statement":"fil_\u2026"}}\'\nlotics run run_app_workflow \'{"app_id":"app_\u2026","alias":"match_statement","inputs":{"record_ids":["rec_\u2026"],"statement":"fil_\u2026","approved":{"updates":[{"record_id":"rec_\u2026","sha":"9f2c\u2026"}],"creates":[{"key":"line-4","sha":"41d0\u2026"}]}}}\'\n```\n\nThe answer\'s `data.applied` names the run (`execution_id`), the records `updated`, each `created` record by its key,\nand each approved row `left` with its `reason`: `not_proposed` (the second call no longer proposes it), `not_acted`\n(an update of a record the act was not run on), `changed` (the second call proposes other values than were read \u2014 read\nthe proposal again), `empty` (an update changing no field), `missing`, `locked` or `conflict`. Every approved row is\nchecked before any is written, and all are written in one transaction or none; the status history of each row written\nthat moved is recorded by the same run, so the workflow step `undo_record_changes` with that `execution_id` as its `workflow_execution_id` takes back both. An act over every\nrow in view takes no `record_ids`. A `file` input takes the id of a file uploaded to the workspace.\n\n## A refusal\n\nA workflow re-checks on the server every rule the screen shows: what an act requires, a bound, a duplicate,\nwhose step it is, a row the caller may not see. A run that is refused writes nothing and answers\n`status: "error"` with the sentence a person would read as `message`, and under `field_errors` the sentence\nfor each input it was refused over. A value of the wrong type, a missing required input and an unknown\nalias are refused before the body runs: the call itself fails with the sentence, and `field_errors` where\nan input is at fault \u2014 within `runs`, a run refused for its inputs answers `status: "error"` in its place,\nand the runs before it stand. A refused read fails the same way, naming the param or the column; within\n`runs`, it answers its `error` and the other reads are still answered.\n\n## Declaring more\n\nWhat a person would ask an agent in the app, and no screen draws, is stated in the model beside the app\'s\nacts. Both are checked by `check_model` and compiled by `apply_model` (`lotics docs model/queries`, `lotics docs model/workflows`).\n\n**A query** \u2014 the rows of one entity, or one figure of them, in the model\'s own aliases:\n\n```jsonc\n"queries": {\n  "hires_overdue": {\n    "description": "A customer\'s hires still out past the day they were due back, longest overdue first.",\n    "params": {\n      "customer": { "type": "record_link", "entity": "customer", "required": false, "description": "Only this customer\'s hires." },\n      "as_of": { "type": "date", "description": "The day a hire is overdue on: due back before it." }\n    },\n    "rows": "hire",\n    "fields": ["customer", "machine", "due_back", "daily_rate"],\n    "where": { "status": ["out"], "customer": { "param": "customer" }, "due_back": { "to": { "param": "as_of" } } },\n    "sort": { "field": "due_back" }\n  }\n}\n```\n\nIt reads under the entity\'s read scope and, on the app\'s own entity, exactly the rows its list reads \u2014\nso never the entity of an app that states `books`, whose list reads several tables. A condition reading an\noptional param narrows nothing when the call leaves it out; no param compares a number read in each row\'s\nown unit or currency, or a date holding a span. `"reading"` in place of `"fields"` returns a count or a sum \u2014\n`{ "value": "daily_rate", "by": "machine" }` \u2014 as a reading does. A declared query, a declared workflow and\na reading\'s `alias` take no name the app generates (`lotics docs model/app.generated-name`).\n\n**A workflow** \u2014 a write no act of the record makes, typed in the model and its body set on the app:\n\n```jsonc\n"workflows": {\n  "import_bookings": {\n    "description": "Books every hire a booking sheet lists, reusing a hire the sheet already booked.",\n    "inputs": {\n      "sheet": { "type": "file", "description": "The booking sheet, one hire per row." },\n      "booked_by": { "type": "member", "required": false, "description": "Who the hires are booked by; absent, the caller." }\n    },\n    "outputs": { "added": { "type": "number" }, "reused": { "type": "number" } }\n  }\n}\n```\n\n`lotics run set_app_workflow` sets its body (`lotics docs workflows`). A query set on a model\'s app outside\nthe model (`set_app_queries`, on the CLI or in chat) is removed by the next apply, whose plan and answer note it; declared under\nits alias in `queries`, it is the model\'s. A caller sees the description and\neach input\'s `description` and nothing else, so each says what the value is and what leaving it out means;\n`check_model` notes one that says nothing.\n\n**Shape each for a caller that is not looking at a screen.** One job a person hands an agent \u2014 a paper read,\na message answered, a sheet brought in \u2014 is one declared workflow named for the job, never a chain of the\ngenerated per-row workflows. Take a list where the job covers many rows, a record\'s lines among them. A body\nthat writes more than one row makes them in one `save_record` workflow step, all or nothing, and recognises\nwhat exists by the identity the input itself carries, declared unique on its table, so the same input sent\ntwice updates instead of adding. Return the ids under `outputs`, so the next run can read them. Gate what\ncannot be undone behind an approval step.\n\n## Prove an app as an agent\n\nRun on a throwaway record.\n\n1. `get_app_capabilities` \u2014 every job the app\'s `description` names has an alias that does it or reads it.\n2. `run_app_query` the list with no param, then with each param a person would narrow by; `count: true`\n   answers how many without the rows.\n3. `run_app_query` `<entity>_record` with one row\'s id, and each `<child>_by_<link>` under it.\n4. `run_app_workflow` an act with `preview: true`, then without.\n5. `run_app_workflow` an act its record is not ready for: the answer is `status: "error"` with the sentence\n   the screen would show.\n6. `run_app_workflow` `record_activity` for the record, then `record_activity_undo` with the entry the act\n   wrote: each field the act changed reads as it did before step 4, but one written since, which `kept`\n   names. A row the act added under the record and a file it made stay.\n7. `run_app_workflow` the app\'s job workflow with the input a person would hand it \u2014 the paper read, the row:\n   it completes in one call. Call it again with the same input: nothing is added.\n';
 // AGENTS.md
 var AGENTS_default = "# @lotics/cli \u2014 agent index\n\nThe model an agent needs before driving this CLI: which surface answers which question, what the\nconventions are, and where the traps are.\n\n| Read | For |\n|---|---|\n| `lotics --help` | The verb inventory (\xA7 COMMANDS) and global flags. The verb LIST is generated and never stale; the prose beside each verb is hand-written, so where it disagrees with `docs/cli_reference.md`, the reference wins. |\n| `lotics tools` \xB7 `lotics tools <name>` | The agent tool registry and one tool's full JSON Schema. |\n| `lotics docs` \xB7 `lotics docs <area>[/<section>]` \xB7 `lotics docs [<area>] --grep <text>` | This CLI's references, carried inside it so each describes the binary answering. Capped at a page: a doc that does not fit hands back its opening and the addresses into it, so the next call is smaller than the last. A page the copy lacks \u2014 one the server added since this binary was built, which a refusal can cite \u2014 is read from the server's `docs` tool with this machine's credential, and so is every `--grep`, over the references the server serves. A custom-code app's SDK reference is `node_modules/@lotics/app-sdk/AGENTS.md` inside the app. |\n| `lotics docs model` \xB7 `lotics docs model/<section>` | How to write a `model.json` \u2014 the file a workspace is built from: its tables, how a row of each is recognised (`records`), and the apps stated over them. Every top-level key, every field type with the config it needs, the row format, the rules, and a worked example; complete example models of several trades are listed at `https://lotics.ai/presets/index.json`. `lotics model apply` checks the file (every problem in one run), applies its tables and mints a version of each app; the WORKSPACE remembers what each alias became, so every later apply binds by id and a relabel on either side is a rename it reports rather than a second table it adds. `lotics model pull` goes the other way \u2014 the workspace's model, rebuilt from what owns each part. |\n| `lotics docs design` \xB7 `lotics docs design/<section>` | Designing an app \u2014 where an app starts: the method, the treatment each kind of row takes with the `model` page stating its keys, the visual bar, and looking at what an apply built. A finding of the apply names its section. |\n| `lotics docs examples` \xB7 `lotics docs examples/<treatment>` | Each treatment worked through in an app of a complete model: the job, the keys to read, where it is the wrong one, and the excerpt. |\n| [docs/building_an_app.md](./docs/building_an_app.md) | The SEQUENCE \u2014 clarify, model, apply or build, prove, look \u2014 for an app stated in a model and for a custom-code app. Read it once before starting an app. Looking is `lotics run screenshot_app '<json>' -o <dir>`, which saves each PNG and its text snapshot there. |\n| [docs/cli_reference.md](./docs/cli_reference.md) | Per-command contracts, flags, exit codes, and gotchas \u2014 the detail `--help` compresses. |\n| [docs/data_model.md](./docs/data_model.md) | Tables, their fields, and how they relate \u2014 one fact per column, one entity per table and the NAME-OVERLAP probe that says when a split has broken, one vocabulary wherever values are copied, a copy boundary that accounts for every source field, provenance as a link, a declared natural key, history as rows, and why derived DEPTH costs more than row count; then every field type, its properties, computed fields, and what `update_fields` takes. Separate from building_an_app because every workspace starts with tables and many never get an app. |\n| [docs/filters.md](./docs/filters.md) | The one filter grammar every filter-taking tool, view and rollup reads \u2014 conditions, groups, and the operators per field type. |\n| [docs/field_values.md](./docs/field_values.md) | The value each field type takes in a write. |\n| [docs/workflows.md](./docs/workflows.md) | Writing a workflow body \u2014 triggers, steps, what an expression reads, the helpers, approvals and agent steps, and table checks. |\n| [docs/app_bindings.md](./docs/app_bindings.md) | The queries, workflows and agents an app binds \u2014 the query tree, typed inputs and outputs, and an agent's declaration. |\n| [docs/document_templates.md](./docs/document_templates.md) | Generating PDF/Excel/Word/email from reusable templates. |\n| [docs/knowledge_docs.md](./docs/knowledge_docs.md) | Authoring the workspace facts an agent can't guess; who can read a doc; catalog-then-stage retrieval. |\n| [docs/migration.md](./docs/migration.md) | What to DO when something an earlier CLI wrote to disk no longer matches what it does \u2014 local app projects are gone, and each verb that read one has a replacement. |\n| [README.md](./README.md) | Install, auth, and worked examples. |\n\n## Two surfaces, and the trap between them\n\n**`lotics tools` is not the CLI's capability list.** There are two disjoint surfaces:\n\n- **Tools** (`lotics tools`, `lotics run <tool>`) \u2014 the *agent tool registry*: what an agent, workflow,\n  or automation may call. Workspace data, templates, knowledge, admin.\n- **Commands** (`lotics --help` \xA7 COMMANDS) \u2014 the CLI's *own verbs*: auth and org/workspace scoping,\n  file upload and download, and those that touch a local file for an app \u2014 `model apply`,\n  `model check`, `model pull`, `app create --custom`, `app pull` and `app deploy`.\n\nSeveral capabilities exist **only** as commands and appear nowhere in `lotics tools` \u2014 downloading a\nfile is the one most often mistaken for missing. Concluding \"the platform can't do X\" from the tool\nlist alone is a mistake; check both.\n\n**`lotics <verb> --help` prints that verb's entries from \xA7 COMMANDS** (`lotics model --help`,\n`lotics file download --help`); `lotics report --help` prints the report frame. To find out whether\nsomething exists, read `lotics --help` \xA7 COMMANDS \u2014 the whole section, not a narrow grep.\n\n## Conventions that hold across every command\n\n- **Scope is resolved per invocation.** `LOTICS_ORG` / `LOTICS_WORKSPACE` (or `LOTICS_API_KEY`) scope a\n  single call without changing the active org or a directory pin \u2014 the safe way to touch one tenant\n  from a shell serving many. Every command that resolves a workspace echoes its target to **stderr**\n  (`lotics \u2192 <org> / <workspace>`); read it back before trusting a write. Resolution precedence is\n  in README \xA7 Organizations.\n- **A machine with no key can still sign in, and the sign-in never blocks you.** `lotics auth\n  login <email>` prints the page a person opens (also mailed) and the code that page must show,\n  records the request, and EXITS. They press Confirm whenever they get to it; the next command that\n  NEEDS a credential collects the key before doing its own work, so \"sign in\" costs you one command\n  and then re-running what you wanted. Never wrap it in a timeout waiting for a human \u2014 `--wait`\n  exists if you really want one blocking command, and killing that one is safe too (the request\n  survives and the next command claims it). A command run before Confirm exits 1 naming the page and\n  code again; once the 15 minutes are up it says to ask again. `lotics setup` falls into the same\n  flow by itself when the email it was given already has an account: it stops having created\n  nothing, and the SAME command run again carries on.\n- **A credential is either a SIGN-IN or an API KEY, and `logout` treats them differently.** A profile\n  from `auth login` / `auth signup` acts as the person who confirmed it and is theirs \u2014 `lotics auth\n  logout` revokes it server-side, and it lapses on its own after 90 idle days (each use pushes that\n  out). A profile from `auth api-key` holds a key an ADMIN issued. A key created in Settings carries\n  its OWN access \u2014 every app and table, or only the ones chosen on the key, so a listing that comes\n  back short is the key's reach, not a bug \u2014 while a key created FOR a person carries that\n  person's access and dies with their membership. Either is routinely also on a server and on\n  other machines, so logout only forgets it locally and says so; only an admin revokes it. A profile that states no kind (saved before the field existed) is resolved against the SERVER\n  and revoked only if the answer is a sign-in; a bare `--api-key` / `LOTICS_API_KEY` names no\n  profile to remove at all. Nothing is ever revoked on a guess \u2014 between two, the destructive one is\n  wrong. `lotics auth whoami` prints the kind, asking the server when the store cannot say.\n- **A key created in Settings never administers the organization, whatever its access.** The verbs\n  `docs/cli_reference.md` marks *admin only* split in two under a key: `workspace doctor`, which only\n  reads inside a workspace the key reaches, runs as before, while applying or pulling a model\n  (`model apply`, `model pull`, `setup`), managing people, sharing or\n  ownership, creating or deleting a workspace, changing workspace settings, setting credit limits,\n  reading the access log and publishing an app's API answer `403` and name the remedy: an admin signed in, so\n  `lotics auth login <email>` and run it again. A sign-in acts as that person and is refused none of\n  them. Do not retry a `403` with the same credential and do not ask for a wider key \u2014 no answer on\n  the key's own screen grants this.\n- **A 401 names its remedy \u2014 act on the hint, do not retry.** \"This credential expired / was\n  revoked / belongs to a member who is no longer active\" carries the one remedy that ends this\n  credential: run `lotics auth login <email>` for a sign-in, or ask the admin who issued it for a\n  new key. A credential minted before that was recorded carries BOTH, because nothing on the row\n  tells them apart \u2014 so on a box with no browser, take the second. Only an UNRECOGNIZED key gets\n  the generic \"Invalid or disabled API key\", and that one is generic on purpose, so re-sending it\n  teaches nothing. A `reason` rides on the body for a script to branch on, since the code stays\n  `unauthorized` for every 401.\n- **Large payloads bypass `ARG_MAX`** \u2014 `lotics run <tool> @args.json`, or piped stdin behind `-`. A leading `@` is\n  unambiguously a file path (JSON args start with `{`).\n- **stdout is the payload, stderr is the narration.** Progress, status lines, and the target echo go to\n  stderr; the result goes to stdout, so piping stays clean. `--json` switches stdout from the\n  agent-readable summary to the full structured object.\n- **Every tool is invoked one way \u2014 `lotics run <tool>`.** Including the ones that RUN something\n  (`run_app_workflow`, `run_app_agent`, `run_app_query`) and every one that changes an app\n  (`set_app_queries`, `set_app_workflow`, `set_app_agent`, `update_app`, `rollback_app`). A command\n  exists only for work that touches a local file.\n- **Every change to an app mints a version of it, and rolling back is the undo.** An apply, a\n  deploy, a single `set_app_*` or `remove_app_binding`: each is a new version, and `rollback_app` makes an\n  earlier one current again. It restores the app \u2014 never a table change or a row a workflow wrote,\n  so try a write on a throwaway record.\n- **Exit codes are assertable, and they report the WORK rather than the call.** `lotics run` exits\n  non-zero when a `run_app_workflow` or `run_app_agent` result's own envelope carries a failed\n  `status` (`error`/`failed`/`cancelled`, or `not_previewed`: a preview asked for and not given) \u2014 any other tool's top-level status is data and exits 0 \u2014\n  so `lotics run \u2026 && next-step` cannot walk past a refused run; `workspace doctor` exits non-zero on\n  findings. An unrecognized status exits 0 \u2014 the list is an allowlist of failure, so a status added\n  later never turns a working script red \u2014 and a parked run (`awaiting_input`) is not a failure.\n- **An app that PUBLISHES an API turns every later binding write into a release.** Publishing\n  snapshots what the app's queries, workflows and agents promise to callers outside it \u2014 a\n  customer's own site or server, which nobody here can redeploy. From then on an additive change\n  re-snapshots silently and a breaking one is REFUSED, naming each change; the tool's\n  `acknowledge_breaking_api_change` carries it out and snapshots the break as a new contract version.\n- **Exposure is per app, all or nothing** \u2014 a public share or a key reaches every alias an app\n  declares, so what outsiders may call is a second app over the same tables\n  ([docs/building_an_app.md](./docs/building_an_app.md) \xA7 7).\n- **`--print-created` / `--cleanup` on any call that reports `side_effects`.** The first prints the\n  records created plus a paste-ready cleanup plan and what cannot be auto-undone; the second runs\n  those deletes (records only \u2014 never files, integrations or notifications). Neither is a rollback.\n- **Text output is the default and is built for reading**; reach for `--json` only when a field is\n  needed programmatically.\n- **`lotics report '<json>'` is the channel for what nothing else records.** Reach for it\n  when the platform is genuinely missing something (a capability that does not exist \u2014 no\n  command ran), when a success was wrong (exited 0, wrong effect), or when an error did\n  not name the remedy \u2014 not for your own mistakes, which the logs already show.\n  **It is a frame, not a paragraph** \u2014 `{goal, actual, expected?, tried?, wanted?}`, because a log\n  reconstructs what you RAN and never what you WANTED, and that gap is the report. `goal` and\n  `actual` are required; there is no severity or category to pick. The\n  session's commands attach themselves \u2014 do not retype them. Run it bare for the full prompt; a\n  long one rides `@file.json` or an explicit `-` for stdin (bare NEVER reads stdin).\n- **`LOTICS_TELEMETRY=1` correlates a whole session** so the authoring loop's rough edges can be\n  found and fixed. Off by default; set it in the shell profile, not per command (each invocation is\n  its own process). It sends no arguments, no file contents, and no record data \u2014 see README\n  \xA7 Diagnostics.\n\n## Where this CLI is not the answer\n\n- **Editing an app in a local directory.** An app stated in a model is changed by applying the\n  model again; its bindings through their `set_app_*` tools; a custom-code app's code by deploying\n  its directory again. Nothing reads a local copy of a live app back.\n- **OAuth connections.** Attaching a connected account is web-only; the CLI can list them.\n";
@@ -46661,10 +46661,10 @@ var filters_default = '# Filters \u2014 choosing records by their fields\n\nOne
 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.\n\n## Values by type\n\n| Type | Value |\n|---|---|\n| `text` | `"hello"` |\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| `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` | `["opt_\u2026"]` |\n| `select_member` | `["mbr_\u2026"]` |\n| `select_record_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`, `select_member`, `select_record_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 `"opt_\u2026"` is accepted and wrapped. A single\n  `select_member` takes a bare `"mbr_\u2026"` the same way.\n- `select_record_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- Two options on a single-select, or two members on a single `select_member`, are refused.\n- `update_records`\' `add_to`, `remove_from` and `replace` take arrays of the same items: `opt_` keys\n  for a select, member ids for a `select_member`, record ids for a `select_record_link`, file ids for\n  `files`.\n';
 // docs/workflows.md
-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\nThe same grammar serves an automation and an app\'s workflow, and the expressions of a table check.\nOnly an automation\'s source opens with a trigger declaration; an app workflow takes its trigger from\nthe app that calls it.\n\n## Triggers\n\nAn automation answers an event outside the records: a schedule, a webhook, an inbound email.\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\nA whole automation:\n\n```\non({ type: "recurring_schedule", cron_expression: "0 9 * * MON" });\n\nconst open = await query_records({\n  table_id: "tbl_tickets",\n  filters: { node_type: "condition", field_key: "fld_status", operator: "has_any_of", value: ["opt_open"] },\n});\nawait send_email({\n  to: "team@example.com",\n  subject: "Weekly digest",\n  body: `${size(open.records)} tickets open as of ${formatDate(now(), "yyyy-MM-dd")}.`,\n});\n```\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 a connection\'s tools too, each a workflow step (`bkav_submit_invoices`, `gmail_send_email`, \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, tools, 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| wait for an approval | `await wait_for_approval({ approvers: <expr>, prompt: <expr> });` \u2014 see **Waiting for an approval** |\n| return | `return({ status: "success" \\| "error", message: <expr>, field_errors: { ... }? });` |\n| validate | `validate({ checks: [{ fail_when: <expr>, field_key: "...", message: <expr> }, ...] });` |\n\nEvery step\'s inputs, the values each takes and its answer: `lotics tools <name>` prints them; the steps only a body\nruns \u2014 a connection\'s, a mail\'s \u2014 are all in `workflow_steps`. A person connects a service in Lotics under\nSettings \u2192 Connections; a step names that connection by its `connected_account_id`.\n\n`return` is a call, not a JavaScript `return` statement. `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 `fld_` key 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\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. Tool names, the reserved\nroots, `linked` and `_s` followed by digits cannot be bound.\n\n### Waiting for an approval\n\n`wait_for_approval` is the wait worth binding \u2014 `wait` and `wait_for_event` carry nothing to read.\nBind it to branch on the decision:\n\n```\nconst approval = await wait_for_approval({\n  approvers: trigger.app_workflow.inputs.approvers,\n  prompt: `Approve this quote?`,\n});\n\nif (approval.status == "approved") {\n  // the approved path\n} else {\n  // the rejected or timed-out path; approval.decision_comment says why\n}\n```\n\nIt resolves to `{ status: "approved" | "rejected" | "timed_out", decided_by: MemberId | null,\ndecided_at: ISO string, decision_comment: string | null }`.\n\n`approvers` takes a bare member id (`"mbr_\u2026"`), a bare group id (`"grp_\u2026"`) or a full principal\n(`{ type: "member_group", id: "grp_x" }`), alone or in a list \u2014 so a member field\'s value passes as it\nis.\n\n### An agent step\n\n`const x = await agent({ instructions, input, tools, model, output });` runs a model with tools as one\nstep \u2014 summarize a record, classify, draft text.\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` or `tools`, which are fixed literals and read no binding.\n- `tools` \u2014 the names of the tools it may call.\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. The agent\'s own tool calls are not readable.\n\n## Keys, not names\n\n1. **Fields and options are named by key.** A field reads as `record["fld_status"]`, an option as\n   `"opt_done"`, a linked field as `linked(record["fld_customer"])[0]["fld_name"]`. `get_table` lists\n   each field\'s `key` and each option\'s `key`; a display name is refused at save with the key to use.\n2. **`==` against a multi-select means "includes".** `record["fld_tags"] == "opt_urgent"` on a\n   multi-select is stored as `includes(record["fld_tags"], "opt_urgent")`; either spelling works.\n3. **Text renders labels.** Inside a template or a text tool input, a select, member or link value\n   renders its display text: `` `${record["fld_status"]}` `` writes "Done", not `opt_done`.\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["fld_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.fld_x` and `record["fld_x"]` read a field; `[n]` reads a list\'s n-th item.\n- A path may start at an awaited call: `(await get_record({...})).data["fld_x"]`. It may not start at a\n  helper\'s result \u2014 `first(found.records).id` is refused; bind `first(found.records)`, then read it.\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 or member as its key or null, a link as its ids. (The record\n  tools called outside a workflow return the stored arrays instead.)\n- `linked(record["fld_link"])[n]["fld_x"]` fetches the n-th linked row and reads a field of it; bare\n  `linked(record["fld_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?.["fld_link"])[0]`.\n- `changes["fld_link"]?.next_value` is the same list of ids; `linked()` over a change is refused \u2014\n  read `linked(record["fld_link"])` or `linked(prev_record["fld_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 `${...}`.\n- Destructuring \u2014 `const { fld_status, fld_name } = record;` binds each name. Renames\n  (`{ fld_status: s }`), quoted keys (`{ "fld_ref": ref }`), array patterns with holes\n  (`const [first, , third] = xs;`) and defaults (`{ fld_note = "" }`, which apply on null too) work on\n  `const`, `let` and `for (const { id } of rows)`. 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). Refused inside a tool input: bind the\n  merged value first and pass the binding.\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` is the same value as `null`. `=== undefined` and `!== undefined` are refused, since they\n  cannot tell a missing key from null: test `isNull(x)`, or `includes(keys(o), "k")` for whether a key\n  was sent.\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>) { return <expr>; }` \u2014 top level only, expanded at every call (a call\n  may come before it). Every parameter needs a default, which gives it its type; the body is one\n  `return <expr>;` reading only its parameters, helpers and the reserved roots \u2014 never the caller\'s\n  names, nor `index`. No recursion; a function never called is refused. A body read back shows the\n  expression at each call, not the `function`.\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`, `wait_for_event` or `wait_for_approval`.\n\n**Refused:** regex, `new`, `typeof`, `instanceof`, `in`, `delete`, `void`, rest elements, computed keys,\nclasses, `throw`, `import`, `export`, and a function as a value (`const f = (x) => ...`).\n\n## Helpers\n\nCalled as `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`, `toString`, `typeOf`, `parseJson`, `toJson`\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`\n- **Text**: `upper`, `lower`, `capitalize`, `trim`, `contains`, `startsWith`, `endsWith`, `replace`,\n  `replaceAll`, `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- **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`,\n  `differenceInCalendarDays`, `differenceInHours`, `differenceInMinutes`, `isBefore`, `isAfter`,\n  `isSameDay`, `isToday`, `isWithinRange`\n- **Other**: `formatCurrency(amount, locale, currency)`, `randomNumber(len)`,\n  `randomAlphaNumeric(len)`, `sample(items)` (a random item)\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>`, `(x) => { return <expr>; }` or `function (x) { return <expr>; }`;\nseveral statements, `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: "tbl_parties" });\nconst lines = await query_records({ table_id: "tbl_sheet_lines" });\nconst byCode = groupBy(parties.records, (p) => p.data["fld_code"] ?? "");\nconst holders = lines.records.map((line) => ({\n  line: line.id,\n  parties: (byCode[line.data["fld_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` and `create_records`\' `records`:\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["fld_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\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: "tbl_customers",\n  filters: { node_type: "condition", field_key: "fld_name", operator: "equals", value: "ACME Corp" },\n});\nconst customer = first(found.records);\nconst order = await get_record({ table_id: "tbl_orders", record_id: trigger.app_workflow.inputs.order_id });\n\nif (customer && includes(order.data["fld_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\n`import_rows`, a workflow step, matches those rows to a table by a key and writes what differs. `match`\nnames the fields that identify a row, compared as trimmed text with case ignored: a row matching no live\nrow is added, one matching a row changes only the cells that differ, and one that changes nothing is\ncounted and not written, so the same file run twice writes nothing the second time. `values` holds a\nrow\'s cells by field key, as `create_records` takes them; a key the row omits is left as the table holds\nit, and `null` is an empty cell, which differs from a filled one as any other value does.\n\nA `match` field may also be a link field holding one row, compared by the row linked: lines keyed by\ntheir parent and a line number state `match: ["fld_invoice", "fld_line"]`, the parent given as its\nrecord id or as `{ lookup: "<text>" }`.\n\nWhat the step is not certain of is held \u2014 answered with why, and not written: a row carrying `hold`\n(its text is the message); a row whose key several live rows carry, or an earlier row of the same call;\na row the table\'s checks refuse, or whose row is locked; with `create: false`, a row matching none. A\nheld row never fails the step, and the rows beside it are written. A row whose key names a row outside\nthe rows the run may write is held `refused` with nothing of that row: no `record_id`, no `changes`.\n\nThe step removes no row, and a row the source leaves out is never touched. A row carrying\n`remove: true`, with its key in `values`, proposes moving the row its key names to the trash: it is\nalways held, whatever `create` and `conflicts` say, and a key naming no row is counted unchanged.\n\n`conflicts` states what a matched row does where a live cell holds another value: `"hold"` writes the\nrow\'s empty cells and holds the differing ones, `"overwrite"` writes over them, `"fill_empty"` leaves\nthem. `conflicts.fields` gives one field its own. A number and the field its unit or currency is read\nfrom on each row are one cell, under the number\'s policy: both are written, or both held.\n\nA link cell takes `{ lookup: "<text>" }` in place of record ids: the linked row is the one row holding\nthat text in the linked table\'s unique or autonumber field, else the one titled it, among the rows the\nrun reads of that table. A text naming no row, or several, holds the row, and the rows it could be are\nanswered beside it. A link holding many rows takes a list, `[{ lookup: "<text>" }, \u2026]`: each text is\nresolved by itself.\n\nThe step keeps nothing of its own: its answer is everything it did. `written` lists each record it\nwrote \u2014 a changed one with each field from old to new as text, a created one by its id alone \u2014 and\n`held_rows` each row it held: its `kind`, `reason` and `message`, the `record_id` of the row it matched,\nits `key`, the `changes` it would make, the `links` it could not resolve with their `candidates`, and\n`values` \u2014 its key and the cells it would write, as the call gave them. A later call given a held row\'s\n`values` under `conflicts: { default: "overwrite" }` writes it. Both lists are read under the run\'s own\nreach of the table, and a workflow hands its caller only what it returns. Two calls matching one table\nby the same fields take turns, so the second matches the rows the first added. The step\'s entry in\n`workflow_steps` states its bounds.\n\n`undo_record_changes`, a workflow step, puts back what one run wrote on records of a table. It takes the\ntable, up to 500 record ids and the run \u2014 what `runtime.execution_id` held in it. A field goes back\nwhere the row still holds what the run wrote. A row the run created goes to the trash\nwhere nothing else has written it or linked a row to it since; in a table where a workflow writes each\nnew row, every row created reads as written since, and is kept. A row the run moved to the trash comes\nback where nothing has touched it since, without the links to it that its removal took off other rows.\nA row the run brought back from the trash stays out of it. A write of the run that was itself an undo is\nnot put back. What the step leaves as it stands is answered in `kept`, one entry a record and reason:\nsomething changed it since, it is outside the rows the member may write, the table refused the write,\nwhat the run wrote on it cannot be read, or the run brought it back from the trash.\n\nTwo more workflow steps read and settle one record\'s saves: `get_record_activity`, a workflow step,\nlists them, and `undo_record_change`, a workflow step, puts one back. What they read is the run\'s to\nread; inside an app\'s workflow it is what the app reads \u2014 the fields of the app\'s entity over the table,\na record that entity\'s own read reaches. An undo, of one save or of a run\'s writes, is the own save of the\nmember the run acts for \u2014 whoever started the app\'s workflow, pressed the button, or made the write a\ntable\'s workflow followed: that member holds the table\'s write as the step runs, each row within the\nrows they may write, and the table\'s locks, checks and write rules answer for them. A run that acts for\nno member \u2014 a schedule\'s, a public visitor\'s \u2014 reads, and its undos are refused.\n\nWhat a business keeps of an import \u2014 the file, its counts, the lines waiting for a person \u2014 is rows of\nits own tables, written by the workflow that ran the step. A garden centre brings its grower\'s price\nsheet into its plants, and keeps each sheet and its lines. A line names its plant through a link\nholding many rows: one holding a single row would make the line that plant\'s own, and a plant its\nlines belong to is not moved to the trash.\n\nThese tables are shown beside the plants, in the same app: the sheets as a log of the plants\' register\n(`logs`, `lotics docs model/logs`), a sheet\'s lines on the page it opens. A line keeping what a cell held\nand what it holds now in two fields reads one against the other (`compare`, `lotics docs model/blocks`).\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 imported = await import_rows({ // a workflow step\n  table_id: "tbl_plants",\n  match: ["fld_code"],\n  rows: sheet.rows.map((row, at) => ({\n    line: at + 2,\n    hold: isNull(row["Price"]) ? "The sheet states no price" : null,\n    values: {\n      fld_code: toString(row["Code"]),\n      fld_name: toString(row["Name"]),\n      fld_price: toNumber(row["Price"]),\n    },\n  })),\n});\n\nconst kept = await create_records({\n  table_id: "tbl_price_sheets",\n  records: [{\n    fld_file: [trigger.app_workflow.inputs.file],\n    fld_run: runtime.execution_id,\n    fld_read: imported.read,\n    fld_created: imported.created,\n    fld_changed: imported.changed,\n    fld_held: imported.held,\n  }],\n});\nconst sheet_id = kept.record_ids[0];\n\nfor (let start = 0; start < size(imported.written); start += 50) {\n  await create_records({\n    table_id: "tbl_sheet_lines",\n    records: slice(imported.written, start, start + 50).map((one) => ({\n      fld_sheet: [sheet_id],\n      fld_plant: [one.record_id],\n      fld_line: one.line,\n      fld_outcome: one.kind,\n      fld_changes: join(one.changes.map((change) => `${change.label}: ${change.before ?? "\u2014"} \u2192 ${change.after ?? "\u2014"}`), "; "),\n    })),\n  });\n}\nfor (let start = 0; start < size(imported.held_rows); start += 50) {\n  await create_records({\n    table_id: "tbl_sheet_lines",\n    records: slice(imported.held_rows, start, start + 50).map((one) => ({\n      fld_sheet: [sheet_id],\n      fld_plant: isNull(one.record_id) ? [] : [one.record_id],\n      fld_line: one.line,\n      fld_outcome: "held",\n      fld_why: one.message,\n      fld_code: one.key["fld_code"],\n      fld_name: toString(one.values["fld_name"]),\n      fld_price: toNumber(one.values["fld_price"]),\n      fld_changes: join(one.changes.map((change) => `${change.label}: ${change.before ?? "\u2014"} \u2192 ${change.after ?? "\u2014"}`), "; "),\n    })),\n  });\n}\n\nreturn({ status: "success", message: `${imported.created} added, ${imported.changed} changed, ${imported.held} held` });\n```\n\nA held line keeps the `values` the step answered for it \u2014 its key and each cell it would write \u2014 in\nfields of its own. It is applied by the act on it, whose workflow hands the step those values again and\nlets it write over what the plant holds. A cell the line holds none of is left out, so a held line\nnever empties a cell of the plant:\n\n```\nconst line = await get_record({ table_id: "tbl_sheet_lines", record_id: trigger.app_workflow.inputs.record_id });\nconst values = {\n  fld_code: line.data["fld_code"],\n  ...(isEmpty(line.data["fld_name"]) ? {} : { fld_name: line.data["fld_name"] }),\n  ...(isNull(line.data["fld_price"]) ? {} : { fld_price: line.data["fld_price"] }),\n};\n\nconst applied = await import_rows({ // a workflow step\n  table_id: "tbl_plants",\n  match: ["fld_code"],\n  conflicts: { default: "overwrite" },\n  rows: [{ values }],\n});\nif (applied.held > 0) {\n  return({ status: "error", message: applied.held_rows[0].message });\n}\n\nawait update_records({ table_id: "tbl_sheet_lines", record_ids: [line.id], set: { fld_outcome: "applied" } });\nreturn({ status: "success", message: "Applied." });\n```\n\nA sheet is undone by the act on it, whose workflow hands the step the run the sheet kept and the\nplants its lines name, 500 at a time:\n\n```\nconst sheet = await get_record({ table_id: "tbl_price_sheets", record_id: trigger.app_workflow.inputs.record_id });\n\nlet reverted = 0;\nlet left = 0;\nlet offset = 0;\nlet more = true;\nwhile (more) {\n  const lines = await query_records({\n    table_id: "tbl_sheet_lines",\n    filters: {\n      logic: "and",\n      children: [\n        { field_key: "fld_sheet", operator: "has_any_of", value: [sheet.id] },\n        { field_key: "fld_outcome", operator: "is_any_of", value: ["created", "changed"] },\n      ],\n    },\n    pagination: { offset, limit: 500 },\n  });\n  if (size(lines.records) > 0) {\n    const undone = await undo_record_changes({ // a workflow step\n      table_id: "tbl_plants",\n      record_ids: flatten(lines.records.map((line) => line.data["fld_plant"])),\n      workflow_execution_id: toString(sheet.data["fld_run"]),\n    });\n    reverted += undone.reverted;\n    left += size(undone.kept);\n  }\n  more = size(lines.records) == 500;\n  offset += 500;\n}\n\nreturn({ status: "success", message: `${reverted} put back, ${left} left as they stand` });\n```\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: { updates: [{ record_id, sha }], creates: [{ key, sha }] }`, 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, so the workflow step `undo_record_changes` with the run\'s id takes back both. 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: "tbl_notes",\n  filters: { field_key: "fld_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["fld_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"]) == one.note?.data["fld_amount"],\n  data: { fld_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: "tbl_notes", creates: [], updates, unplaced } },\n});\n```\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\nOn the CLI or in chat, `set_table_check` creates one, or changes one when given its `table_check_id`\nand only the parts that change, and `remove_table_check` removes one. `get_table` lists a table\'s\nchecks in the source they are written in.\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_id, filter, limit }`, the filter as `query_records` takes it, `limit` from 1 to 50 (50 when left out). A filter value may read the record. |\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_key` | optional; the field the refusal is shown under |\n\nEvery expression is written in the grammar above 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.\n- `lookups.<name>` \u2014 in `fail_when` and `message`, the rows that lookup read.\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), and `now()`.\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 lookup reads with the access of the member who last saved the check, so saving one requires reading\nevery table its lookups read. It reads committed rows: two writes at the same moment can each pass a\ncheck the other would fail, so values no two rows may share are the table\'s `unique`, not a check.\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. 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```\n{\n  "table_id": "tbl_orders",\n  "name": "One open order per reference",\n  "on": ["create", "update"],\n  "when": "isNull(record[\\"fld_closed_at\\"])",\n  "lookups": {\n    "same_ref": "{ table_id: \\"tbl_orders\\", filter: { node_type: \\"group\\", logic: \\"and\\", children: [ { field_key: \\"fld_ref\\", operator: \\"equals\\", value: record[\\"fld_ref\\"] }, { field_key: \\"fld_closed_at\\", operator: \\"is_empty\\" } ] }, limit: 2 }"\n  },\n  "fail_when": "some(lookups.same_ref, (r) => r.id != record.id)",\n  "message": "\\"An open order already has this reference.\\"",\n  "field_key": "fld_ref"\n}\n```\n';
+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\nThe same grammar serves an automation and an app\'s workflow, and the expressions of a table check.\nOnly an automation\'s source opens with a trigger declaration; an app workflow takes its trigger from\nthe app that calls it.\n\n## Triggers\n\nAn automation answers an event outside the records: a schedule, a webhook, an inbound email.\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\nA whole automation:\n\n```\non({ type: "recurring_schedule", cron_expression: "0 9 * * MON" });\n\nconst open = await query_records({\n  table_id: "tbl_tickets",\n  filters: { node_type: "condition", field_key: "fld_status", operator: "has_any_of", value: ["opt_open"] },\n});\nawait send_email({\n  to: "team@example.com",\n  subject: "Weekly digest",\n  body: `${size(open.records)} tickets open as of ${formatDate(now(), "yyyy-MM-dd")}.`,\n});\n```\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 a connection\'s tools too, each a workflow step (`bkav_submit_invoices`, `gmail_send_email`, \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, tools, 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| wait for an approval | `await wait_for_approval({ approvers: <expr>, prompt: <expr> });` \u2014 see **Waiting for an approval** |\n| return | `return({ status: "success" \\| "error", message: <expr>, field_errors: { ... }? });` |\n| validate | `validate({ checks: [{ fail_when: <expr>, field_key: "...", message: <expr> }, ...] });` |\n\nEvery step\'s inputs, the values each takes and its answer: `lotics tools <name>` prints them; the steps only a body\nruns \u2014 a connection\'s, a mail\'s \u2014 are all in `workflow_steps`. A person connects a service in Lotics under\nSettings \u2192 Connections; a step names that connection by its `connected_account_id`.\n\n`return` is a call, not a JavaScript `return` statement. `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 `fld_` key 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\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. Tool names, the reserved\nroots, `linked` and `_s` followed by digits cannot be bound.\n\n### Waiting for an approval\n\n`wait_for_approval` is the wait worth binding \u2014 `wait` and `wait_for_event` carry nothing to read.\nBind it to branch on the decision:\n\n```\nconst approval = await wait_for_approval({\n  approvers: trigger.app_workflow.inputs.approvers,\n  prompt: `Approve this quote?`,\n});\n\nif (approval.status == "approved") {\n  // the approved path\n} else {\n  // the rejected or timed-out path; approval.decision_comment says why\n}\n```\n\nIt resolves to `{ status: "approved" | "rejected" | "timed_out", decided_by: MemberId | null,\ndecided_at: ISO string, decision_comment: string | null }`.\n\n`approvers` takes a bare member id (`"mbr_\u2026"`), a bare group id (`"grp_\u2026"`) or a full principal\n(`{ type: "member_group", id: "grp_x" }`), alone or in a list \u2014 so a member field\'s value passes as it\nis.\n\n### An agent step\n\n`const x = await agent({ instructions, input, tools, model, output });` runs a model with tools as one\nstep \u2014 summarize a record, classify, draft text.\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` or `tools`, which are fixed literals and read no binding.\n- `tools` \u2014 the names of the tools it may call.\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. The agent\'s own tool calls are not readable.\n\n## Keys, not names\n\n1. **Fields and options are named by key.** A field reads as `record["fld_status"]`, an option as\n   `"opt_done"`, a linked field as `linked(record["fld_customer"])[0]["fld_name"]`. `get_table` lists\n   each field\'s `key` and each option\'s `key`; a display name is refused at save with the key to use.\n2. **`==` against a multi-select means "includes".** `record["fld_tags"] == "opt_urgent"` on a\n   multi-select is stored as `includes(record["fld_tags"], "opt_urgent")`; either spelling works.\n3. **Text renders labels.** Inside a template or a text tool input, a select, member or link value\n   renders its display text: `` `${record["fld_status"]}` `` writes "Done", not `opt_done`.\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["fld_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.fld_x` and `record["fld_x"]` read a field; `[n]` reads a list\'s n-th item.\n- A path may start at an awaited call: `(await get_record({...})).data["fld_x"]`. It may not start at a\n  helper\'s result \u2014 `first(found.records).id` is refused; bind `first(found.records)`, then read it.\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 or member as its key or null, a link as its ids. (The record\n  tools called outside a workflow return the stored arrays instead.)\n- `linked(record["fld_link"])[n]["fld_x"]` fetches the n-th linked row and reads a field of it; bare\n  `linked(record["fld_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?.["fld_link"])[0]`.\n- `changes["fld_link"]?.next_value` is the same list of ids; `linked()` over a change is refused \u2014\n  read `linked(record["fld_link"])` or `linked(prev_record["fld_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 `${...}`.\n- Destructuring \u2014 `const { fld_status, fld_name } = record;` binds each name. Renames\n  (`{ fld_status: s }`), quoted keys (`{ "fld_ref": ref }`), array patterns with holes\n  (`const [first, , third] = xs;`) and defaults (`{ fld_note = "" }`, which apply on null too) work on\n  `const`, `let` and `for (const { id } of rows)`. 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). Refused inside a tool input: bind the\n  merged value first and pass the binding.\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` is the same value as `null`. `=== undefined` and `!== undefined` are refused, since they\n  cannot tell a missing key from null: test `isNull(x)`, or `includes(keys(o), "k")` for whether a key\n  was sent.\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>) { return <expr>; }` \u2014 top level only, expanded at every call (a call\n  may come before it). Every parameter needs a default, which gives it its type; the body is one\n  `return <expr>;` reading only its parameters, helpers and the reserved roots \u2014 never the caller\'s\n  names, nor `index`. No recursion; a function never called is refused. A body read back shows the\n  expression at each call, not the `function`.\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`, `wait_for_event` or `wait_for_approval`.\n\n**Refused:** regex, `new`, `typeof`, `instanceof`, `in`, `delete`, `void`, rest elements, computed keys,\nclasses, `throw`, `import`, `export`, and a function as a value (`const f = (x) => ...`).\n\n## Helpers\n\nCalled as `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`, `toString`, `typeOf`, `parseJson`, `toJson`\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`\n- **Text**: `upper`, `lower`, `capitalize`, `trim`, `contains`, `startsWith`, `endsWith`, `replace`,\n  `replaceAll`, `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- **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`,\n  `differenceInCalendarDays`, `differenceInHours`, `differenceInMinutes`, `isBefore`, `isAfter`,\n  `isSameDay`, `isToday`, `isWithinRange`\n- **Other**: `formatCurrency(amount, locale, currency)`, `randomNumber(len)`,\n  `randomAlphaNumeric(len)`, `sample(items)` (a random item)\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>`, `(x) => { return <expr>; }` or `function (x) { return <expr>; }`;\nseveral statements, `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: "tbl_parties" });\nconst lines = await query_records({ table_id: "tbl_sheet_lines" });\nconst byCode = groupBy(parties.records, (p) => p.data["fld_code"] ?? "");\nconst holders = lines.records.map((line) => ({\n  line: line.id,\n  parties: (byCode[line.data["fld_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` and `create_records`\' `records`:\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["fld_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\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: "tbl_customers",\n  filters: { node_type: "condition", field_key: "fld_name", operator: "equals", value: "ACME Corp" },\n});\nconst customer = first(found.records);\nconst order = await get_record({ table_id: "tbl_orders", record_id: trigger.app_workflow.inputs.order_id });\n\nif (customer && includes(order.data["fld_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\n`import_rows`, a workflow step, matches those rows to a table by a key and writes what differs. `match`\nnames the fields that identify a row, compared as trimmed text with case ignored: a row matching no live\nrow is added, one matching a row changes only the cells that differ, and one that changes nothing is\ncounted and not written, so the same file run twice writes nothing the second time. `values` holds a\nrow\'s cells by field key, as `create_records` takes them; a key the row omits is left as the table holds\nit, and `null` is an empty cell, which differs from a filled one as any other value does.\n\nA `match` field may also be a link field holding one row, compared by the row linked: lines keyed by\ntheir parent and a line number state `match: ["fld_invoice", "fld_line"]`, the parent given as its\nrecord id or as `{ lookup: "<text>" }`.\n\nWhat the step is not certain of is held \u2014 answered with why, and not written: a row carrying `hold`\n(its text is the message); a row whose key several live rows carry, or an earlier row of the same call;\na row the table\'s checks refuse, or whose row is locked; with `create: false`, a row matching none. A\nheld row never fails the step, and the rows beside it are written. A row whose key names a row outside\nthe rows the run may write is held `refused` with nothing of that row: no `record_id`, no `changes`.\n\nThe step removes no row, and a row the source leaves out is never touched. A row carrying\n`remove: true`, with its key in `values`, proposes moving the row its key names to the trash: it is\nalways held, whatever `create` and `conflicts` say, and a key naming no row is counted unchanged.\n\n`conflicts` states what a matched row does where a live cell holds another value: `"hold"` writes the\nrow\'s empty cells and holds the differing ones, `"overwrite"` writes over them, `"fill_empty"` leaves\nthem. `conflicts.fields` gives one field its own. A number and the field its unit or currency is read\nfrom on each row are one cell, under the number\'s policy: both are written, or both held.\n\nA link cell takes `{ lookup: "<text>" }` in place of record ids: the linked row is the one row holding\nthat text in the linked table\'s unique or autonumber field, else the one titled it, among the rows the\nrun reads of that table. A text naming no row, or several, holds the row, and the rows it could be are\nanswered beside it. A link holding many rows takes a list, `[{ lookup: "<text>" }, \u2026]`: each text is\nresolved by itself.\n\nThe step keeps nothing of its own: its answer is everything it did. `written` lists each record it\nwrote \u2014 a changed one with each field from old to new as text, a created one by its id alone \u2014 and\n`held_rows` each row it held: its `kind`, `reason` and `message`, the `record_id` of the row it matched,\nits `key`, the `changes` it would make, the `links` it could not resolve with their `candidates`, and\n`values` \u2014 its key and the cells it would write, as the call gave them. A later call given a held row\'s\n`values` under `conflicts: { default: "overwrite" }` writes it. Both lists are read under the run\'s own\nreach of the table, and a workflow hands its caller only what it returns. Two calls matching one table\nby the same fields take turns, so the second matches the rows the first added. The step\'s entry in\n`workflow_steps` states its bounds.\n\n`undo_record_changes`, a workflow step, puts back what one run wrote on records of a table. It takes the\ntable, up to 500 record ids and the run \u2014 what `runtime.execution_id` held in it. A field goes back\nwhere the row still holds what the run wrote. A row the run created goes to the trash\nwhere nothing else has written it or linked a row to it since; in a table where a workflow writes each\nnew row, every row created reads as written since, and is kept. A row the run moved to the trash comes\nback where nothing has touched it since, without the links to it that its removal took off other rows.\nA row the run brought back from the trash stays out of it. A write of the run that was itself an undo is\nnot put back. What the step leaves as it stands is answered in `kept`, one entry a record and reason:\nsomething changed it since, it is outside the rows the member may write, the table refused the write,\nwhat the run wrote on it cannot be read, or the run brought it back from the trash.\n\nTwo more workflow steps read and settle one record\'s saves: `get_record_activity`, a workflow step,\nlists them, and `undo_record_change`, a workflow step, puts one back. What they read is the run\'s to\nread; inside an app\'s workflow it is what the app reads \u2014 the fields of the app\'s entity over the table,\na record that entity\'s own read reaches. An undo, of one save or of a run\'s writes, is the own save of the\nmember the run acts for \u2014 whoever started the app\'s workflow, pressed the button, or made the write a\ntable\'s workflow followed: that member holds the table\'s write as the step runs, each row within the\nrows they may write, and the table\'s locks, checks and write rules answer for them. A run that acts for\nno member \u2014 a schedule\'s, a public visitor\'s \u2014 reads, and its undos are refused.\n\nWhat a business keeps of an import \u2014 the file, its counts, the lines waiting for a person \u2014 is rows of\nits own tables, written by the workflow that ran the step. A garden centre brings its grower\'s price\nsheet into its plants, and keeps each sheet and its lines. A line names its plant through a link\nholding many rows: one holding a single row would make the line that plant\'s own, and a plant its\nlines belong to is not moved to the trash.\n\nThese tables are shown beside the plants, in the same app: the sheets as a log of the plants\' register\n(`logs`, `lotics docs model/logs`), a sheet\'s lines on the page it opens. A line keeping what a cell held\nand what it holds now in two fields reads one against the other (`compare`, `lotics docs model/blocks`).\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 imported = await import_rows({ // a workflow step\n  table_id: "tbl_plants",\n  match: ["fld_code"],\n  rows: sheet.rows.map((row, at) => ({\n    line: at + 2,\n    hold: isNull(row["Price"]) ? "The sheet states no price" : null,\n    values: {\n      fld_code: toString(row["Code"]),\n      fld_name: toString(row["Name"]),\n      fld_price: toNumber(row["Price"]),\n    },\n  })),\n});\n\nconst kept = await create_records({\n  table_id: "tbl_price_sheets",\n  records: [{\n    fld_file: [trigger.app_workflow.inputs.file],\n    fld_run: runtime.execution_id,\n    fld_read: imported.read,\n    fld_created: imported.created,\n    fld_changed: imported.changed,\n    fld_held: imported.held,\n  }],\n});\nconst sheet_id = kept.record_ids[0];\n\nfor (let start = 0; start < size(imported.written); start += 50) {\n  await create_records({\n    table_id: "tbl_sheet_lines",\n    records: slice(imported.written, start, start + 50).map((one) => ({\n      fld_sheet: [sheet_id],\n      fld_plant: [one.record_id],\n      fld_line: one.line,\n      fld_outcome: one.kind,\n      fld_changes: join(one.changes.map((change) => `${change.label}: ${change.before ?? "\u2014"} \u2192 ${change.after ?? "\u2014"}`), "; "),\n    })),\n  });\n}\nfor (let start = 0; start < size(imported.held_rows); start += 50) {\n  await create_records({\n    table_id: "tbl_sheet_lines",\n    records: slice(imported.held_rows, start, start + 50).map((one) => ({\n      fld_sheet: [sheet_id],\n      fld_plant: isNull(one.record_id) ? [] : [one.record_id],\n      fld_line: one.line,\n      fld_outcome: "held",\n      fld_why: one.message,\n      fld_code: one.key["fld_code"],\n      fld_name: toString(one.values["fld_name"]),\n      fld_price: toNumber(one.values["fld_price"]),\n      fld_changes: join(one.changes.map((change) => `${change.label}: ${change.before ?? "\u2014"} \u2192 ${change.after ?? "\u2014"}`), "; "),\n    })),\n  });\n}\n\nreturn({ status: "success", message: `${imported.created} added, ${imported.changed} changed, ${imported.held} held` });\n```\n\nA held line keeps the `values` the step answered for it \u2014 its key and each cell it would write \u2014 in\nfields of its own. It is applied by the act on it, whose workflow hands the step those values again and\nlets it write over what the plant holds. A cell the line holds none of is left out, so a held line\nnever empties a cell of the plant:\n\n```\nconst line = await get_record({ table_id: "tbl_sheet_lines", record_id: trigger.app_workflow.inputs.record_id });\nconst values = {\n  fld_code: line.data["fld_code"],\n  ...(isEmpty(line.data["fld_name"]) ? {} : { fld_name: line.data["fld_name"] }),\n  ...(isNull(line.data["fld_price"]) ? {} : { fld_price: line.data["fld_price"] }),\n};\n\nconst applied = await import_rows({ // a workflow step\n  table_id: "tbl_plants",\n  match: ["fld_code"],\n  conflicts: { default: "overwrite" },\n  rows: [{ values }],\n});\nif (applied.held > 0) {\n  return({ status: "error", message: applied.held_rows[0].message });\n}\n\nawait update_records({ table_id: "tbl_sheet_lines", record_ids: [line.id], set: { fld_outcome: "applied" } });\nreturn({ status: "success", message: "Applied." });\n```\n\nA sheet is undone by the act on it, whose workflow hands the step the run the sheet kept and the\nplants its lines name, 500 at a time:\n\n```\nconst sheet = await get_record({ table_id: "tbl_price_sheets", record_id: trigger.app_workflow.inputs.record_id });\n\nlet reverted = 0;\nlet left = 0;\nlet offset = 0;\nlet more = true;\nwhile (more) {\n  const lines = await query_records({\n    table_id: "tbl_sheet_lines",\n    filters: {\n      logic: "and",\n      children: [\n        { field_key: "fld_sheet", operator: "has_any_of", value: [sheet.id] },\n        { field_key: "fld_outcome", operator: "is_any_of", value: ["created", "changed"] },\n      ],\n    },\n    pagination: { offset, limit: 500 },\n  });\n  if (size(lines.records) > 0) {\n    const undone = await undo_record_changes({ // a workflow step\n      table_id: "tbl_plants",\n      record_ids: flatten(lines.records.map((line) => line.data["fld_plant"])),\n      workflow_execution_id: toString(sheet.data["fld_run"]),\n    });\n    reverted += undone.reverted;\n    left += size(undone.kept);\n  }\n  more = size(lines.records) == 500;\n  offset += 500;\n}\n\nreturn({ status: "success", message: `${reverted} put back, ${left} left as they stand` });\n```\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: { updates: [{ record_id, sha }], creates: [{ key, sha }] }`, 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, so the workflow step `undo_record_changes` with the run\'s id takes back both. 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: "tbl_notes",\n  filters: { field_key: "fld_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["fld_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"]) == one.note?.data["fld_amount"],\n  data: { fld_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: "tbl_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. 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.\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: "tbl_release_orders",\n  match: { fld_number: inputs.number },\n  set: { fld_note: "Read from the paper" },\n  lines: [{\n    table_id: "tbl_release_lines",\n    link: "fld_order",\n    match: ["fld_size"],\n    rows: sheet.rows.map((row) => ({\n      fld_size: toString(row["Size"]),\n      fld_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## 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\nOn the CLI or in chat, `set_table_check` creates one, or changes one when given its `table_check_id`\nand only the parts that change, and `remove_table_check` removes one. `get_table` lists a table\'s\nchecks in the source they are written in.\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_id, filter, limit }`, the filter as `query_records` takes it, `limit` from 1 to 50 (50 when left out). A filter value may read the record. |\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_key` | optional; the field the refusal is shown under |\n\nEvery expression is written in the grammar above 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.\n- `lookups.<name>` \u2014 in `fail_when` and `message`, the rows that lookup read.\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), and `now()`.\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 lookup reads with the access of the member who last saved the check, so saving one requires reading\nevery table its lookups read. It reads committed rows: two writes at the same moment can each pass a\ncheck the other would fail, so values no two rows may share are the table\'s `unique`, not a check.\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. 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```\n{\n  "table_id": "tbl_orders",\n  "name": "One open order per reference",\n  "on": ["create", "update"],\n  "when": "isNull(record[\\"fld_closed_at\\"])",\n  "lookups": {\n    "same_ref": "{ table_id: \\"tbl_orders\\", filter: { node_type: \\"group\\", logic: \\"and\\", children: [ { field_key: \\"fld_ref\\", operator: \\"equals\\", value: record[\\"fld_ref\\"] }, { field_key: \\"fld_closed_at\\", operator: \\"is_empty\\" } ] }, limit: 2 }"\n  },\n  "fail_when": "some(lookups.same_ref, (r) => r.id != record.id)",\n  "message": "\\"An open order already has this reference.\\"",\n  "field_key": "fld_ref"\n}\n```\n';
 // docs/workflow_steps.md
-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`). `lotics tools <name>` prints any tool\'s inputs and answer,\nthese steps among them.\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## bkav\n\n### bkav_attach_files (workflow step)\n\n- Attach workspace files (a bi\xEAn b\u1EA3n, a b\u1EA3ng k\xEA) to an invoice on Bkav.\n- Bkav accepts PDF and Excel, at most 1 MB each.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string |  |  |\n| `partner_invoice_id` | string |  | Your PartnerInvoiceStringID, when invoice_guid is not set |\n| `file_ids` | string[] | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes |  |\n| `results[].PartnerInvoiceID` | number | yes |  |\n| `results[].PartnerInvoiceStringID` | string \\\\| null | yes | Null on a delete\'s answer |\n| `results[].InvoiceGUID` | string | yes |  |\n| `results[].InvoiceForm` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceSerial` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |\n| `results[].MTC` | string \\\\| null | yes | M\xE3 tra c\u1EE9u the buyer looks the invoice up with; null on a draft\'s link answer |\n| `results[].MaCuaCQT` | string \\\\| null |  |  |\n| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |\n| `results[].MessLog` | string | yes |  |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_cancel_invoices (workflow step)\n\n- Cancel issued invoices.\n- A cancelled invoice still reports to the tax authority; correcting one instead is a replacement or adjustment through bkav_submit_invoices. (workflow step, chat)\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guids` | string[] |  | InvoiceGUIDs Bkav returned |\n| `partner_invoice_ids` | string[] |  | Your PartnerInvoiceStringIDs |\n| `reason` | string | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes |  |\n| `results[].PartnerInvoiceID` | number | yes |  |\n| `results[].PartnerInvoiceStringID` | string \\\\| null | yes | Null on a delete\'s answer |\n| `results[].InvoiceGUID` | string | yes |  |\n| `results[].InvoiceForm` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceSerial` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |\n| `results[].MTC` | string \\\\| null | yes | M\xE3 tra c\u1EE9u the buyer looks the invoice up with; null on a draft\'s link answer |\n| `results[].MaCuaCQT` | string \\\\| null |  |  |\n| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |\n| `results[].MessLog` | string | yes |  |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_create_bill (workflow step)\n\n- Record a cash-register bill on Bkav.\n- Field names are Bkav\'s.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `bill` | object | yes |  |\n| `bill.Bill` | object | yes |  |\n| `bill.Bill.BillCode` | number | yes |  |\n| `bill.Bill.OriginalBillCode` | number |  |  |\n| `bill.Bill.BillDate` | string | yes |  |\n| `bill.Bill.BillStatusID` | number | yes |  |\n| `bill.Bill.PayMethod` | string |  |  |\n| `bill.Bill.Note` | string |  |  |\n| `bill.ListBillDetails` | object[] | yes |  |\n| `bill.ListBillDetails[].ItemTypeID` | number |  | 0 goods, 4 description line, 15 promotional goods, \u2026 |\n| `bill.ListBillDetails[].IsDiscount` | boolean |  |  |\n| `bill.ListBillDetails[].ItemCode` | string |  |  |\n| `bill.ListBillDetails[].ItemName` | string | yes |  |\n| `bill.ListBillDetails[].UnitName` | string |  |  |\n| `bill.ListBillDetails[].Qty` | number |  |  |\n| `bill.ListBillDetails[].Price` | number |  |  |\n| `bill.ListBillDetails[].Amount` | number |  |  |\n| `bill.ListBillDetails[].TaxRateID` | number |  | 1 0%, 2 5%, 3 10%, 4 kh\xF4ng ch\u1ECBu thu\u1EBF, 9 8%, \u2026 |\n| `bill.ListBillDetails[].TaxRate` | number |  |  |\n| `bill.ListBillDetails[].TaxAmount` | number |  |  |\n| `bill.ListBillDetails[].OtherAmount` | number |  |  |\n| `bill.ListBillDetails[].DiscountRate` | number |  |  |\n| `bill.ListBillDetails[].DiscountAmount` | number |  |  |\n| `bill.ListBillDetails[].UserDefineDetails` | string |  |  |\n| `bill.ListBillDetails[].IsIncrease` | boolean \\\\| null |  | On an adjustment: true raises the amount, false lowers it, absent adjusts information |\n| `bill.ListBillDetails[].SpecialtyItems` | string |  |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `created` | true | yes |  |\n\n### bkav_create_invoice_from_bills (workflow step)\n\n- Raise one invoice from cash-register bills, by their BillGUIDs.\n- Field names are Bkav\'s.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `input` | object | yes |  |\n| `input.Invoice` | object | yes |  |\n| `input.Invoice.InvoiceTypeID` | number | yes | 1 GTGT, 2 b\xE1n h\xE0ng, 5 PXK ki\xEAm VCNB, 6 PXK g\u1EEDi b\xE1n \u0111\u1EA1i l\xFD |\n| `input.Invoice.InvoiceDate` | string | yes | ISO date |\n| `input.Invoice.BuyerCode` | string |  |  |\n| `input.Invoice.BuyerName` | string |  |  |\n| `input.Invoice.BuyerTaxCode` | string |  |  |\n| `input.Invoice.BuyerUnitName` | string |  |  |\n| `input.Invoice.BuyerAddress` | string |  |  |\n| `input.Invoice.BuyerBankAccount` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `input.Invoice.PayMethodID` | number |  | 1 TM, 2 CK, 3 TM/CK, \u2026 |\n| `input.Invoice.ReceiveTypeID` | number |  | 1 email, 2 SMS, 3 both, 4 courier |\n| `input.Invoice.ReceiverEmail` | string |  |  |\n| `input.Invoice.ReceiverMobile` | string |  |  |\n| `input.Invoice.ReceiverAddress` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `input.Invoice.ReceiverName` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `input.Invoice.Note` | string |  |  |\n| `input.Invoice.BillCode` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `input.Invoice.CurrencyID` | string |  |  |\n| `input.Invoice.ExchangeRate` | number |  |  |\n| `input.Invoice.InvoiceForm` | string |  | M\u1EABu s\u1ED1 |\n| `input.Invoice.InvoiceSerial` | string |  | K\xFD hi\u1EC7u |\n| `input.Invoice.InvoiceNo` | number |  | S\u1ED1; 0 when Bkav assigns it |\n| `input.Invoice.MaCuaCQT` | string |  | Set only by a cash-register flow that already holds the authority\'s code |\n| `input.Invoice.UserDefine` | string |  | JSON-encoded template fields agreed with Bkav |\n| `input.Invoice.UIDefine` | string |  | JSON-encoded delivery-note fields (InvoiceTypeID 5 and 6) |\n| `input.Invoice.isBTH` | boolean |  |  |\n| `input.Invoice.CCCD` | string |  |  |\n| `input.Invoice.PassportNumber` | string |  |  |\n| `input.Invoice.FiscalCodes` | string |  |  |\n| `input.Invoice.Reason` | string |  | Why \u2014 required on a replacement or adjustment |\n| `input.Invoice.OriginalInvoiceIdentify` | string |  | `[m\u1EABu s\u1ED1]_[k\xFD hi\u1EC7u]_[s\u1ED1]` of the invoice a replacement or adjustment corrects |\n| `input.Invoice.InvoiceGUID` | string |  | Addresses the invoice for an update by guid |\n| `input.BillGUIDs` | string[] | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes |  |\n| `results[].PartnerInvoiceID` | number | yes |  |\n| `results[].PartnerInvoiceStringID` | string \\\\| null | yes | Null on a delete\'s answer |\n| `results[].InvoiceGUID` | string | yes |  |\n| `results[].InvoiceForm` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceSerial` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |\n| `results[].MTC` | string \\\\| null | yes | M\xE3 tra c\u1EE9u the buyer looks the invoice up with; null on a draft\'s link answer |\n| `results[].MaCuaCQT` | string \\\\| null |  |  |\n| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |\n| `results[].MessLog` | string | yes |  |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_delete_invoices (workflow step)\n\n- Delete invoices that were never issued.\n- A numbered one can be deleted only if its number is the highest in its range.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guids` | string[] |  | InvoiceGUIDs Bkav returned |\n| `partner_invoice_ids` | string[] |  | Your PartnerInvoiceStringIDs |\n| `reason` | string |  |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes |  |\n| `results[].PartnerInvoiceID` | number | yes |  |\n| `results[].PartnerInvoiceStringID` | string \\\\| null | yes | Null on a delete\'s answer |\n| `results[].InvoiceGUID` | string | yes |  |\n| `results[].InvoiceForm` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceSerial` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |\n| `results[].MTC` | string \\\\| null | yes | M\xE3 tra c\u1EE9u the buyer looks the invoice up with; null on a draft\'s link answer |\n| `results[].MaCuaCQT` | string \\\\| null |  |  |\n| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |\n| `results[].MessLog` | string | yes |  |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_explain_invoice_error (workflow step)\n\n- Explain an erroneous invoice to the tax authority without replacing or adjusting it, optionally answering one of its notices.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string | yes |  |\n| `reason` | string | yes |  |\n| `notice_number` | string |  | S\u1ED1 of the authority\'s notice being answered |\n| `notice_date` | string |  | yyyy-mm-dd; with notice_number |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes |  |\n| `results[].InvoiceGUID` | string | yes |  |\n| `results[].Status` | number | yes | 0 succeeded; otherwise Msg says why |\n| `results[].Msg` | string | yes |  |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_explain_replaced_invoice (workflow step)\n\n- Explain to the tax authority an invoice that was replaced or adjusted.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string | yes |  |\n| `reason` | string | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes |  |\n| `results[].InvoiceGUID` | string | yes |  |\n| `results[].Status` | number | yes | 0 succeeded; otherwise Msg says why |\n| `results[].Msg` | string | yes |  |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_get_bill (workflow step)\n\n- Read a cash-register bill.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `seller_tax_code` | string | yes |  |\n| `organization_code` | string | yes |  |\n| `bill_code` | number | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `bill` | object | yes |  |\n\n### bkav_get_error_notice_pdf (workflow step)\n\n- Save the PDF of an invoice\'s 04/SS error notice as a workspace file.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `partner_invoice_id` | string | yes | Your PartnerInvoiceStringID |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n### bkav_get_file_by_lookup_code (workflow step)\n\n- Save an invoice\'s display copy, conversion copy or XML as a workspace file, found by the m\xE3 tra c\u1EE9u the buyer was sent.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `lookup_code` | string | yes | M\xE3 tra c\u1EE9u |\n| `kind` | "display" \\\\| "converted" \\\\| "xml" | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n### bkav_get_invoice (workflow step)\n\n- Read one invoice as Bkav holds it \u2014 header, lines, status and m\xE3 tra c\u1EE9u.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `id` | string | yes | Your PartnerInvoiceStringID or Bkav\'s InvoiceGUID |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `invoice` | object | yes |  |\n\n### bkav_get_invoice_file (workflow step)\n\n- Save an invoice\'s PDF or signed XML as a workspace file.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `partner_invoice_id` | string | yes | Your PartnerInvoiceStringID |\n| `format` | "pdf" \\\\| "xml" | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n### bkav_get_invoice_history (workflow step)\n\n- Read everything that happened to an invoice on Bkav, oldest first.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `entries` | object[] | yes |  |\n\n### bkav_get_invoice_link (workflow step)\n\n- Get a download link for an invoice\'s display copy, conversion copy, or its 04/SS error notice.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `partner_invoice_id` | string | yes | Your PartnerInvoiceStringID |\n| `kind` | "display" \\\\| "converted" \\\\| "notice_04ss" | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `url` | string | yes |  |\n\n### bkav_get_invoice_status (workflow step)\n\n- Read an invoice\'s status on Bkav.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `invoice_status_id` | number | yes | 1 m\u1EDBi t\u1EA1o, 2 \u0111\xE3 ph\xE1t h\xE0nh, 3 \u0111\xE3 hu\u1EF7, 5\u20138 ch\u1EDD/\u0111\xE3 thay th\u1EBF\u2013\u0111i\u1EC1u ch\u1EC9nh, 11 \u0111\xE3 c\u1EA5p s\u1ED1 ch\u1EDD k\xFD |\n\n### bkav_get_listing (workflow step)\n\n- Save the b\u1EA3ng k\xEA of one invoice type over a window as a workspace spreadsheet.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_type_id` | number | yes | 1 GTGT, 2 b\xE1n h\xE0ng, \u2026 |\n| `from_date` | string | yes | yyyy-mm-dd |\n| `to_date` | string | yes | yyyy-mm-dd |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n### bkav_get_report_bc26 (workflow step)\n\n- Save the BC26/AC invoice usage report for a window as a workspace XML file.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `from_date` | string | yes | yyyy-mm-dd |\n| `to_date` | string | yes | yyyy-mm-dd |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n### bkav_get_tax_status (workflow step)\n\n- Read the tax authority\'s status for an invoice and its m\xE3 c\u1EE7a CQT once granted.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `statuses` | object[] | yes |  |\n| `statuses[].BkavStatus` | number | yes | InvoiceStatusID: 1 m\u1EDBi t\u1EA1o, 2 \u0111\xE3 ph\xE1t h\xE0nh, 3 \u0111\xE3 hu\u1EF7, \u2026 |\n| `statuses[].TaxStatus` | number | yes | 32 waiting, 33 accepted, 34\u201339 returned or failed |\n| `statuses[].TaxAuthorityCode` | string \\\\| null | yes | M\xE3 c\u1EE7a C\u01A1 quan thu\u1EBF, once granted |\n| `statuses[].ErrorContent` | string \\\\| null | yes |  |\n\n### bkav_list_invoices_by_date (workflow step)\n\n- List invoices dated within a window, one page at a time.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `from_date` | string | yes | yyyy-mm-dd |\n| `to_date` | string | yes | yyyy-mm-dd |\n| `page` | number |  | 1-based |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `invoices` | object[] | yes |  |\n\n### bkav_list_invoices_by_number (workflow step)\n\n- List invoices of one m\u1EABu s\u1ED1 and k\xFD hi\u1EC7u by number range.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `form` | string | yes | M\u1EABu s\u1ED1 |\n| `serial` | string | yes | K\xFD hi\u1EC7u |\n| `from_number` | number | yes |  |\n| `to_number` | number | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `invoices` | object[] | yes |  |\n\n### bkav_lookup_company (workflow step)\n\n- Look up a company in the tax registry by M\xE3 s\u1ED1 thu\u1EBF, through the Bkav account.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `tax_code` | string | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `company` | object | yes |  |\n| `company.MaSoThue` | string | yes |  |\n| `company.TenChinhThuc` | string | yes |  |\n| `company.DiaChiGiaoDichChinh` | string | yes |  |\n| `company.DiaChiGiaoDichPhu` | string | yes |  |\n| `company.TrangThaiHoatDong` | string | yes |  |\n| `company.ChuDoanhNghiep` | string |  |  |\n| `company.SoDienThoai` | string \\\\| null |  |  |\n| `company.LastUpdate` | string |  |  |\n\n### bkav_send_lookup_email (workflow step)\n\n- Send an invoice\'s lookup email to the buyer again, or to another email or phone.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string | yes |  |\n| `email` | string |  |  |\n| `mobile` | string |  |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `sent` | true | yes |  |\n\n### bkav_sign_invoices (workflow step)\n\n- Sign \u2014 issue \u2014 invoices with the account\'s HSM signature, making them tax-registered documents.\n- An account that signs with a USB token cannot sign this way.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guids` | string[] | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `signed` | string[] | yes |  |\n\n### bkav_submit_invoices (workflow step)\n\n- Create, replace or adjust invoices on Bkav, in Bkav\'s field names.\n- Each carries PartnerInvoiceStringID, your own id for it, which Bkav uses to refuse a duplicate.\n- Attachments are not accepted here.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `kind` | "create_draft" \\\\| "create" \\\\| "create_draft_own_serial" \\\\| "create_own_number" \\\\| "create_own_serial" \\\\| "replace_draft" \\\\| "adjust_draft" \\\\| "adjust_discount_draft" \\\\| "replace" \\\\| "adjust" \\\\| "adjust_external_draft" \\\\| "adjust_discount" \\\\| "adjust_external" \\\\| "replace_external" \\\\| "replace_external_draft" | yes | create_draft: no number, deletable. create: Bkav numbers it. *_own_*: your form/serial. replace_* / adjust_*: each invoice names its original in Invoice.OriginalInvoiceIdentify and gives Invoice.Reason. *_external*: corrects an invoice issued outside Bkav; its first line is an ItemTypeID 4 description of it. *_draft kinds stay unnumbered. |\n| `invoices` | object[] | yes |  |\n| `invoices[].Invoice` | object | yes |  |\n| `invoices[].Invoice.InvoiceTypeID` | number | yes | 1 GTGT, 2 b\xE1n h\xE0ng, 5 PXK ki\xEAm VCNB, 6 PXK g\u1EEDi b\xE1n \u0111\u1EA1i l\xFD |\n| `invoices[].Invoice.InvoiceDate` | string | yes | ISO date |\n| `invoices[].Invoice.BuyerCode` | string |  |  |\n| `invoices[].Invoice.BuyerName` | string |  |  |\n| `invoices[].Invoice.BuyerTaxCode` | string |  |  |\n| `invoices[].Invoice.BuyerUnitName` | string |  |  |\n| `invoices[].Invoice.BuyerAddress` | string |  |  |\n| `invoices[].Invoice.BuyerBankAccount` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.PayMethodID` | number |  | 1 TM, 2 CK, 3 TM/CK, \u2026 |\n| `invoices[].Invoice.ReceiveTypeID` | number |  | 1 email, 2 SMS, 3 both, 4 courier |\n| `invoices[].Invoice.ReceiverEmail` | string |  |  |\n| `invoices[].Invoice.ReceiverMobile` | string |  |  |\n| `invoices[].Invoice.ReceiverAddress` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.ReceiverName` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.Note` | string |  |  |\n| `invoices[].Invoice.BillCode` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.CurrencyID` | string |  |  |\n| `invoices[].Invoice.ExchangeRate` | number |  |  |\n| `invoices[].Invoice.InvoiceForm` | string |  | M\u1EABu s\u1ED1 |\n| `invoices[].Invoice.InvoiceSerial` | string |  | K\xFD hi\u1EC7u |\n| `invoices[].Invoice.InvoiceNo` | number |  | S\u1ED1; 0 when Bkav assigns it |\n| `invoices[].Invoice.MaCuaCQT` | string |  | Set only by a cash-register flow that already holds the authority\'s code |\n| `invoices[].Invoice.UserDefine` | string |  | JSON-encoded template fields agreed with Bkav |\n| `invoices[].Invoice.UIDefine` | string |  | JSON-encoded delivery-note fields (InvoiceTypeID 5 and 6) |\n| `invoices[].Invoice.isBTH` | boolean |  |  |\n| `invoices[].Invoice.CCCD` | string |  |  |\n| `invoices[].Invoice.PassportNumber` | string |  |  |\n| `invoices[].Invoice.FiscalCodes` | string |  |  |\n| `invoices[].Invoice.Reason` | string |  | Why \u2014 required on a replacement or adjustment |\n| `invoices[].Invoice.OriginalInvoiceIdentify` | string |  | `[m\u1EABu s\u1ED1]_[k\xFD hi\u1EC7u]_[s\u1ED1]` of the invoice a replacement or adjustment corrects |\n| `invoices[].Invoice.InvoiceGUID` | string |  | Addresses the invoice for an update by guid |\n| `invoices[].ListInvoiceDetailsWS` | object[] | yes |  |\n| `invoices[].ListInvoiceDetailsWS[].ItemTypeID` | number |  | 0 goods, 4 description line, 15 promotional goods, \u2026 |\n| `invoices[].ListInvoiceDetailsWS[].IsDiscount` | boolean |  |  |\n| `invoices[].ListInvoiceDetailsWS[].ItemCode` | string |  |  |\n| `invoices[].ListInvoiceDetailsWS[].ItemName` | string | yes |  |\n| `invoices[].ListInvoiceDetailsWS[].UnitName` | string |  |  |\n| `invoices[].ListInvoiceDetailsWS[].Qty` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].Price` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].Amount` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].TaxRateID` | number |  | 1 0%, 2 5%, 3 10%, 4 kh\xF4ng ch\u1ECBu thu\u1EBF, 9 8%, \u2026 |\n| `invoices[].ListInvoiceDetailsWS[].TaxRate` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].TaxAmount` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].OtherAmount` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].DiscountRate` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].DiscountAmount` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].UserDefineDetails` | string |  |  |\n| `invoices[].ListInvoiceDetailsWS[].IsIncrease` | boolean \\\\| null |  | On an adjustment: true raises the amount, false lowers it, absent adjusts information |\n| `invoices[].ListInvoiceDetailsWS[].SpecialtyItems` | string |  |  |\n| `invoices[].PartnerInvoiceStringID` | string | yes |  |\n| `invoices[].AttachListNumber` | string |  | S\u1ED1 of a b\u1EA3ng k\xEA the invoice refers to |\n| `invoices[].AttachListDate` | string |  |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes |  |\n| `results[].PartnerInvoiceID` | number | yes |  |\n| `results[].PartnerInvoiceStringID` | string \\\\| null | yes | Null on a delete\'s answer |\n| `results[].InvoiceGUID` | string | yes |  |\n| `results[].InvoiceForm` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceSerial` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |\n| `results[].MTC` | string \\\\| null | yes | M\xE3 tra c\u1EE9u the buyer looks the invoice up with; null on a draft\'s link answer |\n| `results[].MaCuaCQT` | string \\\\| null |  |  |\n| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |\n| `results[].MessLog` | string | yes |  |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_update_invoices (workflow step)\n\n- Change invoices not yet issued. by names how each invoice is found: partner (its partner id), number (Invoice.InvoiceForm + InvoiceSerial + InvoiceNo) or guid (Invoice.InvoiceGUID).\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `by` | "partner" \\\\| "number" \\\\| "guid" | yes |  |\n| `invoices` | object[] | yes |  |\n| `invoices[].Invoice` | object | yes |  |\n| `invoices[].Invoice.InvoiceTypeID` | number | yes | 1 GTGT, 2 b\xE1n h\xE0ng, 5 PXK ki\xEAm VCNB, 6 PXK g\u1EEDi b\xE1n \u0111\u1EA1i l\xFD |\n| `invoices[].Invoice.InvoiceDate` | string | yes | ISO date |\n| `invoices[].Invoice.BuyerCode` | string |  |  |\n| `invoices[].Invoice.BuyerName` | string |  |  |\n| `invoices[].Invoice.BuyerTaxCode` | string |  |  |\n| `invoices[].Invoice.BuyerUnitName` | string |  |  |\n| `invoices[].Invoice.BuyerAddress` | string |  |  |\n| `invoices[].Invoice.BuyerBankAccount` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.PayMethodID` | number |  | 1 TM, 2 CK, 3 TM/CK, \u2026 |\n| `invoices[].Invoice.ReceiveTypeID` | number |  | 1 email, 2 SMS, 3 both, 4 courier |\n| `invoices[].Invoice.ReceiverEmail` | string |  |  |\n| `invoices[].Invoice.ReceiverMobile` | string |  |  |\n| `invoices[].Invoice.ReceiverAddress` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.ReceiverName` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.Note` | string |  |  |\n| `invoices[].Invoice.BillCode` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.CurrencyID` | string |  |  |\n| `invoices[].Invoice.ExchangeRate` | number |  |  |\n| `invoices[].Invoice.InvoiceForm` | string |  | M\u1EABu s\u1ED1 |\n| `invoices[].Invoice.InvoiceSerial` | string |  | K\xFD hi\u1EC7u |\n| `invoices[].Invoice.InvoiceNo` | number |  | S\u1ED1; 0 when Bkav assigns it |\n| `invoices[].Invoice.MaCuaCQT` | string |  | Set only by a cash-register flow that already holds the authority\'s code |\n| `invoices[].Invoice.UserDefine` | string |  | JSON-encoded template fields agreed with Bkav |\n| `invoices[].Invoice.UIDefine` | string |  | JSON-encoded delivery-note fields (InvoiceTypeID 5 and 6) |\n| `invoices[].Invoice.isBTH` | boolean |  |  |\n| `invoices[].Invoice.CCCD` | string |  |  |\n| `invoices[].Invoice.PassportNumber` | string |  |  |\n| `invoices[].Invoice.FiscalCodes` | string |  |  |\n| `invoices[].Invoice.Reason` | string |  | Why \u2014 required on a replacement or adjustment |\n| `invoices[].Invoice.OriginalInvoiceIdentify` | string |  | `[m\u1EABu s\u1ED1]_[k\xFD hi\u1EC7u]_[s\u1ED1]` of the invoice a replacement or adjustment corrects |\n| `invoices[].Invoice.InvoiceGUID` | string |  | Addresses the invoice for an update by guid |\n| `invoices[].ListInvoiceDetailsWS` | object[] | yes |  |\n| `invoices[].ListInvoiceDetailsWS[].ItemTypeID` | number |  | 0 goods, 4 description line, 15 promotional goods, \u2026 |\n| `invoices[].ListInvoiceDetailsWS[].IsDiscount` | boolean |  |  |\n| `invoices[].ListInvoiceDetailsWS[].ItemCode` | string |  |  |\n| `invoices[].ListInvoiceDetailsWS[].ItemName` | string | yes |  |\n| `invoices[].ListInvoiceDetailsWS[].UnitName` | string |  |  |\n| `invoices[].ListInvoiceDetailsWS[].Qty` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].Price` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].Amount` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].TaxRateID` | number |  | 1 0%, 2 5%, 3 10%, 4 kh\xF4ng ch\u1ECBu thu\u1EBF, 9 8%, \u2026 |\n| `invoices[].ListInvoiceDetailsWS[].TaxRate` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].TaxAmount` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].OtherAmount` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].DiscountRate` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].DiscountAmount` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].UserDefineDetails` | string |  |  |\n| `invoices[].ListInvoiceDetailsWS[].IsIncrease` | boolean \\\\| null |  | On an adjustment: true raises the amount, false lowers it, absent adjusts information |\n| `invoices[].ListInvoiceDetailsWS[].SpecialtyItems` | string |  |  |\n| `invoices[].PartnerInvoiceStringID` | string | yes |  |\n| `invoices[].AttachListNumber` | string |  | S\u1ED1 of a b\u1EA3ng k\xEA the invoice refers to |\n| `invoices[].AttachListDate` | string |  |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes |  |\n| `results[].PartnerInvoiceID` | number | yes |  |\n| `results[].PartnerInvoiceStringID` | string \\\\| null | yes | Null on a delete\'s answer |\n| `results[].InvoiceGUID` | string | yes |  |\n| `results[].InvoiceForm` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceSerial` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |\n| `results[].MTC` | string \\\\| null | yes | M\xE3 tra c\u1EE9u the buyer looks the invoice up with; null on a draft\'s link answer |\n| `results[].MaCuaCQT` | string \\\\| null |  |  |\n| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |\n| `results[].MessLog` | string | yes |  |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n## 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. (workflow step, 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 (workflow step, 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## 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 `{fld_\u2026}`, 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_create_file (workflow step)\n\n- Create an Excel file with styled column headers and auto-filter enabled.\n- Input: { filename, sheets: [{ name, columns: [{ header, width? }], rows: unknown[][] }] } Headers are bold, centered, bordered, with auto-filter on the header row.\n- Best for producing polished report-style spreadsheets.\n- Returns a new file_id \u2014 use it for subsequent operations.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `sheets` | object[] | yes |  |\n| `sheets[].name` | string | yes |  |\n| `sheets[].columns` | object[] | yes |  |\n| `sheets[].columns[].header` | string | yes |  |\n| `sheets[].columns[].width` | number |  |  |\n| `sheets[].rows` | any[][] | yes | 2D array of cell values |\n| `filename` | string | 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### excel_find_cells (workflow step)\n\n- Search for cells matching a text query in an Excel worksheet.\n- Input: { file_id, worksheet: string\\|number, query: "search text", match_type?: "contains"\\|"exact"\\|"regex", max_results?: number } Default match_type is "contains" (case-insensitive).\n- Returns matching cell addresses, values, and positions.\n- Read-only \u2014 does not modify the file.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `worksheet` | string \\\\| number | yes |  |\n| `query` | string | yes | Text to find. |\n| `match_type` | "exact" \\\\| "contains" \\\\| "regex" |  | How to match: exact, contains (default), or regex |\n| `max_results` | number |  | Max matches to return |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `matches` | object[] | yes |  |\n| `matches[].cell` | string | yes | Cell address, e.g. B3 |\n| `matches[].value` | string | yes | Cell value as string |\n| `matches[].row` | number | yes | Row number |\n| `matches[].column` | string | yes | Column letter |\n| `total_matches` | number | yes | Total number of matches found |\n\n### excel_format_range (workflow step)\n\n- Apply formatting to a cell range (fonts, fills, borders, alignment, number formats). range format is always "START:END" \u2014 single cell: "B2:B2", multi-cell: "A1:D10".\n- Never use "B2" alone.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `worksheet` | string \\\\| number | yes |  |\n| `range` | string | yes |  |\n| `format` | object | yes |  |\n| `format.font_bold` | boolean |  |  |\n| `format.font_italic` | boolean |  |  |\n| `format.font_size` | number |  |  |\n| `format.font_color` | string |  | Hex color like #FF0000 |\n| `format.font_name` | string |  |  |\n| `format.font_underline` | "single" \\\\| "double" |  |  |\n| `format.font_strike` | boolean |  |  |\n| `format.background_color` | string |  | Hex color like #FFFF00 |\n| `format.horizontal_align` | "left" \\\\| "center" \\\\| "right" |  |  |\n| `format.vertical_align` | "top" \\\\| "middle" \\\\| "bottom" |  |  |\n| `format.wrap_text` | boolean |  |  |\n| `format.number_format` | string |  | Excel number format code (e.g. #,##0.00, dd/mm/yyyy) |\n| `format.border_top` | object |  |  |\n| `format.border_top.style` | "solid" \\\\| "dashed" \\\\| "dotted" \\\\| "double" |  |  |\n| `format.border_top.width` | number |  |  |\n| `format.border_top.color` | string |  |  |\n| `format.border_bottom` | object |  |  |\n| `format.border_bottom.style` | "solid" \\\\| "dashed" \\\\| "dotted" \\\\| "double" |  |  |\n| `format.border_bottom.width` | number |  |  |\n| `format.border_bottom.color` | string |  |  |\n| `format.border_left` | object |  |  |\n| `format.border_left.style` | "solid" \\\\| "dashed" \\\\| "dotted" \\\\| "double" |  |  |\n| `format.border_left.width` | number |  |  |\n| `format.border_left.color` | string |  |  |\n| `format.border_right` | object |  |  |\n| `format.border_right.style` | "solid" \\\\| "dashed" \\\\| "dotted" \\\\| "double" |  |  |\n| `format.border_right.width` | number |  |  |\n| `format.border_right.color` | string |  |  |\n| `column_widths` | object |  | Column letter \u2192 width mapping |\n| `row_heights` | object |  | Row number \u2192 height mapping |\n| `auto_filter` | string |  | Range for an auto-filter (e.g. A1:D1); one over a table turns on that table\'s own filter |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `formatted_cells` | number | yes |  |\n\n### excel_get_range (workflow step)\n\n- Read cell values from a range in an Excel worksheet. range format is always "START:END" \u2014 single cell: "B2:B2", multi-cell: "A1:D10".\n- Never use "B2" alone. worksheet: use sheet name (preferred) or 0-based index.\n- Use view_file first to see available worksheets.\n- Returns data keyed by row number then column letter, e.g. { "1": { "A": "Hello" } }.\n- Maximum 1000 cells per call \u2014 use smaller ranges and paginate if needed.\n- Read-only \u2014 does not modify the file.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `worksheet` | string \\\\| number | yes |  |\n| `range` | string | yes |  |\n| `options` | object |  | Options for data retrieval |\n| `options.include_formulas` | boolean |  | Include cell formulas instead of calculated values |\n| `options.include_formatting` | boolean |  | Include cell formatting information |\n| `options.max_cell_length` | number |  | Max characters returned per cell; longer text is truncated with an ellipsis. Pass -1 to return cells in full \u2014 use when reading free-text columns like notes. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `worksheet_name` | string | yes | The worksheet name |\n| `range` | string | yes | The requested range |\n| `data` | object | yes | Cell values keyed by row number then column letter |\n| `formatting` | object |  | Cell formatting keyed by row then column |\n| `truncated_cells` | object[] |  | Cells with truncated content |\n| `truncated_cells[].cell` | string | yes | Cell address |\n| `truncated_cells[].original_length` | number | yes | Original text length |\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 |  |\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### excel_update_range (workflow step)\n\n- Write cell values into a range in an Excel worksheet. range format is always "START:END" \u2014 single cell: "B2:B2", multi-cell: "A1:C3".\n- Never use "B2" alone. values is a 2D array matching the range dimensions.\n- Single cell: [["value"]], row: [["a","b","c"]], grid: [[r1...],[r2...]].\n- Strings starting with "=" are interpreted as formulas (e.g. "=SUM(A1:A10)").\n- Set options.interpret_formulas=false to write literal "=" text.\n- Modifies the document in place.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `worksheet` | string \\\\| number | yes |  |\n| `range` | string | yes |  |\n| `values` | any[][] | yes | 2D array of values to write (rows x columns) |\n| `options` | object |  |  |\n| `options.preserve_formatting` | boolean |  | Preserve existing cell formatting (only update values) |\n| `options.apply_number_format` | string |  | Apply a number format to all cells in the range (e.g., \'#,##0.00\') |\n| `options.interpret_formulas` | boolean |  | Set false to write \'=\' strings as literal text |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `worksheet_name` | string | yes |  |\n| `range` | string | yes |  |\n| `updated_cells` | number | yes | Number of cells updated |\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 |  |\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_image (workflow step)\n\n- Generate an image from a text prompt and save it to the workspace.\n- Returns a file_id usable as an image field value or attachment.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `prompt` | string | yes | Description of the image to generate. |\n| `size` | "1024x1024" \\\\| "1024x1536" \\\\| "1536x1024" |  | Square, portrait, or landscape. |\n| `quality` | "low" \\\\| "medium" \\\\| "high" |  | Higher quality costs more. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `url` | string | yes |  |\n| `width` | number | yes |  |\n| `height` | number | yes |  |\n| `mime_type` | 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_activity (workflow step)\n\n- List a record\'s activity, newest first: one entry per save \u2014 a person\'s edits made close together read as one, each field from before the first to after the last \u2014 and, inside an app\'s workflow, the comments the app takes.\n- A change entry says who made it and when, whether it made the record (created), whether it put an earlier change back (undo), who put it back since (undone), and whether the member the run acts for may put it back (undoable).\n- Inside an app\'s workflow the fields are the ones the app reads, and a record the app\'s own read does not reach for that member is not found.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `record_id` | string | yes |  |\n| `after` | string \\\\| null |  | A page\'s `next`. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `entries` | any[] | yes | Newest first. |\n| `next` | string |  | Where the trail continues: pass it as `after`. Absent at its end. |\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. (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 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 (workflow step, 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## import\n\n### import_rows (workflow step)\n\n- Match a source\'s rows to a table by a key and write what differs: a row whose match fields equal no live row\'s is added, one equalling a row\'s changes the cells that differ, one that changes nothing is counted and not written.\n- It keeps nothing of its own: what it wrote and what it held are its answer, read under the run\'s own reach of the table \u2014 a workflow hands its caller only what it returns. match names the fields that identify a row: text, number or date fields a row is written with, compared as trimmed text, case ignored, and link fields holding one row, compared by the row linked. values holds a row\'s cells by field key, as create_records takes them; a link cell also takes { "lookup": "<text>" }, the linked row found by that text in its table\'s unique or autonumber field, else its title, among the rows the run reads of that table, and a link holding many rows a list of them. (workflow step, chat, MCP, CLI)\n- A row is held, never written, when: it carries hold (its text is the message); several live rows or an earlier row of the call carry its key; a link\'s text names no row, or several; the table refuses it or its row is locked; create is false and no row carries its key; or, under conflicts "hold", a live cell holds another value \u2014 the row\'s empty cells are still written. conflicts "overwrite" writes over a differing cell, "fill_empty" leaves it. conflicts.fields sets one field\'s own.\n- A number and the field its unit or currency is read from are one cell, under the number\'s policy: both written, or both held.\n- A row whose key names a row outside the rows the run may write is held "refused" with nothing of that row: no record_id, no changes.\n- A row carrying remove: true proposes moving the row its key names to the trash: always held, whatever create and conflicts say, and counted unchanged where no row carries its key.\n- A row the source leaves out is never touched.\n- One call takes at most 10000 rows; more is refused with the count, never cut short.\n- Returns { read, created, changed, unchanged, held, written, written_omitted, held_rows, held_omitted }: the rows the call took, the rows it added, the rows it changed a cell of, the rows that changed nothing, and the rows held \u2014 a row can be both changed and held. written lists each record written: record_id, kind ("created" or "changed"), line, and changes \u2014 each field changed, with its field_key, its label and its before and after as text, as a read of the table shows them (an option\'s label, a linked row\'s display, a member\'s name; null where empty).\n- A created row lists no changes: its values are the row\'s own. held_rows lists each row held: kind ("create", "update", "remove", or "unmatched" where no row carries its key and create is false), reason, message, record_id where one row carries its key, key (each match field as text), the changes it would make, links (each link text naming no one row, with the rows it could be as candidates { id, display }), and values \u2014 its key and the cells it would write, as the call gave them.\n- A later call given those values under conflicts { "default": "overwrite" } writes it.\n- The two lists hold at most 10000 entries and 8388608 characters of JSON between them, each in the rows\' order, what was written before what was held; written_omitted and held_omitted count what was left out.\n- A row gives each list at most one entry.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `table_id` | string | yes |  |\n| `match` | string[] | yes |  |\n| `rows` | object[] | yes |  |\n| `rows[].values` | object | yes |  |\n| `rows[].hold` | string \\\\| null |  |  |\n| `rows[].remove` | boolean \\\\| null |  |  |\n| `rows[].line` | number \\\\| null |  | Its line in the source, 1-based. |\n| `create` | boolean \\\\| null |  |  |\n| `conflicts` | object \\\\| null |  |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `read` | number | yes |  |\n| `created` | number | yes |  |\n| `changed` | number | yes |  |\n| `unchanged` | number | yes |  |\n| `held` | number | yes |  |\n| `written` | object[] | yes |  |\n| `written[].record_id` | string | yes |  |\n| `written[].kind` | "created" \\\\| "changed" | yes |  |\n| `written[].line` | number |  |  |\n| `written[].changes` | object[] | yes |  |\n| `written[].changes[].field_key` | string | yes |  |\n| `written[].changes[].label` | string | yes |  |\n| `written[].changes[].before` | string \\\\| null | yes |  |\n| `written[].changes[].after` | string \\\\| null | yes |  |\n| `written_omitted` | number | yes |  |\n| `held_rows` | object[] | yes |  |\n| `held_rows[].line` | number |  |  |\n| `held_rows[].kind` | "create" \\\\| "update" \\\\| "remove" \\\\| "unmatched" | yes |  |\n| `held_rows[].reason` | "stated" \\\\| "removal" \\\\| "conflict" \\\\| "no_match" \\\\| "ambiguous_key" \\\\| "unresolved_link" \\\\| "ambiguous_link" \\\\| "locked" \\\\| "refused" | yes |  |\n| `held_rows[].message` | string | yes |  |\n| `held_rows[].record_id` | string |  |  |\n| `held_rows[].key` | object | yes |  |\n| `held_rows[].values` | object | yes |  |\n| `held_rows[].changes` | object[] | yes |  |\n| `held_rows[].changes[].field_key` | string | yes |  |\n| `held_rows[].changes[].label` | string | yes |  |\n| `held_rows[].changes[].before` | string \\\\| null | yes |  |\n| `held_rows[].changes[].after` | string \\\\| null | yes |  |\n| `held_rows[].links` | object[] | yes |  |\n| `held_rows[].links[].field_key` | string | yes |  |\n| `held_rows[].links[].text` | string | yes |  |\n| `held_rows[].links[].candidates` | object[] | yes |  |\n| `held_rows[].links[].candidates[].id` | string | yes |  |\n| `held_rows[].links[].candidates[].display` | string | yes |  |\n| `held_omitted` | number | yes |  |\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## 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\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` | any | yes | Raw dictionary records as returned by MISA |\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 | Caller-controlled UUID identifying the source document |\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 | Caller-controlled UUID identifying the source document |\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 | Caller-controlled UUID identifying the source document |\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 | Caller-controlled UUID identifying the source document |\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. (workflow step, 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 (workflow step, 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## 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## send\n\n### send_notification (workflow step)\n\n- Send a notification to workspace members. recipients is an array of principals: { type, id }.\n- All members: [{ type: "organization", id: "{{organization_id}}" }] Who triggered: [{ type: "member", id: "{{triggered_by_member_id}}" }] A group: [{ type: "member_group", id: "<group_id>" }]\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| `level` | "urgent" \\\\| "warning" \\\\| "info" \\\\| "success" |  | Notification level: urgent, warning, info, success |\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## undo\n\n### undo_record_change (workflow step)\n\n- Put back one change entry of a record\'s activity, as the own save of the member the run acts for. entry_id is the entry\'s id as get_record_activity lists it. (workflow step)\n- Each field the entry changed returns to what it held before it where the record still holds what it wrote; a field changed since is kept.\n- Refused: the entry that made the record, an entry that is itself an undo, an entry already put back, and a record in the trash.\n- The member holds write access to the record\'s table as the step runs, the record within the rows they may write; a run that acts for no member is refused.\n- Returns { reverted, kept }: the fields put back, and those left as they stand, each with why.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `record_id` | string | yes |  |\n| `entry_id` | string | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `reverted` | object[] | yes | The fields put back to what they held before the change. |\n| `reverted[].field_id` | string | yes |  |\n| `reverted[].label` | string | yes |  |\n| `kept` | object[] | yes | The fields left as they stand, each with why. A field already holding what it held before the change is in neither list. |\n| `kept[].field_id` | string | yes |  |\n| `kept[].label` | string | yes |  |\n| `kept[].reason` | "changed_since" \\\\| "refused" | yes | Someone changed it since; or the table refused the write (a lock, a check). |\n\n### undo_record_changes (workflow step)\n\n- Put back what one workflow run wrote on records of a table, as the own writes of the member the run acts for.\n- A field the run changed returns to what it held before where the record still holds what the run wrote; a record the run created moves to the trash where nothing else has written it or linked a row to it since; a record the run moved to the trash comes back where nothing has touched it since, without the links to it its removal took off other rows.\n- A record the run wrote nothing on is left out, and so is a write of the run that was itself an undo.\n- The member holds write access to the table as the step runs, each record within the rows they may write; a run that acts for no member is refused.\n- Takes at most 500 record ids a call.\n- Returns { reverted, kept }: the count of records put back, and the records left as they stand, one entry a record and reason with the field keys kept \u2014 none where the whole record was.\n- A record created in a table where a workflow writes each new row reads as written since, and is kept.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `table_id` | string | yes |  |\n| `record_ids` | string[] | yes |  |\n| `workflow_execution_id` | string | yes | The run whose writes are put back: what runtime.execution_id held in it. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `reverted` | number | yes |  |\n| `kept` | object[] | yes |  |\n| `kept[].record_id` | string | yes |  |\n| `kept[].fields` | string[] | yes |  |\n| `kept[].reason` | "changed_since" \\\\| "refused" \\\\| "outside_your_rows" \\\\| "unreadable" \\\\| "restored" | yes | Someone changed it since \u2014 wrote it, moved it to the trash, or linked a row to it; the table refused the write (a lock, a check); it is outside the rows the caller may write; the trail of what was written cannot be read; or the run brought it back from the trash, where an undo returns no row. |\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## view\n\n### view_files (workflow step)\n\n- View one or more files in a single call.\n- Two modes: - file_ids: explicit list of file IDs (use for cherry-picked files). - source: every file attached to a record\'s file field (use when you want all photos/attachments on a record).\n- Provide exactly one.\n- Reads EVERY readable format: images, PDFs, Word (.docx and legacy .doc), Excel (.xlsx and legacy .xls), CSV, and text formats (.txt, .md, .json, .xml, .yaml, .html).\n- Batch limit: 100 files.\n- Use this whenever you are handed a file_id you cannot already see \u2014 images and PDFs arrive in your context natively, but every other format is a reference you must open with this tool.\n- Files already in your context \u2014 those the user attached to the current message, and those an earlier view_files call returned this conversation \u2014 return a text-only "already in context" reference instead of re-emitting bytes. (workflow step, chat)\n- You do not need to re-call view_files to look at the same image again; scroll back to the original tool_result. (workflow step, chat)\n- Calling with already-seen file_ids is safe but wasteful.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_ids` | string[] |  |  |\n| `source` | object |  |  |\n| `source.record_id` | string | yes |  |\n| `source.field_key` | string | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `files` | object[] | yes |  |\n| `files[].file_id` | string | yes |  |\n| `files[].filename` | string | yes |  |\n| `files[].mime_type` | string | yes |  |\n| `files[].content` | object |  |  |\n| `files[].already_in_context` | boolean |  |  |\n| `files[].error` | string |  |  |\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## word\n\n### word_create_document (workflow step)\n\n- Create a new Word document (.docx), optionally with initial paragraphs and headings.\n- Use {{variable_name}} syntax in text to create template placeholders for data injection via create_word_template. (workflow step, chat, MCP, CLI)\n- Input: { filename, content?: [{ type: "paragraph"\\|"heading", text, level?: 1-6 }] } filename is without the .docx extension (added automatically).\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `filename` | string | yes | Name of the file (without .docx extension) |\n| `content` | object[] |  |  |\n| `content[].type` | "paragraph" \\\\| "heading" | yes |  |\n| `content[].text` | string | yes |  |\n| `content[].level` | number |  | Heading level (1-6), required when type is heading |\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### word_find_text (workflow step)\n\n- Search for text across all paragraphs and table cells in a Word document.\n- Input: { file_id, query: "search text", match_type?: "contains"\\|"exact"\\|"regex", max_results?: number } Default match_type is "contains".\n- Returns matching element indices, types, and text content.\n- Read-only \u2014 does not modify the file.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the Word (.docx) file |\n| `query` | string | yes |  |\n| `match_type` | "contains" \\\\| "exact" \\\\| "regex" |  |  |\n| `max_results` | number |  |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `matches` | object[] | yes |  |\n| `matches[].index` | number | yes |  |\n| `matches[].type` | "paragraph" \\\\| "table" \\\\| "other" | yes |  |\n| `matches[].text` | string | yes |  |\n| `total` | number | yes |  |\n\n### word_get_content (workflow step)\n\n- Read a Word document\'s full native content, paginated.\n- Every element returned is COMPLETE \u2014 full paragraph text and full table cells \u2014 unlike view_files, whose quick-look preview truncates long paragraphs and tables. (workflow step, chat)\n- Input: { file_id, offset?, limit? }.\n- Returns elements with their 0-based indices plus next_offset when more remains; call again with offset=next_offset to continue.\n- A page may end before `limit` to keep elements whole \u2014 follow next_offset, don\'t infer completion from the count.\n- A selection mark \u2014 a highlighted, shaded or coloured run, or a shaded table cell \u2014 surfaces in `marked_text` (the paragraph with each mark shown where it falls, which is what tells you WHICH of two identical `\u25A1` was picked), `highlighted_spans` (the marked text alone) and `marked_cells` (per table), so a form\'s chosen option reads correctly even when it is marked by colour rather than a tick.\n- Bold is OFF by default and reported only with `include_bold`, as a FACT rather than a selection: nearly every heading and label is bold, so on most documents it is noise.\n- Reach for it when a form\'s chosen option carries no glyph and no colour \u2014 some forms record the choice by bolding the chosen option\'s label, and then bold is the tick\'s only trace.\n- On a PARAGRAPH, `formatting_hint` already says the line contains bold (it cannot say which run \u2014 that is what `bold_spans` adds).\n- A TABLE carries no such hint, so on a criteria or option table pass `include_bold` rather than waiting for a signal.\n- Read the result against its siblings: a wholly bold heading or header row is structure, one bold label among plain ones is the choice.\n- Footnotes surface in `footnote_refs` (per paragraph) and `footnote_cells` (per table) with the note\'s own text, since a clause often carries its rule in the footnote rather than the sentence.\n- `orphaned_footnotes` lists notes the file carries with no anchor left in the body \u2014 those render nowhere.\n- Pictures surface in `images` on the element holding them, so a paragraph carrying only a picture is not mistaken for an empty one.\n- `headers_footers` carries header and footer text, which sits outside the body and so has no element index \u2014 a form often states which form it is there rather than in its text.\n- Read-only \u2014 does not modify the file.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the Word (.docx) file |\n| `offset` | integer |  | Element index to start from (pass the prior call\'s next_offset) |\n| `limit` | integer |  | Max elements to return |\n| `include_bold` | boolean |  | Also report WHERE the bold runs are (bold_spans / bold_cells). Off unless asked for \u2014 nearly every heading and label is bold, so it is noise on most documents and the answer on a form that ticks by bolding. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `elements` | object[] | yes |  |\n| `elements[].index` | number | yes |  |\n| `elements[].type` | "paragraph" \\\\| "table" \\\\| "other" | yes |  |\n| `elements[].text` | string |  |  |\n| `elements[].rows` | number |  |  |\n| `elements[].cols` | number |  |  |\n| `elements[].cells` | string[][] |  |  |\n| `elements[].heading_level` | number |  |  |\n| `elements[].list_type` | "bullet" \\\\| "numbered" |  |  |\n| `elements[].list_level` | number |  |  |\n| `elements[].formatting_hint` | string |  |  |\n| `elements[].highlighted_spans` | string[] |  |  |\n| `elements[].bold_spans` | string[] |  |  |\n| `elements[].marked_text` | string |  |  |\n| `elements[].images` | object[] |  |  |\n| `elements[].images[].name` | string |  |  |\n| `elements[].images[].width_cm` | number |  |  |\n| `elements[].images[].height_cm` | number |  |  |\n| `elements[].marked_cells` | object[] |  |  |\n| `elements[].marked_cells[].row` | number | yes |  |\n| `elements[].marked_cells[].col` | number | yes |  |\n| `elements[].marked_cells[].spans` | string[] | yes |  |\n| `elements[].bold_cells` | object[] |  |  |\n| `elements[].bold_cells[].row` | number | yes |  |\n| `elements[].bold_cells[].col` | number | yes |  |\n| `elements[].bold_cells[].spans` | string[] | yes |  |\n| `elements[].footnote_refs` | object[] |  |  |\n| `elements[].footnote_refs[].mark` | number | yes | The superscript number the reader sees |\n| `elements[].footnote_refs[].id` | string | yes |  |\n| `elements[].footnote_refs[].offset` | number | yes | Character offset into this element\'s text where the mark sits |\n| `elements[].footnote_refs[].text` | string |  |  |\n| `elements[].footnote_cells` | object[] |  |  |\n| `elements[].footnote_cells[].row` | number | yes |  |\n| `elements[].footnote_cells[].col` | number | yes |  |\n| `elements[].footnote_cells[].refs` | object[] | yes |  |\n| `elements[].footnote_cells[].refs[].mark` | number | yes | The superscript number the reader sees |\n| `elements[].footnote_cells[].refs[].id` | string | yes |  |\n| `elements[].footnote_cells[].refs[].offset` | number | yes | Character offset into this element\'s text where the mark sits |\n| `elements[].footnote_cells[].refs[].text` | string |  |  |\n| `total` | number | yes |  |\n| `next_offset` | number \\\\| null | yes |  |\n| `orphaned_footnotes` | object[] |  | Notes the file still carries with no anchor left in the body \u2014 they render nowhere |\n| `orphaned_footnotes[].id` | string | yes |  |\n| `orphaned_footnotes[].text` | string | yes |  |\n| `headers_footers` | object[] |  | Header and footer text \u2014 outside the body, so it carries no element index |\n| `headers_footers[].kind` | "header" \\\\| "footer" | yes |  |\n| `headers_footers[].text` | string | yes |  |\n\n### word_get_table_data (workflow step)\n\n- Read the full contents of a table in a Word document as a 2D string array.\n- Input: { file_id, table_index: number, max_rows? } table_index is the 0-based element index from view_files (must point to a table element). (workflow step, chat)\n- Returns data[][] with row_count and col_count.\n- A cell carrying a selection mark \u2014 a highlighted or shaded run, or a shaded cell \u2014 is listed in `marked_cells` ({row, col} aligned with data, spans = the marked text; empty spans = a shaded blank), so a criteria row\'s chosen option reads correctly even when it is marked by colour rather than a tick.\n- `bold_cells` lists the bold cells the same way, but ONLY with `include_bold` \u2014 header rows and label columns are bold, so it is noise on most tables.\n- Nothing in the default output hints that a table contains bold, so pass it whenever a criteria or option table shows no glyph and no colour: some forms record the choice by bolding that row\'s label and it is the tick\'s only trace.\n- It is a fact, never a selection \u2014 a whole bold header row is structure, one bold label among plain siblings is the choice.\n- Read-only \u2014 does not modify the file.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the Word (.docx) file |\n| `table_index` | number | yes | 0-based element index of the table |\n| `max_rows` | number |  | Max rows to return; all rows when omitted |\n| `include_bold` | boolean |  | Also report which cells are bold (bold_cells). Off unless asked for \u2014 header rows and label columns are bold, so it is noise on most tables and the answer on one that ticks by bolding. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `data` | string[][] | yes |  |\n| `row_count` | number | yes |  |\n| `col_count` | number | yes |  |\n| `marked_cells` | object[] |  |  |\n| `marked_cells[].row` | number | yes |  |\n| `marked_cells[].col` | number | yes |  |\n| `marked_cells[].spans` | string[] | yes |  |\n| `bold_cells` | object[] |  |  |\n| `bold_cells[].row` | number | yes |  |\n| `bold_cells[].col` | number | yes |  |\n| `bold_cells[].spans` | string[] | yes |  |\n\n### word_insert_conditional (workflow step)\n\n- Insert {{IF variable_name}}...{{END-IF variable_name}} command rows or paragraphs into a Word document to define a conditional section.\n- For table_rows: wraps the specified row range with command rows.\n- Requires table_index, start_row, end_row.\n- For paragraphs: wraps the specified element range with command paragraphs.\n- Requires start_index, end_index.\n- Use view_files to find element indices first. (workflow step, chat)\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `variable_name` | string | yes | Boolean variable name |\n| `region_type` | "table_rows" \\\\| "paragraphs" | yes |  |\n| `table_index` | integer |  | Index of the table element (required for table_rows) |\n| `start_row` | integer |  | First row to wrap (required for table_rows) |\n| `end_row` | integer |  | Last row to wrap, inclusive (required for table_rows) |\n| `start_index` | integer |  | First element index to wrap (required for paragraphs) |\n| `end_index` | integer |  | Last element index to wrap, inclusive (required for paragraphs) |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n\n### word_insert_loop (workflow step)\n\n- Insert {{FOR loop_var IN variable_name}}...{{END-FOR loop_var}} command rows or paragraphs into a Word document to define a repeating section.\n- Inside the loop, reference each item\'s fields with a $ prefix: {{$loop_var.field}} (or {{$loop_var}} for a scalar item, {{$idx}} for the 0-based index).\n- Without the $ prefix, generation fails.\n- For table_rows: wraps the specified row range with command rows.\n- Requires table_index, start_row, end_row.\n- For paragraphs: wraps the specified element range with command paragraphs.\n- Requires start_index, end_index.\n- Use view_files to find element indices first. (workflow step, chat)\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `variable_name` | string | yes | Array variable name |\n| `loop_variable` | string | yes | Iterator name used inside the loop, e.g. item |\n| `region_type` | "table_rows" \\\\| "paragraphs" | yes |  |\n| `table_index` | integer |  | Index of the table element (required for table_rows) |\n| `start_row` | integer |  | First row to wrap (required for table_rows) |\n| `end_row` | integer |  | Last row to wrap, inclusive (required for table_rows) |\n| `start_index` | integer |  | First element index to wrap (required for paragraphs) |\n| `end_index` | integer |  | Last element index to wrap, inclusive (required for paragraphs) |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n\n### word_replace_text (workflow step)\n\n- Find and replace text across all paragraphs and table cells in a Word document.\n- Replaces all occurrences unless max_replacements is set.\n- A match spanning several runs collapses them into the first run\'s formatting, so tick a checkbox by matching the box character on its own \u2014 \u2610 (U+2610) becomes \u2612 (U+2612), keeping the font that draws both.\n- Matching the phrase around the box drags it into the body font; replacing it with a letter leaves a bare letter beside the boxes still showing \u2610.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the Word (.docx) file |\n| `find` | string | yes |  |\n| `replace` | string | yes |  |\n| `match_type` | "contains" \\\\| "exact" \\\\| "regex" |  | `exact` matches a whole paragraph. None of the three is case-sensitive. |\n| `max_replacements` | number |  | Max number of replacements (default: unlimited) |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `replacements_made` | number | yes |  |\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';
+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`). `lotics tools <name>` prints any tool\'s inputs and answer,\nthese steps among them.\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## bkav\n\n### bkav_attach_files (workflow step)\n\n- Attach workspace files (a bi\xEAn b\u1EA3n, a b\u1EA3ng k\xEA) to an invoice on Bkav.\n- Bkav accepts PDF and Excel, at most 1 MB each.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string |  |  |\n| `partner_invoice_id` | string |  | Your PartnerInvoiceStringID, when invoice_guid is not set |\n| `file_ids` | string[] | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes |  |\n| `results[].PartnerInvoiceID` | number | yes |  |\n| `results[].PartnerInvoiceStringID` | string \\\\| null | yes | Null on a delete\'s answer |\n| `results[].InvoiceGUID` | string | yes |  |\n| `results[].InvoiceForm` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceSerial` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |\n| `results[].MTC` | string \\\\| null | yes | M\xE3 tra c\u1EE9u the buyer looks the invoice up with; null on a draft\'s link answer |\n| `results[].MaCuaCQT` | string \\\\| null |  |  |\n| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |\n| `results[].MessLog` | string | yes |  |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_cancel_invoices (workflow step)\n\n- Cancel issued invoices.\n- A cancelled invoice still reports to the tax authority; correcting one instead is a replacement or adjustment through bkav_submit_invoices. (workflow step, chat)\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guids` | string[] |  | InvoiceGUIDs Bkav returned |\n| `partner_invoice_ids` | string[] |  | Your PartnerInvoiceStringIDs |\n| `reason` | string | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes |  |\n| `results[].PartnerInvoiceID` | number | yes |  |\n| `results[].PartnerInvoiceStringID` | string \\\\| null | yes | Null on a delete\'s answer |\n| `results[].InvoiceGUID` | string | yes |  |\n| `results[].InvoiceForm` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceSerial` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |\n| `results[].MTC` | string \\\\| null | yes | M\xE3 tra c\u1EE9u the buyer looks the invoice up with; null on a draft\'s link answer |\n| `results[].MaCuaCQT` | string \\\\| null |  |  |\n| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |\n| `results[].MessLog` | string | yes |  |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_create_bill (workflow step)\n\n- Record a cash-register bill on Bkav.\n- Field names are Bkav\'s.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `bill` | object | yes |  |\n| `bill.Bill` | object | yes |  |\n| `bill.Bill.BillCode` | number | yes |  |\n| `bill.Bill.OriginalBillCode` | number |  |  |\n| `bill.Bill.BillDate` | string | yes |  |\n| `bill.Bill.BillStatusID` | number | yes |  |\n| `bill.Bill.PayMethod` | string |  |  |\n| `bill.Bill.Note` | string |  |  |\n| `bill.ListBillDetails` | object[] | yes |  |\n| `bill.ListBillDetails[].ItemTypeID` | number |  | 0 goods, 4 description line, 15 promotional goods, \u2026 |\n| `bill.ListBillDetails[].IsDiscount` | boolean |  |  |\n| `bill.ListBillDetails[].ItemCode` | string |  |  |\n| `bill.ListBillDetails[].ItemName` | string | yes |  |\n| `bill.ListBillDetails[].UnitName` | string |  |  |\n| `bill.ListBillDetails[].Qty` | number |  |  |\n| `bill.ListBillDetails[].Price` | number |  |  |\n| `bill.ListBillDetails[].Amount` | number |  |  |\n| `bill.ListBillDetails[].TaxRateID` | number |  | 1 0%, 2 5%, 3 10%, 4 kh\xF4ng ch\u1ECBu thu\u1EBF, 9 8%, \u2026 |\n| `bill.ListBillDetails[].TaxRate` | number |  |  |\n| `bill.ListBillDetails[].TaxAmount` | number |  |  |\n| `bill.ListBillDetails[].OtherAmount` | number |  |  |\n| `bill.ListBillDetails[].DiscountRate` | number |  |  |\n| `bill.ListBillDetails[].DiscountAmount` | number |  |  |\n| `bill.ListBillDetails[].UserDefineDetails` | string |  |  |\n| `bill.ListBillDetails[].IsIncrease` | boolean \\\\| null |  | On an adjustment: true raises the amount, false lowers it, absent adjusts information |\n| `bill.ListBillDetails[].SpecialtyItems` | string |  |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `created` | true | yes |  |\n\n### bkav_create_invoice_from_bills (workflow step)\n\n- Raise one invoice from cash-register bills, by their BillGUIDs.\n- Field names are Bkav\'s.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `input` | object | yes |  |\n| `input.Invoice` | object | yes |  |\n| `input.Invoice.InvoiceTypeID` | number | yes | 1 GTGT, 2 b\xE1n h\xE0ng, 5 PXK ki\xEAm VCNB, 6 PXK g\u1EEDi b\xE1n \u0111\u1EA1i l\xFD |\n| `input.Invoice.InvoiceDate` | string | yes | ISO date |\n| `input.Invoice.BuyerCode` | string |  |  |\n| `input.Invoice.BuyerName` | string |  |  |\n| `input.Invoice.BuyerTaxCode` | string |  |  |\n| `input.Invoice.BuyerUnitName` | string |  |  |\n| `input.Invoice.BuyerAddress` | string |  |  |\n| `input.Invoice.BuyerBankAccount` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `input.Invoice.PayMethodID` | number |  | 1 TM, 2 CK, 3 TM/CK, \u2026 |\n| `input.Invoice.ReceiveTypeID` | number |  | 1 email, 2 SMS, 3 both, 4 courier |\n| `input.Invoice.ReceiverEmail` | string |  |  |\n| `input.Invoice.ReceiverMobile` | string |  |  |\n| `input.Invoice.ReceiverAddress` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `input.Invoice.ReceiverName` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `input.Invoice.Note` | string |  |  |\n| `input.Invoice.BillCode` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `input.Invoice.CurrencyID` | string |  |  |\n| `input.Invoice.ExchangeRate` | number |  |  |\n| `input.Invoice.InvoiceForm` | string |  | M\u1EABu s\u1ED1 |\n| `input.Invoice.InvoiceSerial` | string |  | K\xFD hi\u1EC7u |\n| `input.Invoice.InvoiceNo` | number |  | S\u1ED1; 0 when Bkav assigns it |\n| `input.Invoice.MaCuaCQT` | string |  | Set only by a cash-register flow that already holds the authority\'s code |\n| `input.Invoice.UserDefine` | string |  | JSON-encoded template fields agreed with Bkav |\n| `input.Invoice.UIDefine` | string |  | JSON-encoded delivery-note fields (InvoiceTypeID 5 and 6) |\n| `input.Invoice.isBTH` | boolean |  |  |\n| `input.Invoice.CCCD` | string |  |  |\n| `input.Invoice.PassportNumber` | string |  |  |\n| `input.Invoice.FiscalCodes` | string |  |  |\n| `input.Invoice.Reason` | string |  | Why \u2014 required on a replacement or adjustment |\n| `input.Invoice.OriginalInvoiceIdentify` | string |  | `[m\u1EABu s\u1ED1]_[k\xFD hi\u1EC7u]_[s\u1ED1]` of the invoice a replacement or adjustment corrects |\n| `input.Invoice.InvoiceGUID` | string |  | Addresses the invoice for an update by guid |\n| `input.BillGUIDs` | string[] | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes |  |\n| `results[].PartnerInvoiceID` | number | yes |  |\n| `results[].PartnerInvoiceStringID` | string \\\\| null | yes | Null on a delete\'s answer |\n| `results[].InvoiceGUID` | string | yes |  |\n| `results[].InvoiceForm` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceSerial` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |\n| `results[].MTC` | string \\\\| null | yes | M\xE3 tra c\u1EE9u the buyer looks the invoice up with; null on a draft\'s link answer |\n| `results[].MaCuaCQT` | string \\\\| null |  |  |\n| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |\n| `results[].MessLog` | string | yes |  |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_delete_invoices (workflow step)\n\n- Delete invoices that were never issued.\n- A numbered one can be deleted only if its number is the highest in its range.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guids` | string[] |  | InvoiceGUIDs Bkav returned |\n| `partner_invoice_ids` | string[] |  | Your PartnerInvoiceStringIDs |\n| `reason` | string |  |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes |  |\n| `results[].PartnerInvoiceID` | number | yes |  |\n| `results[].PartnerInvoiceStringID` | string \\\\| null | yes | Null on a delete\'s answer |\n| `results[].InvoiceGUID` | string | yes |  |\n| `results[].InvoiceForm` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceSerial` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |\n| `results[].MTC` | string \\\\| null | yes | M\xE3 tra c\u1EE9u the buyer looks the invoice up with; null on a draft\'s link answer |\n| `results[].MaCuaCQT` | string \\\\| null |  |  |\n| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |\n| `results[].MessLog` | string | yes |  |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_explain_invoice_error (workflow step)\n\n- Explain an erroneous invoice to the tax authority without replacing or adjusting it, optionally answering one of its notices.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string | yes |  |\n| `reason` | string | yes |  |\n| `notice_number` | string |  | S\u1ED1 of the authority\'s notice being answered |\n| `notice_date` | string |  | yyyy-mm-dd; with notice_number |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes |  |\n| `results[].InvoiceGUID` | string | yes |  |\n| `results[].Status` | number | yes | 0 succeeded; otherwise Msg says why |\n| `results[].Msg` | string | yes |  |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_explain_replaced_invoice (workflow step)\n\n- Explain to the tax authority an invoice that was replaced or adjusted.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string | yes |  |\n| `reason` | string | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes |  |\n| `results[].InvoiceGUID` | string | yes |  |\n| `results[].Status` | number | yes | 0 succeeded; otherwise Msg says why |\n| `results[].Msg` | string | yes |  |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_get_bill (workflow step)\n\n- Read a cash-register bill.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `seller_tax_code` | string | yes |  |\n| `organization_code` | string | yes |  |\n| `bill_code` | number | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `bill` | object | yes |  |\n\n### bkav_get_error_notice_pdf (workflow step)\n\n- Save the PDF of an invoice\'s 04/SS error notice as a workspace file.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `partner_invoice_id` | string | yes | Your PartnerInvoiceStringID |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n### bkav_get_file_by_lookup_code (workflow step)\n\n- Save an invoice\'s display copy, conversion copy or XML as a workspace file, found by the m\xE3 tra c\u1EE9u the buyer was sent.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `lookup_code` | string | yes | M\xE3 tra c\u1EE9u |\n| `kind` | "display" \\\\| "converted" \\\\| "xml" | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n### bkav_get_invoice (workflow step)\n\n- Read one invoice as Bkav holds it \u2014 header, lines, status and m\xE3 tra c\u1EE9u.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `id` | string | yes | Your PartnerInvoiceStringID or Bkav\'s InvoiceGUID |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `invoice` | object | yes |  |\n\n### bkav_get_invoice_file (workflow step)\n\n- Save an invoice\'s PDF or signed XML as a workspace file.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `partner_invoice_id` | string | yes | Your PartnerInvoiceStringID |\n| `format` | "pdf" \\\\| "xml" | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n### bkav_get_invoice_history (workflow step)\n\n- Read everything that happened to an invoice on Bkav, oldest first.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `entries` | object[] | yes |  |\n\n### bkav_get_invoice_link (workflow step)\n\n- Get a download link for an invoice\'s display copy, conversion copy, or its 04/SS error notice.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `partner_invoice_id` | string | yes | Your PartnerInvoiceStringID |\n| `kind` | "display" \\\\| "converted" \\\\| "notice_04ss" | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `url` | string | yes |  |\n\n### bkav_get_invoice_status (workflow step)\n\n- Read an invoice\'s status on Bkav.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `invoice_status_id` | number | yes | 1 m\u1EDBi t\u1EA1o, 2 \u0111\xE3 ph\xE1t h\xE0nh, 3 \u0111\xE3 hu\u1EF7, 5\u20138 ch\u1EDD/\u0111\xE3 thay th\u1EBF\u2013\u0111i\u1EC1u ch\u1EC9nh, 11 \u0111\xE3 c\u1EA5p s\u1ED1 ch\u1EDD k\xFD |\n\n### bkav_get_listing (workflow step)\n\n- Save the b\u1EA3ng k\xEA of one invoice type over a window as a workspace spreadsheet.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_type_id` | number | yes | 1 GTGT, 2 b\xE1n h\xE0ng, \u2026 |\n| `from_date` | string | yes | yyyy-mm-dd |\n| `to_date` | string | yes | yyyy-mm-dd |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n### bkav_get_report_bc26 (workflow step)\n\n- Save the BC26/AC invoice usage report for a window as a workspace XML file.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `from_date` | string | yes | yyyy-mm-dd |\n| `to_date` | string | yes | yyyy-mm-dd |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the generated file. |\n| `url` | string | yes | The download URL of the generated file. |\n| `filename` | string | yes | The filename of the generated file, including extension. |\n| `mime_type` | string | yes | The MIME type of the generated file. |\n\n### bkav_get_tax_status (workflow step)\n\n- Read the tax authority\'s status for an invoice and its m\xE3 c\u1EE7a CQT once granted.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `statuses` | object[] | yes |  |\n| `statuses[].BkavStatus` | number | yes | InvoiceStatusID: 1 m\u1EDBi t\u1EA1o, 2 \u0111\xE3 ph\xE1t h\xE0nh, 3 \u0111\xE3 hu\u1EF7, \u2026 |\n| `statuses[].TaxStatus` | number | yes | 32 waiting, 33 accepted, 34\u201339 returned or failed |\n| `statuses[].TaxAuthorityCode` | string \\\\| null | yes | M\xE3 c\u1EE7a C\u01A1 quan thu\u1EBF, once granted |\n| `statuses[].ErrorContent` | string \\\\| null | yes |  |\n\n### bkav_list_invoices_by_date (workflow step)\n\n- List invoices dated within a window, one page at a time.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `from_date` | string | yes | yyyy-mm-dd |\n| `to_date` | string | yes | yyyy-mm-dd |\n| `page` | number |  | 1-based |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `invoices` | object[] | yes |  |\n\n### bkav_list_invoices_by_number (workflow step)\n\n- List invoices of one m\u1EABu s\u1ED1 and k\xFD hi\u1EC7u by number range.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `form` | string | yes | M\u1EABu s\u1ED1 |\n| `serial` | string | yes | K\xFD hi\u1EC7u |\n| `from_number` | number | yes |  |\n| `to_number` | number | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `invoices` | object[] | yes |  |\n\n### bkav_lookup_company (workflow step)\n\n- Look up a company in the tax registry by M\xE3 s\u1ED1 thu\u1EBF, through the Bkav account.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `tax_code` | string | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `company` | object | yes |  |\n| `company.MaSoThue` | string | yes |  |\n| `company.TenChinhThuc` | string | yes |  |\n| `company.DiaChiGiaoDichChinh` | string | yes |  |\n| `company.DiaChiGiaoDichPhu` | string | yes |  |\n| `company.TrangThaiHoatDong` | string | yes |  |\n| `company.ChuDoanhNghiep` | string |  |  |\n| `company.SoDienThoai` | string \\\\| null |  |  |\n| `company.LastUpdate` | string |  |  |\n\n### bkav_send_lookup_email (workflow step)\n\n- Send an invoice\'s lookup email to the buyer again, or to another email or phone.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guid` | string | yes |  |\n| `email` | string |  |  |\n| `mobile` | string |  |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `sent` | true | yes |  |\n\n### bkav_sign_invoices (workflow step)\n\n- Sign \u2014 issue \u2014 invoices with the account\'s HSM signature, making them tax-registered documents.\n- An account that signs with a USB token cannot sign this way.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `invoice_guids` | string[] | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `signed` | string[] | yes |  |\n\n### bkav_submit_invoices (workflow step)\n\n- Create, replace or adjust invoices on Bkav, in Bkav\'s field names.\n- Each carries PartnerInvoiceStringID, your own id for it, which Bkav uses to refuse a duplicate.\n- Attachments are not accepted here.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `kind` | "create_draft" \\\\| "create" \\\\| "create_draft_own_serial" \\\\| "create_own_number" \\\\| "create_own_serial" \\\\| "replace_draft" \\\\| "adjust_draft" \\\\| "adjust_discount_draft" \\\\| "replace" \\\\| "adjust" \\\\| "adjust_external_draft" \\\\| "adjust_discount" \\\\| "adjust_external" \\\\| "replace_external" \\\\| "replace_external_draft" | yes | create_draft: no number, deletable. create: Bkav numbers it. *_own_*: your form/serial. replace_* / adjust_*: each invoice names its original in Invoice.OriginalInvoiceIdentify and gives Invoice.Reason. *_external*: corrects an invoice issued outside Bkav; its first line is an ItemTypeID 4 description of it. *_draft kinds stay unnumbered. |\n| `invoices` | object[] | yes |  |\n| `invoices[].Invoice` | object | yes |  |\n| `invoices[].Invoice.InvoiceTypeID` | number | yes | 1 GTGT, 2 b\xE1n h\xE0ng, 5 PXK ki\xEAm VCNB, 6 PXK g\u1EEDi b\xE1n \u0111\u1EA1i l\xFD |\n| `invoices[].Invoice.InvoiceDate` | string | yes | ISO date |\n| `invoices[].Invoice.BuyerCode` | string |  |  |\n| `invoices[].Invoice.BuyerName` | string |  |  |\n| `invoices[].Invoice.BuyerTaxCode` | string |  |  |\n| `invoices[].Invoice.BuyerUnitName` | string |  |  |\n| `invoices[].Invoice.BuyerAddress` | string |  |  |\n| `invoices[].Invoice.BuyerBankAccount` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.PayMethodID` | number |  | 1 TM, 2 CK, 3 TM/CK, \u2026 |\n| `invoices[].Invoice.ReceiveTypeID` | number |  | 1 email, 2 SMS, 3 both, 4 courier |\n| `invoices[].Invoice.ReceiverEmail` | string |  |  |\n| `invoices[].Invoice.ReceiverMobile` | string |  |  |\n| `invoices[].Invoice.ReceiverAddress` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.ReceiverName` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.Note` | string |  |  |\n| `invoices[].Invoice.BillCode` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.CurrencyID` | string |  |  |\n| `invoices[].Invoice.ExchangeRate` | number |  |  |\n| `invoices[].Invoice.InvoiceForm` | string |  | M\u1EABu s\u1ED1 |\n| `invoices[].Invoice.InvoiceSerial` | string |  | K\xFD hi\u1EC7u |\n| `invoices[].Invoice.InvoiceNo` | number |  | S\u1ED1; 0 when Bkav assigns it |\n| `invoices[].Invoice.MaCuaCQT` | string |  | Set only by a cash-register flow that already holds the authority\'s code |\n| `invoices[].Invoice.UserDefine` | string |  | JSON-encoded template fields agreed with Bkav |\n| `invoices[].Invoice.UIDefine` | string |  | JSON-encoded delivery-note fields (InvoiceTypeID 5 and 6) |\n| `invoices[].Invoice.isBTH` | boolean |  |  |\n| `invoices[].Invoice.CCCD` | string |  |  |\n| `invoices[].Invoice.PassportNumber` | string |  |  |\n| `invoices[].Invoice.FiscalCodes` | string |  |  |\n| `invoices[].Invoice.Reason` | string |  | Why \u2014 required on a replacement or adjustment |\n| `invoices[].Invoice.OriginalInvoiceIdentify` | string |  | `[m\u1EABu s\u1ED1]_[k\xFD hi\u1EC7u]_[s\u1ED1]` of the invoice a replacement or adjustment corrects |\n| `invoices[].Invoice.InvoiceGUID` | string |  | Addresses the invoice for an update by guid |\n| `invoices[].ListInvoiceDetailsWS` | object[] | yes |  |\n| `invoices[].ListInvoiceDetailsWS[].ItemTypeID` | number |  | 0 goods, 4 description line, 15 promotional goods, \u2026 |\n| `invoices[].ListInvoiceDetailsWS[].IsDiscount` | boolean |  |  |\n| `invoices[].ListInvoiceDetailsWS[].ItemCode` | string |  |  |\n| `invoices[].ListInvoiceDetailsWS[].ItemName` | string | yes |  |\n| `invoices[].ListInvoiceDetailsWS[].UnitName` | string |  |  |\n| `invoices[].ListInvoiceDetailsWS[].Qty` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].Price` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].Amount` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].TaxRateID` | number |  | 1 0%, 2 5%, 3 10%, 4 kh\xF4ng ch\u1ECBu thu\u1EBF, 9 8%, \u2026 |\n| `invoices[].ListInvoiceDetailsWS[].TaxRate` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].TaxAmount` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].OtherAmount` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].DiscountRate` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].DiscountAmount` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].UserDefineDetails` | string |  |  |\n| `invoices[].ListInvoiceDetailsWS[].IsIncrease` | boolean \\\\| null |  | On an adjustment: true raises the amount, false lowers it, absent adjusts information |\n| `invoices[].ListInvoiceDetailsWS[].SpecialtyItems` | string |  |  |\n| `invoices[].PartnerInvoiceStringID` | string | yes |  |\n| `invoices[].AttachListNumber` | string |  | S\u1ED1 of a b\u1EA3ng k\xEA the invoice refers to |\n| `invoices[].AttachListDate` | string |  |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes |  |\n| `results[].PartnerInvoiceID` | number | yes |  |\n| `results[].PartnerInvoiceStringID` | string \\\\| null | yes | Null on a delete\'s answer |\n| `results[].InvoiceGUID` | string | yes |  |\n| `results[].InvoiceForm` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceSerial` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |\n| `results[].MTC` | string \\\\| null | yes | M\xE3 tra c\u1EE9u the buyer looks the invoice up with; null on a draft\'s link answer |\n| `results[].MaCuaCQT` | string \\\\| null |  |  |\n| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |\n| `results[].MessLog` | string | yes |  |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n### bkav_update_invoices (workflow step)\n\n- Change invoices not yet issued. by names how each invoice is found: partner (its partner id), number (Invoice.InvoiceForm + InvoiceSerial + InvoiceNo) or guid (Invoice.InvoiceGUID).\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `connected_account_id` | string | yes | Bkav connected account |\n| `by` | "partner" \\\\| "number" \\\\| "guid" | yes |  |\n| `invoices` | object[] | yes |  |\n| `invoices[].Invoice` | object | yes |  |\n| `invoices[].Invoice.InvoiceTypeID` | number | yes | 1 GTGT, 2 b\xE1n h\xE0ng, 5 PXK ki\xEAm VCNB, 6 PXK g\u1EEDi b\xE1n \u0111\u1EA1i l\xFD |\n| `invoices[].Invoice.InvoiceDate` | string | yes | ISO date |\n| `invoices[].Invoice.BuyerCode` | string |  |  |\n| `invoices[].Invoice.BuyerName` | string |  |  |\n| `invoices[].Invoice.BuyerTaxCode` | string |  |  |\n| `invoices[].Invoice.BuyerUnitName` | string |  |  |\n| `invoices[].Invoice.BuyerAddress` | string |  |  |\n| `invoices[].Invoice.BuyerBankAccount` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.PayMethodID` | number |  | 1 TM, 2 CK, 3 TM/CK, \u2026 |\n| `invoices[].Invoice.ReceiveTypeID` | number |  | 1 email, 2 SMS, 3 both, 4 courier |\n| `invoices[].Invoice.ReceiverEmail` | string |  |  |\n| `invoices[].Invoice.ReceiverMobile` | string |  |  |\n| `invoices[].Invoice.ReceiverAddress` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.ReceiverName` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.Note` | string |  |  |\n| `invoices[].Invoice.BillCode` | string |  | Sent empty when absent: Bkav refuses it missing |\n| `invoices[].Invoice.CurrencyID` | string |  |  |\n| `invoices[].Invoice.ExchangeRate` | number |  |  |\n| `invoices[].Invoice.InvoiceForm` | string |  | M\u1EABu s\u1ED1 |\n| `invoices[].Invoice.InvoiceSerial` | string |  | K\xFD hi\u1EC7u |\n| `invoices[].Invoice.InvoiceNo` | number |  | S\u1ED1; 0 when Bkav assigns it |\n| `invoices[].Invoice.MaCuaCQT` | string |  | Set only by a cash-register flow that already holds the authority\'s code |\n| `invoices[].Invoice.UserDefine` | string |  | JSON-encoded template fields agreed with Bkav |\n| `invoices[].Invoice.UIDefine` | string |  | JSON-encoded delivery-note fields (InvoiceTypeID 5 and 6) |\n| `invoices[].Invoice.isBTH` | boolean |  |  |\n| `invoices[].Invoice.CCCD` | string |  |  |\n| `invoices[].Invoice.PassportNumber` | string |  |  |\n| `invoices[].Invoice.FiscalCodes` | string |  |  |\n| `invoices[].Invoice.Reason` | string |  | Why \u2014 required on a replacement or adjustment |\n| `invoices[].Invoice.OriginalInvoiceIdentify` | string |  | `[m\u1EABu s\u1ED1]_[k\xFD hi\u1EC7u]_[s\u1ED1]` of the invoice a replacement or adjustment corrects |\n| `invoices[].Invoice.InvoiceGUID` | string |  | Addresses the invoice for an update by guid |\n| `invoices[].ListInvoiceDetailsWS` | object[] | yes |  |\n| `invoices[].ListInvoiceDetailsWS[].ItemTypeID` | number |  | 0 goods, 4 description line, 15 promotional goods, \u2026 |\n| `invoices[].ListInvoiceDetailsWS[].IsDiscount` | boolean |  |  |\n| `invoices[].ListInvoiceDetailsWS[].ItemCode` | string |  |  |\n| `invoices[].ListInvoiceDetailsWS[].ItemName` | string | yes |  |\n| `invoices[].ListInvoiceDetailsWS[].UnitName` | string |  |  |\n| `invoices[].ListInvoiceDetailsWS[].Qty` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].Price` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].Amount` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].TaxRateID` | number |  | 1 0%, 2 5%, 3 10%, 4 kh\xF4ng ch\u1ECBu thu\u1EBF, 9 8%, \u2026 |\n| `invoices[].ListInvoiceDetailsWS[].TaxRate` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].TaxAmount` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].OtherAmount` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].DiscountRate` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].DiscountAmount` | number |  |  |\n| `invoices[].ListInvoiceDetailsWS[].UserDefineDetails` | string |  |  |\n| `invoices[].ListInvoiceDetailsWS[].IsIncrease` | boolean \\\\| null |  | On an adjustment: true raises the amount, false lowers it, absent adjusts information |\n| `invoices[].ListInvoiceDetailsWS[].SpecialtyItems` | string |  |  |\n| `invoices[].PartnerInvoiceStringID` | string | yes |  |\n| `invoices[].AttachListNumber` | string |  | S\u1ED1 of a b\u1EA3ng k\xEA the invoice refers to |\n| `invoices[].AttachListDate` | string |  |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `results` | object[] | yes |  |\n| `results[].PartnerInvoiceID` | number | yes |  |\n| `results[].PartnerInvoiceStringID` | string \\\\| null | yes | Null on a delete\'s answer |\n| `results[].InvoiceGUID` | string | yes |  |\n| `results[].InvoiceForm` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceSerial` | string \\\\| null | yes | Null on a draft\'s link answer |\n| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |\n| `results[].MTC` | string \\\\| null | yes | M\xE3 tra c\u1EE9u the buyer looks the invoice up with; null on a draft\'s link answer |\n| `results[].MaCuaCQT` | string \\\\| null |  |  |\n| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |\n| `results[].MessLog` | string | yes |  |\n| `failed` | number | yes | Invoices whose own Status is not 0 |\n\n## 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. (workflow step, 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 (workflow step, 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## 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 `{fld_\u2026}`, 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_create_file (workflow step)\n\n- Create an Excel file with styled column headers and auto-filter enabled.\n- Input: { filename, sheets: [{ name, columns: [{ header, width? }], rows: unknown[][] }] } Headers are bold, centered, bordered, with auto-filter on the header row.\n- Best for producing polished report-style spreadsheets.\n- Returns a new file_id \u2014 use it for subsequent operations.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `sheets` | object[] | yes |  |\n| `sheets[].name` | string | yes |  |\n| `sheets[].columns` | object[] | yes |  |\n| `sheets[].columns[].header` | string | yes |  |\n| `sheets[].columns[].width` | number |  |  |\n| `sheets[].rows` | any[][] | yes | 2D array of cell values |\n| `filename` | string | 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### excel_find_cells (workflow step)\n\n- Search for cells matching a text query in an Excel worksheet.\n- Input: { file_id, worksheet: string\\|number, query: "search text", match_type?: "contains"\\|"exact"\\|"regex", max_results?: number } Default match_type is "contains" (case-insensitive).\n- Returns matching cell addresses, values, and positions.\n- Read-only \u2014 does not modify the file.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `worksheet` | string \\\\| number | yes |  |\n| `query` | string | yes | Text to find. |\n| `match_type` | "exact" \\\\| "contains" \\\\| "regex" |  | How to match: exact, contains (default), or regex |\n| `max_results` | number |  | Max matches to return |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `matches` | object[] | yes |  |\n| `matches[].cell` | string | yes | Cell address, e.g. B3 |\n| `matches[].value` | string | yes | Cell value as string |\n| `matches[].row` | number | yes | Row number |\n| `matches[].column` | string | yes | Column letter |\n| `total_matches` | number | yes | Total number of matches found |\n\n### excel_format_range (workflow step)\n\n- Apply formatting to a cell range (fonts, fills, borders, alignment, number formats). range format is always "START:END" \u2014 single cell: "B2:B2", multi-cell: "A1:D10".\n- Never use "B2" alone.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `worksheet` | string \\\\| number | yes |  |\n| `range` | string | yes |  |\n| `format` | object | yes |  |\n| `format.font_bold` | boolean |  |  |\n| `format.font_italic` | boolean |  |  |\n| `format.font_size` | number |  |  |\n| `format.font_color` | string |  | Hex color like #FF0000 |\n| `format.font_name` | string |  |  |\n| `format.font_underline` | "single" \\\\| "double" |  |  |\n| `format.font_strike` | boolean |  |  |\n| `format.background_color` | string |  | Hex color like #FFFF00 |\n| `format.horizontal_align` | "left" \\\\| "center" \\\\| "right" |  |  |\n| `format.vertical_align` | "top" \\\\| "middle" \\\\| "bottom" |  |  |\n| `format.wrap_text` | boolean |  |  |\n| `format.number_format` | string |  | Excel number format code (e.g. #,##0.00, dd/mm/yyyy) |\n| `format.border_top` | object |  |  |\n| `format.border_top.style` | "solid" \\\\| "dashed" \\\\| "dotted" \\\\| "double" |  |  |\n| `format.border_top.width` | number |  |  |\n| `format.border_top.color` | string |  |  |\n| `format.border_bottom` | object |  |  |\n| `format.border_bottom.style` | "solid" \\\\| "dashed" \\\\| "dotted" \\\\| "double" |  |  |\n| `format.border_bottom.width` | number |  |  |\n| `format.border_bottom.color` | string |  |  |\n| `format.border_left` | object |  |  |\n| `format.border_left.style` | "solid" \\\\| "dashed" \\\\| "dotted" \\\\| "double" |  |  |\n| `format.border_left.width` | number |  |  |\n| `format.border_left.color` | string |  |  |\n| `format.border_right` | object |  |  |\n| `format.border_right.style` | "solid" \\\\| "dashed" \\\\| "dotted" \\\\| "double" |  |  |\n| `format.border_right.width` | number |  |  |\n| `format.border_right.color` | string |  |  |\n| `column_widths` | object |  | Column letter \u2192 width mapping |\n| `row_heights` | object |  | Row number \u2192 height mapping |\n| `auto_filter` | string |  | Range for an auto-filter (e.g. A1:D1); one over a table turns on that table\'s own filter |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `formatted_cells` | number | yes |  |\n\n### excel_get_range (workflow step)\n\n- Read cell values from a range in an Excel worksheet. range format is always "START:END" \u2014 single cell: "B2:B2", multi-cell: "A1:D10".\n- Never use "B2" alone. worksheet: use sheet name (preferred) or 0-based index.\n- Use view_file first to see available worksheets.\n- Returns data keyed by row number then column letter, e.g. { "1": { "A": "Hello" } }.\n- Maximum 1000 cells per call \u2014 use smaller ranges and paginate if needed.\n- Read-only \u2014 does not modify the file.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `worksheet` | string \\\\| number | yes |  |\n| `range` | string | yes |  |\n| `options` | object |  | Options for data retrieval |\n| `options.include_formulas` | boolean |  | Include cell formulas instead of calculated values |\n| `options.include_formatting` | boolean |  | Include cell formatting information |\n| `options.max_cell_length` | number |  | Max characters returned per cell; longer text is truncated with an ellipsis. Pass -1 to return cells in full \u2014 use when reading free-text columns like notes. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `worksheet_name` | string | yes | The worksheet name |\n| `range` | string | yes | The requested range |\n| `data` | object | yes | Cell values keyed by row number then column letter |\n| `formatting` | object |  | Cell formatting keyed by row then column |\n| `truncated_cells` | object[] |  | Cells with truncated content |\n| `truncated_cells[].cell` | string | yes | Cell address |\n| `truncated_cells[].original_length` | number | yes | Original text length |\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 |  |\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### excel_update_range (workflow step)\n\n- Write cell values into a range in an Excel worksheet. range format is always "START:END" \u2014 single cell: "B2:B2", multi-cell: "A1:C3".\n- Never use "B2" alone. values is a 2D array matching the range dimensions.\n- Single cell: [["value"]], row: [["a","b","c"]], grid: [[r1...],[r2...]].\n- Strings starting with "=" are interpreted as formulas (e.g. "=SUM(A1:A10)").\n- Set options.interpret_formulas=false to write literal "=" text.\n- Modifies the document in place.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `worksheet` | string \\\\| number | yes |  |\n| `range` | string | yes |  |\n| `values` | any[][] | yes | 2D array of values to write (rows x columns) |\n| `options` | object |  |  |\n| `options.preserve_formatting` | boolean |  | Preserve existing cell formatting (only update values) |\n| `options.apply_number_format` | string |  | Apply a number format to all cells in the range (e.g., \'#,##0.00\') |\n| `options.interpret_formulas` | boolean |  | Set false to write \'=\' strings as literal text |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `worksheet_name` | string | yes |  |\n| `range` | string | yes |  |\n| `updated_cells` | number | yes | Number of cells updated |\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 |  |\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_image (workflow step)\n\n- Generate an image from a text prompt and save it to the workspace.\n- Returns a file_id usable as an image field value or attachment.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `prompt` | string | yes | Description of the image to generate. |\n| `size` | "1024x1024" \\\\| "1024x1536" \\\\| "1536x1024" |  | Square, portrait, or landscape. |\n| `quality` | "low" \\\\| "medium" \\\\| "high" |  | Higher quality costs more. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `url` | string | yes |  |\n| `width` | number | yes |  |\n| `height` | number | yes |  |\n| `mime_type` | 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_activity (workflow step)\n\n- List a record\'s activity, newest first: one entry per save \u2014 a person\'s edits made close together read as one, each field from before the first to after the last \u2014 and, inside an app\'s workflow, the comments the app takes.\n- A change entry says who made it and when, whether it made the record (created), whether it put an earlier change back (undo), who put it back since (undone), and whether the member the run acts for may put it back (undoable).\n- Inside an app\'s workflow the fields are the ones the app reads, and a record the app\'s own read does not reach for that member is not found.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `record_id` | string | yes |  |\n| `after` | string \\\\| null |  | A page\'s `next`. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `entries` | any[] | yes | Newest first. |\n| `next` | string |  | Where the trail continues: pass it as `after`. Absent at its end. |\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. (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 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 (workflow step, 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## import\n\n### import_rows (workflow step)\n\n- Match a source\'s rows to a table by a key and write what differs: a row whose match fields equal no live row\'s is added, one equalling a row\'s changes the cells that differ, one that changes nothing is counted and not written.\n- It keeps nothing of its own: what it wrote and what it held are its answer, read under the run\'s own reach of the table \u2014 a workflow hands its caller only what it returns. match names the fields that identify a row: text, number or date fields a row is written with, compared as trimmed text, case ignored, and link fields holding one row, compared by the row linked. values holds a row\'s cells by field key, as create_records takes them; a link cell also takes { "lookup": "<text>" }, the linked row found by that text in its table\'s unique or autonumber field, else its title, among the rows the run reads of that table, and a link holding many rows a list of them. (workflow step, chat, MCP, CLI)\n- A row is held, never written, when: it carries hold (its text is the message); several live rows or an earlier row of the call carry its key; a link\'s text names no row, or several; the table refuses it or its row is locked; create is false and no row carries its key; or, under conflicts "hold", a live cell holds another value \u2014 the row\'s empty cells are still written. conflicts "overwrite" writes over a differing cell, "fill_empty" leaves it. conflicts.fields sets one field\'s own.\n- A number and the field its unit or currency is read from are one cell, under the number\'s policy: both written, or both held.\n- A row whose key names a row outside the rows the run may write is held "refused" with nothing of that row: no record_id, no changes.\n- A row carrying remove: true proposes moving the row its key names to the trash: always held, whatever create and conflicts say, and counted unchanged where no row carries its key.\n- A row the source leaves out is never touched.\n- One call takes at most 10000 rows; more is refused with the count, never cut short.\n- Returns { read, created, changed, unchanged, held, written, written_omitted, held_rows, held_omitted }: the rows the call took, the rows it added, the rows it changed a cell of, the rows that changed nothing, and the rows held \u2014 a row can be both changed and held. written lists each record written: record_id, kind ("created" or "changed"), line, and changes \u2014 each field changed, with its field_key, its label and its before and after as text, as a read of the table shows them (an option\'s label, a linked row\'s display, a member\'s name; null where empty).\n- A created row lists no changes: its values are the row\'s own. held_rows lists each row held: kind ("create", "update", "remove", or "unmatched" where no row carries its key and create is false), reason, message, record_id where one row carries its key, key (each match field as text), the changes it would make, links (each link text naming no one row, with the rows it could be as candidates { id, display }), and values \u2014 its key and the cells it would write, as the call gave them.\n- A later call given those values under conflicts { "default": "overwrite" } writes it.\n- The two lists hold at most 10000 entries and 8388608 characters of JSON between them, each in the rows\' order, what was written before what was held; written_omitted and held_omitted count what was left out.\n- A row gives each list at most one entry.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `table_id` | string | yes |  |\n| `match` | string[] | yes |  |\n| `rows` | object[] | yes |  |\n| `rows[].values` | object | yes |  |\n| `rows[].hold` | string \\\\| null |  |  |\n| `rows[].remove` | boolean \\\\| null |  |  |\n| `rows[].line` | number \\\\| null |  | Its line in the source, 1-based. |\n| `create` | boolean \\\\| null |  |  |\n| `conflicts` | object \\\\| null |  |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `read` | number | yes |  |\n| `created` | number | yes |  |\n| `changed` | number | yes |  |\n| `unchanged` | number | yes |  |\n| `held` | number | yes |  |\n| `written` | object[] | yes |  |\n| `written[].record_id` | string | yes |  |\n| `written[].kind` | "created" \\\\| "changed" | yes |  |\n| `written[].line` | number |  |  |\n| `written[].changes` | object[] | yes |  |\n| `written[].changes[].field_key` | string | yes |  |\n| `written[].changes[].label` | string | yes |  |\n| `written[].changes[].before` | string \\\\| null | yes |  |\n| `written[].changes[].after` | string \\\\| null | yes |  |\n| `written_omitted` | number | yes |  |\n| `held_rows` | object[] | yes |  |\n| `held_rows[].line` | number |  |  |\n| `held_rows[].kind` | "create" \\\\| "update" \\\\| "remove" \\\\| "unmatched" | yes |  |\n| `held_rows[].reason` | "stated" \\\\| "removal" \\\\| "conflict" \\\\| "no_match" \\\\| "ambiguous_key" \\\\| "unresolved_link" \\\\| "ambiguous_link" \\\\| "locked" \\\\| "refused" | yes |  |\n| `held_rows[].message` | string | yes |  |\n| `held_rows[].record_id` | string |  |  |\n| `held_rows[].key` | object | yes |  |\n| `held_rows[].values` | object | yes |  |\n| `held_rows[].changes` | object[] | yes |  |\n| `held_rows[].changes[].field_key` | string | yes |  |\n| `held_rows[].changes[].label` | string | yes |  |\n| `held_rows[].changes[].before` | string \\\\| null | yes |  |\n| `held_rows[].changes[].after` | string \\\\| null | yes |  |\n| `held_rows[].links` | object[] | yes |  |\n| `held_rows[].links[].field_key` | string | yes |  |\n| `held_rows[].links[].text` | string | yes |  |\n| `held_rows[].links[].candidates` | object[] | yes |  |\n| `held_rows[].links[].candidates[].id` | string | yes |  |\n| `held_rows[].links[].candidates[].display` | string | yes |  |\n| `held_omitted` | number | yes |  |\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## 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\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` | any | yes | Raw dictionary records as returned by MISA |\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 | Caller-controlled UUID identifying the source document |\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 | Caller-controlled UUID identifying the source document |\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 | Caller-controlled UUID identifying the source document |\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 | Caller-controlled UUID identifying the source document |\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. (workflow step, 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 (workflow step, 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## 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- Send a notification to workspace members. recipients is an array of principals: { type, id }.\n- All members: [{ type: "organization", id: "{{organization_id}}" }] Who triggered: [{ type: "member", id: "{{triggered_by_member_id}}" }] A group: [{ type: "member_group", id: "<group_id>" }]\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| `level` | "urgent" \\\\| "warning" \\\\| "info" \\\\| "success" |  | Notification level: urgent, warning, info, success |\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## undo\n\n### undo_record_change (workflow step)\n\n- Put back one change entry of a record\'s activity, as the own save of the member the run acts for. entry_id is the entry\'s id as get_record_activity lists it. (workflow step)\n- Each field the entry changed returns to what it held before it where the record still holds what it wrote; a field changed since is kept.\n- Refused: the entry that made the record, an entry that is itself an undo, an entry already put back, and a record in the trash.\n- The member holds write access to the record\'s table as the step runs, the record within the rows they may write; a run that acts for no member is refused.\n- Returns { reverted, kept }: the fields put back, and those left as they stand, each with why.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `record_id` | string | yes |  |\n| `entry_id` | string | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `reverted` | object[] | yes | The fields put back to what they held before the change. |\n| `reverted[].field_id` | string | yes |  |\n| `reverted[].label` | string | yes |  |\n| `kept` | object[] | yes | The fields left as they stand, each with why. A field already holding what it held before the change is in neither list. |\n| `kept[].field_id` | string | yes |  |\n| `kept[].label` | string | yes |  |\n| `kept[].reason` | "changed_since" \\\\| "refused" | yes | Someone changed it since; or the table refused the write (a lock, a check). |\n\n### undo_record_changes (workflow step)\n\n- Put back what one workflow run wrote on records of a table, as the own writes of the member the run acts for.\n- A field the run changed returns to what it held before where the record still holds what the run wrote; a record the run created moves to the trash where nothing else has written it or linked a row to it since; a record the run moved to the trash comes back where nothing has touched it since, without the links to it its removal took off other rows.\n- A record the run wrote nothing on is left out, and so is a write of the run that was itself an undo.\n- The member holds write access to the table as the step runs, each record within the rows they may write; a run that acts for no member is refused.\n- Takes at most 500 record ids a call.\n- Returns { reverted, kept }: the count of records put back, and the records left as they stand, one entry a record and reason with the field keys kept \u2014 none where the whole record was.\n- A record created in a table where a workflow writes each new row reads as written since, and is kept.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `table_id` | string | yes |  |\n| `record_ids` | string[] | yes |  |\n| `workflow_execution_id` | string | yes | The run whose writes are put back: what runtime.execution_id held in it. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `reverted` | number | yes |  |\n| `kept` | object[] | yes |  |\n| `kept[].record_id` | string | yes |  |\n| `kept[].fields` | string[] | yes |  |\n| `kept[].reason` | "changed_since" \\\\| "refused" \\\\| "outside_your_rows" \\\\| "unreadable" \\\\| "restored" | yes | Someone changed it since \u2014 wrote it, moved it to the trash, or linked a row to it; the table refused the write (a lock, a check); it is outside the rows the caller may write; the trail of what was written cannot be read; or the run brought it back from the trash, where an undo returns no row. |\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## view\n\n### view_files (workflow step)\n\n- View one or more files in a single call.\n- Two modes: - file_ids: explicit list of file IDs (use for cherry-picked files). - source: every file attached to a record\'s file field (use when you want all photos/attachments on a record).\n- Provide exactly one.\n- Reads EVERY readable format: images, PDFs, Word (.docx and legacy .doc), Excel (.xlsx and legacy .xls), CSV, and text formats (.txt, .md, .json, .xml, .yaml, .html).\n- Batch limit: 100 files.\n- Use this whenever you are handed a file_id you cannot already see \u2014 images and PDFs arrive in your context natively, but every other format is a reference you must open with this tool.\n- Files already in your context \u2014 those the user attached to the current message, and those an earlier view_files call returned this conversation \u2014 return a text-only "already in context" reference instead of re-emitting bytes. (workflow step, chat)\n- You do not need to re-call view_files to look at the same image again; scroll back to the original tool_result. (workflow step, chat)\n- Calling with already-seen file_ids is safe but wasteful.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_ids` | string[] |  |  |\n| `source` | object |  |  |\n| `source.record_id` | string | yes |  |\n| `source.field_key` | string | yes |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `files` | object[] | yes |  |\n| `files[].file_id` | string | yes |  |\n| `files[].filename` | string | yes |  |\n| `files[].mime_type` | string | yes |  |\n| `files[].content` | object |  |  |\n| `files[].already_in_context` | boolean |  |  |\n| `files[].error` | string |  |  |\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## word\n\n### word_create_document (workflow step)\n\n- Create a new Word document (.docx), optionally with initial paragraphs and headings.\n- Use {{variable_name}} syntax in text to create template placeholders for data injection via create_word_template. (workflow step, chat, MCP, CLI)\n- Input: { filename, content?: [{ type: "paragraph"\\|"heading", text, level?: 1-6 }] } filename is without the .docx extension (added automatically).\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `filename` | string | yes | Name of the file (without .docx extension) |\n| `content` | object[] |  |  |\n| `content[].type` | "paragraph" \\\\| "heading" | yes |  |\n| `content[].text` | string | yes |  |\n| `content[].level` | number |  | Heading level (1-6), required when type is heading |\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### word_find_text (workflow step)\n\n- Search for text across all paragraphs and table cells in a Word document.\n- Input: { file_id, query: "search text", match_type?: "contains"\\|"exact"\\|"regex", max_results?: number } Default match_type is "contains".\n- Returns matching element indices, types, and text content.\n- Read-only \u2014 does not modify the file.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the Word (.docx) file |\n| `query` | string | yes |  |\n| `match_type` | "contains" \\\\| "exact" \\\\| "regex" |  |  |\n| `max_results` | number |  |  |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `matches` | object[] | yes |  |\n| `matches[].index` | number | yes |  |\n| `matches[].type` | "paragraph" \\\\| "table" \\\\| "other" | yes |  |\n| `matches[].text` | string | yes |  |\n| `total` | number | yes |  |\n\n### word_get_content (workflow step)\n\n- Read a Word document\'s full native content, paginated.\n- Every element returned is COMPLETE \u2014 full paragraph text and full table cells \u2014 unlike view_files, whose quick-look preview truncates long paragraphs and tables. (workflow step, chat)\n- Input: { file_id, offset?, limit? }.\n- Returns elements with their 0-based indices plus next_offset when more remains; call again with offset=next_offset to continue.\n- A page may end before `limit` to keep elements whole \u2014 follow next_offset, don\'t infer completion from the count.\n- A selection mark \u2014 a highlighted, shaded or coloured run, or a shaded table cell \u2014 surfaces in `marked_text` (the paragraph with each mark shown where it falls, which is what tells you WHICH of two identical `\u25A1` was picked), `highlighted_spans` (the marked text alone) and `marked_cells` (per table), so a form\'s chosen option reads correctly even when it is marked by colour rather than a tick.\n- Bold is OFF by default and reported only with `include_bold`, as a FACT rather than a selection: nearly every heading and label is bold, so on most documents it is noise.\n- Reach for it when a form\'s chosen option carries no glyph and no colour \u2014 some forms record the choice by bolding the chosen option\'s label, and then bold is the tick\'s only trace.\n- On a PARAGRAPH, `formatting_hint` already says the line contains bold (it cannot say which run \u2014 that is what `bold_spans` adds).\n- A TABLE carries no such hint, so on a criteria or option table pass `include_bold` rather than waiting for a signal.\n- Read the result against its siblings: a wholly bold heading or header row is structure, one bold label among plain ones is the choice.\n- Footnotes surface in `footnote_refs` (per paragraph) and `footnote_cells` (per table) with the note\'s own text, since a clause often carries its rule in the footnote rather than the sentence.\n- `orphaned_footnotes` lists notes the file carries with no anchor left in the body \u2014 those render nowhere.\n- Pictures surface in `images` on the element holding them, so a paragraph carrying only a picture is not mistaken for an empty one.\n- `headers_footers` carries header and footer text, which sits outside the body and so has no element index \u2014 a form often states which form it is there rather than in its text.\n- Read-only \u2014 does not modify the file.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the Word (.docx) file |\n| `offset` | integer |  | Element index to start from (pass the prior call\'s next_offset) |\n| `limit` | integer |  | Max elements to return |\n| `include_bold` | boolean |  | Also report WHERE the bold runs are (bold_spans / bold_cells). Off unless asked for \u2014 nearly every heading and label is bold, so it is noise on most documents and the answer on a form that ticks by bolding. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `elements` | object[] | yes |  |\n| `elements[].index` | number | yes |  |\n| `elements[].type` | "paragraph" \\\\| "table" \\\\| "other" | yes |  |\n| `elements[].text` | string |  |  |\n| `elements[].rows` | number |  |  |\n| `elements[].cols` | number |  |  |\n| `elements[].cells` | string[][] |  |  |\n| `elements[].heading_level` | number |  |  |\n| `elements[].list_type` | "bullet" \\\\| "numbered" |  |  |\n| `elements[].list_level` | number |  |  |\n| `elements[].formatting_hint` | string |  |  |\n| `elements[].highlighted_spans` | string[] |  |  |\n| `elements[].bold_spans` | string[] |  |  |\n| `elements[].marked_text` | string |  |  |\n| `elements[].images` | object[] |  |  |\n| `elements[].images[].name` | string |  |  |\n| `elements[].images[].width_cm` | number |  |  |\n| `elements[].images[].height_cm` | number |  |  |\n| `elements[].marked_cells` | object[] |  |  |\n| `elements[].marked_cells[].row` | number | yes |  |\n| `elements[].marked_cells[].col` | number | yes |  |\n| `elements[].marked_cells[].spans` | string[] | yes |  |\n| `elements[].bold_cells` | object[] |  |  |\n| `elements[].bold_cells[].row` | number | yes |  |\n| `elements[].bold_cells[].col` | number | yes |  |\n| `elements[].bold_cells[].spans` | string[] | yes |  |\n| `elements[].footnote_refs` | object[] |  |  |\n| `elements[].footnote_refs[].mark` | number | yes | The superscript number the reader sees |\n| `elements[].footnote_refs[].id` | string | yes |  |\n| `elements[].footnote_refs[].offset` | number | yes | Character offset into this element\'s text where the mark sits |\n| `elements[].footnote_refs[].text` | string |  |  |\n| `elements[].footnote_cells` | object[] |  |  |\n| `elements[].footnote_cells[].row` | number | yes |  |\n| `elements[].footnote_cells[].col` | number | yes |  |\n| `elements[].footnote_cells[].refs` | object[] | yes |  |\n| `elements[].footnote_cells[].refs[].mark` | number | yes | The superscript number the reader sees |\n| `elements[].footnote_cells[].refs[].id` | string | yes |  |\n| `elements[].footnote_cells[].refs[].offset` | number | yes | Character offset into this element\'s text where the mark sits |\n| `elements[].footnote_cells[].refs[].text` | string |  |  |\n| `total` | number | yes |  |\n| `next_offset` | number \\\\| null | yes |  |\n| `orphaned_footnotes` | object[] |  | Notes the file still carries with no anchor left in the body \u2014 they render nowhere |\n| `orphaned_footnotes[].id` | string | yes |  |\n| `orphaned_footnotes[].text` | string | yes |  |\n| `headers_footers` | object[] |  | Header and footer text \u2014 outside the body, so it carries no element index |\n| `headers_footers[].kind` | "header" \\\\| "footer" | yes |  |\n| `headers_footers[].text` | string | yes |  |\n\n### word_get_table_data (workflow step)\n\n- Read the full contents of a table in a Word document as a 2D string array.\n- Input: { file_id, table_index: number, max_rows? } table_index is the 0-based element index from view_files (must point to a table element). (workflow step, chat)\n- Returns data[][] with row_count and col_count.\n- A cell carrying a selection mark \u2014 a highlighted or shaded run, or a shaded cell \u2014 is listed in `marked_cells` ({row, col} aligned with data, spans = the marked text; empty spans = a shaded blank), so a criteria row\'s chosen option reads correctly even when it is marked by colour rather than a tick.\n- `bold_cells` lists the bold cells the same way, but ONLY with `include_bold` \u2014 header rows and label columns are bold, so it is noise on most tables.\n- Nothing in the default output hints that a table contains bold, so pass it whenever a criteria or option table shows no glyph and no colour: some forms record the choice by bolding that row\'s label and it is the tick\'s only trace.\n- It is a fact, never a selection \u2014 a whole bold header row is structure, one bold label among plain siblings is the choice.\n- Read-only \u2014 does not modify the file.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the Word (.docx) file |\n| `table_index` | number | yes | 0-based element index of the table |\n| `max_rows` | number |  | Max rows to return; all rows when omitted |\n| `include_bold` | boolean |  | Also report which cells are bold (bold_cells). Off unless asked for \u2014 header rows and label columns are bold, so it is noise on most tables and the answer on one that ticks by bolding. |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `data` | string[][] | yes |  |\n| `row_count` | number | yes |  |\n| `col_count` | number | yes |  |\n| `marked_cells` | object[] |  |  |\n| `marked_cells[].row` | number | yes |  |\n| `marked_cells[].col` | number | yes |  |\n| `marked_cells[].spans` | string[] | yes |  |\n| `bold_cells` | object[] |  |  |\n| `bold_cells[].row` | number | yes |  |\n| `bold_cells[].col` | number | yes |  |\n| `bold_cells[].spans` | string[] | yes |  |\n\n### word_insert_conditional (workflow step)\n\n- Insert {{IF variable_name}}...{{END-IF variable_name}} command rows or paragraphs into a Word document to define a conditional section.\n- For table_rows: wraps the specified row range with command rows.\n- Requires table_index, start_row, end_row.\n- For paragraphs: wraps the specified element range with command paragraphs.\n- Requires start_index, end_index.\n- Use view_files to find element indices first. (workflow step, chat)\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `variable_name` | string | yes | Boolean variable name |\n| `region_type` | "table_rows" \\\\| "paragraphs" | yes |  |\n| `table_index` | integer |  | Index of the table element (required for table_rows) |\n| `start_row` | integer |  | First row to wrap (required for table_rows) |\n| `end_row` | integer |  | Last row to wrap, inclusive (required for table_rows) |\n| `start_index` | integer |  | First element index to wrap (required for paragraphs) |\n| `end_index` | integer |  | Last element index to wrap, inclusive (required for paragraphs) |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n\n### word_insert_loop (workflow step)\n\n- Insert {{FOR loop_var IN variable_name}}...{{END-FOR loop_var}} command rows or paragraphs into a Word document to define a repeating section.\n- Inside the loop, reference each item\'s fields with a $ prefix: {{$loop_var.field}} (or {{$loop_var}} for a scalar item, {{$idx}} for the 0-based index).\n- Without the $ prefix, generation fails.\n- For table_rows: wraps the specified row range with command rows.\n- Requires table_index, start_row, end_row.\n- For paragraphs: wraps the specified element range with command paragraphs.\n- Requires start_index, end_index.\n- Use view_files to find element indices first. (workflow step, chat)\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `variable_name` | string | yes | Array variable name |\n| `loop_variable` | string | yes | Iterator name used inside the loop, e.g. item |\n| `region_type` | "table_rows" \\\\| "paragraphs" | yes |  |\n| `table_index` | integer |  | Index of the table element (required for table_rows) |\n| `start_row` | integer |  | First row to wrap (required for table_rows) |\n| `end_row` | integer |  | Last row to wrap, inclusive (required for table_rows) |\n| `start_index` | integer |  | First element index to wrap (required for paragraphs) |\n| `end_index` | integer |  | Last element index to wrap, inclusive (required for paragraphs) |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n\n### word_replace_text (workflow step)\n\n- Find and replace text across all paragraphs and table cells in a Word document.\n- Replaces all occurrences unless max_replacements is set.\n- A match spanning several runs collapses them into the first run\'s formatting, so tick a checkbox by matching the box character on its own \u2014 \u2610 (U+2610) becomes \u2612 (U+2612), keeping the font that draws both.\n- Matching the phrase around the box drags it into the body font; replacing it with a letter leaves a bare letter beside the boxes still showing \u2610.\n\n**Inputs**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes | The ID of the Word (.docx) file |\n| `find` | string | yes |  |\n| `replace` | string | yes |  |\n| `match_type` | "contains" \\\\| "exact" \\\\| "regex" |  | `exact` matches a whole paragraph. None of the three is case-sensitive. |\n| `max_replacements` | number |  | Max number of replacements (default: unlimited) |\n\n**Answer**\n\n| Name | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `file_id` | string | yes |  |\n| `replacements_made` | number | yes |  |\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';
 // docs/app_bindings.md
 var app_bindings_default = "# App bindings \u2014 the queries, workflows and agents an app calls\n\nA custom-code app reaches workspace data through three kinds of binding, each declared on the app\nunder an alias \u2014 a JS identifier (`/^[a-zA-Z_$][a-zA-Z0-9_$]*$/`):\n\n| Binding | Declared with | The app calls it with | An agent calls it with |\n|---|---|---|---|\n| Query | `set_app_queries` (CLI, chat) | `useQuery(\"<alias>\", params?)` | `run_app_query` |\n| Workflow | `set_app_workflow` | `useWorkflow(\"<alias>\")({ ...inputs })` | `run_app_workflow` |\n| Agent | `set_app_agent` (CLI, chat) | `useAgentRun(\"<alias>\")({ ...inputs })` | \u2014 |\n\nEach runs under the app's authority (`{ type: \"app\", app_id }`), the app owner's reach \u2014 never the\ncalling member's. Declaring one needs the app's owner or an admin. A write is live: the app's next\ncall uses it. `get_app_capabilities` lists an app's aliases with their params and inputs.\n\nEach reader returns a fingerprint of what it read \u2014 `get_app_workflow`'s `body_sha`, and on the CLI and in chat\n`get_app_query`'s `sha` and `get_app_agent`'s `instructions_sha` \u2014 and a write built on that read passes it back:\n`set_app_queries`' `expected_shas` (alias \u2192 `sha`), `set_app_workflow`'s `expected_body_sha`,\n`set_app_agent`'s `expected_instructions_sha`, `remove_app_binding`'s `expected_sha`. The write is\nrefused, and writes nothing, when the binding changed since; omit it for an unconditional write.\n\n## Queries\n\nA query declaration is `{ ast, params?, description?, templates? }`:\n\n- `ast` \u2014 a query template (a QueryNode, below). It fixes the tables, filters and columns the alias\n  reads, so a caller cannot widen it.\n- `params` \u2014 the typed value holes the caller fills, each an input declaration (see **Inputs**),\n  named in the ast as `{{params.<name>}}`. A param fills a VALUE position only \u2014 a filter value, a\n  `search` \u2014 never a `table_id` or a field key. Every token the ast names is declared. An optional\n  param left unset drops the conditions that read it; a required param that arrives empty is\n  refused where a filter reads it.\n- `description` \u2014 one line saying what the query returns, for an agent choosing between aliases.\n- `templates` \u2014 the document templates an export of its rows may fill, by name:\n  `{ <name>: { template_id: \"dtl_\u2026\", rows: \"<key the template lists the rows under>\" } }`.\n\nA save checks what a deploy checks: every table is in this workspace and within the owner's reach,\nevery projected, filtered and sorted field resolves, every param token is declared, and a key a\nnode's kind does not take (a stray `sort`, `limit`, `filter`, `search`) is refused by name.\n\nOn the CLI and in chat, `set_app_queries` takes `{ <alias>: <declaration> }`, one alias or several, and merges each: send\nonly the fields you change, `null` clears `params`, `description` or `templates` (never `ast`), and a\nnew alias needs an `ast`. Any other field is refused by name. An alias it omits is kept.\n`remove_app_binding` with `kind: \"query\"` deletes one; `get_app_query` reads one back.\n\n### The query tree\n\nEvery node has a `kind`; all but `from_table` read the node under `from` (`join`: `left`/`right`,\n`union`: `sources`).\n\n| `kind` | Keys |\n|---|---|\n| `from_table` | `table_id`, `filter?`, `search?`, `sort?`, `limit?` |\n| `project` | `columns` \u2014 the output columns |\n| `filter` | `predicate` \u2014 a filter tree over the input's columns |\n| `join` | `left`, `right`, `on: { left_column, right_column }`, `type: \"inner\" \\| \"left\"` |\n| `union` | `sources` (at least two, columns aligned by name and type) |\n| `group` | `by` (columns, `{ bucket: { source, granularity, output } }`, or `{ band: { source, tiers, output } }`), `aggregates` |\n| `window` | `partition_by`, `order_by`, `frame?`, `aggregates?`, `functions?` |\n| `sort` | `by: [{ field_key, order }]` |\n| `limit` | `n`, `offset?` or `keyset?` |\n| `unpivot` | `passthrough`, `row_columns`, `rows` \u2014 one source row into several |\n| `unnest` | `source`, `output`, `display_output?`, `keep_empty?` \u2014 one row per element of a multi-value cell |\n\nFilters (`from_table.filter`, `filter.predicate`, an aggregate's `filter`) are the filter grammar \u2014 the\n`filters` reference \u2014 over the input's columns, taking `{{params.x}}` as values. `search` matches\nevery text-bearing field of the row, accent- and case-insensitive.\n\nA `project` column is a field key as a bare string (output name and type come from the field), or\n`{ output?, type?, source, writable_target?, limit? }` to rename, compute or bound one. A computed\n`source` is a field key, `{ literal }`, `{ eq: [a, b] }`, `{ neq: [a, b] }`, `{ isEmpty }`,\n`{ isNotEmpty }`, `{ coalesce: [...] }`, `{ concat: [...] }`, `{ record_id: true }`,\n`{ link: { source, field } }` (a field of the first linked record),\n`{ link_agg: { source, field, operation } }` (`sum`, `avg`, `min`, `max`, `count`, `string_agg`\nover every linked record), or `{ expression }`. A computed column states its `type`: `text`,\n`number`, `boolean`, `date`, `datetime`, `select`, `select_record_link`, `select_member`, `files`\nor `json`. `limit` (1\u201310) bounds a `files` column's entries per cell.\n\nAn aggregate column is `{ output, type, operation, input_column?, filter? }` \u2014 `string_agg` also\ntakes `separator`, `distinct` and `max_values`. A `window` function is\n`{ output, fn }` for `row_number`, `rank`, `dense_rank`, `percent_rank`, `cume_dist`, plus\n`buckets` for `ntile` and `input_column`, `offset?`, `default?` for `lag` / `lead`; functions need\na non-empty `order_by`.\n\n## Inputs\n\nA query's `params`, a workflow's `inputs` and an agent's `inputs` are one vocabulary: a map of\nname \u2192 `{ type, required?, description?, \u2026per type }`. An entry is required unless it states\n`required: false`.\n\n| `type` | Takes |\n|---|---|\n| `text`, `number`, `boolean`, `date`, `datetime`, `email` | \u2014 |\n| `record_link` | `table_id`; `multi?`; `max?` (with `multi`, the most ids one call carries) |\n| `select` | exactly one of `options: [{ label, value }]` or `field: \"fld_\u2026\"` (a select field whose CURRENT options back it); `multi?` |\n| `date_range` | `include_time?` |\n| `member` | `multi?`; `group?` (a member group the value must belong to) |\n| `file` | `multi?` \u2014 an uploaded `fil_\u2026` id, for a files field |\n| `json` | \u2014 any value |\n| `object` | `fields` \u2014 a nested map of entries |\n| `array` | `items` \u2014 one entry |\n\nNesting stops at depth 8. A `field`-form select tracks the field's options as they change; an\ninline `options` set is a fixed list.\n\n## Outputs\n\nA workflow's and an agent's `outputs` declare the structured data handed back: a map of\nname \u2192 `{ type, required?, description?, \u2026per type }`, every entry present unless it states\n`required: false`.\n\n| `type` | Takes |\n|---|---|\n| `text`, `number`, `boolean`, `date`, `datetime`, `email`, `json` | \u2014 |\n| `record_link` | `table_id`, `multi?` |\n| `select` | exactly one of `options: [{ label, value }]` or `field: \"fld_\u2026\"`; `multi?` |\n| `object` | `fields` |\n| `array` | `items` |\n\nThe returned value is checked against it, and the app reads it typed. An inline `options` set is\nalso enforced on the value returned, so the producer is told the legal keys; a `field`-form select\nkeeps the type tracking the live field.\n\n## Workflows\n\n`set_app_workflow` binds a workflow body to an alias: `{ app_id, alias, source, inputs?, outputs?,\nname?, description? }`. On an app built from a model, the alias is one the model names \u2014 an act's own\n`workflow`, or an entry of the app's `workflows`, which states `inputs`, `outputs` and `description`:\na call stating any of them for it is refused, and outputs the entry leaves out are derived from the\nbody. An alias the model names nowhere is archived by the next apply. An entry of `workflows` runs\nonly for someone who holds the app: on an app shared by a public link, a visitor's call of it is\nrefused as an alias the app does not have.\n\n- `source` is the body with no `on({...})` trigger \u2014 the app is the trigger. It reads each declared\n  input as `trigger.app_workflow.inputs.<name>`; no record is in scope, so it reads each one by id\n  with `get_record`.\n  The body's steps are the `workflows` reference.\n- `inputs` is the payload the call site passes (see **Inputs**). Omitted, an existing workflow keeps\n  its inputs; on a first bind it takes an untyped payload. `{}` clears them.\n- `outputs` is what `return({ data })` hands back (see **Outputs**). Usually omit it: the type is\n  derived from the body's `return({ data })`, and the result echoes the bound `outputs`. Declared,\n  the body does not save unless its return matches.\n- A save checks the body \u2014 parse, type-check against the declared inputs, names, lint, structure \u2014\n  and answers with `[source/code] location: message` lines. `verify_only: true` makes every check\n  and writes nothing. A call naming a live alias replaces its body in place, keeping its run history.\n- A call whose payload does not match `inputs` is refused before the body runs.\n\n`get_app_workflow` reads the body back; `dry_run_workflow` with `trigger_type: \"app_workflow\"`\nruns it against sample inputs before binding; on the CLI and in chat, `remove_app_binding` with\n`kind: \"workflow\"` unbinds it.\n\n## Agents\n\nOn the CLI and in chat, `set_app_agent` binds a streaming tool-loop agent to an alias. A run streams its work to the app,\nreturns a typed result and keeps a run history per session.\n\nThe declaration:\n\n- `instructions` \u2014 the task, every run. A new alias needs it.\n- `tool_names` \u2014 the tools it may call, from these and no other: `analyze_pdf_template`,\n  `code_edit_file`, `code_exec`, `code_read_file`, `code_write_file`, `excel_create_file`,\n  `excel_find_cells`, `excel_format_range`, `excel_get_range`, `excel_update_range`,\n  `generate_bank_qr_code`, `generate_document`, `generate_image`, `generate_qr_code`, `get_template`,\n  `grep_knowledge`, `list_banks`, `list_knowledge`, `lookup_business`, `query_templates`,\n  `read_knowledge`, `run_app_query`, `run_app_workflow`, `validate_excel_template`,\n  `vietcombank_convert_currency`, `view_files`, `word_create_document`, `word_find_text`,\n  `word_get_content`, `word_get_table_data`, `word_insert_conditional`, `word_insert_loop`,\n  `word_replace_text`. `[]` is a reasoning-only agent. A few fields of a document read well through\n  the `excel_*` / `word_*` tools; a cross-check, reconciliation or transform a decision rests on\n  belongs in the code tools.\n- `query_aliases` / `workflow_aliases` \u2014 the app's own queries and workflows it may call through\n  `run_app_query` / `run_app_workflow`. They are its whole reach over records: no agent tool takes a\n  `table_id`, so a read is bounded by the query's tables, rows and columns, and a write goes through\n  the app's own workflow.\n- `knowledge_doc_ids` \u2014 knowledge docs it may read with `grep_knowledge` / `read_knowledge`\n  (declare them in `tool_names`). Each must be one the app owner and you can use. Nothing is\n  inlined and size does not matter. The list is the agent's whole reach \u2014 `list_knowledge` finds no\n  doc outside it \u2014 so name a doc's id in `instructions` to point it there. `code_exec` computes\n  across a corpus (counting, cross-referencing); reading needs only the knowledge tools.\n- `model_tier` \u2014 `haiku`, `sonnet` or `opus`. Omitted, the run follows the platform's default tier\n  and moves with new models; pin one only as a tested choice, and never `haiku`, a utility tier.\n- `effort_level` \u2014 `low`, `medium`, `high`, `xhigh` or `max`, one the pinned tier supports; it\n  needs `model_tier`.\n- `prefix_cache_ttl` \u2014 `5m` (the default) or `1h`. `1h` doubles the cache write price and pays only\n  when runs land 5 to 60 minutes apart, as a scheduled sweep does.\n- `inputs` \u2014 the per-run payload (see **Inputs**); omitted, the payload is untyped.\n- `outputs` \u2014 the structured result (see **Outputs**), checked before the run is saved and typed\n  as `run.output` in the app; omitted, the result is the final message.\n- `writes` \u2014 where the outputs land: `{ table_id, row, fields }`, `row` naming a single\n  `record_link` input to `table_id` and `fields` mapping each output name to a field key of that\n  table. A result that validates is written to that row under the app's authority.\n\nSend only what you change: an omitted field keeps its stored value, `null` clears an optional one.\nOn the CLI and in chat, `get_app_agent` reads one back; `remove_app_binding` with `kind: \"agent\"` deletes it.\n";