Orchestration

I need to...	Guide	Summary
Understand what Orchestration does and when to use it	What Orchestration Is	Use Orchestration when external automation platforms (Activepieces, Zapier, n8n) need to invoke Drupal workflows, AI agents, or business logic via HTTP. JSON:API handles data CRUD; Orchestration handles behavior. ECA is the internal half; Orchestration is the external half.
Understand the internal architecture	Architecture	Orchestration has three layers: the Connect controller (REST endpoints), ServicesProviderManager (collects tagged providers), and the Webhooks service. Providers register as Symfony services tagged orchestration_services_provider — no plugin annotation system. Service UUID format is provider_id::service_id (double colon).
Install and enable the module	Installation and Setup	Require drupal/orchestration, enable basic_auth and orchestration core module, then enable only the submodules matching your use case. Create a dedicated service account user with the single use orchestration connect permission. Run drush cache-rebuild after enabling submodules.
Expose ECA models to external platforms	ECA Services Provider	Use orchestration_eca to make ECA models callable from external platforms. The model must subscribe to the eca_base.tool event and define an arguments YAML field — those become the service's callable parameters. Service UUID format is eca::{wildcard}.
Expose AI Agents or AI Function Call plugins	AI Agents and AI Function Providers	Use orchestration_ai_agents to invoke AI Agent config entities from external platforms (service UUID: ai_agent::{machine_name}). Use orchestration_ai_function only for custom ai.function_calls plugins not covered by other providers — it auto-deduplicates against eca, ai_agents, and tool providers.
Expose Tool API plugins	Tool API Provider	Use orchestration_tool to let external platforms call drupal/tool plugins directly. Service UUID is tool::{plugin_id}; entity-typed inputs expect the entity's numeric ID (resolved internally before execute()). The Tool API is explicitly marked early-stage — treat orchestration_tool as similarly unstable.
Register and manage webhooks	Webhooks and Outbound Events	Webhooks are stored in Drupal's KeyValue store (orchestration collection). Register via admin UI (remote: false) or via /orchestration/webhook/register API (remote: true). Dispatch using the orchestration_dispatch_webhook ECA action. Failed deliveries are silently discarded in 1.0.0 — monitor at the receiving platform.
Understand the REST endpoints and request/response shapes	Orchestration API Reference	Five REST endpoints, all requiring Basic Auth + use orchestration connect. Service UUIDs use double colon (provider::id). Unknown service IDs return HTTP 500, not 404. Sending both timestamp and id to the poll endpoint silently uses timestamp. Always send Content-Type: application/json.
Understand authentication and permissions	Authentication and Permissions	There is one permission: use orchestration connect. It gates all five API endpoints and the admin UI — no per-service granularity in 1.0.0. Use Basic Auth with a dedicated service account user. Always enforce HTTPS in production; Basic Auth credentials travel Base64-encoded in every request.
Connect Drupal to Activepieces	Connecting Activepieces	Activepieces is the only platform with a built Drupal connector (as of May 2026). It uses JSON:API for content CRUD and the Orchestration API for workflow/agent/tool invocation. Activepieces Cloud cannot reach a localhost Drupal site; use self-hosted Docker or ngrok for local development.
Write a custom services provider	Custom Services Provider	Implement ServicesProviderInterface and register the class as a Symfony service tagged orchestration_services_provider. No plugin annotation needed. Provider ID must not contain colons — the UUID is {provider_id}::{service_id}. execute() must return array\|string.
Understand security risks and mitigations	Security Considerations	Orchestration exposes an HTTP API that executes arbitrary Drupal logic. Enforce HTTPS (Basic Auth credentials are Base64 in every header), use a minimal-permission dedicated service account, enable only needed submodules, and never assign use orchestration connect to the authenticated role. Failed webhook deliveries are silently discarded in 1.0.0.