Parameters & Configuration

Understanding how parameters flow through handlers, blocks, and nodes.

What are Parameters?

Parameters are configurable values that control how blocks and handlers behave.

Parameters are the configurable inputs that make blocks and handlers flexible and reusable. They flow through the system from handler schemas to block definitions to node configurations, allowing you to customize behavior without changing code.

Overview

Parameters flow through the system from handler schemas to node configurations, enabling flexible and reusable automation.

Parameter Types

• Schema defaults: Defined in handler actions
• Block parameters: Stored in block definitions
• Node config: Static values from locked parameters
• Node inputs: Dynamic values from unlocked parameters

Key Benefits

• Reusability: Same block, different configurations
• Flexibility: Easy conversion between static and dynamic
• Type safety: Validation and conversion
• Expression support: Dynamic value computation

Handler Parameter Schema

JSON Schema definitions that define the structure and validation rules for handler actions.

Example: Email Handler Action Schema

{
  "action_name": "send_email",
  "parameter_schema": {
    "type": "object",
    "properties": {
      "to": {
        "type": "string",
        "description": "Recipient email address",
        "format": "email"
      },
      "subject": {
        "type": "string", 
        "description": "Email subject line"
      },
      "body": {
        "type": "string",
        "description": "Email body content"
      },
      "priority": {
        "type": "string",
        "enum": ["low", "normal", "high"],
        "default": "normal"
      }
    },
    "required": ["to", "subject", "body"]
  }
}

• Defines structure: Parameter names, types, descriptions, and validation rules
• Sets defaults: Default values for optional parameters
• Enforces validation: Required fields, format validation, enum constraints
• Action-specific: Each handler action has its own parameter schema

Block Parameters

Parameter instances with values, locked/unlocked states, and type conversion.

Example: Block Parameter Configuration

{
  "parameters": {
    "to": {
      "title": "Recipient",
      "type": "string",
      "description": "Recipient email address",
      "required": true,
      "locked": false,
      "value": null,
      "is_expression": false
    },
    "subject": {
      "title": "Subject",
      "type": "string", 
      "description": "Email subject line",
      "required": true,
      "locked": false,
      "value": "Welcome!",
      "is_expression": false
    },
    "priority": {
      "title": "Priority",
      "type": "string",
      "description": "Email priority level",
      "required": false,
      "locked": true,
      "value": "normal",
      "is_expression": false,
      "options": [
        {"value": "low", "label": "Low"},
        {"value": "normal", "label": "Normal"},
        {"value": "high", "label": "High"}
      ]
    }
  }
}

• Parameter instances: Concrete values derived from handler schema
• Locked parameters: Become node config (static, pre-configured values)
• Unlocked parameters: Become node inputs (user-configurable, dynamic values)
• Easy conversion: Toggle locked/unlocked to move between config and inputs
• Type conversion: Values are converted to match schema types during resolution
• Expression support: Parameters can contain expressions for dynamic values

Node Configuration

Static configuration (from locked parameters) and dynamic inputs (from unlocked parameters) that override block parameters at runtime.

Node Config (Static)

{
  "config": {
    "to": "user@example.com",
    "subject": "{{workflow.name}} - Notification",
    "priority": "high"
  }
}

Static values from locked block parameters

Node Inputs (Dynamic)

{
  "inputs": {
    "to": "{{previous_node.outputs.email}}",
    "subject": "{{previous_node.outputs.title}}",
    "body": "{{previous_node.outputs.message}}"
  }
}

Dynamic values from unlocked block parameters

• Config overrides: Locked parameters become static node config
• Inputs override: Unlocked parameters become dynamic node inputs
• Easy conversion: Toggle parameter lock state to switch between config and inputs
• Expression resolution: All values are processed through the expression engine
• Type safety: Final values are validated against the original schema

Parameter Resolution Process

The step-by-step process of resolving parameters from schema to execution.

1. Schema Defaults

Start with default values from the handler's parameter schema. These provide the baseline configuration.

2. Block Configuration

Apply static values from the block's parameter definitions. Type conversion happens here to ensure compatibility.

3. Node Inputs

Apply dynamic inputs from the node configuration. These override both schema defaults and block config.

4. Expression Resolution

Process all expressions using the execution context (workflow variables, previous node outputs, etc.).

Best Practices

Guidelines for effective parameter management and configuration.

Use descriptive parameter names: Make parameter purposes clear in both schema and UI
Provide meaningful defaults: Set sensible defaults for optional parameters to improve UX
Lock critical parameters: Use locked parameters for values that shouldn't be changed by users
Validate early: Leverage schema validation to catch errors before execution
Use expressions wisely: Balance dynamic behavior with readability and maintainability
Document parameter purposes: Include clear descriptions in schemas for better developer experience

Documentation