# Orchestrator Plugin API

!!! info "Stable API"
    Classes on this page are marked `@api` and are guaranteed backward compatible in the 1.x release line.
    See the [BC Policy](bc-policy.md) for details.

The Orchestrator plugin system controls how workflows are executed. Use these classes to create custom execution strategies (synchronous, asynchronous, stateful, etc.).

## Overview

| Class | Type | Description |
|-------|------|-------------|
| [`Orchestrator`](#orchestrator-attribute) | final class | Attribute for Orchestrator plugins. |
| [`OrchestratorPluginInterface`](#orchestratorplugininterface) | interface | Interface for Orchestrator plugins. |
| [`OrchestratorPluginBase`](#orchestratorpluginbase) | abstract class | Base class for Orchestrator plugins. |
| [`OrchestratorInterface`](#orchestratorinterface) | interface | Interface for workflow orchestrators. |
| [`InterruptExceptionInterface`](#interruptexceptioninterface) | interface | Interface for interrupt exceptions that pause workflow execution. |
| [`FlowDropInterruptException`](#flowdropinterruptexception) | abstract class | Base exception for workflow interrupt signals (control flow, not errors). |

## Orchestrator (Attribute)

**Namespace:** `Drupal\flowdrop_orchestration\Attribute`  
**Type:** final class  
**Extends:** `Plugin`  
**Source:** `modules/flowdrop_orchestration/src/Attribute/Orchestrator.php`  

Attribute for Orchestrator plugins.

This attribute provides plugin discovery metadata for FlowDrop orchestrators.
Orchestrators handle how workflows are executed (synchronously,
asynchronously, with state management, etc.).

Example usage:

### Constructor Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `$id` | `string` | — | The plugin ID (e.g., "synchronous", "asynchronous", "stategraph"). |
| `$label` | `TranslatableMarkup` | — | The human-readable label for the orchestrator. |
| `$description` | `string` | "" | A description of what this orchestrator does. |
| `$capabilities` | `array` | [] | List of capability names this orchestrator supports. Common capabilities: - synchronous_execution: Can execute in current request - async_execution: Can execute via background queue - parallel_execution: Can run multiple jobs simultaneously - pipeline_based: Uses pipeline entities for execution - job_tracking: Tracks individual job status - stateful: Maintains execution state with checkpointing - retry_support: Can retry failed operations - error_recovery: Can recover from errors gracefully - interrupt_support: Supports execution interruption - checkpointing: Creates state checkpoints during execution. |
| `$deriver` | `?string` | NULL | (optional) The deriver class for dynamic plugin definitions. |

---

## OrchestratorPluginInterface

**Namespace:** `Drupal\flowdrop_orchestration\Plugin\Orchestrator`  
**Type:** interface  
**Extends:** `OrchestratorInterface, PluginInspectionInterface`  
**Source:** `modules/flowdrop_orchestration/src/Plugin/Orchestrator/OrchestratorPluginInterface.php`  

Interface for Orchestrator plugins.

Orchestrators control how workflows are executed. Different orchestrators
provide different execution strategies:
- Synchronous: Direct execution in the current request
- Asynchronous: Queue-based execution
- StateGraph: Stateful execution with checkpointing.

Each orchestrator can provide its own configuration form elements by
implementing the buildConfigurationForm(), validateConfigurationForm(),
and submitConfigurationForm() methods.

This interface extends the base OrchestratorInterface for backward
compatibility with code that expects the service-based interface.

### Methods

#### `buildConfigurationForm(array $form, FormStateInterface $form_state, array $settings): array`

Builds the orchestrator-specific configuration form elements.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$form` | `array` | The form array to add elements to. |
| `$form_state` | `FormStateInterface` | The current form state. |
| `$settings` | `array` | Current orchestrator settings from the trigger configuration. |

#### `validateConfigurationForm(array $form, FormStateInterface $form_state): void`

Validates the orchestrator-specific configuration form.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$form` | `array` | The form array. |
| `$form_state` | `FormStateInterface` | The current form state. |

#### `submitConfigurationForm(array $form, FormStateInterface $form_state): array`

Processes the orchestrator-specific configuration form submission.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$form` | `array` | The form array. |
| `$form_state` | `FormStateInterface` | The current form state. |

#### `getDefaultConfiguration(): array`

Gets the default configuration for this orchestrator.

---

## OrchestratorPluginBase

**Namespace:** `Drupal\flowdrop_orchestration\Plugin\Orchestrator`  
**Type:** abstract class  
**Extends:** `PluginBase`  
**Implements:** `OrchestratorPluginInterface`  
**Source:** `modules/flowdrop_orchestration/src/Plugin/Orchestrator/OrchestratorPluginBase.php`  

Base class for Orchestrator plugins.

Provides common functionality for orchestrator implementations.
Extend this class to create custom orchestrators.

This base class provides default implementations for the configuration
form methods with common fields (priority, timeout). Subclasses can
override these methods to add orchestrator-specific configuration.

### Methods

#### `getType(): string`

#### `orchestrate(OrchestrationRequest $request): OrchestrationResponse`

#### `supportsWorkflow(array $workflow): bool`

#### `getCapabilities(): array`

#### `buildConfigurationForm(array $form, FormStateInterface $form_state, array $settings): array`

#### `validateConfigurationForm(array $form, FormStateInterface $form_state): void`

#### `submitConfigurationForm(array $form, FormStateInterface $form_state): array`

#### `getDefaultConfiguration(): array`

#### `protected generateExecutionId(): string`

Generates a unique execution ID.

---

## OrchestratorInterface

**Namespace:** `Drupal\flowdrop_orchestration\Service\Orchestrator`  
**Type:** interface  
**Source:** `modules/flowdrop_orchestration/src/Service/Orchestrator/OrchestratorInterface.php`  

Interface for workflow orchestrators.

### Methods

#### `getType(): string`

Get the orchestrator type.

#### `orchestrate(OrchestrationRequest $request): OrchestrationResponse`

Execute a workflow using this orchestrator.

#### `supportsWorkflow(array $workflow): bool`

Check if this orchestrator supports the given workflow.

#### `getCapabilities(): array`

Get orchestrator capabilities.

---

## InterruptExceptionInterface

**Namespace:** `Drupal\flowdrop_orchestration\Exception`  
**Type:** interface  
**Extends:** `Throwable`  
**Source:** `modules/flowdrop_orchestration/src/Exception/InterruptExceptionInterface.php`  

Interface for interrupt exceptions that pause workflow execution.

Interrupt exceptions are special exceptions that indicate a workflow node
needs to pause execution and wait for external input (typically user input
in a human-in-loop scenario).

Unlike regular exceptions, interrupt exceptions should NOT be treated as
failures. Instead, they signal that:
- The workflow should be paused (not failed).
- The interrupt details should be returned to the caller.
- The workflow can be resumed once the interrupt is resolved.

### Methods

#### `getInterruptId(): string`

Gets the unique identifier of the interrupt.

#### `getInterruptType(): string`

Gets the type of interrupt.

#### `getExecutionContext(): array`

Gets the execution context for resuming the workflow.

#### `toArray(): array`

Converts the exception to an array for API responses.

---

## FlowDropInterruptException

**Namespace:** `Drupal\flowdrop_orchestration\Exception`  
**Type:** abstract class  
**Extends:** `Exception`  
**Implements:** `InterruptExceptionInterface`  
**Source:** `modules/flowdrop_orchestration/src/Exception/FlowDropInterruptException.php`  

Base exception for workflow interrupt signals (control flow, not errors).

Extends \Exception (not FlowDropException/\RuntimeException) so that
catch (\RuntimeException) blocks don't accidentally swallow interrupt
signals. Interrupts pause execution for external input; they are not
failures.

All concrete interrupt exceptions should extend this class and
implement InterruptExceptionInterface.

---

## See Also

- [Workflow Snapshots & Orchestrators](../../development/workflow-snapshots-and-orchestrators.md) — concepts and usage
- [flowdrop_orchestration module](../../modules/flowdrop_orchestration.md) — module overview
- [BC Policy](bc-policy.md) — backward compatibility guarantees

---

*This page was auto-generated from source code PHPDoc annotations. Run `php scripts/generate-api-docs.php` to regenerate.*
