skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
objectstack-ai/objectstack239 installs

objectstack-automation

Design ObjectStack automation — Flows (visual logic), Triggers, Approvals, state machines, and the `jobs` (`defineJob`) / `webhooks` (`defineWebhook`) stack collections. Use when the user is adding `*.flow.ts`, wiring an event-driven rule, modelling an approval chain, or building an interactive screen flow / wizard (objectstack-ui routes those here). Do not use for data lifecycle hooks at the object layer (see objectstack-data) or for kernel / plugin events (see objectstack-platform). CEL expressions in flow conditions / edge guards: load objectstack-formula alongside.

How do I install this agent skill?

npx skills add https://github.com/objectstack-ai/objectstack --skill objectstack-automation
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill provides a protocol for designing automation flows, including event-driven triggers, human sign-offs, and external service integrations. It incorporates security best practices such as delegated secret management and HMAC-SHA256 signature verification. However, it handles untrusted data that influences logic execution and high-privilege operations, which is a standard risk for automation frameworks.

  • Socketpass

    No alerts

  • Snykwarn

    Risk: MEDIUM · 1 issue

What does this agent skill do?

Automation Design — ObjectStack Automation Protocol

When to Use This Skill

Also vendor-integration callbacks and assignment rules.

Predicates and conditions are CEL — every condition / guard / entryCondition / filter value is an Expression envelope: a plain CEL string, or the P\...`/cel`...`` tag (author-time validation); pick one per file.


Flows — Visual Logic Orchestration

Flow Types

TypeWhen to Use
autolaunchedRuns without user interaction — triggered by events, APIs, or other flows
screenInteractive — presents UI screens to the user
scheduleRuns on a cron/interval cadence declared on the start node's config.schedule — or a per-record date sweep via config.timeRelative
record_changeFires automatically on record create/update/delete. autolaunched + the same record-* binding behaves identically; record_change also opts into the trigger-readiness lint
apiInbound webhook (Inbound webhook triggers); a flow only ever started explicitly is autolaunched

A flow an installed package ships is read-only. To change what it does, save a same-named flow in the base's paired .custom package declaring overrides: { package: '<base>', basedOn: '<base version>' } (objectstack-platform § Customizing an installed package): it is armed in the base's place, keeps the base's name and its one activation switch (POST /api/v1/automation/:name/toggle, { enabled: false } = off for this deployment), and a run suspended on the old body finishes on that body. An undeclared same-named flow in the pair or in a dependent is refused at publish. A flow beside it is "new similar": POST /api/v1/automation/:name/clone { name, label, package? } lands the copy switched off in the pair, never package-less; a flow holding a secret / signingSecret is refused (409): author it anew.

A package ships a flow switched off with defaultActive: false (beside status: 'active'): unarmed (_status enabled: false) until an administrator turns that switch on, which then outlives restart, upgrade and reinstall. status: 'obsolete' disarms past the switch; a flow authored in the deployment is refused the key (its switch is status).

Flow Node Types

Built-in (plugins register more):

Control Flow

