Skip to main content

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.

Feature ID: FW-16
Status: ✅ Complete (All Phases)
Spec Reference: 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 / ProducerTypePurpose
Producers (publish to FW-16)EventHR, RH, FA, FW, and other cores publish domain events via publishEvent() from @/platform/events
FW-03 (Automation Engine)Intra-core / RuntimeMatches event to automation rules and starts workflow executions
FW-06 (Advanced Workflow Builder)Intra-core / UIEvent and date-relative trigger configuration in workflow start node
PF-83 (SLA Management)Platform / ConsumerConsumes domain events for SLA instance creation and deadline tracking
FW-46 (Durable Execution Worker)Intra-core / FutureExtends fw_process_domain_event() to enqueue worker messages
PF-84 (Business Calendar)Platform / OptionalDate-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 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
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

FeatureIntegration ImpactConsuming Components
Schema ValidationpublishEvent() 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 IDcorrelation_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 Deprecationdeprecated_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 UINew page at /settings/automation/events with schema rendering, consumer list, and diff view.FW-22 (correlation filter link)
CI Scriptscripts/check-event-schemas.ts detects breaking schema changes and enforces version bumps.CI pipeline (build.yml)
Permissionsfw.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

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 }>