Building Workflows

This guide walks you through creating a workflow step-by-step.

Opening the workflow builder

1. Go to Collections → open a collection
2. Click into a Proxy
3. Click Edit Workflow

The workflow builder opens with a canvas. A new workflow starts with:

http_trigger -> response_node

You can also start from prebuilt workflow templates (orchestration, transformation, resiliency, canary) and then customize.

Adding a node

1. Click Add node in the builder toolbar to open the palette (search, drag, or click to place on the canvas)
2. Select the node type you want
3. The node appears on the canvas
4. Connect it by dragging from the output handle of one node to the input of another

Connecting nodes

Each node has:

• Input handle (left side) — where data flows in
• Output handles (right side) — where data flows out

Output handles can be:

• default — normal execution path
• success — executed when the node succeeds
• error — executed when the node fails (useful for error handling)
• Custom labels — for condition_node and switch_node branches

Drag from an output handle to an input handle to create a connection (edge).

Configuring a node

Click on any node to open its configuration panel on the right. Each node type has different fields — see the Node Reference for full details.

Fields that support expressions use {{ expression }} syntax. For example:

URL: https://api.example.com/users/{{ $json['http_trigger'].request.path_params.userId }}

Example: Enrich response with database data

Goal: When a client requests /orders/{orderId}, fetch the order from the backend, then look up the customer details from MongoDB, and return a merged response.

Workflow:

1. http_trigger
2. proxy_node (GET /orders/{orderId} from backend)
3. mongodb_node (find customer by customerId from order)
4. set_node (build combined response object)
5. response_node (return to client)

Step 1: After http_trigger, add a proxy_node

• Path: {{ $json['http_trigger'].request.path }}
• Method: {{ $json['http_trigger'].request.method }}

Step 2: Add a mongodb_node

• Credential: select your MongoDB credential
• Collection: customers
• Operation: find_one
• Filter: { "id": "{{ $json['proxy_node'].response.body.customerId }}" }

Step 3: Add a set_node to merge

• Set result.order = {{ $json['proxy_node'].response.body }}
• Set result.customer = {{ $json['mongodb_node'].document }}

Step 4: Add a response_node

• Status: 200
• Body: {{ JSON.stringify($json['set_node'].result) }}

Example: Mock an API (no backend)

Goal: Return a static response without any backend.

Workflow:

http_trigger → response_node

In response_node:

{
  "status": 200,
  "headers": { "Content-Type": "application/json" },
  "body": "{\"message\": \"Hello from Zerq!\", \"items\": [1, 2, 3]}"
}

This is useful for building API stubs while the real backend is in development.

Example: Conditional routing

Goal: Route to different backends based on the request's plan query parameter.

Workflow:

1. http_trigger
2. condition_node (plan == "enterprise")
3. true branch -> http_request_node (enterprise backend)
4. false branch -> http_request_node (standard backend)
5. both branches connect to response_node

condition_node config:

• Condition: $json['http_trigger'].request.query.plan === 'enterprise'
• True branch → enterprise node
• False branch → standard node

Testing a workflow

Testing works regardless of whether the workflow is enabled or disabled.

Execute Workflow

Use Execute Workflow in the toolbar to run the graph with sample data. You can:

• Set test request parameters, headers, and body (when the entry node is http_trigger)
• See the output of each node after execution
• Debug expressions and data flow

If execution fails, a compact Run failed chip appears in the toolbar. Click Details to read the full message in a small overlay panel. Click outside the panel or press Escape to close it; use Dismiss to clear the error.

Trigger test-listen modes

For trigger nodes that wait for external events, use the dedicated test-listen panel available in the node config:

Trigger	Test mode	How it works
http_trigger	Listen for Request	Opens a temporary URL; send an HTTP request to it and the payload is captured
imap_trigger	Listen for Email	Connects read-only to IMAP; waits for the first unseen email
cron_trigger	Execute Workflow	Runs immediately with a mock triggered_at timestamp
kafka_consumer	Execute Workflow	Runs immediately with mock Kafka message fields
manual_trigger	Execute Workflow	Runs immediately with a mock triggered_at timestamp

After a trigger event is captured, the downstream workflow runs automatically so you can inspect all node outputs in one pass. See Testing: Listen for Trigger for full details.

Saving vs enabling

Save and Enable are independent actions.

Action	What it does	Requires workflow enabled?
Save	Persists the workflow definition to the backend	No — save works at any time
Enable	Activates production triggers (IMAP scheduler, cron, Kafka consumer)	N/A — this is the toggle

The Save button is disabled when the workflow definition has no unsaved changes. It becomes active as soon as you modify the canvas (add/remove nodes, change config fields, reconnect edges). If you attempt to navigate away or refresh the page with unsaved changes, the browser will prompt you to confirm.

Enabling a workflow does not automatically save. Likewise, saving does not start production triggers — triggers only run when the workflow is both enabled and in published status.

When a workflow is disabled, you can still:

• Edit the canvas and save
• Run test modes (Execute Workflow, Listen for Request, Listen for Email)

Enabling / disabling

Use the Enable Workflow toggle in the builder toolbar to activate or deactivate production execution without deleting the workflow.

• Enabled: production triggers (cron scheduler, Kafka consumer, IMAP scheduler) are active. For http_trigger workflows the proxy routes live traffic through the workflow engine.
• Disabled: production triggers are stopped. The proxy falls back to simple pass-through forwarding. All test modes remain available.

Validating a workflow

Click Validate to check the workflow definition for:

• Exactly one entry trigger node (http_trigger, manual_trigger, cron_trigger, kafka_consumer, or imap_trigger)
• Missing required node fields
• Invalid expression syntax
• Disconnected nodes (nodes with no path to response_node)
• Circular dependencies

Workflows with zero entry triggers or multiple entry triggers are rejected by backend validation (including when toggling to enabled).

Related docs

• Workflow Templates