Building workflows

A PostHog workflow is a directed graph: a list of action nodes (actions) wired by edges (edges), with exactly one trigger node that starts every run. You author that graph as JSON and ship it over MCP. Always call it a "workflow" to the user. "Hog flow" is the internal code name (HogFlow), not a user-facing term.

The single biggest failure mode is getting the graph JSON structurally wrong. The backend stores actions/config as loose JSON, but the visual editor parses every node against a strict schema, so a malformed node saves but then breaks the editor view for the whole workflow. Before composing or editing any graph, read references/graph-schema.md. It is the contract; do not improvise node shapes from these examples alone.

The lifecycle

Work the workflow through these stages. Don't jump straight to enabling it.

1. Compose the graph. Build actions + edges per references/graph-schema.md. For any function node, don't guess the template: list the live catalog with cdp-function-templates-list and read its required inputs with cdp-function-templates-retrieve.
2. Create as a draft. workflows-create. Every workflow is created draft; it does not execute yet.
3. Test-run it. workflows-test-run runs one step at a time. Start at the first step (omit current_action_id, or point it at the trigger) with sample globals ({event, person, groups}); the result includes the next step's id (nextActionId). Feed that back as current_action_id and run again, walking step by step to the end. Skip delay nodes by jumping to the action after them (delays aren't simulated). Async side effects (HTTP/email/SMS/push) are mocked unless you set mock_async_functions=false. Read each step's trace to confirm the path taken.
4. Read logs while iterating. workflows-logs shows the per-step execution trace (levels DEBUG to ERROR). This is how you see why a step skipped, branched, or errored.
5. Edit, then re-test. Patch the graph with workflows-patch-graph (see Editing a draft). Every edit invalidates your earlier test — re-run the affected path before moving on. On a draft workflow, edits apply directly; on an active one they stage a draft (see Changing a live workflow).