Agentic Flows Drupal Integration

Agentic Flows - Drupal Integration

Overview

Drupal (ECA, FlowDrop, orchestration) triggers platform flows by calling the workflow-engine API. One base URL: WORKFLOW_ENGINE_URL.

Environment

Variable	Example	Purpose
WORKFLOW_ENGINE_URL	https://workflow.bluefly.internal	Base URL for workflow-engine (no trailing slash)

Configure in Drupal via Fleet Extension settings (workflow_engine_url) or http_client_manager overrides. Recipe Onboarding Fleet Extension syncs workflow_engine_url to the workflow_engine client base_uri.

API Endpoints (stable)

Run by flow id
POST {WORKFLOW_ENGINE_URL}/api/v1/flows/{flowId}/execute
Body: { "inputs": { ... }, "tweaks?", "sessionId?", "metadata?" }
Response: FlowResponse (id, status, outputs, logs, metadata).
Run by flow name
POST {WORKFLOW_ENGINE_URL}/api/v1/flows/execute-by-name
Body: { "name": "my-flow", "inputs": { ... }, "tweaks?", "sessionId?", "metadata?" }
Response: FlowResponse or 404 if name not found.
Run by trigger (Drupal payload)
POST {WORKFLOW_ENGINE_URL}/api/v1/trigger
Body: DrupalTriggerPayload (see below).
Response: 200 FlowResponse (sync) or 202 TriggerAccepted (async; use jobId to poll). Add ?async=1 or header X-Trigger-Async: 1 for 202.

Drupal trigger payload

Matches agentic-flows src/triggers/drupal.ts and ECA-style events:

{
  "hook": "entity_insert",
  "entityType": "node",
  "bundle": "article",
  "entity": { "nid": "1", "title": "Example" },
  "context": { "uid": "1", "site": "default" }
}

All fields optional. workflow-engine resolves payload to a registered flow via TRIGGER_FLOW_MAP env (e.g. {"entity_insert:node:article":"flow-id"} or {"*":"default-flow-id"}).

Sequence (Drupal to platform)

Drupal: ECA event (e.g. entity insert) or FlowDrop node fires.
ECA action "Invoke platform flow" or http_client_manager: POST to {WORKFLOW_ENGINE_URL}/api/v1/trigger with Drupal payload (or POST to /api/v1/flows/execute-by-name with flow name and inputs).
workflow-engine: Resolves trigger (or name) to flowId, dispatches to Inngest for execution, returns FlowResponse or 202.
Drupal: Uses response (outputs, jobId) for logging, redirect, or next steps.

Drupal setup

Fleet Extension (recipe_onboarding_fleet_extension)

Set Workflow engine base URL at Configuration > Recipe Onboarding > Fleet Extension (e.g. https://workflow.bluefly.internal). This becomes the workflow_engine http_client base_uri.
HTTP client operations: RunByTrigger, ExecuteByName, ExecuteFlow, Approve. Use from PHP: $client->call('RunByTrigger', $payload) or $client->call('ExecuteByName', ['name' => 'x', 'inputs' => []]).

ECA action "Invoke platform flow"

Plugin ID: recipe_onboarding_fleet_extension_invoke_platform_flow.
Mode: Run by trigger (hook, entity type, bundle, entity JSON, context JSON) or Execute by flow name (flow name + inputs JSON).
Result token: name to store the workflow response (e.g. workflow_result); use [workflow_result:error] for errors.
Requires: recipe_onboarding_fleet_extension, eca, http_client_manager; workflow_engine_url set in Fleet Extension settings.

api_normalization (optional)

Import workflow-engine OpenAPI from api-schema-registry (or api.blueflyagents.com) to expose Tool plugins for "Execute flow", "Run by trigger"; ECA can call those tools.

OpenAPI

Spec: api-schema-registry openapi/workflow-engine/openapi.yaml. Aggregated at api.blueflyagents.com. Schemas: ExecuteFlowRequest, FlowResponse, ExecuteByNameRequest, DrupalTriggerPayload, TriggerAccepted.

workflow-engine implementation

POST /api/v1/flows/:flowId/execute, POST /api/v1/flows/execute-by-name, POST /api/v1/trigger implemented in workflow-engine (src/service.ts). Name resolution: listWorkflows().find(w => w.name === name). Trigger resolution: TRIGGER_FLOW_MAP env JSON.
Execution is durable via Inngest (workflow/execute event).