Skip to content

Start with Triggers

Start a flow automatically by configuring a trigger source and mapping values into the flow’s inputs. To run an agent at set times, use an agent schedule instead of a workflow. An enabled source records events before publication, independently of execution. Ordinary dispatch runs the published live release. Development tests perform real actions and spend usage.

For Daily invoice digest, use workflow data with these development rows:

Invoice ID Amount Review needed
INV-104 120 false
INV-105 1500 true
INV-106 600 false

Configure one digest at 09:00 America/Chicago. Create the docs-digest-test Slack channel and select its actual ID. Expect three invoices, one needing review, and exactly one message per run. An empty queue must produce one zero-item digest. Before live verification, separately import or copy live rows. Publishing copies no records.

Source Configure Deliver a sample
Schedule Time and timezone Wait for a scheduled firing.
Webhook Generated endpoint Send a request to the returned URL.
Email Generated inbound address Send email to that address.

In the app: open Workflows → Daily invoice digest → flow → Triggers → Add new trigger. Choose the source/event, complete the settings, then choose Add Trigger. For schedules, choose Daily → Time → 09:00. There is no timezone picker. The timezone comes from the stored setting or your profile. To specify America/Chicago, use the assistant path.

With an assistant: every workflow-scoped tool call carries an explicit workflowId. Find the workflow’s ID with workflow_list:

{ "limit": 100 }

Note its data.items[].id as <workflowId>. Only when data.hasMore is false can you trust a workflow’s absence. Otherwise, get the ID from the app or owner. Find the flow with flow_list:

{ "workflowId": "<workflowId>" }

Find the schedule source with trigger_search:

{ "workflowId": "<workflowId>", "query": "schedule" }

Note the flow’s data.items[].id as <flowId> and the schedule’s data.nodes[].slug and eventKeys[].key as <slug> and <eventKey>.

Inspect the schedule properties with trigger_component_props to find the values needed for creation.

{ "workflowId": "<workflowId>", "node": "<slug>", "event": "<eventKey>" }

Start with data.propsForCreate and leave hidden props unset. Create only when data.readyForCreate is true and required values are filled. Timezone priority is the explicit setting, your profile, then UTC. Create this schedule with trigger_create, passing the nested cron object in props, to get its creation fields.

{
"workflowId": "<workflowId>",
"flow": "<flowId>",
"node": "<slug>",
"event": "<eventKey>",
"sourceBasis": "explicit-in-request",
"props": { "cron": { "cron": "0 9 * * *", "timezone": "America/Chicago" } }
}

Keep four creation fields under data as distinct placeholders. Use triggerId to control the canvas and backendTriggerId to list or replay events. Use triggerNodeId to select samples and runSubflowNodeId to map inputs.

Creating a trigger provisions the source before saving the canvas. After STATE_CONFLICT or an uncertain result, inspect existing triggers and provider sources before retrying. Cleanup can fail. Another create can duplicate a source.

List triggers with trigger_list to see which already exist.

{ "workflowId": "<workflowId>" }

Does another source need an account or options?

Section titled “Does another source need an account or options?”

Use that source’s discovered <slug> and <eventKey>. Below, <nodeSlug> is the same slug. List connections with connection_list and, if none fits, request a link to connect an account with connection_connect_url.

{ "integration": "<slug>" }
{ "nodeSlug": "<nodeSlug>" }

Complete the connection at data.url, list again, and note data.items[].id as <connectionId>.

Inspect properties with that connection, using trigger_component_props, to get the creation values.

{ "workflowId": "<workflowId>", "node": "<slug>", "event": "<eventKey>", "connection": "<connectionId>" }

Keep data.propsForCreate with your chosen values as the <configured> object. Keep the latest data.id as <dynamicPropsId>. Resolve each data.unresolvedOptionProps name as <name>. To find its options with trigger_prop_options, replace <text> with the desired option label.

{
"workflowId": "<workflowId>",
"node": "<slug>",
"event": "<eventKey>",
"connection": "<connectionId>",
"prop": "<name>",
"configured": <configured>,
"dynamicPropsId": "<dynamicPropsId>",
"query": "<text>"
}

To browse options, omit query and pass "page": 0. On subsequent zero-based pages, pass the returned data.context as prevContext. Merge the exact data.options[].value into <configured>. Reload the properties with trigger_component_props to check whether the trigger is ready for creation.

{
"workflowId": "<workflowId>",
"node": "<slug>",
"event": "<eventKey>",
"connection": "<connectionId>",
"configured": <configured>,
"dynamicPropsId": "<dynamicPropsId>"
}

When readyForCreate is true and required values are filled, create this alternative. According to the source choice, use <basis> as explicit-in-request, user-answer, or inferred-from-existing-workflow. Omit connection and dynamicPropsId when they are not needed. Create the alternative source with trigger_create to get its creation IDs.

