Orchestrate a Workflow

The workflow editor uses a React Flow canvas. The node panel on the left adds nodes, the central canvas connects the flow, and the drawer on the right configures the selected node. Workflows support manual triggers, webhook triggers, and cron scheduling (requires additional deployment of a scheduler task).

Workflow Builder Interface

Layout

The workflow editor consists of the following parts:

• Nodes Panel (Left): Available node types, organized by category
  • Model: LLM, Media Generation
  • Logic: Condition, Question Classifier, Decision, Iteration, Loop, Pause
  • Transform: Code, Template, File to URL, Variable Aggregator, Variable Assignment, Parameter Extractor
  • Extension: Sub-workflow, Agent, Tool, Knowledge Retrieval, Answer
• Canvas (Center): Workflow design area; add, connect, and arrange nodes
• Properties Panel (Right): Node configuration, settings, and variables
• Toolbar (Top): Save workflow, test (debug) workflow, zoom controls

Building a Workflow — Step by Step

1. Add a Start Node: Every workflow begins with a start node (user input or trigger), which defines the input parameters
2. Add Processing Nodes: Add nodes to process data; see Node Types below
3. Connect Nodes: Click the output port of the source node, drag to the input port of the target node
4. Configure Nodes: Configure each node's settings in the properties panel
5. Add an Answer Node: Use the Answer node to define the final output returned by the workflow; it is the builder's output node, not a separate runtime terminal named end
6. Test the Workflow: Click the Test (debug) button, enter test inputs, run, and review results
7. Save and Publish: Click Save to store as a draft; click Publish to activate the workflow

Variables and Data Flow

Variable Scope:

• Input Variables: Defined at the start node, collected from the user or trigger
• Node Variables: Outputs from nodes, referenced in subsequent nodes
• System Variables:
  • {{workflow.id}} — Workflow ID
  • {{workflow.name}} — Workflow name
  • {{run.id}} — Current run ID

Variable Usage:

• In prompts: Analyze this inquiry from {{customer_email}}: {{inquiry_text}}
• In conditions: {{analysis.urgency}} == "high"

Error Handling

There is no try-catch / retry UI in the builder. What happens after a node failure depends on the executor and workflow structure; the error is recorded on the run/node execution for inspection. The HTTP request executor retries up to 3 times by default, but the builder has no separate retry setting.

Workflow Templates

Built-in workflow templates:

• Simple Q&A Bot: A basic question-answering bot using an LLM
• RAG Knowledge Bot: Knowledge-base-powered Q&A with retrieval augmentation
• Intent Router: Route conversations based on detected intent
• Code Review Assistant: Automated code review with multiple perspectives

Templates are instantiated into new workflows. After instantiation, review and configure model, knowledge-base, and other node references in the editor; do not assume that template variable names are fixed API field names.

Keyboard Shortcuts

• Space + Drag: Pan canvas
• Ctrl/Cmd + Scroll: Zoom
• Ctrl/Cmd + 0: Reset zoom

Creating and Saving Drafts

1. Navigate to Apps > Create App > Workflow.
2. In Workflow Settings, fill in the name, description, visibility, and owning team.
3. Choose a start node: User Input suits interactive forms; Trigger suits API or Webhook calls.
4. Drag nodes from the node panel onto the canvas, or click Add Node.
5. Drag from a source handle to a target handle to create a connection. The start node cannot be deleted.
6. Select Save. The editor records the last saved time and unsaved state.

Defining Variables

Start nodes use workflow-level variables. Variable types include text, paragraph, dropdown options, number, boolean, array, object, file, image, multi-file, and multi-image. Each variable can set required, default value, label, and description.

Use the editor selector when referencing variables; do not hand-write names that do not exist. The current definition format schema_version: 2 supports native object and array passing.

Node Types

The editor provides the following node types, organized by category:

The palette organizes nodes into four categories; the tables below use the same grouping. Type identifiers are what you write in API definitions, so use the exact values from the tables.

Model Nodes

Logic Nodes

Transform Nodes

Extension Nodes

Configuring Nodes

Configure node parameters by task:

LLM Node

• Model: Select a configured model (e.g., GPT-4 Turbo, Claude, etc.)
• Prompt: Use {{variable}} syntax to reference upstream variables
• Temperature: Commonly configured as 0-2; the available range depends on the selected model. Controls output randomness
• Max Tokens: Limit the length of model output
• Top P: Commonly configured as 0-1; the available range depends on the selected model. Nucleus sampling parameter
• Output Variable: Define the variable name to store model output

Output variables: response, reasoning, usage (plus the configured output variable).

Media Generation Node