NodePurpose
startEntry point — every flow has exactly one
endExit point — can have multiple (early exit, error exit)
decisionConditional branching — routed by edge condition predicates, not node config
loopIterate a nested config.body region once per item of config.collection — a CEL value envelope or an inline list, never a string; iteratorVariable (default item) and optional indexVariable bind inside it, maxIterations caps it
parallelFan out into config.branches[] (≥ 2 regions) run concurrently, joined implicitly at block end
try_catchRun config.try; on failure run config.catch with the error in errorVariable (default $error); config.retry re-runs try with backoff first; in a record-after-* flow it (or errorHandling.strategy: 'retry') may not reach an inline http / connector_action: the save would wait out every attempt. Inside a subflow / map child, retried by either flow, that is silent: the flow saves but never arms (GET /api/v1/automation/_status: bound: false, unboundCause: retried_callout_in_subflow) until the child's http is durable: true or nothing retries the call. No finally — the container's ordinary out-edges are the continuation
mapSequential multi-instance — invoke the config.flowName flow (named as subflow's) per item of config.collection (shaped as loop's); each may pause (batch approvals); a refused name fails it at the first item
waitPause execution until a timer elapses or a named signal arrives
subflowInvoke the flow bare config.flowName names: a package's flow gets its own, else the one holder in its dependencies closure plus sys; a package-less flow, the environment's, else the one package holder. Else os validate passes and the node fails at run time (subflow 'X' failed: … naming every candidate; no code): outside-closure — held only by an undeclared package (declare it) or the environment; ambiguous-in-closure / ambiguous-in-environment — two packages hold it (package / package-less caller)
parallel_gateway / join_gateway / boundary_eventBPMN-interop forms a parallel / try_catch container lowers into; author the container

Data Operations

NodePurpose
assignmentSet variable values
create_recordInsert a new record
update_recordModify existing records
delete_recordRemove records
get_recordFetch records with filters — there is no query_record node
save_noticeTell the saver what this create/update started — record create/update trigger only, not after a pause: objectstack-data rules/lifecycle.md § Save Notice

External Integration