{
"workflowId": "<workflowId>",
"flow": "<flowId>",
"node": "<slug>",
"event": "<eventKey>",
"sourceBasis": "<basis>",
"connection": "<connectionId>",
"props": <configured>,
"dynamicPropsId": "<dynamicPropsId>"
}

Keep these creation IDs separate.

List captured events with trigger_event_list to find a sample. It takes the backend ID as a numeric-string triggerId; every captured-event ID is also a numeric string.

{ "workflowId": "<workflowId>", "triggerId": "<backendTriggerId>", "limit": 50 }

Note the original sample’s data.events[].id as <eventId>. The default is the five newest events. The maximum is 50. Capture needs neither publication nor development permission. If nothing arrives, inspect source settings, destination and capture.sourceEnabled from trigger_get. A disabled source captures nothing.

Inspect the trigger with trigger_get (canvas triggerId) and the event with trigger_event_get, then select the sample with trigger_event_select to access its fields.

{ "workflowId": "<workflowId>", "triggerId": "<triggerId>" }
{ "workflowId": "<workflowId>", "eventId": "<eventId>" }
{ "workflowId": "<workflowId>", "triggerNodeId": "<triggerNodeId>", "eventId": "<eventId>" }

If dataTypeName or its schema is unavailable, wait and select the same event again. Write field expressions only after expression context exposes them.

In the app: open the trigger canvas for Webhook URL, Email address, and Sample event → View. For schedules, use the assistant path because the sample picker is hidden. Open the flow’s Inputs → Add new input and add Schedule as text. In the trigger’s Run flow node, set it to 09:00 America/Chicago. This example supplies a label explicitly. It assumes no schedule payload field.

With an assistant: use data.runSubflowNodeId as <nodeId> below. If absent, add the input with flow_input_add.

{ "workflowId": "<workflowId>", "flowId": "<flowId>", "display": "Schedule", "type": "text" }

Inspect its mapping property and expression context with node_prop_list and expr_context, each called with:

{ "workflowId": "<workflowId>", "nodeId": "<nodeId>" }

Keep the Schedule property’s returned name as <name>. Each input creates a mapping property. Event values never enter the flow automatically.

Set the Schedule label with node_prop_set and an inline js expression, then call node_prop_list again to inspect its mapping.

{ "workflowId": "<workflowId>", "nodeId": "<nodeId>", "prop": "<name>", "js": "\"09:00 America/Chicago\"" }

For event-derived inputs, bind the exact compatible field expression from context instead. Keep existing source IDs when repairing mappings.

First, test the flow directly with run_flow to check its logic in isolation.

{ "workflowId": "<workflowId>", "flowId": "<flowId>", "target": "dev", "inputs": { "Schedule": "09:00 America/Chicago" } }

In the app, select Dev, open the flow and choose Test (tooltip “Test current flow”). After success, replay the original sample once with trigger_replay to test the trigger path.

{ "workflowId": "<workflowId>", "triggerId": "<backendTriggerId>", "eventId": "<eventId>", "target": "dev" }

Keep the new data.eventId separate from the original sample ID. Use data.workflowExecutionId as <workflowExecutionId>. Development replay requires an enabled development trigger. It bypasses incoming-event permission. Every replay creates another captured event and real execution. Pending is not a reason to replay again.

Inspect the execution with execution_get to get its status.

{ "workflowId": "<workflowId>", "workflowExecutionId": "<workflowExecutionId>" }

Repeat until data.status is completed, completed_with_error, failed or cancelled. For paused, use execution inspection.

Then inspect the tree with execution_tree, using the same arguments, to find the node’s execution ID. Note the relevant data.items[].id as <nodeExecutionId>.

Read its values with execution_node_get to check the mapping and message.

{ "workflowId": "<workflowId>", "nodeExecutionId": "<nodeExecutionId>", "full": true }

Check mapping and send values, invoice and review counts, and exactly one Slack message per test. With the empty queue, repeat and expect one zero-item digest.

Disabling development stops its canvas execution and leaves incoming-event permission intact. It stops neither source capture nor the published trigger. Publish the disabled definition to change live execution. When retained permission would double-run alongside a live path, the assistant tools refuse re-enabling. Disallow incoming-event permission first.

Before turning Allow test events in dev mode On, rule out a live path or explicitly accept both executions and charges. While enabled, permission immediately admits real traffic. After one event, inspect Run history, then turn it Off. Replay’s target is separate.

To test incoming events intentionally, allow them into development for a real execution with trigger_test_events_set.

{ "workflowId": "<workflowId>", "triggerId": "<triggerId>", "allowed": true }

Add "acknowledgeDualRun": true only after the user accepts a reported double-run hazard.

Follow Publish a Workflow for the complete trigger audit and live verification. Publication through the assistant tools rejects unacknowledged dual dispatch. The app/shared service can publish with a warning. Capture happens before asynchronous typing and dispatch, so if no run appears, reread events and executions before diagnosing publication, enablement, routing or ingestion failure. If a run starts with empty mapped inputs, inspect its mapping.