Skip to main content

​
Creating Workflows

This guide walks you through creating your first workflow, from setting up a trigger to executing and monitoring the workflow.

​
Prerequisites

Before creating a workflow, you’ll need:
  1. A KnoxCall account
  2. Basic understanding of APIs (HTTP requests, JSON)

​
Step 1: Create a New Workflow

  1. Navigate to Workflows in the sidebar
  2. Click + Create Workflow
  3. Enter workflow details:
Name: My First Workflow
Description: A simple workflow that fetches data and processes it
Environment: production (optional)
  1. Click Create
You’ll see the workflow editor with an empty canvas and a trigger node.

​
Step 2: Configure the Trigger

The trigger node is already on the canvas. Click it to configure: 
Trigger Type: Manual
This lets you run the workflow on-demand from the UI.

​
Webhook Trigger

Trigger Type: Webhook
Method: POST
This creates an endpoint that triggers the workflow when called.

​
Route Event Trigger

Trigger Type: Route Event
Event: request.completed
Routes: (select specific routes)
This triggers when requests pass through your routes.

​
Step 3: Add an HTTP Request Node

Let’s add a node that makes an API call:
  1. Click the + button on the trigger node’s output
  2. Select HTTP Request
  3. Configure the node:
Name: Fetch User Data

Method: GET
URL: https://jsonplaceholder.typicode.com/users/1

Headers:
  Content-Type: application/json
This calls a free test API that returns user data.

​
Step 4: Add a Code Block Node

Let’s transform the response:
  1. Click the + on the HTTP Request node
  2. Select Code Block
  3. Configure:
Name: Transform Data
  1. Enter the code:
// Get the user data from the previous node
const user = input.nodes['Fetch User Data'].response.data;

// Transform and return new data
return {
  id: user.id,
  fullName: user.name,
  email: user.email,
  company: user.company.name,
  processed_at: new Date().toISOString()
};

​
Step 5: Add a Condition Node

Let’s add conditional logic:
  1. Click the + on the Code Block node
  2. Select Condition
  3. Configure:
Name: Check User ID
Condition: {{nodes['Transform Data'].output.id}} === 1
This creates two paths:
  • True: When user ID equals 1
  • False: When user ID doesn’t equal 1

​
Step 6: Add Nodes to Each Branch

​
True Path

  1. Click the + on the Condition’s True output
  2. Select Code Block
  3. Name it: “Success Response”
  4. Code:
return {
  status: 'success',
  message: 'User verified!',
  data: input.nodes['Transform Data'].output
};

​
False Path

  1. Click the + on the Condition’s False output
  2. Select Code Block
  3. Name it: “Error Response”
  4. Code:
return {
  status: 'error',
  message: 'User verification failed',
  expected_id: 1,
  received_id: input.nodes['Transform Data'].output.id
};

​
Step 7: Save Your Workflow

  1. Click Save in the top right
  2. Your workflow is saved as version 1
Your workflow should look like this: 
[Trigger]
    ↓
[Fetch User Data] (HTTP Request)
    ↓
[Transform Data] (Code Block)
    ↓
[Check User ID] (Condition)
    ↓           ↓
   True        False
    ↓           ↓
[Success]   [Error]

​
Step 8: Test Your Workflow

​
Manual Execution

  1. Click Run in the top right
  2. (Optional) Add input data for the trigger:
{
  "test": true
}
  1. Click Execute

​
Watch Execution

You’ll see:
  • Each node highlights as it executes
  • Green checkmark when successful
  • Red X if an error occurs
  • Execution time per node

​
View Results

Click on any node to see:
  • Input: Data that went into the node
  • Output: Data that came out
  • Execution Time: How long it took

​
Step 9: Enable the Workflow

  1. Toggle Enabled to ON
  2. Your workflow is now active
For webhook triggers, you’ll now see the webhook URL to call.

​
Adding More Nodes

​
HTTP Request with POST

Name: Create Record
Method: POST
URL: https://api.example.com/records

Headers:
  Authorization: Bearer {{env.API_TOKEN}}
  Content-Type: application/json