NodePurpose
httpCall an external HTTP API — always set timeoutMs (unset = no timeout). url and headers are served as written with the definition to every member who can read flows — only signingSecret and a start node's secret are withheld — so never a credential there: a credential means a declared connector called via connector_action. Retried after a record change: durable: true (outbox-queued, else sent once in the background, unretried; no response)
notifySend a notification (below)
connector_actionDispatch an action of a declared connector (§ Integrations are declared, not coded) or a plugin's. connectorConfig.input is a value-slot map like subflow input. Once evaluated, it is judged against the action's inputSchema (required, type, properties, items) before dispatch: a breach fails the step VALIDATION_ERROR (fault-routable); os validate does not judge the inputSchema fit yet. Retried after a record change: drop the retry, or run the flow on demand / on a schedule
scriptCall a registered function (Valid-but-silently-wrong #3)
screenDisplay a UI form to the user (screen flows only). config.fields[]: { name, label, type, required, options, defaultValue }, type an open widget hint; 'file' renders the upload widget and resumes with the sys_file id bound to name — a later create_record / update_record writes it into a file field, which claims the file: collect first, write after the last screen. 'record_link' (never 'record', an object field type) takes no input — it shows the reference record whose id defaultValue evaluates to, by display name, as a link to its record page: the result screen of a flow that created records, { name: 'account_link', type: 'record_link', reference: 'crm_account', defaultValue: { dialect: 'cel', source: 'account.id' } } over a create_record outputVariable: 'account'. Both keys required; required / options / placeholder / min / max refused; a resume value under its name refused (400 INVALID_SCREEN_INPUT). A completed end message is refused and a markdown link in a screen description renders literally. Next / Submit and "Step N of M" are not authored: the engine reads the graph when the screen pauses and serves progress, which alone labels the button and draws the counter. A decision, fault edge, loop back, non-screen pause (approval, wait) or subflow after a screen means "Next", no count. progress in a node config is refused

Human Decision

NodePurpose
approvalRoute a record for human sign-off

notify

An undeclared key is a named parse error. RAW keys are read as written: a {token} in one is refused. The node as JSON (TypeScript: the same literal, a FlowNode):

{ "id": "tell_owner", "type": "notify", "label": "Notify Owner", "config": {
    "recipients": { "dialect": "cel", "source": "record.owner_id" },
    "title": "Done: {{ record.title }}",
    "message": "Closed {{ record.closed_at | date:long }}",
    "topic": "task",
    "severity": "warning",
    "channels": ["inbox"],
    "sourceObject": "task",
    "sourceId": { "dialect": "cel", "source": "record.id" },
    "actionUrl": "/tasks/{{ record.id }}"
} }
  • recipients — REQUIRED: id, list, or envelope; a CSV is ONE id. 4th form { "emailField": "applicant_email" }: an email field of the trigger record, for a non-user — then channels: 'email' alone. An envelope must yield USER ids: an address no user holds fails the node.
  • title — inline; XOR template (RAW, localizable). message — body; only with inline title.
  • RAW: topic (default 'notify'), severity (CLOSED enum info | warning | critical), channels (default inbox).
  • sourceObject + sourceId — the link: a PAIR, else dropped; none of the 3 ⇒ the trigger record (not on delete/before-create), if any. actionUrl overrides the pair.

A recipient string, written or evaluated, may be an audience selector:

  • team:ID — that team's members.
  • owner_of:OBJECT:ID — that record's owner; a computed id: source: "'owner_of:crm_case:' + record.case_id".
  • org:members — every member of the run's organization, else that of the record the notification is about, else nobody (single posture: a schedule flow declaring no organization, no record). Any other org: value reaches nobody too. Each warns in the server log only; the node succeeds.

An option label in a notice: {{ stage | option:opportunity.stage }} in the mail template (each recipient's language; mail-only, refused in inline title / message) — never label() in templateData, evaluated once per run, before fan-out.

Flow Variables

variables is an array; a variable has no label: variables: [{ name: 'case_id', type: 'text', isInput: true }, { name: 'approval_result', type: 'boolean', isOutput: true }].

→ references/examples-flows.md § Flow Example — Auto-Escalate Overdue Cases.

Failure routing & runAs

Handling a failed node: a fault edge. { source, target, type: 'fault' } routes a failed node to a handler instead of ending the run. A label: 'error' alone does nothing: an ordinary edge traverses on SUCCESS (objectstack validate reports flow-error-label-not-fault). A handled failure does not consume the flow-level retry (errorHandling.strategy: 'retry'), which replays from the start — prefer a fault edge for a local failure. The handler reads {{ <nodeId>.error }} (run-wide {{ $error.message }}; in CEL, vars["$error"]); the run then reports success and the failed step stays in the trace.

ROUTES (runtime failure)Does NOT route (fatal either way)
404, rate-limit, rejected write, failed subflowmissing required config key (objectName, url, flowName, connectorId/actionId); filter operand that evaluated to null or a non-value; graph past the nesting ceiling; unscoped run

Writing a readonly field? Set runAs: 'system' (approval stamps, SLA markers, rollups). Under the default runAs: 'user' the engine strips it from create_record / update_record — the step succeeds, the drop is named in the step's warnings; os validate / os build fail a runAs:'user' update_record writing one (readonlyWhen: a warning). A button, an action, an endpoint or the trigger route does not let a user start an autolaunched, record_change or schedule flow declared runAs: 'system' (403 PERMISSION_DENIED), so for a flow a user starts from a button the elevated routes are a screen or api flow declared runAs: 'system', or a user-run flow whose subflow node calls the elevated flow.

Elevate the write, not the flow. Prefer the subflow route — raising a whole screen flow silently elevates every other write in it, and an api flow adds a webhook secret and an inbound endpoint a button never uses.

Elevation stops at identity assignment. A runAs: 'system' write (insert through purge) of sys_user_position, sys_user_permission_set, sys_invitation or sys_member is refused PERMISSION_DENIED, a system subflow included. Grant positions and permission sets from a runAs: 'user' flow — the delegated-administration gate judges that user and records them as granted_by; invitations and memberships change through the organization endpoints (row 1b, https://objectstack.ai/docs/permissions/system-context#1-authorization-and-scoping).

A runAs: 'system' sweep must pin its organization. System context has no trigger user, so a scan or rollup with no organization predicate reads and writes across every tenant; filter on the platform-injected tenant column, never re-declare it per object.

Who may START a flow: requiredPermissions: ['…'] on the flow — the four entrances above refuse a non-system caller missing any named capability with 403 PERMISSION_DENIED; an action starting it inherits the list, a subflow node is not an entrance. Gate an elevated screen / api flow here, never on current_user.positions inside it.

A hook elevates itself with runAs, never with sudo. An object hook (objectstack-data) declares its own runAs: 'system' | 'user' | 'inherit' — default 'inherit', the context of the write that fired it — scoping that hook's ctx.api data operations only, on the in-process handler and the sandboxed body alike. A 'user' hook whose trigger resolved no user has nothing to scope to: its ctx.api data operations are refused (HOOK_UNSCOPED_DATA_ACCESS, 403) rather than run unscoped.

Filter operands (config.filter)

  • Each operand is a value slot, evaluated before the query. A whole-string query placeholder ({current_user_id}, {today}, {current_year_start}) passes through verbatim for the query engine; a flow variable never shadows it, and only filter gets this hand-off.
  • An operand that evaluates to null refuses the node: a dropped condition does not narrow a query, it widens it, so a routed delete_record would empty the object while the run reports success. Where the value may be absent, route around the node with a decision; to match an empty field, write the literal null. A relation hop (record.owner.email) needs the start node's config.expand to list the field — else the fault names the missing hop, not the remedy.
  • A computed operand is a value, never a query operator: a string, number, bigint, boolean or date, or at an $in / $nin / $between comparand a list of them with no empty entry. Anything else fails the node as a guard. Make the expression evaluate to the compared value (for a record, its id), and write conditions in the filter itself.

Valid-but-silently-wrong (passes build, fails at runtime)

Most are caught by objectstack build:

  1. A value slot takes a literal or a CEL envelope — never a {…} token. In assignments.*, fields.*, subflow / map input.*, script inputs.*, loop / map collection, notify recipients / templateData.* / sourceId, http body and every CRUD filter operand, a string is the literal text it spells, and a {…} token is refused — at objectstack validate (expression-invalid), registerFlow and the executor — naming its CEL spelling. Compute with { dialect: 'cel', source: '…' }:

    • '{record.owner}' → source: 'has(record.owner) ? record.owner : null' — CEL refuses an absent key where the template wrote nothing, so nothing / null / a default is now YOUR call; '{record.tags.0}' → 'record.tags[0]'; a deep path guards each step: has(vars.source) && has(vars.source.id) ? vars.source.id : null
    • run user: {$User.Id} → current_user.id; a flow that can run without a user guards it, current_user != null ? current_user.id : null. current_user holds id, positions, organizationId, isPlatformAdmin only — an email or a name is a sys_user read by that id

    Text slots (notify title / message / actionUrl, screen title / description, end message, http url / headers) render {{ }} holes — a variable path, optional formatter (a default: argument is literal text, never a path), no logic; a {…} token there is refused with its {{ }} spelling. A date or the run user has no hole: assign it first (assignments: { v: { dialect: 'cel', source: 'current_user.id' } }), then write {{ v }}. create_record / update_record fields also take a text slot, marked { dialect: 'template', source }, for a sentence people read. It is written in the organization's language (Localization setting if set, else i18n.defaultLocale; key: objectstack-i18n), never the run starter's; untranslated, the authored text; an unreadable setting fails the node. A bare string stays a literal, never translated.

  2. create_record's outputVariable holds the created RECORD, not its id. ❌ fields: { ref: { dialect: 'cel', source: 'newRec' } } ✅ source: 'newRec.id'

  3. script nodes call a registered function — nothing else. config.function (required: an empty node refuses at execute, an unregistered name fails loudly) names one registered in defineStack({ functions }).

    The name resolves from the flow's package, as subflow's flowName does, the platform's ownerless function in every flow's reach; a .custom override reads as a package-less flow. Packages of two namespaces each run their own normalize_phone. One namespace (or none): both held at boot warn Bare-name conflict at boot; a later one installs but binds NONE of its functions or hooks (error Failed to bind declarative hooks): rename, or another namespace. If the flow's package holds none, two holders in reach or one only outside its dependencies closure fail the step as a guard (no fault edge; $error.code: 'RESOURCE_CONFLICT' in a try_catch); a flow door's innerRefusal names each holder. Fix: declare the dependency, or rename.

    A flow function is a PURE compute step — it does NOT read/write the database. It receives ctx.input and returns a value; a later declarative node persists its outputVariable:

    [
      { "id": "ai", "type": "script", "label": "AI Triage", "config": {
          "function": "helpdesk.aiTriageStub",
          "inputs": { "ticketId": { "dialect": "cel", "source": "record.id" } },
          "outputVariable": "ai" } },
      { "id": "apply", "type": "update_record", "label": "Apply Category", "config": {
          "objectName": "helpdesk_ticket",
          "filter": { "id": { "dialect": "cel", "source": "record.id" } },
          "fields": { "ai_category": { "dialect": "cel", "source": "ai.ai_category" } } } }
    ]
    

    A function that writes where the platform cannot see declares it, so the run reports "cannot say" rather than acted: 0 (project code — a function has no JSON form):

    defineStack({ functions: {
      'billing.sync': { handler: syncBilling, effect: 'writes' },
    } });
    
  4. A select is compared and written by its option value, never its label. The request speaks the label ("Lost"); the row stores the value (lost). condition: "record.status == 'Lost'" parses, matches no row: the flow stages clean and never fires; fields: { status: 'Lost' } / a filter fails the run (invalid_option). Read the field's options.


→ State Machines & Approvals: references/state-machines-and-approvals.md — its state-introspection route is GET /api/v1/meta/object/:name/state/:field?from=:state.


Assignment rules — route a new record to a queue or a person

assignmentRules on the stack routes each inserted row of an ownership: 'user' object whose owner_id and queue are both still empty — once, after every beforeInsert hook, never on update, never refusing the insert. Entries are ordered; the first whose criteria (CEL over record.*) match decides:

<!-- os:check -->
import { defineAssignmentRule } from '@objectstack/spec/automation';

export const caseIntake = defineAssignmentRule({
  name: 'crm_case_intake',
  object: 'crm_case',
  entries: [
    { name: 'urgent', criteria: 'record.priority == "urgent"',
      assignTo: { type: 'queue', value: 'crm_escalations' } },       // no strategy: parked for a claim
    { name: 'rest', assignTo: { type: 'queue', value: 'crm_support_intake' },
      strategy: 'least_loaded', load: 'record.status != "closed"' }, // or 'round_robin'; `load` only with least_loaded
  ],
});

strategy is for a queue target only; assignTo: { type: 'user', value: '<id>' } names one owner, who holds the row only while an active member of its organization (else ownerless). Queues are declared in queues (objectstack-data); an approval for the same people is a queue approver (Approver Types). ⛔ Never a beforeInsert hook that picks an owner, nor a round-robin counter field.

A packaged rule's queue is its package's own, else the one holder in its dependencies closure plus sys: acme.helpdesk naming acme.crm's queue declares dependencies: { 'acme.crm': '^1.0.0' }. Else refused — outside-closure (an undeclared package's or environment-only queue), ambiguous-in-closure (two in it) — the row is written ownerless, in no queue, and the server log warns once (… does not resolve … from the rule's package). An organization's sys_assignment_rule row and a rule no package ships read environment-wide (two package holders: ambiguous-in-environment). A name no queues entry declares reads the organization's sys_queue row.


Triggers — Event-Driven Automation

There is no standalone trigger object and no top-level trigger / event key.

Prerequisite — declare the capabilities your nodes need

Metadata registers without its defineStack({ requires }) token. Two pairs are instead refused at os validate / build / dev / serve (422); neither token implies the other:

requires tokenTurns onAbsent ⇒
automationthe flow engine + node executorsflows never execute
triggers + automationrecord-* / schedule / api start bindingsauto-launched flow refused: STACK_TRIGGER_CAPABILITY_REQUIRED
job°cron cadence + the timeRelative sweepscheduled flows never launch
queue°the inbound-webhook consumerinbound POST answers 503
approvalsapproval / approval_revise (plugin-approvals)no executor for the node type
messaging°notify delivery to inbox (sys_inbox_message)silent: success with skipped: true
webhooks + realtimedefineStack({ webhooks }) outbound dispatchdeclared webhook refused: STACK_WEBHOOK_CAPABILITY_REQUIRED

° Always-on, so list it only under --preset minimal (objectstack-platform § requires:).

Inbound webhook (api) triggers (ADR-0041 Tier 1)

Endpoint: POST /api/v1/automation/hooks/:flowName/:hookId. Configure it on the start node config:

config keyPurpose
hookIdURL path token (default 'default'). Rotate it to revoke a leaked endpoint
secretRef / secretHMAC-SHA256 secret, one required (else refused at registration and os validate). Ship secretRef: 'NAME': an env var the deployment fills, not OS_*; unfilled ⇒ 503. Never a literal
  • Signature: x-objectstack-signature: t=<unix seconds>,v1=<hex> — HMAC-SHA256 of <t>.<raw body>; t within 300 s. Vendor-signed: config.signature replaces it (recipe 4).
  • Idempotency: x-idempotency-key dedupes retries — author the flow to be idempotent (delivery is at-least-once).
  • Queue-backed: the endpoint ACKs 202 and enqueues; the flow runs on the consumer.
  • The JSON body surfaces to the flow as the trigger record (record.* / bare fields) plus params.
  • A flow name two packages hold: the bare hook above answers 401 INVALID_SIGNATURE whatever the signature (cause: server log only). Each package's flow is reached only at POST /api/v1/automation/hooks/:namespace/:flowName/:hookId, by its manifest.namespace (_env there: a flow no package ships).

Trigger Types (start-node config.triggerType)

triggerTypeObjectQL hook
record-before-create (can modify/reject)beforeInsert
record-after-createafterInsert
record-before-updatebeforeUpdate
record-after-updateafterUpdate
record-before-deletebeforeDelete
record-after-deleteafterDelete
record-before-write / record-after-write — one flow, both eventsinsert + update hooks

Trigger Configuration — on the start node

{
  id: 'start',
  type: 'start',
  label: 'On Case Escalated',
  config: {
    objectName: 'support_case',
    triggerType: 'record-after-update',
    condition: "previous.status != 'escalated' && record.status == 'escalated'",
  },
}

Prefer record-after-*; guard one that writes its own object, or it re-triggers itself. A record-before-* flow that throws silently blocks the write — give it a user-facing message.

→ references/examples-flows.md § Time-relative triggers.


Integrations are declared, not coded

A vendor system reachable over HTTP is a connectors: entry inside the app — provider: 'openapi' | 'mcp' | 'rest', a packaged spec, auth.credentialRef (the customer's administrator supplies the value) — dispatched by connector_action. Never a plugin. Recipes, credential hand-off, loader limits: references/integration-recipes.md. Platform code only when one holds — and then it is the platform's, filed as a card, the app still writing none: the protocol is not HTTP; the work writes identity objects (users, units, positions); it processes files locally; one fixed action contract spans several vendors; the callback is signed in no form config.signature declares. A document the loader cannot take yet (YAML, Swagger 2.0, $ref) is a gap named against its platform card.


Verify your work

os validate (os build also emits dist/); CEL checks: objectstack-formula § Verify your work.


References

See references/_index.md for pointers to the Zod schemas in node_modules/@objectstack/spec/src/.

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/objectstack-ai/objectstack/objectstack-automation">View objectstack-automation on skillZs</a>