• Provider: image | video
• Prompt: {{prompt}}
• Width/Height: (image)
• Duration/Aspect Ratio: (video)

Condition Node

• Condition Expression: Use Jinja2 syntax, e.g., {{analysis_result.urgency}} == "high"
• True Branch: Downstream node connected when condition is true
• False Branch: Downstream node connected when condition is false

Question Classifier Node

Classify the user's input into one of several intents/categories and route accordingly. It puts the categories in a prompt for a chat model to answer as JSON, then parses category out of the text; use the Decision node below when you need probabilities, confidence, or a guarantee that the answer will not come back in the wrong shape.

Decision Node

A Decision node asks a decision model (non-generative) one typed question about a state and takes the branch that matches the answer. The model produces no prose — it returns a probability distribution plus a confidence, so the route never depends on parsing generated text and cannot drift because the model added an extra sentence.

The question type determines branch handles and outputs:

Branch handles and renaming

• Each option (choice) or level (score) is an output handle on the canvas, named after that option or level; the fallback handle is named by defaultHandle (default by default).
• Editing option text remaps existing connections by position as long as the number of options is unchanged. If the count changed, the leftover connections point at an outdated output handle and the checklist reports decisionBranchHandleInvalid — reconnect them to a current handle.
• You do not have to connect every branch, but any branch you do connect needs downstream nodes. A low-confidence answer is rerouted to the fallback branch, so if the fallback has no downstream nodes the flow ends at this node.

Fallback branch and confidence threshold

• The threshold only fires when confidence is strictly below it; a confidence exactly equal to the threshold still takes the model's branch.
• The threshold affects routing only, not outputs: answer is always the option/level the model picked, while selected_handle is the branch actually taken.
• Without a threshold, only "no branch handle resolved" uses the fallback. noul never uses the fallback because it always answers yes or no.
• A decision node is retried up to 2 times by default (1 second initial delay, exponential backoff with jitter). Retries are independent of the threshold, which exists for answers that came back uncertain.

Output variables

Downstream nodes can record the verdict with {{decisionNodeId.answer}}, or branch again on {{decisionNodeId.confidence}} / {{decisionNodeId.probabilities}} to add a human review layer.

Failure paths

Worked example: ticket triage

Debugging a decision branch

• The checklist reports each problem separately: model not selected, state empty, instructions empty, too few or too many options/levels, empty or duplicate options, and connections using an outdated handle.
• In the run trace, read selected_handle (which branch ran) and confidence (whether the threshold rerouted it). If it always falls to the fallback, check probabilities: two near-equal options mean adjusting the threshold, while a flat distribution means the instructions or state need rewriting.
• A decision node is one call with one result and no intermediate steps: you can only debug it by running the whole workflow — there are no breakpoints or single-step execution.

Iteration / Loop Node

• Collection: {{items}}
• Item Variable: item
• Output Variable: results

Pause Node

Pause execution until a team member supplies requested variables or submits an approval decision. A pause can be configured in Variables mode or Approval mode; a waiting run resumes after the request is handled.

• Mode: variables | approval
• Title: Review request
• Input Variables: List of variables to collect or approve

Code Node

• Language: Python or JavaScript
• Code: Custom execution logic
• Timeout: The code executor currently fixes this at 30 seconds; it is not a freely configurable 1-300 second range in the builder
• Input Variables: Variables passed to the code
• Output Variables: Variables returned by the code execution

Template Node

Render a template string with variables (e.g., Jinja-like {{variable}} substitution).

File to URL Node

Convert a file (e.g., a sandbox artifact) into a downloadable URL.

Variable Assignment Node

Assign a value to a variable.

Variable Aggregator Node

Aggregate values (e.g., collect loop iteration results into an array).

Parameter Extractor Node

Extract structured parameters from text using LLM, regex, or JSON path.

• Extraction Method: llm | regex | json_path
• Source Variable: {{source}}
• Parameters: [...]

HTTP Request Node

• Method: GET / POST / PUT / PATCH / DELETE
• URL: Target endpoint address
• Headers: Custom HTTP headers
• Body: JSON-formatted request payload
• Timeout: Default 30 seconds; no verified 1-300 second code-execution timeout range is exposed
• Output Variable: Store the response data

Tool Node

• Tool: Select a configured tool
• Parameter Mapping: Map upstream variables to tool parameters
• Output Variable: Store the tool execution result

Built-in tools available: web_search, fetch_webpage, calculate, unit_convert, get_weather, get_current_time, format_datetime, markitdown, plus sandbox tools (bash, read, edit, write, artifact).

Knowledge Retrieval Node

