Skip to main content

Workflow Structure

A workflow configuration consists of three main sections:

Table of Contents​

1. Addons Configuration​

Addons are plugins that extend the workflow engine with additional actions:

{
  "addons": [
    {
      "id": "my-addon-instance",
      "type": "addon-name",
      "name": "My Example Addon",
      "enabled": true,
      "config": {
        "api_url": "https://api.example.com",
      },
      "secrets": {
        "api_key": "MY_API_KEY",
        "another_secret": "ANOTHER_SECRET"
      }
    }
  ]
}

Addon Properties:

  • id: Unique identifier for the addon
  • type: Addon type (determines which package to load)
  • name: Human-readable name
  • enabled: Whether the addon is active (used for debugging)
  • config: Static across steps configuration values
  • secrets: References to secret values (resolved at runtime)

2. Entrypoints​

Entrypoints define how workflows can be triggered, the "default" entrypoint is the one that always will be used if you did not send any specific as parameters when running the nexroo run command

{
  "entrypoints": [
    {
      "id": "default",
      "name": "Default Entry Point",
      "startAt": "first-step"
    },
    {
      "id": "user-message",
      "name": "User Message Handler",
      "startAt": "validate-step",
      "guards": [
        {
          "condition": "{{payload.text}} != ''",
          "error": "Empty messages are not allowed"
        }
      ]
    }
  ]
}

Entrypoint Properties:

  • id: Unique identifier
  • name: Descriptive name
  • startAt: First step to execute
  • guards: Optional conditions that must pass before workflow starts

3. Workflow Definition​

The workflow contains the step definitions and execution logic:

{
  "workflow": {
    "id": "my-workflow",
    "name": "My Workflow",
    "version": "1.0.0",
    "description": "Description of what this workflow does",
    "steps": [
      {
        "id": "step-1",
        "name": "First Step",
        "action": "builtin::log",
        "runLimit": 1,
        "parameters": {
          "message": "Hello {{user.name}}",
          "level": "info"
        },
        "condition": {
          "if": "{{step-1.output.success}} == true",
          "then": "step-2",
          "else": "error-step"
        },
        "onError": {
          "action": "retry-step",
          "maxRetries": 3,
          "retryDelay": 5
        },
        "next": ["step-2", "step-3"]
      }
    ]
  }
}

Workflow Properties:

  • id: Unique identifier for the workflow (required)
  • name: Human-readable name for the workflow (required)
  • version: Optional version string for the workflow (e.g., "1.0.0", "v2.1")
  • description: Optional description of what the workflow does
  • breakpoint: Optional breakpoint config for debug, refer to Breakpoint Debugging
  • steps: Array of step definitions (required)

Step Properties:

  • id: Unique identifier within the workflow (required)
  • name: Descriptive name for logging and debugging (required)
  • action: Action to execute in format addon-id::method or builtin::method (required)
  • runLimit: Maximum times this step can execute (default: 1, use -1 for infinite)
  • timeout: Maximum execution time in seconds before step times out (optional)
  • parameters: Input parameters object (supports template variables)
  • condition: Conditional logic for flow control with if, then, else
  • onError: Error handling strategy with action and retry configuration
  • next: Array of next step IDs to execute
  • mockOutput: Step-level mock override for testing scenarios
  • breakpoint: Boolean flag to enable breakpoint, refer to Breakpoint Debugging

Workflow Versioning​

The optional version field in the workflow definition allows you to track different versions of your workflows. When specified, the version is displayed during workflow initialization for better tracking and debugging.

It use semantic versioning (e.g., "1.0.0", "2.1.3")

Example with Version:

{
  "workflow": {
    "id": "my-workflow",
    "name": "My Workflow",
    "version": "2.1.0",
    "description": "Workflow description",
    "steps": [...]
  }
}

The version field is purely informational and does not affect workflow execution. It serves as a helpful identifier for workflow management and tracking purposes.

Breakpoint Debugging​

The breakpoint system allows you to pause workflow execution at specific steps for debugging purposes. When a breakpoint is triggered, you will be prompted with the selected method (Web interface, API, terminal,...)

Workflow-Level Configuration​

Configure breakpoints at the workflow level, then you will be able to activate it on specific steps:

{
  "workflow": {
    "id": "debug-workflow",
    "name": "Debug Workflow",
    "version": "1.0.0",
    "breakpoint": {
      "enabled": true,
      "mode": "terminal",
      "timeout": 300 // api mode only, not for terminal
    },
    "steps": [...]
  }
}

Breakpoint Configuration:

  • enabled: Enable/disable breakpoint system (default: false)
  • mode: "terminal" for interactive CLI or "api" for external control
  • timeout: Timeout in seconds for API mode (default: 300)

Step-Level Breakpoints​

Once breakpoint is configured at workflow level, enable breakpoints on individual steps:

{
  "id": "debug-step",
  "name": "Step to Debug",
  "action": "builtin::log",
  "breakpoint": true,
  "parameters": {
    "message": "Debug this step"
  }
}

Terminal Mode​

In terminal mode, when a breakpoint is hit:

============================================================
🔴 BREAKPOINT - Step to Debug
============================================================
ID: debug-step_1234567890
Step: debug-step
Action: builtin::log
Parameters: {"message": "Debug this step"}

Context: Queue=3, Completed=2, Available=1
Step States: {"step1": "success", "step2": "success"}
Commands: [c]ontinue, [s]kip, [x]abort
>

Commands:

  • c or continue: Resume execution
  • s or skip: Skip current step
  • x or abort: Abort workflow

API Mode​

For cloud/programmatic usage, configure API mode and provide external callback for breakpoint handling.