Workflows

Create, manage, and execute complex workflows with visual workflow builder

What is a Workflow?

A workflow is a sequence of connected nodes that automate a process.

Workflows are the core automation engine of Blocktion. They connect blocks together to create complex, multi-step processes that can be triggered manually or by events. Each workflow consists of nodes (instances of blocks) connected by edges that define the flow of data and execution order.

Key Features

• Visual drag-and-drop interface
• Conditional logic and branching
• Error handling and retries
• Real-time execution monitoring

Use Cases

• Data processing pipelines
• API integrations
• Automated notifications
• Business process automation

Workflow Statuses

draft

Workflow is being created or edited

active

Workflow is active and can be executed

paused

Workflow is temporarily paused

archived

Workflow is archived and cannot be executed

Execution Statuses

pending

Execution is waiting to start

running

Execution is currently running

completed

Execution finished successfully

failed

Execution encountered an error

cancelled

Execution was cancelled

Workflow Nodes

Nodes are instances of blocks within a workflow. Each node represents a specific block configuration and position in the workflow graph.

Node Structure

Core properties of workflow nodes

idstring

Unique identifier for the node within the workflow

block_idstring

ID of the block this node is an instance of

position_xnumber

X coordinate for visual positioning in the workflow builder

position_ynumber

Y coordinate for visual positioning in the workflow builder

configobject

Runtime configuration and parameters for this node instance

is_triggerboolean

Whether this node can initiate workflow execution

Node Types

Different types of nodes in workflows

Trigger Nodes

Nodes that can initiate workflow execution

webhookschedulemanual

Processing Nodes

Nodes that process data and perform operations

transformapi_callconditional

Integration Nodes

Nodes that connect to external services

gmaildatabaseslack

Node Configuration

How to configure nodes in workflows

Positioning

• position_x - Horizontal position in pixels
• position_y - Vertical position in pixels
• Used for visual layout in workflow builder
• Can be updated without affecting execution

Configuration

• config - Node-specific parameters
• Inherits from block definition
• Can be overridden per node instance
• Supports expressions and variables

Example Node Configuration

{
  "node_1": {
    "id": "node_1",
    "block_id": "webhook_trigger",
    "name": "Webhook Trigger",
    "position_x": 100,
    "position_y": 100,
    "config": {
      "endpoint": "/webhook/email-campaign",
      "method": "POST",
      "timeout": 30
    },
    "is_trigger": true,
    "input_schema": {...},
    "outputs": {...}
  }
}

Node Connections

Nodes are connected through data flow and control flow connections. Connections define how data moves between nodes and the execution order. Blocktion supports both explicit user-defined connections and derived connections automatically generated from expressions.

Connection Types

Different ways nodes can be connected

Data Connections

Pass data from one node's output to another's input

connection_type: "data"

Control Flow

Define execution order and dependencies

connection_type: "control_flow"

Both

Combines data flow and control flow

connection_type: "both"

Connection Properties

Key properties of node connections

source_node_idstring

ID of the source node

target_node_idstring

ID of the target node

source_outputstring

Specific output from source node

target_inputstring

Specific input on target node

is_requiredboolean

Whether this connection is required for execution

derived_from_expressionboolean

Whether this connection was auto-generated from expressions

Explicit Connections

User-defined connections created manually

Manual Creation

Created by users in the workflow builder interface

• Drag-and-drop connections between nodes
• Explicit control flow definitions
• Custom data mapping configurations

Properties

• created_by: "user"
• derived_from_expression: false
• Stored in explicit_connections array
• Always visible in API responses

Derived Connections

Auto-generated connections from expressions

Automatic Detection

Generated automatically when nodes reference other nodes

• {{outputs.node_id.output}} expressions
• Dynamic connection discovery
• Real-time calculation on-demand

Properties

• created_by: "system"
• derived_from_expression: true
• Calculated via get_derived_connections()
• Controllable via include_derived parameter

Data Flow & Expressions

How data flows between nodes using expressions and connection detection

Expression Syntax