Body:
  name: "{{nodes['Transform Data'].output.fullName}}"
  email: "{{nodes['Transform Data'].output.email}}"
  source: "workflow"

​
Loop Over Array

Name: Process Items
Type: Loop
Items: {{trigger.body.items}}
Variable: item
Inside the loop, access the current item: 
{{loop.item.name}}
{{loop.index}}

​
Delay

Name: Wait Before Retry
Duration: 5
Unit: seconds

​
Error Handler

  1. Add an Error Handler node
  2. Connect it to nodes that might fail
  3. Configure what to catch:
Name: Handle API Errors
Catch From: Fetch User Data, Create Record
  1. Add nodes after the error handler for recovery:
// In a Code Block after Error Handler
return {
  error_logged: true,
  original_error: input.error.message,
  timestamp: new Date().toISOString()
};

​
Using Variables

​
Trigger Data

// Access data from the trigger
{{trigger.body.user_id}}
{{trigger.headers['content-type']}}
{{trigger.query.page}}

​
Previous Node Output

// Access output from a named node
{{nodes['Fetch User Data'].response.data}}
{{nodes['Transform Data'].output.email}}

​
Environment Variables

// Access secrets stored in KnoxCall
{{env.API_KEY}}
{{env.SLACK_WEBHOOK}}
Environment variables use KnoxCall secrets. Create secrets in the Secrets section, then reference them in workflows.

​
Loop Variables

// Inside a loop
{{loop.item}}       // Current item
{{loop.index}}      // Current index (0-based)
{{loop.isFirst}}    // true if first item
{{loop.isLast}}     // true if last item

​
Workflow Examples

​
Simple API Call

Trigger (Manual)
    ↓
HTTP Request (GET https://api.example.com/data)
    ↓
Code Block (Format response)

​
Data Sync

Trigger (Webhook)
    ↓
HTTP Request (Fetch from Source API)
    ↓
Loop (For each record)
    ↓
HTTP Request (Push to Destination API)

​
Error Handling

Trigger
    ↓
HTTP Request → Error Handler → Slack Notification
    ↓
Code Block
    ↓
Condition
    ↓         ↓
Success    Failure
    ↓         ↓
Continue   Log Error

​
Execution History

View past executions:
  1. Open the workflow
  2. Click Executions tab
  3. See list with:
    • Status (completed, failed, running, cancelled)
    • Started at
    • Duration
    • Trigger type
Click any execution to see:
  • Full node-by-node timeline
  • Input/output for each node
  • Error details

​
Versioning

Each time you save, a new version is created:
  1. Click Versions tab
  2. See all saved versions
  3. Click a version to view it
  4. Click Restore to revert

​
Troubleshooting

​
”Variable not found”

Error: Cannot read property 'data' of undefined
Cause: Referencing a node that hasn’t executed yet or doesn’t exist. Fix: Check node names match exactly (case-sensitive).

​
”HTTP Request failed”

Error: ECONNREFUSED
Cause: Target API is unreachable. Fix:
  • Verify URL is correct
  • Check if API requires authentication
  • Ensure API is accessible from the internet

​
”Code Block error”

Error: Unexpected token
Cause: JavaScript syntax error. Fix: Check your code for:
  • Missing brackets
  • Incorrect variable references
  • Invalid JSON

​
”Condition always false”

Cause: Comparison type mismatch (string vs number). Fix: Use correct types: 
// String comparison
{{nodes.http.response.data.status}} === 'success'

// Number comparison
parseInt({{nodes.http.response.data.count}}) > 0

​
Best Practices

  1. Name nodes descriptively - “Fetch Customer Data” not “HTTP 1”
  2. Add error handlers for external API calls
  3. Test with sample data before enabling
  4. Use environment variables for secrets
  5. Keep workflows focused - one purpose per workflow
  6. Document complex logic in node names/descriptions

​
Next Steps

Workflows Overview

Understanding workflow concepts

Webhooks

Trigger workflows from webhooks

API Logs

Debug workflow API calls

Route Examples

API patterns to use in workflows

Statistics

  • Level: beginner
  • Time: 12 minutes

Tags

workflows, tutorial, getting-started, automation