F
Flowman docsWorkflow SDK
Back to app

Triggers and events

Triggers are the routing layer between normalized platform events and workflow runs. Connectors emit events; trigger evaluation decides which workflow deliveries should exist, and dispatch launch sends those deliveries to the workflow dispatch route.

This page exposes user-configured connector triggers only. Flowman also publishes versioned workflow lifecycle events and evaluates code-owned triggers for internal automation. Those events and trigger definitions are intentionally absent from this UI.

A run cannot be deleted while lifecycle work with a managed subscriber is pending or processing, so deletion cannot cancel an asynchronous automation. Deleting a run detaches its indexed run link but retains the lifecycle event and delivery diagnostics.

Event flow

  1. An IMAP connector polls a mailbox, applies ingestion filters, and stores a normalized email in emails.
  2. The connector ingestion mutation emits an email.received row in events.
  3. Convex schedules trigger evaluation. The evaluator loads enabled workflowTriggers for the same project and event type.
  4. Matching triggers create or reuse a triggerDeliveries row without requiring dispatch configuration.
  5. Dispatch launch reads pending deliveries, marks each one dispatching, and posts it to /api/internal/workflow-dispatch.
  6. The centralized dispatch route calls the registered workflow's existing Next.js route handler created by createWorkflowRoute.

Trigger rules

Manage rules from /p/<slug>/triggers. A rule has an optional connector scope, an event type, a target workflow, a priority, an enabled flag, and generic conditions.

  • Use Any connector when a workflow should react to the same event type across sources.
  • Use connector-specific triggers when one mailbox needs a different routing rule from another mailbox.
  • Conditions are evaluated against the event payload. For emails, common fields are email.subject, email.from, email.to, and email.hasAttachments.
  • Supported operators include contains, equals, exists, and not_equals.
  • Lower priority numbers run first. Multiple matching triggers may start multiple workflow runs for the same event.

Workflow input

Triggered runs still enter through the workflow's canonical route. The dispatch payload always includes the event payload as workflow input and a source object on the FlowmanRunRecord. The source includes the trigger id, event id, connector id, email id, and source type.

Triggers can also map values into the selected workflow's params. Each mapping can use a static literal, a dotted event field path such as email.subject, or a project env key name. Env-key mappings pass the key name into the workflow, not the secret value; the workflow resolves the key from record.env at run time. Workflow params registered with env-key or HTTP connection lookup metadata render searchable pickers and only accept existing project env keys or connection profile slugs.

record.input.event.email.subject
record.input.prompt
record.input.tokenEnvKey
record.source?.triggerId
record.source?.eventId
record.source?.connectorId
record.source?.emailId

For the coding-agent workflow, IMAP events can provide parsed email request fields and Convex-backed attachments. Map email.request.repositoryName instead of a static repository id when the sender should choose the repo from the email.

repositoryName -> email.request.repositoryName
prompt         -> email.request.prompt
planMode       -> email.request.planMode
attachments    -> email.workflowAttachments

# Fixed-repo alternative:
repositoryId   -> static registered repository id

Dispatch configuration

Trigger evaluation can create delivery records without dispatch configuration. Dispatch launch runs in a Convex action outside your browser and cannot call your machine's localhost. To launch triggered workflow runs, set a deployment environment variable named FLOWMAN_APP_URL or NEXT_PUBLIC_APP_URL to a publicly reachable app URL.

  • In production, use the public Vercel URL or custom domain for this Flowman app.
  • For local testing, expose http://localhost:4208 with zrok, then use that public URL.
  • Internal dispatch is token-guarded with FLOWMAN_INTERNAL_DISPATCH_TOKEN or, as a fallback, CONNECTOR_RUNTIME_TOKEN.

For the exact local tunnel commands and Convex cloud environment update, see Zrok setup.

Failures and retries

The Triggers page shows recent events, status, attempt count, event errors, and delivery-level errors. If dispatch launch fails after a bad deployment URL or transient problem, use Reset to move it back to pending and reschedule evaluation and launch.

  • Reset clears the event error and resets failed or pending deliveries.
  • Started deliveries remain idempotency-protected and are not rerun by reset.
  • If the dispatch URL is still unreachable, the event will fail again with the new error visible in the table.

Data model

  • events: normalized platform events with source type, payload, status, attempts, errors, and timestamps.
  • workflowTriggers: project-scoped routing rules with connector scope, event type, conditions, workflow id, priority, enabled flag, and timestamps.
  • triggerDeliveries: idempotent execution records for each event/trigger pair, including workflow and trigger snapshots used at dispatch time.
ConnectorsWorkflow routes