npm package: @onlineapps/conn-orch-orchestrator
Description: Workflow orchestration connector for OA Drive - handles message routing and workflow execution
Author: OA Drive Team
Latest version: 1.0.105

# @onlineapps/conn-orch-orchestrator

Workflow orchestration coordinator managing complete workflow execution for OA Drive microservices.

## Features

- 🎯 **Workflow coordination** - Complete workflow execution management
- 🔀 **Control flow handling** - If/else, switch, foreach, fork-join patterns
- 📊 **State management** - Workflow state tracking and persistence
- 🚦 **Step routing** - Intelligent routing to next services
- 📈 **Statistics tracking** - Workflow execution metrics
- ⚡ **Async processing** - Non-blocking workflow execution

## Installation

```bash
npm install @onlineapps/conn-orch-orchestrator
```

## Quick Start

```javascript
const { OrchestratorConnector } = require('@onlineapps/conn-orch-orchestrator');

const orchestrator = new OrchestratorConnector({
  amqpUrl: process.env.AMQP_URL,
  storageUrl: process.env.MINIO_URL
});

// Process workflow message
const result = await orchestrator.processWorkflowMessage({
  workflowId: 'wf-123',
  steps: [
    { service: 'validation', operation: 'validate' },
    { service: 'processing', operation: 'process' },
    { service: 'notification', operation: 'notify' }
  ],
  currentStep: 0,
  context: { /* workflow data */ }
});

// Get statistics
const stats = orchestrator.getStats();
console.log(`Processed: ${stats.processed}, Failed: ${stats.failed}`);
```

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `AMQP_URL` | RabbitMQ connection URL | required |
| `STORAGE_URL` | MinIO storage URL | required |
| `WORKFLOW_TIMEOUT` | Max workflow execution time (ms) | 300000 |
| `MAX_RETRIES` | Maximum retry attempts | 3 |

## Control Flow Patterns

### If/Else
```javascript
{
  type: 'if',
  condition: { field: 'status', operator: 'equals', value: 'active' },
  then: { service: 'activeHandler' },
  else: { service: 'inactiveHandler' }
}
```

### Switch/Case
```javascript
{
  type: 'switch',
  field: 'priority',
  cases: {
    'high': { service: 'urgentHandler' },
    'normal': { service: 'standardHandler' },
    'low': { service: 'batchHandler' }
  },
  default: { service: 'defaultHandler' }
}
```

### Foreach
```javascript
{
  type: 'foreach',
  items: 'context.items',
  step: { service: 'itemProcessor' }
}
```

### Fork-Join
```javascript
{
  type: 'fork-join',
  parallel: [
    { service: 'validator' },
    { service: 'enricher' },
    { service: 'scorer' }
  ],
  join: { service: 'aggregator' }
}
```

## API Reference

### OrchestratorConnector

Main orchestrator class for workflow execution.

#### Methods

- `processWorkflowMessage(message)` - Process a workflow message
- `processStep(message)` - Process a single workflow step
- `handleControlFlow(step, message)` - Handle control flow steps
- `routeToNextService(message, nextService, result, nextIndex)` - Route to next service
- `completeWorkflow(message, result)` - Complete workflow execution
- `handleWorkflowFailure(message, error)` - Handle workflow failures
- `getStats()` - Get execution statistics
- `resetStats()` - Reset statistics

## Testing

```bash
# Run all tests
npm test

# Run unit tests
npm run test:unit

# Run integration tests
npm run test:integration
```

## Error Classification

The WorkflowOrchestrator classifies errors before retry decisions using `error.type` and `error.statusCode`:

| Error Type | Retry? | Action |
|---|---|---|
| TRANSIENT (500, 502, 503) | Yes | Retry with exponential backoff |
| TIMEOUT (504, 408) | Yes | Retry with backoff |
| BUSINESS (404, 403, 409) | No | Straight to DLQ |
| VALIDATION (400, 422) | No | Straight to DLQ |

DLQ records include `error_type`, `error_code`, `status_code`, and `details[]` for monitoring. This works in tandem with the ApiMapper's error context preservation -- see [Error Handling Standard](/docs/standards/ERROR_HANDLING.md#error-classification-and-retry-behavior).

## Documentation

- [Connectors Architecture](/docs/architecture/connector.md)
- [Workflow Architecture](/docs/architecture/workflow.md)
- [Error Handling Standard](/docs/standards/ERROR_HANDLING.md)

## Version History
- 1.0.101: Error classification in catch block -- BUSINESS/VALIDATION skip retries
- 1.0.13: Added variable reference resolution in step inputs