# FlowDrop Workflow Executor

Enables executing FlowDrop workflows from within other workflows, with sync and async execution modes.

This module is now stable. Some internal classes are marked `@internal` and are not covered by backward compatibility promises. See the [BC Policy](../../docs/reference/api/bc-policy.md) for details.

## Service

### WorkflowExecutionServiceInterface

**Service ID:** `flowdrop_workflow_executor.service`

```php
use Drupal\flowdrop_workflow_executor\Service\WorkflowExecutionServiceInterface;
use Drupal\flowdrop_workflow_executor\Enum\WorkflowExecutionMode;

$service = \Drupal::service('flowdrop_workflow_executor.service');

// Synchronous - blocks until complete
$result = $service->execute($workflow, $inputData, WorkflowExecutionMode::Job);

// Async - returns immediately with session ID
$result = $service->execute($workflow, $inputData, WorkflowExecutionMode::JobAsync);

// Fire & forget - queued for cron processing
$result = $service->execute($workflow, $inputData, WorkflowExecutionMode::JobFireForget);

// Retrieve async results later
$result = $service->getResults($sessionId, $waitForCompletion, $timeout);
$service->isComplete($sessionId): bool;
$service->getStatus($sessionId): WorkflowExecutionStatus;
```

### Execution Modes

| Enum Case | Behavior |
|-----------|----------|
| `WorkflowExecutionMode::Job` | Blocks until workflow completes or times out |
| `WorkflowExecutionMode::JobAsync` | Returns session ID immediately for later retrieval |
| `WorkflowExecutionMode::JobFireForget` | Queues for cron processing, no result retrieval |

## DTO

### WorkflowExecutionResult

```php
$result->isSuccess(): bool;
$result->getStatus(): WorkflowExecutionStatus;
$result->getSessionId(): string;
$result->getOutputs(): array;
$result->getErrorMessage(): string;
$result->getExecutionTimeMs(): int;
$result->toArray(): array;
```

## Node Processors

### Workflow Executor (`workflow_executor`)

Executes a child workflow from within a parent workflow. Parameters: `workflow_id`, `input_data`, `execution_mode`, `timeout`.

### Workflow Results Retriever (`workflow_results_retriever`)

Retrieves results from an async workflow execution. Parameters: `session_id`, `wait_for_completion`, `timeout`.

## Safety Features

- Maximum recursion depth: 5 levels
- Circular reference detection
- Execution chain tracking via session metadata
