Automation

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;
  },
};

The building blocks

• Hooks intercept every record operation with before/after events — reads, writes, deletes, and their bulk variants. Hooks support priority ordering, fire-and-forget async mode, CEL condition guards, and a retryPolicy with 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 setInterval or cron via the job service, alongside schedule-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.

What's in this module

Related

• 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.