# FlowDrop Orchestration Connector

> Exposes FlowDrop workflows to external automation platforms via Drupal's Orchestration module, enabling bidirectional integration.

## Installation

`flowdrop_orchestration_connector` requires the **Drupal Orchestration** module as an additional dependency. This is a separate contrib module not bundled with FlowDrop.

```bash
# 1. Install the Orchestration module via Composer
composer require drupal/orchestration

# 2. Enable both modules
drush en orchestration flowdrop_orchestration_connector

# 3. Clear cache
drush cr
```

The `drupal/orchestration` package is available on [Drupal.org](https://www.drupal.org/project/orchestration). Verify it is compatible with your Drupal version before installing.

!!! warning
    Running `drush en flowdrop_orchestration_connector` without first installing `drupal/orchestration` via Composer will fail with a module-not-found error. Always run `composer require drupal/orchestration` first.

## Overview

The `flowdrop_orchestration_connector` module bridges FlowDrop with Drupal's Orchestration module, exposing workflows as callable services that external automation platforms can invoke. It creates an "Orchestration Invoke" trigger type that enables external systems to trigger FlowDrop workflows and receive results back.

The module also provides event subscribers that dispatch webhooks on pipeline completion and support polling for pipeline results, enabling asynchronous integration patterns.

## Dependencies

- [flowdrop_workflow](flowdrop_workflow.md) (workflow definitions)
- [flowdrop_trigger](flowdrop_trigger.md) (trigger system)
- [flowdrop_runtime](flowdrop_runtime.md) (workflow execution)
- `drupal:orchestration` (Drupal Orchestration module)

## Tips and Tricks

### Integration Pattern

The typical integration flow:

1. External platform discovers available FlowDrop workflows via the Orchestration services API
2. Platform invokes a workflow by creating an orchestration invoke trigger
3. FlowDrop executes the workflow via the configured orchestrator
4. Results are returned via webhook (push) or polling (pull)

### Webhook vs Polling

- **Webhook** (`PipelineEventSubscriber`) — Dispatches result to a callback URL when the pipeline completes. Best for platforms that support webhooks.
- **Polling** (`PollEventSubscriber`) — Allows the external platform to check pipeline status and retrieve results on demand. Best for simpler integrations.

## Developer API

### Services

| Service ID | Class | Description |
|-----------|-------|-------------|
| `flowdrop_orchestration_connector.services_provider` | `ServicesProvider` | Exposes FlowDrop workflows as callable orchestration services |
| `flowdrop_orchestration_connector.invoke_trigger_service` | `InvokeTriggerService` | Bridges Orchestration API calls to FlowDrop pipeline/job execution |
| `flowdrop_orchestration_connector.pipeline_event_subscriber` | `PipelineEventSubscriber` | Dispatches webhooks on pipeline completion |
| `flowdrop_orchestration_connector.poll_event_subscriber` | `PollEventSubscriber` | Enables polling for pipeline results |

### Events

The module subscribes to pipeline events from [flowdrop_runtime](flowdrop_runtime.md) and translates them into orchestration callbacks.

## References

- [flowdrop_trigger](flowdrop_trigger.md) — trigger system that this module extends
- [flowdrop_runtime](flowdrop_runtime.md) — executes the triggered workflows
- [flowdrop_orchestration](flowdrop_orchestration.md) — orchestrator plugin system