• {{outputs.node_id.output_name}} - Reference node output (creates derived connection)
• {{variables.var_name}} - Reference workflow variable
• {{inputs.input_name}} - Reference workflow input
• {{env.VAR_NAME}} - Reference environment variables
• Supports complex expressions and transformations

Connection Detection

• Expression Parsing - Scans node configs for references
• Dependency Mapping - Maps output references to connections
• Real-time Calculation - Derived connections calculated on-demand
• AI-Friendly API - Controllable visibility via parameters

Example: How Derived Connections Work

Node Configuration:

{
  "node_b": {
    "config": {
      "input_data": "{{outputs.node_a.result}}",
      "template": "Hello {{outputs.node_a.name}}!"
    }
  }
}

Auto-Generated Connections:

[
  {
    "source_node_id": "node_a",
    "target_node_id": "node_b", 
    "source_output": "result",
    "target_input": "input_data",
    "derived_from_expression": true,
    "created_by": "system"
  },
  {
    "source_node_id": "node_a",
    "target_node_id": "node_b",
    "source_output": "name", 
    "target_input": "template",
    "derived_from_expression": true,
    "created_by": "system"
  }
]

Connection Visibility & API Control

Control which connections are included in API responses for different use cases

include_derived Parameter

The include_derived query parameter controls whether derived connections are included in API responses.

• include_derived=true (default) - Include all connections
• include_derived=false - Only explicit connections
• Available on GET /workflows/{id} and GET /workflows/{id}/topology
• Optimizes performance for AI systems

Use Cases

• AI Integration - Get complete connection graph for analysis
• Performance - Skip expensive derived connection calculations
• Debugging - Focus on explicit user-defined connections
• Visualization - Control detail level in workflow diagrams

API Examples

Include All Connections (Default):

GET /api/v1/workflows/workflow_123
GET /api/v1/workflows/workflow_123?include_derived=true

Returns: explicit_connections + derived_connections

Explicit Connections Only:

GET /api/v1/workflows/workflow_123?include_derived=false

Returns: only explicit_connections (user-defined)

Workflow Variables

Workflow variables provide a way to store and share data across all nodes in a workflow. They can be used as inputs, outputs, or intermediate storage.

Variable Properties

Core properties of workflow variables

typestring

Variable type (string, number, boolean, object, array)

descriptionstring

Human-readable description of the variable

defaultany

Default value for the variable

requiredboolean

Whether the variable is required

is_inputboolean

Whether the variable can be used as workflow input

Variable Types

Supported variable types and their usage

Primitive Types

stringnumberboolean

Complex Types

objectarray

Usage Patterns

• Input variables - Set at workflow start
• Output variables - Set by nodes
• Intermediate variables - Shared between nodes

Variable Usage in Nodes

How variables are used within workflow nodes

Expression References

• {{variables.var_name}} - Reference variable value
• {{variables.user.email}} - Access object properties
• {{variables.items[0]}} - Access array elements
• Variables are resolved at runtime

Variable Scope

• Workflow-level - Available to all nodes
• Input - Set when workflow starts
• Output - Set by nodes during execution
• Persistent - Survive across executions

Example Variable Configuration

{
  "user_email": {
    "type": "string",
    "description": "Email address of the user",
    "default": "",
    "required": true,
    "is_input": true
  },
  "campaign_data": {
    "type": "object",
    "description": "Campaign configuration data",
    "default": {},
    "required": false,
    "is_input": false
  },
  "results": {
    "type": "array",
    "description": "Execution results from nodes",
    "default": [],
    "required": false,
    "is_input": false
  }
}

Workflow Lifecycle

Understanding how workflows progress through different states

Draft

Active

Paused

Archived

Workflows can be paused and resumed at any time, and archived workflows cannot be executed but can be restored.

Overview

Workflows are visual representations of business processes that can be executed to automate tasks. They consist of nodes (block instances) connected through data and control flow.

Workflow Components

• Nodes - Instances of blocks with specific configurations
• Connections - Data flow and control flow between nodes
• Variables - Shared data storage across the workflow
• Triggers - Entry points that initiate execution

Key Features

• Visual workflow builder with drag-and-drop
• Expression-based data flow between nodes
• Real-time execution monitoring and debugging
• Version control and validation
• Marketplace integration for blocks

