AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

building-workflows

Build, edit, test, enable, and monitor PostHog workflows over MCP. Author the action/edge graph so it runs and opens cleanly in the visual editor, then change drafts surgically with patch operations. Use when asked to build, set up, automate, change, fix, or debug a workflow, campaign, broadcast, drip sequence, or event-triggered automation in the workflows product, including first-time messaging setup (email channel, sending domain, frequency cap) before the first workflow.

Original source
posthog
License
MIT
Pinned revision
cac7c80a9e5b73484d18eda1bffb47297c938e0c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read posthog--building-workflows at revision cac7c80a9e5b73484d18eda1bffb47297c938e0c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 4

references/graph-schema.md

Workflow graph schema

The contract for actions and edges. The stored workflow is loose JSON, but the visual editor validates every node against a strict schema keyed on type. A node that saves successfully but doesn't match this contract will break the editor view for the whole workflow when someone opens it. Treat the shapes below as required, not advisory.

Contents

  • Node (action) shape
  • Action types and their config
  • Edges
  • function* inputs
  • Duration strings (delay_duration, max_wait_duration)
  • Waiting until a date (delay_until)
  • Conversion & exit condition
  • Pre-submit checklist

Node (action) shape

Every action object has these common fields plus a type-specific config:

{
  "id": "unique_within_workflow",
  "name": "Human label",
  "description": "",
  "type": "<see action types>",
  "config": {},
  "on_error": "continue",
  "filters": null,
  "output_variable": null
}
  • id — unique within the workflow; edges reference it by from/to.
  • on_error — optional; only continue or abort. Omit to use the default.
  • filters — optional property filters gating the action: {properties: [<cond>]}. Send properties, not bytecode.
  • output_variable — optional; store a step result into a workflow variable. {key, result_path?, spread?}.

Action types and their config

Use only these type values — they are the complete supported set. An unknown or unsupported type breaks the editor's parse for the entire graph.

