MES Integration Layer — Overview & module guide

Features (Phase 1–5)

• MES Endpoints — REST, MQTT, OPC-UA, SOAP, Webhook, SFTP, Local
• Event Dispatcher — Outbound via REST, Webhook, MQTT, SFTP, Local folder
• Inbound Webhook — Receive shop-floor events from external MES
• REST API — Read endpoints/events, submit events, APS schedule sync
• Outbound Webhooks — event.queued, event.processed, event.failed
• Field Mapping — Transform payload fields per endpoint/event type
• Multi-Plant Routing — Route by plant_id when Multi-Plant module active
• Integration Reports — Endpoint SLA, error rates, archive stats
• SFTP / Local Transport — File-based inbound/outbound with cron polling
• Retry Queue — Exponential backoff for failed outbound events
• Credential Encryption — Secure storage of endpoint secrets
• Event Archive — Archive processed events before retention purge
• Dashboard — Integration stats, status chart, recent events
• Permissions — Role-based access for all MES features

Requirements

• BIXCRM 2.3+ (tested on 3.4.1)
• PHP 8.1+
• Optional: Manufacturing module for shop-floor event capture

Usage

Configure an MES Endpoint

1. Go to MES Integration Layer → MES Endpoints
2. Click New MES Endpoint
3. Enter endpoint code, name, vendor, and protocol
4. Fill protocol-specific configuration
5. Save

Enable Manufacturing Sync

1. Ensure Manufacturing module is active
2. Go to Settings
3. Enable Manufacturing Sync
4. Shop-floor events (work orders, QC, downtime, IoT) will be queued automatically

View Integration Events

Go to MES Integration Layer → Integration Events to view, create manual test events, or reprocess failed events.

Architecture

Manufacturing Module          MES Integration Layer          External MES
     (hooks)          →       (event queue)          →      (Phase 2+)
  work_order_*                  mes_events                    REST/MQTT/etc.
  qc_failed                     mes_endpoints
  downtime_*                    mes_event_types
  iot_reading

No core BIXCRM or Manufacturing files are modified. Integration uses existing do_action hooks from the Manufacturing module.

Inbound Webhook Example

curl -X POST "https://your-crm.com/mes/mes_webhook/receive" \
  -H "Content-Type: application/json" \
  -H "X-MES-Token: YOUR_WEBHOOK_SECRET" \
  -d '{
    "event_ref": "MES-EXT-1001",
    "event_code": "operation_scan",
    "payload": {
      "scan_code": "OP:123",
      "action": "start",
      "work_order_id": 10,
      "operation_id": 123
    }
  }'

Supported inbound events: operation_scan, iot_reading_ingested, downtime_started, downtime_ended, qc_result, qc_failed.

Roadmap

See [docs/ROADMAP.md](docs/ROADMAP.md) for the full phase plan.