Workflow Execution Flow

1. Trigger - Workflow starts from a trigger node (webhook, schedule, manual)

2. Node Execution - Nodes execute in order based on connections and dependencies

3. Data Flow - Data flows between nodes through expressions and connections

4. Variables - Shared variables allow data persistence across node executions

5. Completion - Workflow completes when all required nodes finish execution

Endpoints

GET/api/workflows

List Workflows

List workflows with pagination and filters

Query Parameters

workflow_status(string)Filter by workflow status

search(string)Search by name or description

tag(string)Filter by tag

include_system(boolean)Include system workflows (default: false)

page(number)Page number (starts at 1)

limit(number)Items per page (default 10)

Response

{
  "data": [
    {
      "id": "workflow_123456",
      "name": "Email Marketing Campaign",
      "description": "Send promotional emails to subscribers",
      "is_system": false,
      "status": "active",
      "tags": [
        "marketing",
        "email"
      ],
      "blocks_count": 3,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:22:00Z",
      "user_id": "user_123"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10
}

cURL Example

curl -X GET "https://api.blocktion.io/api/workflows" \
  -H "Authorization: Bearer <your_access_token>"

GET/api/workflows/{workflow_id}

Get Workflow

Get workflow by ID with optional derived connections

Query Parameters

include_derived(boolean)Include derived connections from expressions (default: true)

Response

{
  "data": {
    "id": "workflow_123456",
    "name": "Email Marketing Campaign",
    "description": "Send promotional emails to subscribers",
    "is_system": false,
    "status": "active",
    "tags": [
      "marketing",
      "email"
    ],
    "blocks_count": 3,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T14:22:00Z",
    "user_id": "user_123",
    "nodes": {
      "node_1": {
        "id": "node_1",
        "block_id": "webhook_trigger",
        "position_x": 100,
        "position_y": 100,
        "config": {},
        "is_trigger": true
      }
    },
    "connections": [
      {
        "id": "conn_1",
        "source_node_id": "node_1",
        "target_node_id": "node_2",
        "connection_type": "data",
        "source_output": "email_data",
        "target_input": "recipient_email",
        "is_required": true,
        "derived_from_expression": false,
        "created_by": "user"
      },
      {
        "id": "conn_2",
        "source_node_id": "node_1",
        "target_node_id": "node_3",
        "connection_type": "data",
        "source_output": "result",
        "target_input": "input_data",
        "is_required": true,
        "derived_from_expression": true,
        "created_by": "system"
      }
    ],
    "variables": {}
  }
}

cURL Example

curl -X GET "https://api.blocktion.io/api/workflows/{workflow_id}" \
  -H "Authorization: Bearer <your_access_token>"

POST/api/workflows

Create Workflow

Create a new workflow

Request Body

{
  "name": "string (required)",
  "description": "string (optional)",
  "tags": "string[] (optional)",
  "nodes": "object (optional)",
  "connections": "array (optional)"
}

Response

{
  "data": {
    "id": "workflow_123456",
    "name": "Email Marketing Campaign",
    "description": "Send promotional emails to subscribers",
    "is_system": false,
    "status": "draft",
    "tags": [
      "marketing"
    ],
    "blocks_count": 0,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "user_id": "user_123",
    "nodes": {},
    "connections": [],
    "variables": {}
  }
}

cURL Example

curl -X POST "https://api.blocktion.io/api/workflows" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
  "name": "string (required)",
  "description": "string (optional)",
  "tags": "string[] (optional)",
  "nodes": "object (optional)",
  "connections": "array (optional)"
}'

PUT/api/workflows/{workflow_id}

Update Workflow

Update an existing workflow

Request Body

{
  "name": "string (optional)",
  "description": "string (optional)",
  "status": "string (optional)",
  "tags": "string[] (optional)",
  "nodes": "object (optional)",
  "connections": "array (optional)",
  "variables": "object (optional)"
}

Response

{
  "data": {
    "id": "workflow_123456",
    "name": "Updated Workflow",
    "description": "Updated description"
  },
  "message": "Workflow updated successfully"
}

cURL Example

curl -X PUT "https://api.blocktion.io/api/workflows/{workflow_id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
  "name": "string (optional)",
  "description": "string (optional)",
  "status": "string (optional)",
  "tags": "string[] (optional)",
  "nodes": "object (optional)",
  "connections": "array (optional)",
  "variables": "object (optional)"
}'

