# FlowDrop Orchestration Connector

Exposes FlowDrop workflows to external automation platforms (like Activepieces) via the [Orchestration](https://www.drupal.org/project/orchestration) module.

All PHP classes in this module are `@internal`. See the [BC Policy](../../docs/reference/api/bc-policy.md) for details.

## Overview

This module creates a bridge between FlowDrop's workflow system and external automation platforms. It introduces:

1. **Orchestration Invoke Trigger** - A new trigger type that fires when external platforms invoke a workflow
2. **Services Provider** - Exposes workflows as callable services via the Orchestration API
3. **Webhook Integration** - Notifies external platforms when workflows complete
4. **Poll Support** - Allows external platforms to poll for workflow results

## How It Works

### For Workflow Authors

1. Create a workflow in FlowDrop
2. Add an **Orchestration Trigger** node to start the workflow
3. Configure the trigger with:
   - Description (shown to external platform users)
   - Expected payload schema
   - Orchestrator settings (sync/async, retry policy, etc.)
4. The workflow is now available to external platforms

### For External Platforms

**Service Discovery:**
```
GET /orchestration/services
Authorization: Basic <credentials>
```

Returns list of available FlowDrop workflows with their configuration schemas.

**Execute Workflow:**
```
POST /orchestration/service/execute
Authorization: Basic <credentials>
Content-Type: application/json

{
  "id": "flowdrop::my_workflow__node_abc123",
  "config": {
    "payload": {
      "field1": "value1",
      "field2": "value2"
    }
  }
}
```

**Register Webhook:**
```
POST /orchestration/webhook/register
Authorization: Basic <credentials>
Content-Type: application/json

{
  "id": "flowdrop::my_workflow__node_abc123",
  "webHookUrl": "https://external-platform.com/webhook/callback"
}
```

**Poll for Results:**
```
POST /orchestration/poll
Authorization: Basic <credentials>
Content-Type: application/json

{
  "name": "flowdrop_pipelines",
  "timestamp": 1234567890
}
```

## Requirements

- Drupal 11.2+
- FlowDrop Workflow module
- FlowDrop Trigger module  
- FlowDrop Runtime module
- Orchestration module (drupal/orchestration)

## Installation

1. Enable the module:
   ```bash
   drush en flowdrop_orchestration_connector
   ```

2. Grant the "use orchestration" permission to appropriate roles

3. Create workflows with Orchestration Trigger nodes

## Trigger Configuration

When you add an Orchestration Trigger node to a workflow, a trigger configuration entity is created. You can configure:

- **Description**: Shown to external platform users
- **Payload Schema**: JSON Schema defining expected input structure
- **Required Fields**: Fields that external platforms must provide
- **Orchestrator Settings**: 
  - Type: synchronous_pipeline (default) or asynchronous
  - Pipeline mode: new, reuse, or singleton
  - Retry policy
  - Timeout

## Webhook Events

When registered, webhooks receive events for:

- `workflow.completed` - Workflow finished successfully
- `workflow.failed` - Workflow execution failed

Payload structure:
```json
{
  "event": "workflow.completed",
  "timestamp": 1234567890,
  "execution_id": "exec_abc123",
  "pipeline_id": "123",
  "workflow_id": "my_workflow",
  "trigger_config_id": "my_workflow__node_abc",
  "status": "completed",
  "output": { ... },
  "error": null,
  "execution_time": 1.234
}
```

## Poll Response

Poll requests return completed pipelines since the last poll:

```json
[
  {
    "timestamp": 1234567890,
    "data": {
      "pipeline_id": "123",
      "workflow_id": "my_workflow",
      "trigger_config_id": "my_workflow__node_abc",
      "status": "completed",
      "started": 1234567880,
      "completed": 1234567890,
      "input_data": { ... },
      "output_data": { ... },
      "error_message": null
    }
  }
]
```

## Architecture

```
External Platform (Activepieces, etc.)
        │
        ▼
┌───────────────────────────────────────┐
│     Orchestration Module API          │
│  /orchestration/service/execute       │
└───────────────────────────────────────┘
        │
        ▼
┌───────────────────────────────────────┐
│  flowdrop_orchestration_connector     │
│     ServicesProvider.execute()        │
└───────────────────────────────────────┘
        │
        ▼
┌───────────────────────────────────────┐
│     InvokeTriggerService.invoke()     │
│  - Loads trigger configuration        │
│  - Builds orchestration request       │
│  - Executes via orchestrator          │
└───────────────────────────────────────┘
        │
        ▼
┌───────────────────────────────────────┐
│     FlowDrop Pipeline/Job System      │
│  - Creates pipeline entity            │
│  - Generates jobs from workflow       │
│  - Executes nodes                     │
└───────────────────────────────────────┘
        │
        ▼
┌───────────────────────────────────────┐
│   PipelineEventSubscriber             │
│  - Listens for completion events      │
│  - Dispatches webhooks                │
└───────────────────────────────────────┘
        │
        ▼
External Platform Webhook Callback
```

## Troubleshooting

**Workflows not appearing in service list:**
- Ensure the workflow has an Orchestration Trigger node
- Check that the trigger is enabled (status = true)
- Verify the workflow is enabled

**Authentication failures:**
- Ensure basic_auth module is enabled
- User must have "use orchestration" permission
- Check credentials are correct

**Webhook not firing:**
- Verify webhook is registered via /orchestration/webhook/register
- Check that pipeline was triggered via orchestration (not manually)
- Review logs for dispatch errors

## License

GPL-2.0-or-later