• Knowledge Base: Select the target knowledge base
• Query Template: Use {{variable}} to reference query content
• Top K: Default 5; the exact upper bound depends on the endpoint and configuration, so this guide does not present a fixed 1-100 range
• Score Threshold: Default 0.0. Minimum similarity score
• Search Mode: hybrid

Sub-workflow Node

Run another workflow as a sub-step and capture its output.

Agent Node

Invoke an AI agent with a message and optional context.

Answer Node

Return a final answer/output from the workflow.

Trigger Configuration

Workflows support three trigger types:

Manual Trigger

No additional configuration required. Once published, users with permissions can trigger the workflow via the UI or API.

Webhook Trigger

After setting the trigger type to Webhook, the system automatically generates a webhook token. The trigger endpoint is:

POST /api/v1/workflows/webhook/{webhook_token}

Request requirements:

• Authentication: Provide a valid clou_ API key in the Authorization header
• Body: Workflow input variables (raw JSON or {"inputs": {...}} format)
• Webhook token: Matched using constant-time comparison to prevent timing attacks

Cron Trigger

After setting the trigger type to Cron, the schedule expression is stored in trigger_config (e.g., 0 9 * * 1-5 for weekdays at 9 AM). The UI's frequency presets are converted into the same expression; custom mode takes minute hour day month weekday directly.

Draft and Publication

Workflows have three statuses:

Draft

• Workflow is being edited
• Cannot be triggered
• Visible only to editors
• Can be saved at any time

Published

• Workflow is operational
• Can be triggered via UI, API, or webhook
• Visible to all users with permissions
• Must be unpublished before modification

Archived

• Workflow is retired
• Not visible in normal lists
• Configuration preserved

Pre-publish Checks

Select Checklist and resolve the following issues before debugging and publishing:

After validation passes, use Debug Run to test the workflow, confirm the output matches expectations, then publish.

Running a Workflow

Accessing Workflows

1. Navigate to Apps (/app/apps).
2. Open the Workflow tab.
3. Select a workflow card to open /app/apps/workflow/{id}.
4. Choose Run to start a manual execution.

Workflow List

The list shows:

Manual Execution

Steps:

1. Open the workflow
2. Click the Run button
3. If the workflow has input variables:
   • Fill in required inputs
   • Review optional inputs
   • Click Start
4. Watch the execution in real-time
5. View the results when complete

Input Variables

Workflows may require inputs:

• Text: Free-form text input
• Number: Numeric values
• Select: Dropdown options
• Boolean: Yes/No checkbox

Watching Execution

Real-time progress:

• ⏸️ Pending: Not started yet
• ⏳ Running: Currently executing
• ⏳ Waiting: Paused for an external input or approval
• ✅ Success: Completed successfully
• ❌ Failed: Execution failed
• ⏭️ Skipped: Skipped (conditional)

Execution Details: Click on a node to see details including status, duration, input, and output.

Streaming Output: LLM nodes stream their output in real-time; the execution view shows partial content while running.

Execution Results

Success: Shows execution duration, nodes executed, and status.

Failed: Shows the failed node and error message.

Common Errors:

• Invalid input format
• API call failed
• Timeout exceeded
• Resource not found
• Permission denied

Stopping Execution

During execution:

1. Click the Stop Execution button
2. Confirm the stop action
3. The workflow stops at the current node

Workflow Variables

Input Variables: Provided when starting the workflow.

Output Variables: Generated during execution by the Answer node and other node outputs.

Viewing Execution History

Execution History

1. Select a workflow
2. Click the Execution History tab
3. View the run list:
   • Run ID
   • Status (running, success, failed, etc.)
   • Start time
   • Duration
   • Trigger source
   • Input/Output

Related API endpoints:

• GET /api/v1/workflows/runs - Get all run records
• GET /api/v1/workflows/{workflow_id}/runs - Get runs for a specific workflow
• GET /api/v1/workflows/{workflow_id}/runs/mine - Get current user's runs

Execution Details

Click an individual run to view detailed information:

• Run Information: Run ID, workflow name, status, start time, completion time, duration, trigger method
• Node Execution Timeline: Start time, completion time, and duration for each node
• Node-level Details: GET /runs/{run_id}/nodes for per-node execution details
• Streamed Events: GET /runs/{run_id}/stream for real-time node execution events

Workflow Logs

Workflow execution history is available from the workflow's Logs view at /app/apps/workflow/{id}/logs. Open Apps → Workflow, select the workflow, then choose Logs from its workflow menu.

Run Details Fields:

Status Icons:

Viewing Node Execution Details

View the node-by-node execution:

1. Open the run's node executions
2. Each node shows its status, duration, input, output, and error (if any)

Streaming

