refactor: move skill to skills/inkreach-teable (from .agents/skills/)
git mv rename (history preserved); install.sh + README updated. The skill is consumed via user-level install (~/.zcode/skills), so in-repo .agents discovery was unnecessary.
This commit is contained in:
yeuimu
@@ -0,0 +1,333 @@
|
||||
# Action Types Reference
|
||||
|
||||
All 7 actions of the inkreach-teable automation engine. Actions run in topological order after the trigger; each receives the merged upstream output.
|
||||
|
||||
An action node:
|
||||
```json
|
||||
{
|
||||
"id": "node-2",
|
||||
"type": "action",
|
||||
"category": "<one of the 7 types below>",
|
||||
"config": { ... },
|
||||
"name": null
|
||||
}
|
||||
```
|
||||
|
||||
Use `inkreach-teable action add <wfId> --type <T> ...` (don't hand-build the JSON).
|
||||
|
||||
---
|
||||
|
||||
## Sandbox Globals (all script actions)
|
||||
|
||||
Inside a `script` action, these are available:
|
||||
|
||||
| Global | Description |
|
||||
|--------|-------------|
|
||||
| `triggerInput` | Merged output of trigger + all upstream actions. Contains `_accessToken`, `_apiBaseUrl`, `_baseId`, `_workflowId`, `_nodeId`, `_secrets`, `_publicOrigin` |
|
||||
| `console` | Captured to execution logs (`logs.stdout` / `logs.stderr`) |
|
||||
| `fetch` | Standard fetch (30s timeout recommended) |
|
||||
| `process.env` | Secrets (by name) + `AUTOMATION_TOKEN` + `PUBLIC_ORIGIN` |
|
||||
| `require` | Controlled — allows whitelisted npm deps declared via `dependencies` |
|
||||
|
||||
**NOT available**: `fs`, `eval`, `Function`, `process` (only `process.env`), `child_process`.
|
||||
|
||||
**Trigger user role** (user-initiated triggers only — buttonClick / recordCreated /
|
||||
recordUpdated / recordCondition / formSubmitted): when a real user fires the
|
||||
workflow, `triggerInput` also carries their role in THIS base:
|
||||
|
||||
| Field | Type | Meaning |
|
||||
|-------|------|---------|
|
||||
| `triggerInput.user` | `{id,name,email}` | Who triggered (absent for scheduledTime/webhook) |
|
||||
| `triggerInput._triggerUserRoles` | `string[]` | Display names of the user's enabled, non-deleted roles in this base. `[]` for admins (admins have no AM role) |
|
||||
| `triggerInput._triggerUserIsAdmin` | `boolean` | `true` for space owner, AM admin users, or everyone when AM is disabled for the base |
|
||||
|
||||
These fields are **absent** for system triggers (scheduledTime / webhook) — no
|
||||
user context. Branch on them in scripts:
|
||||
```js
|
||||
const roles = triggerInput._triggerUserRoles ?? [];
|
||||
const isAdmin = triggerInput._triggerUserIsAdmin ?? false;
|
||||
if (isAdmin) { /* admin path */ }
|
||||
else if (roles.includes('工厂运营')) { /* operator path */ }
|
||||
else if (roles.includes('售后客服')) { /* support path */ }
|
||||
```
|
||||
|
||||
**Back-channel API access**: inside scripts, call the instance's own API:
|
||||
```js
|
||||
const res = await fetch(triggerInput._apiBaseUrl + '/api/table/tblXXX/record', {
|
||||
headers: { Authorization: 'Bearer ' + triggerInput._accessToken }
|
||||
});
|
||||
```
|
||||
`_accessToken` is a 1-hour JWT auto-created on activation (scope: table|read + record|read/create/update).
|
||||
|
||||
---
|
||||
|
||||
## 1. script — Run JavaScript
|
||||
|
||||
```bash
|
||||
inkreach-teable action add <wfId> --type script \
|
||||
--code 'return { doubled: triggerInput.record.fields.Amount * 2 }'
|
||||
# or from a file
|
||||
inkreach-teable action add <wfId> --type script --code-file ./my-script.js --timeout 120000
|
||||
```
|
||||
|
||||
**With npm dependencies** (installed into a sandbox cache, then `require()`-able):
|
||||
```bash
|
||||
# JSON form (recommended)
|
||||
inkreach-teable action add <wfId> --type script \
|
||||
--code-file ./sync.js \
|
||||
--dependencies '[{"name":"axios","version":"1.6.0"},{"name":"dayjs","version":"1.11.10"}]'
|
||||
# shorthand: name@version,name (version omitted → 'latest')
|
||||
inkreach-teable action add <wfId> --type script --code-file ./sync.js --dependencies 'axios@1.6.0,dayjs'
|
||||
# replace / clear deps on an existing node
|
||||
inkreach-teable action update <wfId> <nodeId> --dependencies '[{"name":"axios"}]'
|
||||
inkreach-teable action update <wfId> <nodeId> --dependencies '[]' # clear
|
||||
```
|
||||
|
||||
> ⚠️ **Deployment requirement**: the backend installs deps via `spawn('npm')`, so `npm` must be on the **service** PATH. systemd user units default to a PATH that omits the nvm bin dir → scripts with deps fail with `spawn npm ENOENT`. Fix: add `Environment=PATH=<nvm-bin>:/usr/local/sbin:...` to `teable-backend.service`.
|
||||
|
||||
**Config:**
|
||||
```json
|
||||
{
|
||||
"code": "// JS code",
|
||||
"timeout": 60000,
|
||||
"dependencies": [ { "name": "axios", "version": "1.6.0" } ]
|
||||
}
|
||||
```
|
||||
- `timeout`: default 60000 (120000 in batch mode).
|
||||
- `dependencies`: optional npm packages; `require('axios')` works in-sandbox. Install is cached by `name@version` hash; first run downloads, later runs reuse. CLI accepts JSON `[{"name","version?"}]` or shorthand `name@version,name`. `update` replaces the whole array (not append).
|
||||
|
||||
> ⚠️ **`--config` must be the FLAT action config itself** — the JSON above, exactly as shown. It is assigned directly to `node.config` (CLI does `config = JSON.parse(opts.config)`).
|
||||
> Do **NOT** wrap it in a node envelope like `{"config": {...}}` or `{"type": "script", "config": {...}}` — the engine then reads `config.code` as `undefined` and the node becomes a **silent empty script**: it "succeeds" in ~1ms with empty stdout and `result: {}`, and every downstream `{{nodeId.result.*}}` variable reference breaks (e.g. sendNotification fails with `Missing required fields: message`).
|
||||
>
|
||||
> Correct: `--config '{"code":"return 1","timeout":120000}'` · Wrong: `--config '{"config":{"code":"return 1"}}'`
|
||||
>
|
||||
> **Verify after every `--config` deploy** (also guards against the automation editor overwriting CLI changes with a stale draft — close the editor before CLI updates):
|
||||
> ```bash
|
||||
> inkreach-teable workflow get <wfId> --base-id <bseId> --json | python3 -c "
|
||||
> import json,sys
|
||||
> d=json.load(sys.stdin)
|
||||
> for n in d.get('nodes',[]):
|
||||
> if n.get('id')=='<nodeId>':
|
||||
> c=n.get('config') or {}
|
||||
> print('keys:',list(c.keys()),'code-len:',len(c.get('code') or ''))"
|
||||
> # expect keys ['code','timeout',...] and code-len > 0
|
||||
> ```
|
||||
> Symptom cheat-sheet: script "succeeded" but `executionTime` ≈ 1ms, `stdout` empty, `result` `{}` → config shape was wrong (code never deployed).
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
{ "result": "<return value>", "logs": { "stdout": "...", "stderr": "..." }, "executionTime": 123 }
|
||||
```
|
||||
|
||||
In batch mode (`triggerInput.records` array):
|
||||
```js
|
||||
const records = triggerInput.records || [triggerInput.record];
|
||||
const results = await Promise.allSettled(records.map(async (r) => {
|
||||
// per-record work
|
||||
}));
|
||||
return { ok: results.filter(r => r.status === 'fulfilled').length };
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. sendEmail — Send an email
|
||||
|
||||
```bash
|
||||
inkreach-teable action add <wfId> --type sendEmail \
|
||||
--to user@example.com --subject 'Alert' --body '<p>Check this</p>'
|
||||
```
|
||||
|
||||
**Config:**
|
||||
```json
|
||||
{
|
||||
"to": "user@example.com",
|
||||
"subject": "Alert",
|
||||
"body": "<html>...</html>",
|
||||
"transporterName": "automation"
|
||||
}
|
||||
```
|
||||
- `transporterName`: `automation` (default) or `notify`. Requires SMTP configured on the server.
|
||||
|
||||
**Output:** `{ "sent": true, "to": "..." }`
|
||||
|
||||
Variable reference: `--body '{{n0.record.fields.Name}}'` injects upstream data.
|
||||
|
||||
---
|
||||
|
||||
## 3. httpRequest — Call an external API
|
||||
|
||||
```bash
|
||||
inkreach-teable action add <wfId> --type httpRequest \
|
||||
--url https://api.example.com/webhook --method POST \
|
||||
--headers '{"X-Api-Key":"xxx"}' --req-body '{"event":"test"}'
|
||||
```
|
||||
|
||||
**Config:**
|
||||
```json
|
||||
{
|
||||
"url": "https://...",
|
||||
"method": "POST",
|
||||
"headers": { "X-Api-Key": "xxx" },
|
||||
"body": { ... }
|
||||
}
|
||||
```
|
||||
- `method`: GET (default) | POST | PUT | PATCH | DELETE.
|
||||
- 30s hard timeout.
|
||||
- GET/HEAD do not send a body.
|
||||
|
||||
**Output:** `{ "statusCode": 200, "headers": {...}, "body": <parsed> }`
|
||||
|
||||
---
|
||||
|
||||
## 4. sendNotification — System in-app notification (站内信，非邮件)
|
||||
|
||||
```bash
|
||||
inkreach-teable action add <wfId> --type sendNotification \
|
||||
--to-user usr4ioKJl6XpZgyFhxW \
|
||||
--title '新工单' --message '工单 {{n0.record.id}} 已创建' \
|
||||
--severity info
|
||||
```
|
||||
|
||||
**Config:**
|
||||
```json
|
||||
{
|
||||
"toUserId": "usr4ioKJl6XpZgyFhxW",
|
||||
"title": "新工单",
|
||||
"message": "工单 {{n0.record.id}} 已创建",
|
||||
"path": "/base/bseX/table/tblY",
|
||||
"severity": "info"
|
||||
}
|
||||
```
|
||||
- `toUserId`: recipient user ID. Can reference the trigger user with `{{n0.user.id}}` (submitter/operator — only populated on user-initiated triggers; scheduled/webhook resolve to empty).
|
||||
- `title` + `message`: notification text; both support `{{nodeId.path}}` variables (or `{{index.path}}` — both formats resolve identically). If title set, rendered as `title\nmessage`.
|
||||
- `path` (optional): click-through URL in the notification center.
|
||||
- `severity`: `info` (default) | `warning` | `critical`.
|
||||
|
||||
**Empty-value semantics**: `toUserId` is required, but if it resolves to an **empty string** the node **silently skips** — status `succeeded`, `sentCount: 0`, output `{ sentCount: 0, invalidUserIds: [], toUserId: '', skipped: true, skipReason: 'toUserId is empty' }`, and `sendCommonNotify` is NOT called. This enables conditional-notify patterns: a script action that returns an empty recipient implements "notify only when X". An empty `message` still fails the node with `Missing required fields: message`.
|
||||
|
||||
**IMPORTANT**: this is a **system in-app notification** (bell badge + notification center + realtime socket push). It calls `NotificationService.sendCommonNotify` with `type=system` and **no email config — no email is sent**. Prefer it over `sendEmail` unless an actual email is required.
|
||||
|
||||
**Output:** `{ "sentCount": 1, "invalidUserIds": [], "toUserId": "usr..." }` (skipped case: see empty-value semantics above)
|
||||
|
||||
---
|
||||
|
||||
## 5. createRecord — Create records
|
||||
|
||||
```bash
|
||||
inkreach-teable action add <wfId> --type createRecord \
|
||||
--target-table tblXXX \
|
||||
--records '[{"fields":{"Name":"New","Source":"{{n0.record.id}}"}}]'
|
||||
```
|
||||
|
||||
**Config:**
|
||||
```json
|
||||
{
|
||||
"tableId": "tblXXX",
|
||||
"fieldKeyType": "id",
|
||||
"records": [ { "fields": { "fldName": "value" } } ]
|
||||
}
|
||||
```
|
||||
- `fieldKeyType`: `id` (default) or `name`.
|
||||
|
||||
**Output:** `{ "records": [ { "id": "recXXX", "fields": {...} } ] }`
|
||||
|
||||
---
|
||||
|
||||
## 6. updateRecord — Update records
|
||||
|
||||
```bash
|
||||
inkreach-teable action add <wfId> --type updateRecord \
|
||||
--target-table tblXXX \
|
||||
--records '[{"id":"recXXX","fields":{"Status":"Done"}}]'
|
||||
```
|
||||
|
||||
**Config:**
|
||||
```json
|
||||
{
|
||||
"tableId": "tblXXX",
|
||||
"fieldKeyType": "id",
|
||||
"records": [ { "id": "recXXX", "fields": { "fldStatus": "Done" } } ]
|
||||
}
|
||||
```
|
||||
- Each record **must** include `id` (recordId).
|
||||
|
||||
**Output:** `{ "records": [ ... ] }`
|
||||
|
||||
---
|
||||
|
||||
## 7. getRecords — Query records
|
||||
|
||||
```bash
|
||||
inkreach-teable action add <wfId> --type getRecords \
|
||||
--target-table tblXXX \
|
||||
--query '{"pageSize":100,"filter":{"conjunction":"and","filterSet":[]}}'
|
||||
```
|
||||
|
||||
**Config:**
|
||||
```json
|
||||
{
|
||||
"tableId": "tblXXX",
|
||||
"query": {
|
||||
"pageSize": 100,
|
||||
"page": 1,
|
||||
"filter": { "conjunction": "and", "filterSet": [...] },
|
||||
"orderBy": "fldXXX",
|
||||
"search": "keyword"
|
||||
}
|
||||
}
|
||||
```
|
||||
- `search` string is auto-normalized to the `search[]` tuple format the API expects.
|
||||
|
||||
**Output:** `{ "records": [...], "total": 123 }`
|
||||
|
||||
---
|
||||
|
||||
## Variable References
|
||||
|
||||
In any action's **string** config field, use `{{nodeId.path}}` to inject upstream output. The positional `{{index.path}}` form is also accepted — both resolve identically:
|
||||
|
||||
| Reference | Resolves to |
|
||||
|-----------|-------------|
|
||||
| `{{n0.record.id}}` (≡ `{{1.record.id}}`) | trigger record id (trigger = node 1) |
|
||||
| `{{n0.record.fields.fldStatus}}` | trigger record's Status field |
|
||||
| `{{n2.result}}` (≡ `{{2.result}}`) | script action's return value |
|
||||
| `{{n3.records}}` (≡ `{{3.records}}`) | getRecords output array |
|
||||
| `{{n2.statusCode}}` (≡ `{{2.statusCode}}`) | httpRequest status |
|
||||
|
||||
- **`{{nodeId.path}}`** — node ID form (teable generates ids like `n0`, `n1`, `n2`…). Preferred for clarity.
|
||||
- **`{{index.path}}`** — numeric form; **index = topological execution order** (trigger is always 1, then actions in chain order).
|
||||
|
||||
**Empty resolution**: when a referenced value is missing/undefined, the variable resolves to `''` (see sendNotification §4 for skip semantics).
|
||||
|
||||
Script actions can also read everything via `triggerInput` (the merged upstream output):
|
||||
```js
|
||||
const prev = triggerInput; // has all upstream fields merged
|
||||
```
|
||||
|
||||
## Common Action Patterns
|
||||
|
||||
### Call OpenAI with a secret
|
||||
```js
|
||||
// secret named OPENAI_KEY must be set first
|
||||
const res = await fetch('https://api.openai.com/v1/chat/completions', {
|
||||
method: 'POST',
|
||||
headers: { Authorization: 'Bearer ' + process.env.OPENAI_KEY, 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
model: 'gpt-4o-mini',
|
||||
messages: [{ role: 'user', content: triggerInput.record.fields.Prompt }]
|
||||
})
|
||||
});
|
||||
const data = await res.json();
|
||||
return { reply: data.choices[0].message.content };
|
||||
```
|
||||
|
||||
### Conditional logic
|
||||
```js
|
||||
const status = triggerInput.record.fields.Status;
|
||||
if (status === 'Done') {
|
||||
// call API
|
||||
return { skipped: false };
|
||||
}
|
||||
return { skipped: true };
|
||||
```
|
||||
(There's no dedicated "if" node — do branching inside a script.)
|
||||
@@ -0,0 +1,430 @@
|
||||
# Field Types Reference
|
||||
|
||||
Complete reference of all Teable field types, aliases, option shapes, and smart inference rules.
|
||||
|
||||
> ✅ **Verified 2026-08**: aliases, string choices, compact `--fields` format, smart
|
||||
> inference, and name resolution (`foreignTableName`/`linkFieldName`/`lookupFieldName`)
|
||||
> are implemented in the CLI (`src/lib/field-normalize.ts`, repo root)
|
||||
> and covered by unit tests (`field-normalize.spec.ts`, 20 cases).
|
||||
|
||||
---
|
||||
|
||||
## Type Overview
|
||||
|
||||
| `--type` value | Display name | Purpose | Requires `--options` |
|
||||
|---------------|-------------|---------|---------------------|
|
||||
| `singleLineText` | Single Line Text | Short text (titles, names, IDs) | No |
|
||||
| `longText` | Long Text | Rich text, descriptions, notes | No |
|
||||
| `number` | Number | Integers or decimals | No (defaults to integer) |
|
||||
| `singleSelect` | Single Select | Pick one from fixed options | Yes (`choices`) |
|
||||
| `multipleSelect` | Multiple Select | Pick many (tags/labels) | Yes (`choices`) |
|
||||
| `date` | Date | Date or datetime | No |
|
||||
| `checkbox` | Checkbox | Yes/no toggle | No |
|
||||
| `rating` | Rating | Star/numeric rating 1..10 | No (defaults: max=5, star, yellow) |
|
||||
| `attachment` | Attachment | Files, images, documents | No |
|
||||
| `user` | User | Person/collaborator reference | No |
|
||||
| `link` | Link | Reference records in another table | Yes (`foreignTableId`/`foreignTableName`) |
|
||||
| `lookup` | Lookup | Mirror a field from linked record | Yes (`lookupOptions`) |
|
||||
| `rollup` | Rollup | Aggregate linked records (SUM, COUNT, etc.) | Yes (expression + `lookupOptions`) |
|
||||
| `conditionalRollup` | Conditional Rollup | Aggregate from ANY table (no link required) | Yes (expression + `lookupOptions` + conditions) |
|
||||
| `formula` | Formula | Per-row computation | Yes (`expression`) |
|
||||
| `createdTime` | Created Time | Auto-set when record created | No |
|
||||
| `lastModifiedTime` | Last Modified Time | Auto-updated on any change | No |
|
||||
| `createdBy` | Created By | Auto-set to creator's user | No |
|
||||
| `lastModifiedBy` | Last Modified By | Auto-updated to last editor | No |
|
||||
| `autoNumber` | Auto Number | Auto-incrementing integer | No |
|
||||
| `button` | Button | Click-to-trigger automation | Yes (`workflow`; see Button section) |
|
||||
|
||||
### Date vs DateTime
|
||||
|
||||
There is no separate `dateTime` type. Use `date` and control the time component via `--options`:
|
||||
|
||||
```bash
|
||||
# Date-only
|
||||
--options '{"formatting":{"date":"YYYY-MM-DD","time":"None","timeZone":"UTC"}}'
|
||||
|
||||
# DateTime (with time)
|
||||
--options '{"formatting":{"date":"YYYY-MM-DD","time":"HH:mm","timeZone":"America/New_York"}}'
|
||||
```
|
||||
|
||||
| `time` value | Behavior |
|
||||
|-------------|----------|
|
||||
| `"None"` | Date only (no time picker) |
|
||||
| `"HH:mm"` | 24-hour time |
|
||||
| `"hh:mm A"` | 12-hour time with AM/PM |
|
||||
|
||||
---
|
||||
|
||||
## Type Aliases
|
||||
|
||||
When using `field create --type <alias>` or `table create --fields` compact format:
|
||||
|
||||
| Alias | Full type |
|
||||
|-------|-----------|
|
||||
| `text`, `str` | `singleLineText` |
|
||||
| `long` | `longText` |
|
||||
| `num`, `int` | `number` |
|
||||
| `check`, `bool` | `checkbox` |
|
||||
| `sel`, `select` | `singleSelect` |
|
||||
| `multi`, `tags` | `multipleSelect` |
|
||||
| `date` | `date` |
|
||||
| `rate`, `star` | `rating` |
|
||||
| `user`, `person` | `user` |
|
||||
| `file`, `attach` | `attachment` |
|
||||
| `link`, `rel` | `link` |
|
||||
| `rollup` | `rollup` |
|
||||
| `condRollup` | `conditionalRollup` |
|
||||
| `formula` | `formula` |
|
||||
| `auto` | `autoNumber` |
|
||||
| `created` | `createdTime` |
|
||||
| `modified` | `lastModifiedTime` |
|
||||
| `createdBy` | `createdBy` |
|
||||
| `modifiedBy` | `lastModifiedBy` |
|
||||
| `button` | `button` |
|
||||
|
||||
**`table create --fields` compact format** also supports inline select options:
|
||||
|
||||
| Format | Meaning |
|
||||
|--------|---------|
|
||||
| `"Name:text"` | Single line text field |
|
||||
| `"Amount:num"` | Number field |
|
||||
| `"Status:sel:Todo,Doing,Done"` | Single select with choices |
|
||||
| `"Tags:mul:Bug,Feature,UI"` | Multi-select with choices |
|
||||
| `"Done:check"` | Checkbox |
|
||||
| `"Score:rate"` | Rating (defaults) |
|
||||
|
||||
---
|
||||
|
||||
## Option Shapes by Type
|
||||
|
||||
### SingleSelect / MultipleSelect
|
||||
|
||||
```bash
|
||||
# Simple — strings only, colors auto-assigned
|
||||
inkreach-teable field create --table-id tblXXX --name "Status" --type singleSelect \
|
||||
--options '{"choices":["Todo","Doing","Done"]}'
|
||||
|
||||
# With explicit colors
|
||||
inkreach-teable field create --table-id tblXXX --name "Priority" --type singleSelect \
|
||||
--options '{"choices":[{"name":"High","color":"redBright"},{"name":"Low","color":"gray"}]}'
|
||||
|
||||
# With default value
|
||||
inkreach-teable field create --table-id tblXXX --name "Status" --type singleSelect \
|
||||
--options '{"choices":["Todo","Done"],"defaultValue":"Todo"}'
|
||||
```
|
||||
|
||||
| Option key | Type | Required | Notes |
|
||||
|-----------|------|----------|-------|
|
||||
| `choices` | `string[]` or `{name,color}[]` | yes | Colors auto-assigned from palette if omitted |
|
||||
| `defaultValue` | `string` (singleSelect) / `string[]` (multipleSelect) | no | Must match a choice name |
|
||||
| `preventAutoNewOptions` | `boolean` | no | Disable adding choices from cell editing |
|
||||
|
||||
**Available colors**: `blue`, `cyan`, `gray`, `green`, `orange`, `pink`, `purple`, `red`, `teal`, `yellow` — each with `Light2`, `Light1`, `Bright`, (base), `Dark1` variants. When colors are auto-assigned, the system cycles through a built-in palette.
|
||||
|
||||
### Number
|
||||
|
||||
```bash
|
||||
# Integer (default — no options needed)
|
||||
inkreach-teable field create --table-id tblXXX --name "Count" --type number
|
||||
|
||||
# Decimal with 2 places
|
||||
inkreach-teable field create --table-id tblXXX --name "Price" --type number \
|
||||
--options '{"formatting":{"precision":2}}'
|
||||
|
||||
# With default value
|
||||
inkreach-teable field create --table-id tblXXX --name "Quantity" --type number \
|
||||
--options '{"defaultValue":1}'
|
||||
```
|
||||
|
||||
| Option key | Type | Default | Notes |
|
||||
|-----------|------|---------|-------|
|
||||
| `formatting.precision` | `number` | `0` | Decimal places (0 = integer) |
|
||||
| `formatting.type` | `"decimal"` / `"integer"` | `"decimal"` | Number type |
|
||||
| `showAs` | object | — | Display as percentage, currency, etc. |
|
||||
| `defaultValue` | `number` | — | Numeric default for new records |
|
||||
|
||||
### Rating
|
||||
|
||||
```bash
|
||||
# Quick: default (max=5, star icon, yellow)
|
||||
inkreach-teable field create --table-id tblXXX --name "Score" --type rating
|
||||
|
||||
# Custom
|
||||
inkreach-teable field create --table-id tblXXX --name "Priority" --type rating \
|
||||
--options '{"max":3,"icon":"flame","color":"redBright"}'
|
||||
|
||||
# Max 10
|
||||
inkreach-teable field create --table-id tblXXX --name "NPS" --type rating \
|
||||
--options '{"max":10,"icon":"star","color":"tealBright"}'
|
||||
```
|
||||
|
||||
| Option key | Type | Default | Notes |
|
||||
|-----------|------|---------|-------|
|
||||
| `max` | `number` | `5` | 1–10 |
|
||||
| `icon` | `"star"` / `"moon"` / `"sun"` / `"zap"` / `"flame"` / `"heart"` / `"apple"` / `"thumb-up"` | `"star"` | Icon to display |
|
||||
| `color` | `"yellowBright"` / `"redBright"` / `"tealBright"` | `"yellowBright"` | Icon fill color |
|
||||
|
||||
### Date
|
||||
|
||||
```bash
|
||||
# Date only (default)
|
||||
inkreach-teable field create --table-id tblXXX --name "Due" --type date
|
||||
|
||||
# Date with time
|
||||
inkreach-teable field create --table-id tblXXX --name "Appointment" --type date \
|
||||
--options '{"formatting":{"date":"YYYY-MM-DD","time":"HH:mm","timeZone":"Asia/Shanghai"}}'
|
||||
|
||||
# Auto-fill with "now" for new records
|
||||
inkreach-teable field create --table-id tblXXX --name "Created At" --type date \
|
||||
--options '{"defaultValue":"now"}'
|
||||
```
|
||||
|
||||
| Option key | Type | Default | Notes |
|
||||
|-----------|------|---------|-------|
|
||||
| `formatting.date` | `string` | `"YYYY-MM-DD"` | Preset: `M/D/YYYY`, `D/M/YYYY`, `YYYY/MM/DD`, `YYYY-MM-DD`, `YYYY-MM`, `MM-DD`, `YYYY`, `MM`, `DD` |
|
||||
| `formatting.time` | `"None"` / `"HH:mm"` / `"hh:mm A"` | `"None"` | Time picker if not `"None"` |
|
||||
| `formatting.timeZone` | `string` | System local | IANA timezone name |
|
||||
| `defaultValue` | `"now"` | — | Auto-fills current time on new records |
|
||||
|
||||
### Link
|
||||
|
||||
```bash
|
||||
# Using table name (preferred)
|
||||
inkreach-teable field create --table-id tblXXX --name "Project" --type link \
|
||||
--options '{"foreignTableName":"Projects","relationship":"manyOne"}'
|
||||
|
||||
# Using table ID
|
||||
inkreach-teable field create --table-id tblXXX --name "Project" --type link \
|
||||
--options '{"foreignTableId":"tblXXX","relationship":"manyOne"}'
|
||||
|
||||
# Many-to-many
|
||||
inkreach-teable field create --table-id tblXXX --name "Tags" --type link \
|
||||
--options '{"foreignTableName":"Tags","relationship":"manyMany"}'
|
||||
```
|
||||
|
||||
| Option key | Type | Required | Notes |
|
||||
|-----------|------|----------|-------|
|
||||
| `foreignTableName` | `string` | * | Resolved to `foreignTableId` by CLI; preferred over ID |
|
||||
| `foreignTableId` | `string` | * | Direct ID; use `foreignTableName` instead |
|
||||
| `relationship` | `"oneOne"` / `"oneMany"` / `"manyOne"` / `"manyMany"` | yes | Direction is from THIS table to the FOREIGN table |
|
||||
| `isOneWay` | `boolean` | no | No symmetric field in foreign table |
|
||||
| `filterByViewId` | `string` | no | Limit selectable records to a view |
|
||||
| `visibleFieldIds` | `string[]` | no | Fields shown in linked record picker |
|
||||
|
||||
**Relationship quick reference**:
|
||||
|
||||
| Relationship | Meaning | Example |
|
||||
|-------------|---------|---------|
|
||||
| `manyOne` | Many records here → one record there | Tasks → Project |
|
||||
| `oneMany` | One record here → many records there | Project → Tasks |
|
||||
| `oneOne` | One-to-one | User ↔ Profile |
|
||||
| `manyMany` | Many-to-many | Tasks ↔ Tags |
|
||||
|
||||
> **Name resolution**: use `foreignTableName` instead of `foreignTableId` — the CLI resolves it. Preferred over manual ID lookups.
|
||||
|
||||
### Formula
|
||||
|
||||
```bash
|
||||
inkreach-teable field create --table-id tblXXX --name "Full Name" --type formula \
|
||||
--options '{"expression":"{fldFirstName} & \" \" & {fldLastName}"}'
|
||||
|
||||
inkreach-teable field create --table-id tblXXX --name "Total" --type formula \
|
||||
--options '{"expression":"{fldQuantity} * {fldPrice}"}'
|
||||
```
|
||||
|
||||
| Option key | Type | Required | Notes |
|
||||
|-----------|------|----------|-------|
|
||||
| `expression` | `string` | yes | Formula referencing fields by ID: `{fldXXX}` |
|
||||
| `timeZone` | `string` | no | For date functions |
|
||||
| `formatting` | object | no | Formatting for result (number/date) |
|
||||
|
||||
**Field references**: use `{fldXXX}` with field IDs. Get IDs from `field list <tableId>`.
|
||||
|
||||
### Rollup
|
||||
|
||||
```bash
|
||||
# Requires an existing link field + a target field in the linked table
|
||||
inkreach-teable field create --table-id tblXXX --name "Total Hours" --type rollup \
|
||||
--options '{"expression":"sum({values})"}' \
|
||||
--lookup-options '{"linkFieldName":"Tasks","lookupFieldName":"Hours","foreignTableId":"tblTasks"}'
|
||||
```
|
||||
|
||||
| Required | Meaning |
|
||||
|----------|---------|
|
||||
| `--options.expression` | Aggregation: `sum({values})`, `count({values})`, `average({values})`, `max({values})`, `min({values})`, `concatenate({values})`, `unique({values})`, `countDistinct({values})` |
|
||||
| `--lookup-options.linkFieldName` | The link field in THIS table pointing to the foreign table |
|
||||
| `--lookup-options.lookupFieldName` | The field in the FOREIGN table to aggregate |
|
||||
| `--lookup-options.foreignTableId` | The foreign table (typically same as the link field's target) |
|
||||
|
||||
**Name resolution**: `linkFieldName` and `lookupFieldName` accept field display names — CLI resolves them to IDs.
|
||||
|
||||
### Lookup
|
||||
|
||||
```bash
|
||||
# Mirror a field from a linked record
|
||||
inkreach-teable field create --table-id tblXXX --name "Project Name" --type singleLineText \
|
||||
--is-lookup \
|
||||
--lookup-options '{"linkFieldName":"Project","lookupFieldName":"Name","foreignTableId":"tblProjects"}'
|
||||
```
|
||||
|
||||
Lookup uses the base type of the field being mirrored (here copied as `singleLineText`), with `--is-lookup` and `--lookup-options`.
|
||||
|
||||
### ConditionalRollup
|
||||
|
||||
```bash
|
||||
# Aggregate from ANY table without a link field
|
||||
inkreach-teable field create --table-id tblXXX --name "Active Tasks" --type conditionalRollup \
|
||||
--options '{"expression":"sum({values})"}' \
|
||||
--lookup-options '{"lookupFieldName":"Estimate","foreignTableId":"tblTasks"}' \
|
||||
--conditions '{"conjunction":"and","filterSet":[{"fieldId":"fldStatus","operator":"isNot","value":"Done"}]}'
|
||||
```
|
||||
|
||||
### Button
|
||||
|
||||
```bash
|
||||
# Create a button field bound to a workflow
|
||||
inkreach-teable field create --table-id tblXXX --name "Approve" --type button \
|
||||
--options '{"label":"Approve","color":"blue","workflow":{"id":"wflXXX","name":"Approval Flow"}}'
|
||||
|
||||
# With click limit
|
||||
inkreach-teable field create --table-id tblXXX --name "Run Once" --type button \
|
||||
--options '{"label":"Run","color":"teal","maxCount":1,"workflow":{"id":"wflXXX"}}'
|
||||
|
||||
# With confirmation dialog
|
||||
inkreach-teable field create --table-id tblXXX --name "Delete" --type button \
|
||||
--options '{"label":"Delete","color":"red","workflow":{"id":"wflXXX"},"confirm":{"title":"Are you sure?","description":"This cannot be undone","confirmText":"Yes, delete"}}'
|
||||
```
|
||||
|
||||
| Option key | Type | Required | Default | Notes |
|
||||
|-----------|------|----------|---------|-------|
|
||||
| `label` | `string` | no | `"Button"` | Display text on the button |
|
||||
| `color` | Color enum | no | `"teal"` | Button color |
|
||||
| `workflow.id` | `string` | **yes** | — | Workflow ID triggered on click |
|
||||
| `workflow.name` | `string` | no | — | Workflow display name (informational) |
|
||||
| `workflow.isActive` | `boolean` | no | — | Captured at creation time; reflects whether workflow was active |
|
||||
| `maxCount` | `number` | no | — | Max clicks per record; empty = unlimited |
|
||||
| `resetCount` | `boolean` | no | — | Reset click count behavior |
|
||||
| `confirm.title` | `string` | no | — | Confirmation dialog title |
|
||||
| `confirm.description` | `string` | no | — | Confirmation dialog body |
|
||||
| `confirm.confirmText` | `string` | no | — | Confirm button label |
|
||||
|
||||
**Available button colors**: `blueLight2`, `blueLight1`, `blueBright`, `blue`, `blueDark1`, `cyan`, `cyanBright`, `cyanDark1`, `gray`, `grayBright`, `grayDark1`, `green`, `greenBright`, `greenDark1`, `orange`, `orangeBright`, `orangeDark1`, `pink`, `pinkBright`, `pinkDark1`, `purple`, `purpleBright`, `purpleDark1`, `red`, `redBright`, `redDark1`, `teal`, `tealBright`, `tealDark1`, `yellow`, `yellowBright`, `yellowDark1`.
|
||||
|
||||
**Key behaviors**:
|
||||
|
||||
1. **Workflow binding**: button clicks fire the `buttonClick` trigger of the bound workflow. The workflow MUST be active (`inkreach-teable workflow activate wflXXX`) for the button to be clickable.
|
||||
2. **`workflow.isActive` snapshot**: captured when the field is created. If the workflow is deactivated later, the field's `isActive` goes stale — the button won't be clickable. Resolve by updating the field options or re-activating the workflow.
|
||||
3. **Billing**: in this self-hosted CE fork, button fields are **always available** — billing gate is lifted.
|
||||
4. **Cell value**: read-only `{"count": N}` tracking click count. Automatically incremented by the backend.
|
||||
5. **Click limit**: when `maxCount` is set and count reaches it, button becomes disabled.
|
||||
|
||||
---
|
||||
|
||||
### Last Modified Time (tracked-field references)
|
||||
|
||||
A `lastModifiedTime` field can track **only specific fields** instead of all of them, so
|
||||
the timestamp resets when a referenced field changes but stays put on ordinary edits.
|
||||
Write the references inside the `expression` option:
|
||||
|
||||
```bash
|
||||
# Track by field name — resets only when 流转状态 or 流转角色 change
|
||||
inkreach-teable field create --table-id tblXXX --name "流转时间" --type lastModifiedTime \
|
||||
--options '{"expression":"LAST_MODIFIED_TIME([流转状态],[流转角色])"}'
|
||||
|
||||
# Track by field id (mixed syntax also allowed)
|
||||
inkreach-teable field create --table-id tblXXX --name "流转时间" --type lastModifiedTime \
|
||||
--options '{"expression":"LAST_MODIFIED_TIME({fldAbc123},{fldDef456})"}'
|
||||
```
|
||||
|
||||
| Reference syntax | Meaning |
|
||||
|---|---|
|
||||
| `LAST_MODIFIED_TIME()` | Track **all** fields (default) |
|
||||
| `LAST_MODIFIED_TIME([Name])` | Reference a field by its name |
|
||||
| `LAST_MODIFIED_TIME({fldId})` | Reference a field by its id |
|
||||
|
||||
**Key behaviors**:
|
||||
|
||||
1. The expression is parsed server-side into `trackedFieldIds` (the field's effective
|
||||
`options.trackedFieldIds`); the stored `expression` is normalized back to the canonical
|
||||
`LAST_MODIFIED_TIME()` form while `trackedFieldIds` carries the references.
|
||||
2. An unresolvable field **name** returns `400 Unknown field referenced in expression: <name>`;
|
||||
unresolvable `{fldId}` values are simply ignored (harmless — never match).
|
||||
3. You can also set `options.trackedFieldIds` directly (an array of field ids); an explicit
|
||||
`trackedFieldIds` wins over the expression when both are present.
|
||||
4. Works on create **and** convert (`PUT /api/table/:tableId/field/:fieldId/convert` with
|
||||
`{"type":"lastModifiedTime","options":{"expression":"..."}}`).
|
||||
|
||||
---
|
||||
|
||||
## Smart Inference
|
||||
|
||||
### Type inference from `--name`
|
||||
|
||||
When `--type` is omitted, the CLI infers the type from the field name:
|
||||
|
||||
| Name pattern | Inferred type |
|
||||
|-------------|---------------|
|
||||
| `status`, `priority`, `category`, `type`, `stage`, `level` | `singleSelect` |
|
||||
| `tag`, `label` | `multipleSelect` |
|
||||
| `description`, `notes`, `comment`, `content`, `body` | `longText` |
|
||||
| `count`, `amount`, `price`, `quantity`, `total`, `number`, `age` | `number` |
|
||||
| `rating`, `score`, `stars` | `rating` |
|
||||
| `is*`, `has*`, `active`, `enabled`, `done`, `completed` | `checkbox` |
|
||||
| `assignee`, `owner`, `user` | `user` |
|
||||
| `attachment`, `file`, `image`, `photo`, `document` | `attachment` |
|
||||
| `email`, `url` | `singleLineText` |
|
||||
| `created time`, `created` (without "by") | `createdTime` |
|
||||
| `last modified`, `updated` (without "by") | `lastModifiedTime` |
|
||||
| `created by`, `author` | `createdBy` |
|
||||
| `modified by`, `updated by` | `lastModifiedBy` |
|
||||
|
||||
### Options inference
|
||||
|
||||
| If you pass | Type inferred | Notes |
|
||||
|-------------|--------------|-------|
|
||||
| `--options '{"choices":["A","B"]}'` (no `--type`) | `singleSelect` | Colors auto-assigned |
|
||||
| `--options '{"max":5}'` (no `--type`) | `rating` | Icon `star`, color `yellowBright` defaults applied |
|
||||
| `--options '{"foreignTableName":"X"}'` (no `--type`) | `link` | |
|
||||
| `--options '{"expression":"..."}'` (no `--type`) | `formula` | Unless combined with `foreignTableId` + conditions → `conditionalRollup` |
|
||||
| `--options '{"workflow":{"id":"wflXXX"}}'` (no `--type`) | `button` | |
|
||||
| No `--type`, no `--options` | Depot on `--name` pattern | Falls back to `singleLineText` if no match |
|
||||
|
||||
### Options defaults
|
||||
|
||||
| Type | Defaults applied when omitted |
|
||||
|------|------------------------------|
|
||||
| `rating` | `{"max":5,"icon":"star","color":"yellowBright"}` |
|
||||
| `number` | `{"formatting":{"precision":0,"type":"decimal"}}` |
|
||||
| `date` | `{"formatting":{"date":"YYYY-MM-DD","time":"None","timeZone":"<system>"}}` |
|
||||
| `button` | `{"label":"Button","color":"teal"}` |
|
||||
| `singleSelect` / `multipleSelect` | Choices auto-colored if no `color` in choice objects |
|
||||
|
||||
---
|
||||
|
||||
## Typecast Reference
|
||||
|
||||
`--typecast` converts human-readable values to internal IDs on `record create`/`record update`.
|
||||
|
||||
| Field type | Without typecast | With typecast |
|
||||
|-----------|-----------------|---------------|
|
||||
| `user` | `{"id":"usrXXX","title":"Alice"}` | `"Alice"` or `"alice@example.com"` |
|
||||
| `link` (single) | `{"id":"recXXX"}` or `[{"id":"recXXX"}]` | `"Record Display Name"` |
|
||||
| `link` (multi) | `[{"id":"recA"},{"id":"recB"}]` | `["Record A","Record B"]` |
|
||||
|
||||
**When to use**: always use `--typecast` when creating/updating records with user or link fields — it eliminates manual ID lookups.
|
||||
|
||||
---
|
||||
|
||||
## Field Type Selection Guide
|
||||
|
||||
| Data shape | Use | Not |
|
||||
|-----------|-----|-----|
|
||||
| Fixed options (status, priority) | `singleSelect` | `singleLineText` (no color/filter) |
|
||||
| Multiple tags per record | `multipleSelect` | `singleSelect` (only one value) |
|
||||
| Numbers with decimals | `number` with `precision` | `singleLineText` (can't calculate) |
|
||||
| 1–10 ratings | `rating` | `number` (no star UI) |
|
||||
| Yes/no flags | `checkbox` | `number` 0/1 (worse UX) |
|
||||
| Dates/times | `date` with time formatting | `singleLineText` (can't sort/filter) |
|
||||
| Reference another table | `link` | `singleSelect` (hardcoded list; breaks when added) |
|
||||
| Auto-increment IDs | `autoNumber` | Manual numbering |
|
||||
| Trigger an action | `button` | Any other type |
|
||||
@@ -0,0 +1,265 @@
|
||||
# Trigger Types Reference
|
||||
|
||||
All 8 triggers of the inkreach-teable automation engine. **Use these exact config keys** — they differ from official teable and from the (stale) `docs/automation/triggers.md`.
|
||||
|
||||
Every trigger node has this shape (stored in `workflow_node`):
|
||||
```json
|
||||
{
|
||||
"id": "node-1",
|
||||
"type": "trigger",
|
||||
"category": "<one of the 8 types below>",
|
||||
"config": { ... },
|
||||
"name": null
|
||||
}
|
||||
```
|
||||
|
||||
> You don't build this JSON by hand — use `inkreach-teable trigger set <wfId> --type <T> ...` which constructs it correctly.
|
||||
|
||||
---
|
||||
|
||||
## 1. recordCreated — When a record is created
|
||||
|
||||
```bash
|
||||
inkreach-teable trigger set <wfId> --type recordCreated --table-id tblXXX \
|
||||
[--conditions '<filter json>'] \
|
||||
[--batch '{"enabled":true,"batchWindow":2000,"batchSize":100}']
|
||||
```
|
||||
|
||||
**Config:**
|
||||
```json
|
||||
{
|
||||
"tableId": "tblXXX",
|
||||
"conditions": null,
|
||||
"batch": { "enabled": false, "batchWindow": 2000, "batchSize": 100 }
|
||||
}
|
||||
```
|
||||
|
||||
**Output variables** (available to downstream actions):
|
||||
- `record.id`, `record.fields.<fieldId>`
|
||||
- `user` (who created)
|
||||
- `tableId`
|
||||
|
||||
---
|
||||
|
||||
## 2. recordUpdated — When a record is updated
|
||||
|
||||
```bash
|
||||
inkreach-teable trigger set <wfId> --type recordUpdated --table-id tblXXX \
|
||||
--field-ids '["fldXXX"]' \
|
||||
[--batch '{...}']
|
||||
```
|
||||
|
||||
**Config:**
|
||||
```json
|
||||
{
|
||||
"tableId": "tblXXX",
|
||||
"fieldIds": ["fldXXX"],
|
||||
"batch": { ... }
|
||||
}
|
||||
```
|
||||
- `fieldIds: []` (empty) = watch **all** fields (including future-created ones).
|
||||
- ⚠️ **Key is `fieldIds`, NOT `watchFieldIds`.**
|
||||
- ⚠️ recordUpdated **ignores `conditions`** — use `recordCondition` if you need filtering.
|
||||
|
||||
**Output:** `record.id`, `record.fields.*` (post-update values), `oldFields.*` (pre-update values, field-ID keys), `user`, `tableId`, `changedFieldIds` (array of field IDs whose value changed).
|
||||
|
||||
**changedFieldIds / oldFields semantics** (delivered on both v1 and v2 API update paths):
|
||||
- `oldFields` = full pre-update field snapshot keyed by field ID; `changedFieldIds` = deep-equal diff of before/after snapshots.
|
||||
- ⚠️ **`oldFields` is TOP-LEVEL** (`triggerInput.oldFields.fldXXX`), a sibling of `record` — NOT nested inside `record`. Script access: `triggerInput.oldFields?.['fldXXX']`; variable reference: `{{n0.oldFields.fldXXX}}`.
|
||||
- `fieldIds` watch-filter matches against `changedFieldIds`.
|
||||
- On batch mode (`_batch`), each `records[]` entry carries its own `changedFieldIds` + `oldFields`.
|
||||
- ⚠️ **Write-path coverage** (verified 2026-08): browser grid cell edits DO fire this trigger — every grid editor commit funnels through `record.updateCell` → the REST `updateRecord` API (no ShareDB op submit exists in the frontend). Covered surfaces: single/batch record update (REST v1+v2), grid paste (small `paste-by-id`, large `paste-*-stream`, range `paste`), grid cell clear (`clear` / `clear-by-id`), record duplicate, and programmatic/automation writes (workflow actions call the REST API). Form submissions intentionally emit ONLY the `formSubmitted` event (independent channel). Record deletions emit no automation event (no delete trigger category exists).
|
||||
- Values resolve to `undefined` (not `[]`) if the emitting path could not snapshot before-values — scripts should guard `changedFieldIds ?? []`.
|
||||
|
||||
**Workflow-write echo suppression** (all 4 record triggers: `recordCreated` / `recordUpdated` / `recordCondition` / `recordCreatedOrUpdated`):
|
||||
- Writes made BY workflow executions (script `fetch` with `triggerInput._accessToken`, `createRecords`/`updateRecords` actions) are tagged `writeSource: {workflowId, executionId}` on the event.
|
||||
- **Self-echoes are always dropped**: a workflow never fires on its own writes (the script's PATCH re-triggering its own workflow was the duplication bug — one edit cascaded into 3-5 executions, every echo ending in a `skipped` no-op guard).
|
||||
- Writes by OTHER workflows still fire by default — cross-workflow chaining is load-bearing (e.g. the order-sync job 建档 and this workflow stamping the initial 待处理). Opted-in events carry `triggerInput.writeSource.workflowId` for loop-guarding inside scripts.
|
||||
- Config `"skipWorkflowWrites": true` additionally drops cross-workflow writes (stronger dedup when a workflow should react ONLY to human edits).
|
||||
- Human grid edits, form/API/CLI writes are never tagged and always fire; suppressed writes still reach other listeners (e.g. record subscriptions) — only record-trigger handlers drop them.
|
||||
|
||||
---
|
||||
|
||||
## 3. recordCondition — When a record matches conditions
|
||||
|
||||
```bash
|
||||
inkreach-teable trigger set <wfId> --type recordCondition --table-id tblXXX \
|
||||
--conditions '{"conjunction":"and","filterSet":[{"fieldId":"fldStatus","operator":"is","value":"Done"}]}'
|
||||
```
|
||||
|
||||
**Config:**
|
||||
```json
|
||||
{
|
||||
"tableId": "tblXXX",
|
||||
"conditions": { "conjunction": "and", "filterSet": [ ... ] },
|
||||
"batch": { ... }
|
||||
}
|
||||
```
|
||||
- ⚠️ **Category is `recordCondition`, NOT `recordMatchesConditions`.**
|
||||
- `conditions` is **required**.
|
||||
- Fires on create AND update when the record transitions to matching.
|
||||
|
||||
**conditions structure** (same as view filters):
|
||||
```json
|
||||
{
|
||||
"conjunction": "and" | "or",
|
||||
"filterSet": [
|
||||
{ "fieldId": "fldXXX", "operator": "is", "value": "Done" },
|
||||
{ "fieldId": "fldNum", "operator": "isGreater", "value": 100 }
|
||||
]
|
||||
}
|
||||
```
|
||||
Common operators: `is`, `isNot`, `isEmpty`, `isNotEmpty`, `isAnyOf`, `isNoneOf`, `contains`, `isGreater`, `isLess`, `isAfter`, `isBefore`.
|
||||
|
||||
**Output:** `record.id`, `record.fields.*`, `user`, `tableId`; on update events also top-level `oldFields.*` + `changedFieldIds` (see §2 semantics).
|
||||
|
||||
---
|
||||
|
||||
## 4. recordCreatedOrUpdated — When a record is created or updated
|
||||
|
||||
```bash
|
||||
inkreach-teable trigger set <wfId> --type recordCreatedOrUpdated --table-id tblXXX \
|
||||
[--conditions '<filter json>'] \
|
||||
[--batch '{...}']
|
||||
```
|
||||
|
||||
**Config:**
|
||||
```json
|
||||
{ "tableId": "tblXXX", "conditions": null, "batch": { ... } }
|
||||
```
|
||||
- Ignores `fieldIds` (watches all fields).
|
||||
- `conditions` optional.
|
||||
|
||||
**Output:** same as recordCreated; on update events also top-level `oldFields.*` + `changedFieldIds` (see §2 semantics).
|
||||
|
||||
---
|
||||
|
||||
## 5. formSubmitted — When a form is submitted
|
||||
|
||||
```bash
|
||||
inkreach-teable trigger set <wfId> --type formSubmitted --table-id tblXXX --form-ids 'viwXXX1,viwXXX2'
|
||||
```
|
||||
|
||||
**Config:**
|
||||
```json
|
||||
{ "tableId": "tblXXX", "formIds": ["viwXXX1", "viwXXX2"] }
|
||||
```
|
||||
- `formIds` is an array of **form view ids** (views of type `form`). The trigger
|
||||
fires when **any** of the listed forms is submitted.
|
||||
- **Legacy compatibility:** the older single-string `formId` key is still
|
||||
accepted (migrated to `[formId]` automatically), so existing workflows keep
|
||||
working.
|
||||
- An empty `formIds` array means the trigger never fires.
|
||||
|
||||
**Output:** `record.id`, `record.fields.*`, `user`, `tableId`, `formId`.
|
||||
|
||||
---
|
||||
|
||||
## 6. scheduledTime — On a schedule
|
||||
|
||||
```bash
|
||||
inkreach-teable trigger set <wfId> --type scheduledTime \
|
||||
--schedule '{"timing":{"type":"minutes","interval":5}}'
|
||||
```
|
||||
|
||||
**Config (only these fields are honored):**
|
||||
```json
|
||||
{ "timing": { "type": "minutes", "interval": 5 } }
|
||||
```
|
||||
|
||||
| `timing.type` | `interval` range | Meaning |
|
||||
|---------------|------------------|---------|
|
||||
| `minutes` | 1–60 | Every N minutes |
|
||||
| `hours` | 1–24 | Every N hours |
|
||||
| `days` | 1–N | Every N days |
|
||||
| `months` | 1–N | Every N months (uses a fixed day) |
|
||||
|
||||
⚠️ **Backend limitations (known gotchas):**
|
||||
- `triggerTime`, `weekdays`, `daysOfMonth`, `starting`, `ending`, `tz` are **all IGNORED**.
|
||||
- `weeks` type is hardcoded to every Sunday (ignores `weekdays`).
|
||||
- `OneTime` type is unsupported → falls back to every 60s.
|
||||
- The scheduler is in-process `setInterval`; **multi-instance deployments fire duplicates**.
|
||||
|
||||
If you need precise scheduling, set `interval` to a friendly value. Do NOT pass the extra fields — they give false confidence.
|
||||
|
||||
**Output:** none useful (no record context); typically used with a `getRecords` + `script` action chain.
|
||||
|
||||
---
|
||||
|
||||
## 7. buttonClick — When a button field is clicked
|
||||
|
||||
```bash
|
||||
inkreach-teable trigger set <wfId> --type buttonClick --table-id tblXXX --field-ids '["fldGo"]'
|
||||
```
|
||||
|
||||
**Config:**
|
||||
```json
|
||||
{ "tableId": "tblXXX", "fieldIds": ["fldGo"] }
|
||||
```
|
||||
- The field **must be a Button-type field** whose `options.workflow.id` points to this workflow.
|
||||
- Create it: `inkreach-teable field create --table-id tblXXX --name "Go" --type button --options '{"workflow":{"id":"wflXXX"},"label":"Go"}'`
|
||||
|
||||
**Triggering:** the click comes from `POST /api/table/{tableId}/record/{recordId}/{fieldId}/button-click` (the web UI calls this; CLI tests via `fire button-click`).
|
||||
|
||||
**Output:** `record.id`, `record.name` (primary field), `record.fields.<buttonFieldId>` (**only the clicked button field's count, NOT all fields**), `fieldId`, `user`, `runId`, `name`, `tableId`, `workflowId`.
|
||||
|
||||
⚠️ **`record.fields` contains ONLY the button field itself** (e.g. `{fldXxx:{count:1}}`), not the record's other fields. To read other fields (e.g. an "订单号" text field), use the back-channel API inside a script:
|
||||
```js
|
||||
const rec = await fetch(`${triggerInput._apiBaseUrl}/api/record/${triggerInput.record.id}`, {
|
||||
headers: { Authorization: 'Bearer ' + triggerInput._accessToken }
|
||||
}).then(r => r.json());
|
||||
return { orderId: rec.fields.fldXxx };
|
||||
```
|
||||
`record.name` (primary field) and `record.id` ARE directly available.
|
||||
|
||||
⚠️ The Button field's `options` captures a stale `isActive` snapshot at creation. After deactivating, the API validates the DB `isActive` instead — so a deactivated workflow returns 400 "not active" on click. Re-`activate` to fix.
|
||||
|
||||
---
|
||||
|
||||
## 8. webhook — On external HTTP POST
|
||||
|
||||
```bash
|
||||
inkreach-teable trigger set <wfId> --type webhook
|
||||
```
|
||||
|
||||
**Config:**
|
||||
```json
|
||||
{ "authorization": { "type": "none" } }
|
||||
```
|
||||
|
||||
⚠️ **`authorization` is UI-only — the backend does NOT validate it.** Anyone with the URL can trigger it. Don't rely on it for security.
|
||||
|
||||
**Real webhook URL:**
|
||||
```
|
||||
POST http://<endpoint>/api/webhook/{baseId}/{workflowId}
|
||||
```
|
||||
- ⚠️ The route is `/api/webhook/{baseId}/{workflowId}` — **no** `/base/` or `/workflow/` segments (the frontend UI shows a different, WRONG URL).
|
||||
- Test: `inkreach-teable fire webhook <baseId> <wfId> --body '{"any":"json"}'`
|
||||
|
||||
**Output:** `headers` (request headers), `body` (parsed JSON body), `method`, `baseId`, `webhookId`.
|
||||
|
||||
---
|
||||
|
||||
## Batch Processing
|
||||
|
||||
For `recordCreated`/`recordUpdated`/`recordCondition`/`recordCreatedOrUpdated`, add `--batch`:
|
||||
|
||||
```json
|
||||
{ "enabled": true, "batchWindow": 2000, "batchSize": 100 }
|
||||
```
|
||||
|
||||
- Events within `batchWindow` ms (up to `batchSize`) are merged into ONE run.
|
||||
- The script receives `triggerInput.records` (array) instead of `triggerInput.record` (single).
|
||||
- Use `Promise.allSettled` in scripts to handle the array concurrently.
|
||||
|
||||
```bash
|
||||
inkreach-teable trigger set wflXXX --type recordCreated --table-id tblXXX \
|
||||
--batch '{"enabled":true,"batchWindow":2000,"batchSize":100}'
|
||||
inkreach-teable action add wflXXX --type script --code '
|
||||
const records = triggerInput.records || [triggerInput.record];
|
||||
const results = await Promise.allSettled(records.map(async (r) => {
|
||||
// process each record
|
||||
}));
|
||||
return { processed: results.length };
|
||||
'
|
||||
```
|
||||
Reference in New Issue
Block a user