activepieces

Activepieces enables users to define automation workflows declaratively through a visual flow builder UI that compiles to an intermediate representation executed by the flow execution engine. The system uses a directed acyclic graph (DAG) model where flows consist of triggers, actions, routers, and loops connected via data bindings. The frontend state management captures the flow structure and persists it to the backend database, while the engine deserializes and executes the flow step-by-step with full context propagation between steps.

Activepieces supports multiple trigger types (webhooks, polling, AI agent invocations, scheduled cron) that activate flows when external events occur. Triggers are implemented as pieces with special lifecycle hooks that register listeners or polling intervals. The system maintains trigger state (last poll time, webhook subscriptions) in the database and uses a queue-based worker architecture to dequeue trigger events and spawn flow executions. Webhook triggers expose unique URLs per flow instance, while polling triggers run on configurable intervals via the worker pool.

Activepieces supports loop steps that iterate over arrays and execute a set of steps for each array element. The loop step receives an array input (from previous step output or flow variable) and repeats the enclosed steps once per element. Each iteration has access to the current element via a loop variable and can access previous iteration results. Loops support break/continue semantics and can be nested to handle multi-dimensional arrays.

Activepieces implements the Model Context Protocol (MCP) specification, exposing workflows and pieces as tools that AI agents (Claude, GPT-4, etc.) can invoke. The MCP server exposes a standardized interface where each workflow or piece becomes a callable tool with input schemas and descriptions. AI agents can discover available tools, invoke them with parameters, and receive results in a structured format. The MCP server handles authentication, input validation, and error handling transparently.

Activepieces generates unique webhook URLs for each flow that accept HTTP POST requests and trigger flow executions. Webhooks validate incoming payloads against optional JSON schemas and transform payloads before passing them to the flow. The webhook system supports request authentication (API keys, OAuth tokens) and rate limiting to prevent abuse. Webhook payloads are stored in the execution history for debugging and replay purposes.

Activepieces provides a real-time debugging interface that displays step-by-step execution progress, input/output data for each step, and detailed error messages. The system captures logs at each step (piece execution, code execution, router decisions) and streams them to the frontend via WebSocket or polling. Users can inspect intermediate values, understand why a step failed, and replay executions with modified inputs for testing.

Activepieces implements configurable error handling and retry logic at the step level. Each step can be configured with retry policies (max attempts, backoff strategy) that automatically retry failed steps before propagating errors. The system supports exponential backoff with jitter to prevent thundering herd problems. Failed steps can be configured to trigger error handlers (alternative steps) or pause the flow for manual intervention.

Activepieces includes native pieces for Claude, OpenAI, Grok, and other LLM providers that enable workflows to invoke language models for text generation, summarization, and structured data extraction. The Claude piece specifically supports JSON schema-based extraction via the tool_use feature, allowing workflows to parse unstructured data into typed objects. LLM pieces handle authentication via API keys stored in the connection management system and support dynamic prompt templating using flow context variables.

Activepieces allows workflows to include custom JavaScript code steps that execute in an isolated sandbox environment (packages/engine/src/lib/core/code/code-sandbox.ts). The code executor receives the flow execution context (previous step outputs, trigger data, variables) as input and can return arbitrary JSON data to downstream steps. The sandbox uses Node.js VM module or similar isolation mechanism to prevent code from accessing the host filesystem or network directly, though it can invoke other pieces and make API calls through the flow context.

Activepieces provides a centralized connection management system (packages/engine/src/lib/services/connections.service.ts) that securely stores and retrieves authentication credentials for external services. Connections support multiple authentication methods: OAuth 2.0 flows with automatic token refresh, API key storage with encryption, basic auth, and custom authentication schemes. Each piece declares its required authentication type, and the flow execution engine injects the appropriate connection credentials when the piece executes. Credentials are encrypted at rest in the database and never exposed to the frontend.

Activepieces uses a queue-based architecture (packages/server/worker) where flow executions are enqueued as jobs and processed by a pool of worker processes. The system supports multiple queue backends (Redis, in-memory for development) and scales horizontally by adding more worker instances. Each worker dequeues flow execution jobs, loads the flow definition and trigger data, and executes the flow step-by-step using the flow execution engine. The queue system handles job retries, dead-letter queues for failed jobs, and priority-based job scheduling.

Activepieces provides a pieces framework (packages/pieces/community) where each integration (Discord, Google Drive, Slack, etc.) is a self-contained TypeScript package that exports actions, triggers, and authentication handlers. Pieces follow a standardized interface with input/output schema definitions, error handling, and connection management. The framework includes a piece loader that dynamically imports pieces at runtime and registers them with the flow execution engine. Community members can contribute new pieces via pull requests, and the framework validates piece structure and compatibility.

Activepieces maintains a complete version history of flow definitions in the database, allowing users to view, compare, and rollback to previous versions. Each flow execution is recorded with its input data, step-by-step outputs, and final result. The system supports branching flows (creating new versions from old ones) and comparing versions side-by-side. Execution history is queryable by date range, status, and trigger type, enabling debugging and auditing of past runs.

Activepieces supports pausing flows at specific steps and resuming them later with full state preservation. When a flow is paused, the execution context (all previous step outputs, trigger data, variables) is serialized and stored in the database. When resumed, the context is deserialized and execution continues from the next step. This enables workflows that wait for external approvals, manual interventions, or time-based delays without consuming worker resources.

Activepieces includes a router step type that enables conditional branching based on flow context variables. The router evaluates conditions (e.g., 'if step1.output > 100') and routes execution to different downstream steps based on the result. Conditions are defined using a simple expression language that supports comparisons, logical operators, and variable interpolation. Multiple conditions can be chained to create complex branching logic, and a default path handles cases where no conditions match.