Automations

The Automations module is Workestra's cross-module workflow engine. It lets you define if-this-then-that flows that span any combination of modules — trigger on a CRM deal, create a Finance invoice, notify a Support agent, and open a Project, all in one workflow.

Enabling Automations

The Visual Builder ships feature-flagged off. An admin enables it deployment-wide by setting two environment variables:

NEXT_PUBLIC_AUTOMATIONS_ENABLED=true
AUTOMATIONS_ENABLED=true

Effects of the flag:

The cron sweep always processes any already-queued workflow_executions rows, so a workflow that was mid-run when the flag flipped off still completes.

Where to Find It

Automations is a top-level module in the sidebar — not buried under Settings.

Core Concepts

Workflow

A workflow is a saved automation with three parts:

Trigger  →  (optional Conditions)  →  Actions[]

Status

Execution

When an active workflow matches a trigger, Workestra:

1. Creates a workflow_executions row in pending status.
2. Runs the actions in order, recording each step's outcome.
3. Flips the execution to completed (or failed / paused depending on the workflow's error-handling strategy).

Runs are visible at /automations/runs with status, duration, and error details.

Available Triggers

Triggers are grouped by module. Wired triggers fire automatically when the corresponding domain event happens. Manual triggers fire only when you hit "Run now" or when the daily cron sweeps a matching scheduled workflow.

CRM

Projects

Support

Finance

Recruiting

Platform

Available Actions

Actions execute in order. Each routes through a shared platform service — emails via sendEmail, notifications via notificationService, webhooks with HMAC signing, audit events via the audit log.

Creating a Workflow

From Scratch

1. Navigate to Automations in the sidebar.
2. Click New Workflow.
3. Give the workflow a name and optional description.
4. Select a Trigger from the dropdown (searchable, grouped by module).
5. Add one or more Actions from the left palette. Drag to reorder.
6. Set a per-action Delay if you want a pause before it runs.
7. Click Save — the workflow is saved as a Draft.
8. Click Activate to make it live.

From a Template

1. Navigate to Automations → Templates.
2. Browse templates grouped by category (Sales, Marketing, Customer Success, Operations).
3. Click Use Template — a real workflow is created in your workspace and the editor opens on it.
4. Review and adjust the trigger and actions.
5. Click Save then Activate.

Default Templates

Every workspace sees the same 20 system templates in /automations/templates. Pick one, click Use Template, the workflow is copied into your workspace as an editable draft. Every copy is yours to tweak — the original system template stays pristine.

Sales

Customer Success

Operations

Marketing

Custom / Platform

★ = featured. Featured templates show at the top of the gallery.

Publishing your own templates

Workspace admins can publish custom workflows as templates via TemplatesService.publish(). They appear in the same gallery — scoped to your workspace only — next to the system defaults, marked with a Workspace badge. Use this to share recurring patterns with the rest of your team without duplicating each workflow manually.

Usage counts

Each time someone clicks Use Template for a given template, its usage_count bumps by 1. The gallery surfaces the count under each card so you can see which templates are most popular.

Run History

The Runs tab (/automations/runs) shows every execution in the workspace.

Filter by status using the tabs at the top. Click a row to jump to the workflow it came from.

Error Handling

Each workflow has an error-handling strategy set in the right-hand Workflow Settings panel:

Failures are captured in completed_actions[].error on the execution row, and surfaced inline on /automations/runs.

Security

• Workspace isolation — every workflow and execution is scoped by workspace_id via RLS. The stats view uses security_invoker=true so it honours RLS of the base tables.
• Role-gated deletes — only workspace owners and admins can delete workflows.
• Signed webhooks — Call Webhook actions sign the payload with HMAC-SHA256 using WEBHOOK_SIGNING_SECRET. The receiving server verifies via the X-Workestra-Signature header.
• Defense-in-depth on the JSONB shape — CHECK constraints on workflows.trigger / .actions / .conditions reject malformed rows at the DB boundary. Application writes validate with Zod before the insert.
• Executor whitelisting — Update Deal only accepts a fixed list of columns, so a workflow author cannot rewrite arbitrary fields.

Difference: Quick Rules vs. Workflows

Architecture (For Developers)

Layers

UX:        /automations/* pages           →  Thin shells over the module
Module:    src/modules/automations/*      →  Services, hooks, schemas, components, events
Dispatch:  src/modules/automations/events/dispatcher.ts  →  fireWorkflowEvent
Runner:    src/modules/automations/events/runner.ts      →  runExecution + sweep
Cron:      /api/cron/workflow-runner       →  Daily sweep of pending executions
Data:      Supabase: workflows + workflow_executions + workflow_run_stats view

Key files

Supabase objects

How domain events fire workflows

The dispatcher (fireWorkflowEvent) is called from the following paths. Each call is fire-and-forget and wrapped in try/catch — workflow dispatch never breaks the underlying mutation.

The in-process runner is called immediately after a dispatch for low latency. The daily cron at /api/cron/workflow-runner is the backstop for executions that crashed, were delayed, or need to resume after a Wait / Delay action.

Next Steps

• CRM Automations — CRM-specific Quick Rules
• Projects Automations — Project-level automation patterns
• API Reference — Trigger workflows via webhook from external systems