Orchestrator Plugin API¶
Stable API
Classes on this page are marked @api and are guaranteed backward compatible in the 1.x release line.
See the BC Policy 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 |
final class | Attribute for Orchestrator plugins. |
OrchestratorPluginInterface |
interface | Interface for Orchestrator plugins. |
OrchestratorPluginBase |
abstract class | Base class for Orchestrator plugins. |
OrchestratorInterface |
interface | Interface for workflow orchestrators. |
InterruptExceptionInterface |
interface | Interface for interrupt exceptions that pause workflow execution. |
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 — concepts and usage
- flowdrop_orchestration module — module overview
- BC Policy — backward compatibility guarantees
This page was auto-generated from source code PHPDoc annotations. Run php scripts/generate-api-docs.php to regenerate.