Runs stream events in real-time (GET /api/v1/workflows/runs/{run_id}/stream), including node status updates and LLM token output.

Filtering History

Execution Statistics

Summary metrics (per workflow or system-wide):

• Total Runs
• Success Rate
• Failed Runs
• Avg Duration

Deleting History

Delete Single Execution:

1. Find the execution in the history
2. Click the "..." menu
3. Select "Delete"
4. Confirm deletion
5. The execution is removed

Webhook Management

Creating or Regenerating a Webhook Token

1. Edit the workflow
2. Set trigger type to Webhook
3. Save — a webhook_token is generated automatically
4. Regenerate anytime via POST /api/v1/workflows/{workflow_id}/regenerate-webhook-token

Testing a Webhook

Use curl to test the webhook:

curl -X POST "https://your-domain.com/api/v1/workflows/webhook/TOKEN" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "test@example.com",
    "inquiry_text": "Test inquiry",
    "priority": "low"
  }'

Webhook Logs

API Endpoints

The Workflow API supports programmatic management of the workflow lifecycle:

Troubleshooting

Workflow Execution Failed

1. Open the failed run in Execution History
2. Check node execution details and error messages
3. Common errors:
   • Node Timeout: Increase timeout or optimize the node
   • Invalid Input: Validate input variable format
   • API Error: Check API credentials and connectivity
   • LLM Error: Verify model availability and API key
   • Tool Error: Check tool configuration
4. Re-trigger using POST /api/v1/workflows/{workflow_id}/run

Webhook Not Triggering

1. Confirm the workflow trigger type is webhook
2. Confirm POST to the correct /api/v1/workflows/webhook/{webhook_token} endpoint
3. Confirm the Authorization header contains a valid clou_ API key
4. Confirm the workflow is published (unpublished workflows reject webhook triggers)

Schedule Not Running

1. Confirm the workflow is published and trigger_type is cron
2. Confirm trigger_config holds a valid cron expression (the scheduling task reads the cron key)
3. Confirm the custom deployment added app.services.workflow.tasks to the Celery include list and dispatches workflow.check_scheduled from Beat (once a minute, for example)
4. Confirm the worker running that task consumes the queue it actually lands on (default)

High Execution Time

1. Optimize nodes: Reduce LLM max_tokens, use faster models, optimize tool calls
2. Shorten the serial chain: the plan is layered by topology, but nodes inside a layer still run one after another and the canvas has no parallel node; fold repeated work into an Iteration node and shrink its input instead
3. Add timeouts: Set reasonable node timeouts and handle gracefully
4. Monitor performance: Review run duration statistics in run history

Workflow Won't Start

1. Check if the workflow is published
2. Verify you have permission to run
3. Ensure all required inputs are provided
4. Refresh the page and try again

Execution Stuck

1. Check if a node is waiting for an external response
2. Verify API endpoints are accessible
3. Stop and restart the execution
4. Contact the administrator

Cannot View History

1. Refresh the page
2. Check if you have permission
3. Verify the workflow has been executed
4. Check the date-range filter
5. Contact the administrator

Missing Executions

1. Check filters (may be hiding results)
2. Verify the date range
3. Check if executions were deleted

Cannot Start a New Run

1. Check that you have permission to run the workflow
2. Verify the workflow is published
3. Start a new execution from the workflow page

Best Practices

Workflow Design

• Keep workflows simple and focused; avoid excessive complexity
• Use descriptive node names, include an action verb, be specific
• Add error handling logic
• Test thoroughly before activation
• Document workflow purpose
• Use variables for reusability; avoid hardcoding values
• Add logging for debugging
• Set appropriate timeouts

Performance Optimization

• Reduce serial steps: there is no parallel node, and independent nodes in the same layer still run one after another; merging nodes beats splitting them and hoping they overlap
• Keep iteration size down: an Iteration node that exceeds its cap truncates its input, so filter out items you do not need first
• Cache repeated operations
• Optimize LLM prompts
• Use appropriate models for the task
• Set reasonable timeouts
• Monitor execution times
• Optimize tool calls

Inputs and Monitoring

Inputs:

• Provide all required inputs
• Use correct data types
• Test with sample data first

Monitoring:

• Watch the execution progress
• Check node outputs
• Stop if behavior is unexpected

Error Handling:

• Read error messages carefully
• Check input values
• Review node configuration
• Try again with corrected inputs

Security

• Use webhook authentication (API key in Authorization header)
• Regenerate webhook tokens when compromised
• Enable audit logging
• Monitor for suspicious activity

Exiting and Lost Changes

Before returning to the app list or closing the page, the editor shows a confirmation dialog when there are unsaved changes. Select Leave Without Saving to discard the current draft changes.