Skip to main content

Events

Event-driven communication is mandatory: solutions observe the platform event bus and emit their own lifecycle events onto it. There is no out-of-band signaling between a solution and the host.

Tool vs Event vs Flow vs Automation​

Keep these four names distinct. They are not interchangeable.

ConceptWhat it isWho runs itExample
ToolA capability invoked as a flow stepQefro Runtime (entity.reservation.create) or an external SDK toolCreate the reservation document
EventA fact on the bus (<domain>.<past-tense>)Runtime (or SDK ctx.emit for external systems)reservation.created
FlowMetadata workflow compiled to BusinessFlow / FlowRunnerQefro FlowRunnercreate-reservation (ask → tool → complete)
AutomationCRM Automation reacting to a business eventPlatform Automations host (host: automations)reservation.created → Send WhatsApp
Chat / form
  → Flow (create-reservation)
      → Tool (entity.reservation.create)
          → Event (reservation.created)
              → Automation (CRM: Send WhatsApp)

Marketplace Apps declare events on the manifest (events:). There is no events/ package directory. Automations are not YAML in the app; they are configured on the portal Automations host after install.

SDK-hosted apps may also advertise events on capabilities.list — that is the external integration path.

The ui.* lifecycle events​

Solution UIs emit five lifecycle events; they ride the existing bus as ordinary event_type values — the event model is unchanged:

EventEmitted when
ui.loadedThe solution UI bundle finished loading for a user
ui.closedThe user left / closed the solution UI
ui.actionA user performed a declared action (e.g. form submit)
ui.errorA scoped render or data error surfaced to the user
ui.navigateThe user navigated between declared pages

Bus semantics for UI events​

  • Appended and acked. The runtime dispatcher appends ui.* events to the ui_events table and acks.
  • Never dead-lettered. UI events cannot fail a pipeline; they are observational.
  • Never trigger workflows. ui.* events do not match workflow triggers. Business automation must start from business events or direct workflow triggers — see below.

Reading events back​

Tenants read their own UI events through a tenant-scoped endpoint:

GET /v1/ui/events?limit=50

The portal's Developer mode shows them in a Solution UI events panel, which is the fastest way to debug "did the UI actually emit that?".

Business events vs UI events​

ConcernUI events (ui.*)Business events
PurposeObservation, audit, UX signalsState changes, automation
Triggers workflowsNeverYes — via workflow trigger: definitions
EmissionPortal on behalf of the UIRuntime, connectors, API
Exampleui.action reservation form submittedreservation.confirmed

restaurant-pro-runtime emits ui.action for audit when a form submits, while automation starts from the business event reservation.created (CRM Automation → Send WhatsApp). The booking itself is the flow create-reservation, not the UI event. See Workflows.

Emitting events declaratively​

Solutions never construct events manually:

  • Form widgets declare action.emit: <event name> to put an event on the bus at submit.
  • Navigation emits ui.navigate automatically.
  • Load/close telemetry (ui.loaded / ui.closed) is emitted by the portal's solution UI host.

Emission reuses the platform's standard event ingestion (POST /api/v1/runtime/events), so every event carries tenant identity, solution attribution and a server-side timestamp.

Design rules​

  1. Emit for audit and observation; trigger workflows for action.
  2. Name business events <domain>.<past-tense> — reservation.confirmed, payment.settlement_failed.
  3. Keep payloads small and non-sensitive; events are readable by tenant users with developer access.
  4. Never encode secrets or credentials in event payloads.