Workflow Design Guide

Design Flowker workflows with confidence — node types, edges, real-world patterns, status transitions, and best practices for reliable orchestration.

Design workflows in Flowker with clarity and control. This guide walks through node types, edges, real-world patterns, status transitions, technical limits, and best practices to help you build reliable and maintainable orchestrations.

Node types

---

Every workflow is built from nodes. Each node has a type that defines how Flowker processes it at runtime.

trigger

A trigger node is an execution entry point. Draft workflows can be incomplete, but activation requires at least one trigger node. When an execution starts through a trigger, the engine enters at that node and routes from it.

The examples on this page show node topology only. A real trigger node also carries a triggerType and that trigger’s configuration in its data — see Configuring a webhook trigger or Running a workflow on a schedule.

{
  "id": "node-trigger",
  "type": "trigger",
  "name": "Payment Received"
}

executor

Calls an external service through a provider configuration. This is the core building block for integrating with fraud engines, payment providers, notification services, and other external systems.

The examples on this page show node topology only. A real executor node also carries a providerConfigId in its data, plus an executorId naming the catalog executor it invokes. A node that calls an operation of an uploaded OpenAPI document omits the executorId and carries operation_path and operation_method instead. See the Integration guide.

{
  "id": "node-fraud-check",
  "type": "executor",
  "name": "Check Fraud Score"
}

conditional

Evaluates a condition against the execution context and routes to different branches based on the result. Use conditional nodes to implement branching logic, for example, routing to an approval path when risk is high, or continuing directly when it is low.

The condition lives in the node’s data.condition. A free-text expression evaluates to a boolean and produces the output handle true or false; each outgoing edge declares which handle it follows via sourceHandle. Conditional nodes built in the Console use a structured, case-based condition where each case routes to its own output handle — see the Canvas editor.

{
  "id": "node-risk-decision",
  "type": "conditional",
  "name": "Evaluate Risk Score",
  "data": { "condition": "node-fraud-check.riskScore < 70" }
}

action

Represents a synchronous internal set_output operation. It can write an interpolated output value and, optionally, override the synchronous HTTP response status. It does not provide a built-in pause, generic event emission, or a generic state-change operation.

{
  "id": "node-record-approval",
  "type": "action",
  "name": "Record Approval Decision"
}

Edges

---

Edges connect nodes and define execution paths. Each edge includes the following fields:

Field	Description
id	Unique identifier for the edge.
source	ID of the origin node.
target	ID of the destination node.
sourceHandle	Output handle of the source node this edge follows. Required to route out of a conditional node: it must match the branch outcome (true or false for a free-text condition).
condition	Legacy free-text field kept for backward compatibility. It is not evaluated for routing — leave it empty for new workflows.
label	Human-readable label used for visualization and debugging.

Example edge

{
  "id": "edge-approved",
  "source": "node-risk-decision",
  "target": "node-process-payment",
  "sourceHandle": "true",
  "label": "Approved"
}

Routing depends on the source node’s type. A conditional node evaluates its data.condition and follows the single outgoing edge whose sourceHandle matches the branch outcome; if no edge matches, that branch ends. Every other node type follows all of its outgoing edges when it completes successfully.

Status transitions

---

Workflows follow a well-defined lifecycle. Understanding these transitions is key to safely deploying and evolving workflows.

• draft — The initial state. All modifications (adding nodes, editing edges, changing configuration) are only allowed in draft status.
• active — A workflow that has been activated. It can be executed. No modifications are permitted while active.
• inactive — A workflow that has been deactivated. It can no longer be executed, but it can be moved back to draft for editing.

Rules

• Only a draft workflow can be activated (transition: draft → active).
• Only an active workflow can be deactivated (transition: active → inactive).
• Only an inactive workflow can be moved back to draft (transition: inactive → draft).
• Attempting an invalid transition returns error FLK-0102.
• Attempting to modify a workflow that is not in draft returns error FLK-0103.

