| title | Automation |
|---|---|
| description | Hooks, flows, workflows, approvals, scheduled jobs, and durable webhooks — the process engine that reacts to your data. |
Automation is ObjectStack's process engine: you attach business logic to the data model declaratively — as metadata — instead of scattering it through application code. It is a cross-protocol capability: automations are declared in the Automation Protocol namespace and executed by the ObjectStack runtime against ObjectQL data.
The smallest useful automation is a hook (from the CRM example app):
import type { Hook, HookContext } from '@objectstack/spec/data';
export const OpportunityStageHook: Hook = {
name: 'opportunity_stage_probability',
object: 'crm_opportunity',
events: ['beforeInsert', 'beforeUpdate'],
priority: 100,
handler: async (ctx: HookContext) => {
const input = ctx.input as { stage?: string; probability?: number };
if (input.stage === 'closed_won') input.probability = 100;
if (input.stage === 'closed_lost') input.probability = 0;
},
};- Hooks intercept every record operation with before/after events — reads, writes, deletes, and their bulk variants. Hooks support priority ordering, fire-and-forget
asyncmode, CELconditionguards, and aretryPolicywith backoff (Hooks). - Flows are node-based processes built from nodes like decision, loop, record operations, http, notify, script, screen, wait, subflow, and parallel/join gateways — and the set is registry-extensible: plugins can contribute new node types via
registerNodeExecutor. Flows launch on record changes, on a schedule, from a screen, or via API (Flows). - Workflows model a record's lifecycle as a finite state machine: states, transitions, and guards (Workflows).
- Approvals are flow nodes with approver resolution, approve/reject decisions, and escalation (Approvals).
- Webhooks deliver events to external systems through a durable outbox — exponential/linear/fixed retry with dead-lettering, HMAC signing, and an admin redeliver endpoint (Webhook Delivery).
- Scheduled jobs run on
setIntervalor cron via the job service, alongsideschedule-type flows.
Rule of thumb: model state with workflows, model steps with flows, use hooks for code-level reactions, and webhooks to notify the outside world.
- Spec: State Machine (Lifecycle), Runtime Capabilities
- Schema reference: Automation
- Neighbors: validation rules that block bad data live in Data Modeling; who may trigger an automation is governed by Permissions & Identity; the services hooks call (email, queue, storage…) are documented in Kernel & Services.