Workflow builder

The workflow-builder block stores workflows as graphs that members edit on a canvas and publish per tenant. A published version runs on the engine you choose. The Workflow SDK adapter compiles each version to a workflow and records the status of each node, so the canvas shows a run as it happens.

better-supabase sql add workflow-builder   # adds workflows, tenant and access as well

Grant the keys to your roles in sql.modules.access.roles.

GraphsCopy Anchor Link

A graph is a list of nodes and the edges between them. It has one trigger node, and the other nodes run in dependency order once the trigger reaches them.

import type { WorkflowGraph } from "better-supabase/blocks/workflow-builder";

const graph: WorkflowGraph = {
  nodes: [
    { id: "start", kind: "trigger" },
    {
      id: "lookup",
      kind: "step",
      step: "crm.lookup",
      config: { field: "email" },
    },
    {
      id: "isPaid",
      kind: "condition",
      config: { path: "results.lookup.plan", op: "equals", value: "pro" },
    },
    { id: "review", kind: "approval" },
    { id: "wait", kind: "sleep", config: { duration: "1d" } },
    {
      id: "welcome",
      kind: "step",
      step: "email.send",
      config: { template: "welcome" },
    },
  ],
  edges: [
    { id: "e1", source: "start", target: "lookup" },
    { id: "e2", source: "lookup", target: "isPaid" },
    { id: "e3", source: "isPaid", target: "review", branch: "true" },
    { id: "e4", source: "isPaid", target: "wait", branch: "false" },
    { id: "e5", source: "review", target: "welcome", branch: "true" },
    { id: "e6", source: "wait", target: "welcome" },
  ],
};

An edge without a branch runs its target when its source ran. From a condition or an approval, branch: "true" or "false" picks the outcome it follows. A node runs when one of its incoming edges is active, so two branches can join again.

validateGraph(graph, steps) returns the errors: a missing or second trigger, a cycle, an edge to an unknown node, a step outside the library or an invalid condition. The database runs the same checks when it saves a draft and when it publishes one. diffGraphs(from, to) lists the nodes and edges that were added, removed or changed.

Editing and publishingCopy Anchor Link

import "server-only";

import {
  createBuilder,
  sqlTransport,
} from "better-supabase/blocks/workflow-builder";
import {
  compileGraph,
  graphStarter,
} from "better-supabase/workflow-sdk/builder";

import { steps, stepLibrary } from "@/workflows/steps";
import { graphExecutor } from "@/workflows/graph";

export const builderFor = (sql: Sql) =>
  createBuilder({
    transport: sqlTransport(sql),
    service: sqlTransport(postgres.admin),
    steps: stepLibrary,
    compile: compileGraph,
    start: graphStarter({ steps, executor: graphExecutor }),
  });

const builder = builderFor(await bs.sql());

const definition = await builder.definitions
  .save({ tenant: organizationId, slug: "onboarding", name: "Onboarding" })
  .orThrow();
const draft = await builder.versions.save(definition.id, graph).orThrow();
const published = await builder.versions.publish(draft.id).orThrow();
const runId = await builder
  .run({ definition: definition.id, input: { email } })
  .orThrow();

versions.save updates the open draft, or opens the next version when the last one is published. versions.publish runs compile on the graph (a throw fails the publish), publishes the version as the caller and archives the version that was published before. The compiled form is stored through the service transport; without one it isn't stored. publish_workflow_version refuses a non-null compiled from anyone but the service role (WORKFLOW_COMPILED_FORBIDDEN), so a member with workflow.publish can't store code for the server to run. run starts the published version through start with a fresh idempotency key unless you pass one, and returns the engine's run id. The run appears in workflow_runs like any other run.

steps.sync() writes steps to the library (service role). Run it at deploy time or on start-up, so the palette and the database's checks know every step the deployment has. Each step has a name, a title, JSON Schemas for its config and output, and the credentialKind it needs.

TriggersCopy Anchor Link

await builder.triggers.save({ definition: id, kind: "webhook" }).orThrow();
const token = await builder.triggers.rotateToken(triggerId).orThrow(); // shown once

export const POST = (request: Request) =>
  serviceBuilder.triggers.webhook(request);

The webhook route answers 202 with { runId }, 404 for an unknown or disabled token and 405 for a method other than POST. A body that is not JSON arrives as { body: "<text>" }. An Idempotency-Key header keys the start, so a retried delivery starts one run. Only the token's SHA-256 is stored; rotating it ends the old one.

Schedule triggers run on the workflows schedule tick. Pass builder.triggers.starter(fallback) as its start: it starts the builder-trigger: schedules here and hands the others to fallback.

CredentialsCopy Anchor Link

import { vaultCredentials } from "better-supabase/credentials";

const builder = createBuilder({
  transport,
  service,
  credentials: vaultCredentials(sql),
});

const slack = await builder.credentials
  .create({
    tenant: organizationId,
    kind: "slack",
    name: "Team Slack",
    ref,
    secret,
  })
  .orThrow();
const { token } = await builder.credentials.resolve(slack.id).orThrow(); // inside a step
await builder.credentials.revoke(slack.id);

A credential row holds a credential_ref, never the secret, and the ref carries the row's tenant (tenant refs). create stores secret first when the provider can store one, and authorize returns the URL that connects an account for providers that authorize (such as Vercel Connect). resolve is a service-role call for steps: it returns the token from the provider named in the ref, with the row's scopes. revoke deletes the row and then revokes the secret. Members with workflow.admin manage the tenant's credentials; members with workflow.read list them. Organization exports leave out credential_ref, and the organization purge in data lifecycle revokes each credential before it deletes the row.

Run status on the canvasCopy Anchor Link

nodeRunReporter from better-supabase/workflow-sdk/builder wraps each step so it records running, then completed with its output or failed with its error, in workflow_node_runs. Each record pings workflow-run:<id>.

"use client";

import {
  useWorkflowBuilder,
  useWorkflowCanvasRun,
} from "better-supabase/blocks/workflow-builder/react";

export function CanvasStatus({ runId }: { runId: string }) {
  const { run, nodes } = useWorkflowCanvasRun(runId);
  return (
    <p>
      {run?.status}:{" "}
      {Object.values(nodes).filter((n) => n.status === "completed").length}{" "}
      nodes done
    </p>
  );
}

useWorkflowBuilder({ tenant }) returns the definitions, the step library and a builder bound to the user's session. useWorkflowCanvasRun(id) returns the run and each node's status by node id, and loads them again on every message on workflow-run:<id>. Both are Client Component hooks; in Server Components, call builder.definitions.list() and builder.nodeRuns.list(run) instead.

AlertsCopy Anchor Link

await builder.alerts.save({
  definition: id,
  onEvent: "failed",
  channel: { type: "email", to },
});
await builder.alerts.save({
  definition: id,
  onEvent: "slow",
  threshold: 3600,
  channel,
});
await serviceBuilder.alerts.check(); // from a cron route

A failed alert fires when a run of the definition fails. A slow alert fires from alerts.check() when a run is still unfinished threshold seconds after it started. Each alert fires once per run and emits a workflow_alert.triggered outbox event with the alert, its channel and the run. Your outbox consumer sends it; the module only stores the channel. Runs match a definition on their bs.definition attribute, which graphStarter sets.

FunctionsCopy Anchor Link