Moving an inactive workflow back to draft

If you deactivated a workflow and want to edit it again, move it back to draft by calling POST /v1/workflows/{id}/draft. This makes the workflow editable without needing to clone it.

This is useful when you deactivated a workflow by mistake or when you want to iterate on an existing workflow instead of creating a copy.

Only inactive workflows can be moved to draft. If you need to modify an active workflow without taking it offline, use the clone approach described below.

Iterating safely with clone

To modify an active workflow, clone it first. Cloning creates a new draft from any status, copying all nodes and edges. You can then update, test, and activate it without impacting the current version.

This is the recommended approach for production versioning.

Technical limits

---

Limit	Value	Error code
Maximum nodes per workflow	100	FLK-0113
Maximum edges per workflow	200	FLK-0114
Maximum execution input payload	1 MB	FLK-0506

Keep these limits in mind when designing complex flows. Workflows with more than ~50 nodes usually indicate that the flow should be split into smaller, composable workflows.

Common patterns

---

Sequential

The simplest pattern. Nodes execute in a linear sequence. Use this when each step depends on the previous one and no branching is required.

Example: Payment orchestration

{
  "nodes": [
    { "id": "n1", "type": "trigger",  "name": "Payment Initiated" },
    { "id": "n2", "type": "executor", "name": "Validate Payment Data" },
    { "id": "n3", "type": "executor", "name": "Route to Provider" },
    { "id": "n4", "type": "executor", "name": "Send Confirmation Notification" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Valid" },
    { "id": "e3", "source": "n3", "target": "n4", "label": "Routed" }
  ]
}

Conditional branching

A conditional node evaluates its condition and routes execution accordingly. The branch outcome selects which outgoing edge is followed, matched by sourceHandle.

Example: Anti-fraud check

{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Transaction Received" },
    { "id": "n2", "type": "executor",    "name": "Get Fraud Score" },
    {
      "id": "n3",
      "type": "conditional",
      "name": "Evaluate Score",
      "data": { "condition": "n2.fraudScore < 70" }
    },
    { "id": "n4", "type": "executor",    "name": "Approve Transaction" },
    { "id": "n5", "type": "executor",    "name": "Reject Transaction" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Score received" },
    {
      "id": "e3",
      "source": "n3",
      "target": "n4",
      "sourceHandle": "true",
      "label": "Approved"
    },
    {
      "id": "e4",
      "source": "n3",
      "target": "n5",
      "sourceHandle": "false",
      "label": "Rejected"
    }
  ]
}

Real-world examples

---

Anti-fraud check

A transaction arrives, a fraud score is retrieved, and execution is routed to approval or rejection.

{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Transaction Received" },
    { "id": "n2", "type": "executor",    "name": "Get Fraud Score" },
    {
      "id": "n3",
      "type": "conditional",
      "name": "Evaluate Fraud Score",
      "data": { "condition": "n2.fraudScore < 70" }
    },
    { "id": "n4", "type": "executor",    "name": "Approve Transaction" },
    { "id": "n5", "type": "executor",    "name": "Reject and Notify" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Score received" },
    {
      "id": "e3",
      "source": "n3",
      "target": "n4",
      "sourceHandle": "true",
      "label": "Low risk"
    },
    {
      "id": "e4",
      "source": "n3",
      "target": "n5",
      "sourceHandle": "false",
      "label": "High risk"
    }
  ]
}

Payment orchestration

A linear flow that validates incoming payment data, routes it to the appropriate provider, and sends a confirmation.

{
  "nodes": [
    { "id": "n1", "type": "trigger",  "name": "Payment Initiated" },
    { "id": "n2", "type": "executor", "name": "Validate Payment Data" },
    { "id": "n3", "type": "executor", "name": "Route to Payment Provider" },
    { "id": "n4", "type": "executor", "name": "Send Confirmation" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Valid" },
    { "id": "e3", "source": "n3", "target": "n4", "label": "Payment routed" }
  ]
}

KYC onboarding

Use a workflow to submit a document check to an external approval system. Flowker does not have a built-in pause: for asynchronous human review, start a later, separate workflow execution after your approval system publishes its decision.

Manual approval flow

A submission is sent for review. An executor retrieves the review decision from the external system. A conditional node then routes to either the approved or rejected path. Flowker executions run straight through — there is no built-in pause step, so a human decision must come from an external system the workflow queries.

{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Request Submitted" },
    { "id": "n2", "type": "executor",    "name": "Submit for Review" },
    { "id": "n3", "type": "executor",    "name": "Get Approval Decision" },
    {
      "id": "n4",
      "type": "conditional",
      "name": "Decision Received",
      "data": { "condition": "n3.decision == 'approved'" }
    },
    { "id": "n5", "type": "executor",    "name": "Process Approved Request" },
    { "id": "n6", "type": "executor",    "name": "Notify Rejection" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Submitted" },
    { "id": "e3", "source": "n3", "target": "n4", "label": "Decision received" },
    {
      "id": "e4",
      "source": "n4",
      "target": "n5",
      "sourceHandle": "true",
      "label": "Approved"
    },
    {
      "id": "e5",
      "source": "n4",
      "target": "n6",
      "sourceHandle": "false",
      "label": "Rejected"
    }
  ]
}

Best practices

---

Node naming conventions

Use descriptive, action-oriented names that communicate what the node does, not what type it is.

• correct: Validate Payment Data, Get Fraud Score, Notify Customer, Get Approval Decision
• wrong: executor1, conditional node, node3

Good names make workflows readable without opening the node configuration. They also appear in execution records and traces, making debugging significantly faster.

Condition expressions

Free-text conditions on conditional nodes are evaluated against the execution context at runtime. Keep them simple and explicit:

• Use direct field comparisons: <nodeId>.status == 'approved'
• Use numeric comparisons: <nodeId>.riskScore < 70
• Use boolean fields: <nodeId>.reviewRequired == true
• Combine with AND / OR when needed: <nodeId>.score < 70 AND <nodeId>.verified == true

Avoid complex expressions that are hard to read or debug. If logic is non-trivial, give the conditional node a clear name that encapsulates the decision.

A condition that is missing or fails to evaluate at runtime fails the execution (FLK-0105 identifies an invalid conditional expression). Always test conditions before activating a workflow.

Error handling strategies

Design workflows to handle failure explicitly:

• Add rejection paths from conditional nodes for every decision point that can fail.
• Use separate executor nodes for retry logic or fallback providers.
• Name error paths clearly (e.g., Reject and Notify, Fallback to Manual Review) so execution records are self-explanatory.

Avoiding cycles

Flowker uses a DFS-based cycle guard at runtime. If a cycle is detected during execution, the workflow fails with FLK-0508. Cycles are not caught at design time, so validate your edge structure before activating.

Rules to prevent cycles:

• Edges must always point forward in the flow — never back to a previously executed node.
• Review the graph visually before activating any workflow with branching or merging paths.
• If a retry or loop is needed, model it as a separate workflow invocation, not a back-edge in the current graph.

Versioning via clone

Never edit an active workflow directly. Instead:

1. Clone the workflow (creates a new draft with all nodes and edges copied).

2. Make your changes in the draft.

3. Validate or preview the draft. Activate it before running execution tests.

4. Activate the new version.

5. Deactivate the old version if it is no longer needed.

This preserves the execution history of the active version and gives you a clean rollback path if the new version has issues.

Error reference

---

The following error codes are relevant to workflow design and execution:

Code	Description
FLK-0102	Invalid status transition
FLK-0103	Workflow cannot be modified — not in draft status
FLK-0105	Invalid conditional expression
FLK-0113	Too many nodes — maximum is 100
FLK-0114	Too many edges — maximum is 200
FLK-0506	Execution input payload too large — maximum is 1 MB
FLK-0508	Cycle detected during workflow execution