| type | config | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | trigger | a trigger config (see below). Exactly one trigger node per workflow. | | delay | { "delay_duration": "30m" }, or { "delay_until": {"expression": "<HogQL date>", "offset?": "-1d"}, "max_delay_duration?": "30d" } to wait for a per-person date. Exactly one of the two. See duration rules and delay_until below. | | conditional_branch | { "conditions": [ { "filters": {"properties": [<cond>]}, "name?": "" } ] }. Index N pairs with the branch edge index: N. | | random_cohort_branch | { "cohorts": [ { "percentage": 50, "name?": "A" } ] }. Percentages are relative weights and should sum to 100, but a total above or below 100 still splits traffic in the given proportions. | | wait_until_condition | { "condition?": {"filters": {"properties": [<cond>]}}, "events?": [{"filters": {...}, "name?": ""}], "max_wait_duration": "7d" }. condition is optional: an events-only wait is valid (server seeds a missing condition as {filters: null}). Duration rules as delay. | | wait_until_time_window | { "timezone": "UTC", "use_person_timezone?": false, "day": <"weekday" / "weekend" / "any" / ["monday",...]>, "time": <"any" / ["10:00","11:00"]> }. | | function | { "template_id": "<live template id>", "inputs": { ... }, "mappings?": [] }. Don't guess the id or its inputs — discover them live (see below). | | function_email | { "template_id?": "template-email", "template_uuid?": "<saved template UUID>", "inputs": {"email": {"value": {...}}}, "message_category_type?": <"marketing" / "transactional">, "tracking_enabled?": <bool> }. template_id is the literal template-email; omit it and the server infers it from the step type. Reference a saved library template (from workflows-list-email-templates) by putting its UUID in template_uuid, never in template_id — a UUID sent as template_id is moved into template_uuid automatically. When template_uuid is set and the value has no body keys (subject/text/html/design), the server copies the template's body into inputs.email.value at save (a snapshot — later template edits don't propagate); you still supply from and to. Set from to {integrationId: <sender id>} for one sender. To rotate across up to 10 senders, also set integrationIds: [<sender id>, ...]; keep integrationId as the first sender for compatibility. Workflow runs using the same sender list resolve to the same sender, including across multiple email steps. If you author any body key inline, your body wins and template_uuid is provenance only. tracking_enabled defaults to true; when false, no open pixel is injected and links are not rewritten, so opens/clicks are not recorded for this step (delivery/bounce/unsubscribe still are). | | function_sms | { "template_id?": "template-twilio", "inputs": { ... }, "message_category_type?": "..." }. template_id is the literal template-twilio; omit it and the server infers it. | | function_push | { "template_id?": "template-native-push", "inputs": { ... }, "message_category_type?": <"marketing" / "transactional"> }. template_id is the literal template-native-push; omit it and the server infers it. Sends a mobile push notification via FCM/APNs. Its inputs are richer than email's — title, body, and a channels list of the FCM/APNs integration ids to send through — so retrieve the template-native-push inputs_schema (as with function) for the exact keys, and use the project's push integration ids for channels. | | exit | { "reason?": "Done" }. Usually one terminal exit node. |

Branch and wait condition filters (the filters wrapper is mandatory)

conditional_branch and wait_until_condition gate on a filters object, the action-filter shape ({properties?, events?, actions?, source?, filter_test_accounts?}). The wrapper is not optional:

  • Write { "filters": { "properties": [<cond>] } } on each condition, never { "properties": [<cond>] } directly on the condition object. The bare form saves but the visual editor flags it and the branch compiles to a constant, so it never evaluates your condition.
  • conditional_branch conditions are property-only (person/group <cond>s). Event/action filters are rejected here ("Event filters are not allowed in conditionals").
  • wait_until_condition is event-aware: its condition.filters and each events?[].filters may also carry events/actions. An entry naming neither an event nor an action is dropped (it would match everything).
  • source is optional (defaults to events). Never send bytecode; the server compiles it from properties.

Trigger config (the trigger node)

Discriminated on config.type:

  • event — { "type": "event", "filters": { "events": [{ "id": "<event>", "name": "<event>", "type": "events", "order": 0, "properties": [<cond>] }], "properties": [<cond>], "filter_test_accounts": false } }. Fires on every matching occurrence. Throttle repeats with trigger_masking (dedup/sampling — not behavioral filtering).
  • webhook / manual / tracking_pixel — { "type": "webhook", "template_id": "<literal>", "inputs": { ... } }. These use a fixed built-in source template, not one you look up: template-source-webhook for both webhook and manual, template-source-webhook-pixel for tracking_pixel. Omitting or guessing it fails the create with Template not found against the trigger node. They are source_webhook templates and are not in the destination catalog (cdp-function-templates-list is type=destination), so don't try to discover them there. Each needs inputs.event and inputs.distinct_id wrapped in {value: ...}, and the right values differ per trigger type because a different request reaches the template:
    • webhook — a POST whose body you control: "inputs": { "event": { "value": "{request.body.event}" }, "distinct_id": { "value": "{request.body.distinct_id}" } }.
    • manual — the "trigger manually" button POSTs {user_id, $variables}, so the body carries no event: use the fixed literal "inputs": { "event": { "value": "$workflow_triggered" }, "distinct_id": { "value": "{request.body.user_id}" } }. Pointing event at {request.body.event} here makes every manual run return 400 (the source template rejects an empty event) while the UI still shows a success toast, so the workflow silently never fires.
    • tracking_pixel — a bodyless GET, so read query params: "inputs": { "event": { "value": "{request.query.ph_event}" }, "distinct_id": { "value": "{request.query.ph_distinct_id}" } }. Body references resolve empty here and the pixel still returns its 200 GIF, so every hit is dropped with no error to retry on.
  • batch — { "type": "batch", "filters": { "properties": [<cond>] } }. The audience: person-property conditions and/or cohort references. No event/action filters (silently dropped, so rejected). Does not fire on enable — dispatch a one-off broadcast with workflows-run-batch, or make it recurring with workflows-schedule-create (attaches an RRULE schedule; each firing re-broadcasts to this same config.filters.properties audience). A recurring broadcast is a batch trigger plus a schedule. Editing config.filters pauses any schedule attached to it, since the confirmed recipient count no longer holds - preview again and re-create the cadence.
  • schedule — { "type": "schedule" }. One person-less run per occurrence, for jobs that act on their own (for example a "Create AI task" step). Attach the cadence with workflows-schedule-create; no audience preview is needed. Changing this trigger to batch pauses any schedule already attached, because that cadence was never sized against an audience - re-create it after the blast-ra