> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Event-Based Workflow Triggers - Integration

> Feature ID: FW-16 Status: ✅ Complete (All Phases) Spec Reference: FW-16-event-based-workflow-triggers.md Last Updated: 2026-03-17

**Feature ID:** FW-16\
**Status:** ✅ Complete (All Phases)\
**Spec Reference:** [FW-16-event-based-workflow-triggers.md](../../../specs/fw/archive/FW-16-event-based-workflow-triggers.md)\
**Last Updated:** 2026-03-17

***

## Overview

FW-16 provides a domain event system for workflow triggers: an event registry (`fw_workflow_events`), an organization-scoped event log (`fw_domain_events`), and platform-layer event publication (`publishEvent()`). Cores publish events via the Platform Integration Layer; the FW automation engine consumes events and starts workflows. Date-relative triggers and event filtering are supported.

***

## Integration Points (from Spec)

| Consumer / Producer               | Type                 | Purpose                                                                                             |
| --------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------- |
| **Producers (publish to FW-16)**  | Event                | HR, RH, FA, FW, and other cores publish domain events via `publishEvent()` from `@/platform/events` |
| FW-03 (Automation Engine)         | Intra-core / Runtime | Matches event to automation rules and starts workflow executions                                    |
| FW-06 (Advanced Workflow Builder) | Intra-core / UI      | Event and date-relative trigger configuration in workflow start node                                |
| PF-83 (SLA Management)            | Platform / Consumer  | Consumes domain events for SLA instance creation and deadline tracking                              |
| FW-46 (Durable Execution Worker)  | Intra-core / Future  | Extends `fw_process_domain_event()` to enqueue worker messages                                      |
| PF-84 (Business Calendar)         | Platform / Optional  | Date-relative triggers may use business calendar for “business days” (when implemented)             |

***

## Platform Layer Contract

* **Event publication:** `publishEvent({ event_name, payload, organization_id, site_id? })` in `src/platform/events/publishEvent.ts`
* **Event types:** `src/platform/events/types.ts`; event names aligned with `fw_workflow_events.event_name`
* **Documentation:** `src/platform/events/README.md` for cores integrating with FW-16

***

## Event Contracts

* Event payloads must conform to the JSON Schema in `fw_workflow_events.payload_schema` for the given `event_name`.
* New events are registered via seed migrations (insert into `fw_workflow_events`). See [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md) for planned and existing event names.
* Idempotency and retry semantics are documented in EVENT\_CONTRACTS.md; FW-16 logs events in `fw_domain_events` and marks them processed via `fw_process_domain_event()`.

***

## Security and Tenant Isolation

* Event registry (`fw_workflow_events`) is global and read-only for authenticated users.
* Event log (`fw_domain_events`) is scoped by `organization_id`; RLS uses `has_org_access(auth.uid(), organization_id)` (or platform equivalent). Insert allowed for authenticated users in org.
* Event publication requires organization context; payloads must not contain PHI beyond what is necessary for workflow context.

***

## Phase 2: Event Schema Registry Expansion

**Spec:** [FW-16-PHASE-2-EVENT-SCHEMA-EXPANSION.md](../../../specs/fw/archive/FW-16-PHASE-2-EVENT-SCHEMA-EXPANSION.md)\
**Status:** 📋 Specification (Not Started)

Phase 2 adds event governance on top of the FW-16 event system without redefining durable execution (FW-46) or changing the core publish/trigger flow.

### Phase 2 Integration Additions

| Feature               | Integration Impact                                                                                                                                                                                                                                                    | Consuming Components                                                           |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| **Schema Validation** | `publishEvent()` validates payload against `fw_workflow_events.payload_schema` (JSON Schema draft 2020-12) before insert. Mode controlled by `fw_event_schema_validation_mode` setting.                                                                               | All cores calling `publishEvent()`                                             |
| **Correlation ID**    | `correlation_id UUID` added to `fw_domain_events`. Propagated from event → execution (FW-46) → sub-workflow (FW-41) → follow-on events.                                                                                                                               | FW-46 (execution), FW-41 (sub-workflows), FW-22 (monitoring UI)                |
| **Event Deprecation** | `deprecated_at`, `replacement_event` on `fw_workflow_events`. Grace period enforcement in `publishEvent()`. Consumer notification in FW-03 automation rule list.                                                                                                      | FW-03 (warning badges, migration helper)                                       |
| **Event Registry UI** | New page at `/settings/automation/events` with schema rendering, consumer list, and diff view.                                                                                                                                                                        | FW-22 (correlation filter link)                                                |
| **CI Script**         | `scripts/check-event-schemas.ts` detects breaking schema changes and enforces version bumps.                                                                                                                                                                          | CI pipeline (`build.yml`)                                                      |
| **Permissions**       | `fw.events.view` (staff + org\_admin), `fw.events.deprecate` / `fw.events.migrate` / `fw.settings.manage` (org\_admin). Constants: `FW_PERMISSIONS` in `src/platform/permissions/constants.ts`; seeds: migration `20260319180001_f8e4d2c0b1a3498780fefw16p2perm.sql`. | Event Registry UI, deprecate/migrate dialogs, Event Schema Governance settings |

### Updated Platform Layer Contract

```typescript theme={null}
publishEvent({
  event_name: string;
  payload: Record<string, unknown>;
  organization_id: string;
  site_id?: string;
  correlation_id?: string; // Phase 2: optional; generated if not provided
}): Promise<{ event_id: string; correlation_id: string }>
```

***

## Related Docs

* [FW-16 Spec](../../../specs/fw/archive/FW-16-event-based-workflow-triggers.md)
* [FW-16 Phase 2 Spec](../../../specs/fw/archive/FW-16-PHASE-2-EVENT-SCHEMA-EXPANSION.md)
* [PLATFORM\_INTEGRATION\_LAYERS.md](./PLATFORM_INTEGRATION_LAYERS.md) — FW-16 Event Publishing Integration Layer
* [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md)
* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)