objectstack-ai/objectstack/objectstack-automation

Automation Design — ObjectStack Automation Protocol

When to Use This Skill

Flows (auto-launched, screen, scheduled), state machines and approvals, record-change triggers, vendor integrations and their 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. Contract, stdlib, legacy → CEL table: objectstack-formula.

Flows — Visual Logic Orchestration

Flow Types

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.

Flow Node Types

Flows are built from built-in node types (plugins register more):

Control Flow

Data Operations

External Integration

Human Decision

notify — the most-used node type

NotifyConfigSchema is strictObject — an undeclared key is a named parse error. RAW keys are read as written: a {token} in one is refused.

{ id: 'tell_owner', type: 'notify', label: 'Notify Owner', config: {
    recipients: { dialect: 'cel', source: 'record.assignee' }, // 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: 'Done: {{ record.title }}', // inline; XOR `template` (RAW, localizable)
    message: 'Closed {{ record.closed_at | date:long }}', // body; only with inline `title`
    topic: 'task',                     // RAW; default 'notify'
    severity: 'warning',               // RAW; CLOSED enum info|warning|critical
    channels: ['inbox'],               // RAW; default inbox
    sourceObject: 'task',              // link: PAIR, else dropped; none of the 3 ⇒ the
    sourceId: { dialect: 'cel', source: 'record.id' }, // trigger record (not on delete/before-create), if any
    actionUrl: '/tasks/{{ record.id }}', // overrides the pair
} }

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 of { name, type, isInput, isOutput } entries — not a name-keyed map; 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. **type: 'fault'

is what routes — 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 a flow-level errorHandling.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.

Writing a `readonly` field? Set `runAs: 'system'`. Under the default

runAs: 'user' the engine strips it from create_record / update_record

— the step succeeds, the value never lands, the drop is named in the step's

warnings — so a flow maintaining one (approval stamps, SLA markers, rollups)

runs runAs: 'system'; os validate / os build fail a runAs:'user'

update_record writing one (readonlyWhen: a warning). Do not remove

readonly instead.

Elevate the write, not the flow. A screen flow stays runAs: 'user'; a

step that must write a readonly field moves into a dedicated runAs: 'system'

flow called from a subflow node — raising the whole flow silently elevates

every other write in it.

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.