DELETE/api/workflows/{workflow_id}

Delete Workflow

Delete a workflow

Response

{
  "data": {
    "success": true,
    "id": "workflow_123456"
  }
}

cURL Example

curl -X DELETE "https://api.blocktion.io/api/workflows/{workflow_id}" \
  -H "Authorization: Bearer <your_access_token>"

POST/api/workflows/{workflow_id}/execute

Execute Workflow

Execute a workflow with trigger-based initiation

Request Body

{
  "trigger_node_id": "string (optional)",
  "inputs": "object (optional)"
}

Response

{
  "data": {
    "session_id": "session_123456",
    "workflow_id": "workflow_123456",
    "status": "running",
    "message": "Workflow execution started successfully",
    "trigger_node_id": "node_1",
    "inputs": {}
  },
  "message": "Workflow execution started successfully"
}

cURL Example

curl -X POST "https://api.blocktion.io/api/workflows/{workflow_id}/execute" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
  "trigger_node_id": "string (optional)",
  "inputs": "object (optional)"
}'

POST/api/workflows/{workflow_id}/duplicate

Duplicate Workflow

Duplicate a workflow

Response

{
  "data": {
    "id": "workflow_789",
    "name": "Copy of Email Marketing Campaign"
  }
}

cURL Example

curl -X POST "https://api.blocktion.io/api/workflows/{workflow_id}/duplicate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>"

PUT/api/workflows/{workflow_id}/status

Update Workflow Status

Update a workflow's status

Request Body

{
  "workflow_status": "string (required)"
}

Response

{
  "data": {
    "id": "workflow_123456",
    "status": "active"
  }
}

cURL Example

curl -X PUT "https://api.blocktion.io/api/workflows/{workflow_id}/status" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
  "workflow_status": "string (required)"
}'

POST/api/workflows/{workflow_id}/validate

Validate Workflow

Validate workflow structure

Response

{
  "data": {
    "is_valid": true,
    "errors": [],
    "issues": []
  }
}

cURL Example

curl -X POST "https://api.blocktion.io/api/workflows/{workflow_id}/validate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>"

GET/api/workflows/{workflow_id}/topology

Get Workflow Topology

Get complete workflow topology for visualization with optional derived connections

Query Parameters

include_derived(boolean)Include derived connections from expressions (default: true)

Response

{
  "data": {
    "workflow_id": "workflow_123456",
    "workflow_name": "Email Marketing Campaign",
    "nodes": [
      {
        "id": "node_1",
        "block_id": "webhook_trigger",
        "position_x": 100,
        "position_y": 100,
        "is_trigger": true
      },
      {
        "id": "node_2",
        "block_id": "email_sender",
        "position_x": 300,
        "position_y": 100,
        "is_trigger": false
      }
    ],
    "connections": [
      {
        "id": "conn_1",
        "source_node_id": "node_1",
        "target_node_id": "node_2",
        "connection_type": "data",
        "source_output": "email_data",
        "target_input": "recipient_email",
        "is_required": true,
        "derived_from_expression": false,
        "created_by": "user"
      },
      {
        "id": "conn_2",
        "source_node_id": "node_1",
        "target_node_id": "node_2",
        "connection_type": "data",
        "source_output": "result",
        "target_input": "template_data",
        "is_required": true,
        "derived_from_expression": true,
        "created_by": "system"
      }
    ],
    "trigger_nodes": [
      "node_1"
    ],
    "metrics": {
      "total_nodes": 2,
      "total_connections": 2,
      "explicit_connections": 1,
      "derived_connections": 1
    },
    "execution_paths": [
      {
        "path": [
          "node_1",
          "node_2"
        ],
        "execution_order": 1
      }
    ]
  }
}

cURL Example

curl -X GET "https://api.blocktion.io/api/workflows/{workflow_id}/topology" \
  -H "Authorization: Bearer <your_access_token>"

POST/api/workflows/{workflow_id}/publish

Publish Workflow

Publish a workflow to the marketplace

Response

{
  "data": {
    "workflow_id": "workflow_123456",
    "status": "published"
  },
  "message": "Workflow published successfully"
}

cURL Example

curl -X POST "https://api.blocktion.io/api/workflows/{workflow_id}/publish" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>"

GET/api/workflows/{workflow_id}/blocks/{block_id}/available-inputs

Get Block Available Inputs

Get available inputs for a block in a workflow

Response

{
  "data": {
    "available_inputs": {
      "node_1": {
        "block_id": "node_1",
        "block_name": "Previous Block",
        "outputs": [
          "output"
        ]
      }
    },
    "variables": {
      "workflow_var": {
        "name": "workflow_var",
        "type": "string"
      }
    },
    "block_id": "node_2"
  }
}

cURL Example

curl -X GET "https://api.blocktion.io/api/workflows/{workflow_id}/blocks/{block_id}/available-inputs" \
  -H "Authorization: Bearer <your_access_token>"

AI-Friendly API Design

Optimizing workflow APIs for AI system integration and analysis

Connection Visibility Control

• Use include_derived=false for performance-critical operations
• Use include_derived=true for complete workflow analysis
• AI systems can choose appropriate detail level
• Reduces API response size when derived connections aren't needed
• Enables efficient workflow graph traversal

AI Integration Patterns

• Workflow Analysis - Get complete connection graph
• Performance Monitoring - Focus on explicit connections
• Debugging - Compare explicit vs derived connections
• Visualization - Control detail level in diagrams
• Automation - Build workflows programmatically

AI System Integration Example

For Workflow Analysis (AI needs complete picture):

GET /api/v1/workflows/workflow_123?include_derived=true
# Returns: explicit_connections + derived_connections
# AI can analyze complete data flow and dependencies

For Performance Monitoring (AI needs user intent):

GET /api/v1/workflows/workflow_123?include_derived=false
# Returns: only explicit_connections
# AI can focus on user-defined workflow structure

Best Practices

Guidelines for creating and managing workflows effectively

Workflow Design

• Keep workflows focused on a single purpose
• Use descriptive names and clear documentation
• Implement proper error handling and retry logic
• Test workflows thoroughly before deployment
• Version control your workflow definitions
• Use expressions for dynamic data flow
• Balance explicit and derived connections

Performance & Monitoring

• Monitor execution times and success rates
• Set appropriate timeouts for long-running workflows
• Use logging and debugging tools effectively
• Implement proper resource management
• Regular review and optimization of workflows
• Use include_derived=false for performance-critical APIs
• Monitor derived connection calculation overhead

Documentation

Workflows

What is a Workflow?

Key Features

Use Cases

Workflow Statuses

draft

active

paused

archived

Execution Statuses

pending

running

completed

failed

cancelled

Workflow Nodes

Node Structure

Node Types

Trigger Nodes

Processing Nodes

Integration Nodes

Node Configuration

Positioning

Configuration

Example Node Configuration

Node Connections

Connection Types

Data Connections

Control Flow

Both

Connection Properties

Explicit Connections

Manual Creation

Properties

Derived Connections

Automatic Detection

Properties

Data Flow & Expressions

Expression Syntax

Connection Detection

Example: How Derived Connections Work

Connection Visibility & API Control

include_derived Parameter

Use Cases

API Examples

Workflow Variables

Variable Properties

Variable Types

Primitive Types

Complex Types

Usage Patterns

Variable Usage in Nodes

Expression References

Variable Scope

Example Variable Configuration

Workflow Lifecycle

Overview

Workflow Components

Key Features

Workflow Execution Flow

Endpoints

List Workflows

Query Parameters

Response

cURL Example

Get Workflow

Query Parameters

Response

cURL Example

Create Workflow

Request Body

Response

cURL Example

Update Workflow

Request Body

Response

cURL Example

Delete Workflow

Response