Event Triggers

Event triggers provides a flexible way to implement event-driven flow execution.

Terminology

Events
Are JSON documents with a specific type, some metadata, and optional data payload. See event data for a complete description.

Persistent events
Are saved in the database when they reach the server’s event processor, while transient events are not stored.

System events
Are generated by the server, and are mostly persistent. See the complete list.

User events
Are created in flows with the event node. They are persistent by default, and may contain data from the node’s input, or from manually configured JSON on the node.

Event triggers
Are used to run one or more flows when a specific event type occurs.

Event processor
Is the server’s internal event processing component. It is responsible for saving persistent events to the database, executing event triggers, and enforcing event loop protection.

Event browser
Is available in the UI to inspect all persistent events in the database. It can also delete specific events.

Event retention period
Is a server setting which, if enabled, will cause the server to delete events in the database after a certain amount of time. User events may be given a custom retention period in the event node’s configuration.

Event Data

Events are JSON objects. Here’s an example system event, as seen in the event browser:

{
   "id": "8c1c7fea-823b-4148-8e06-473db9b56fc3",
   "ts": "2024-02-25T11:58:12.336598Z",
   "kind": "sys",
   "type": "auth.ok",
   "persistent": true,
   "src": "",
   "src_id": "",
   "handled": false,
   "data": {
      "ip": "127.0.0.1",
      "username": "admin"
   },
   "source_flow_id": "",
   "origin_flow_id": "",
   "origin_trigger_id": "",
   "updated_at": "2024-02-25T11:58:12.337455Z"
}

Events contain and describe the following details:

field	type	note
id	string	unique UUID
ts	string	event generation timestamp within the server or a flow. Accurate millisecond precision.
kind	string	sys for internal, usr for user events
type	string	identifies the type of event
persistent	boolean	If true, the event will be stored in the database when it reaches the server’s event processor
src	string	Optional, describes the origin of the event
src_id	string	Optional, describes the origin identifier of the event
handled	boolean	Indicates whether the event has been processed through any event triggers
data	null/object	Optional. Contains type-specific data associated with the event. If not null, it always contains a JSON object
source_flow_id	null/string	Source flow ID that directly generated the event. Used in loop prevention
origin_flow_id	null/string	Originating flow ID that caused the event to be generated. Used in loop prevention
origin_trigger_id	null/string	Originating trigger ID that caused the event to be generated. Used in loop prevention
updated_at	string	Generated by the database once persistent events are saved/updated.

Event Data Retention

By default, the server automatically deletes event data that is older than a certain threshold. This behaviour is controlled by the configuration setting SIRVEO_RETENTION_PERIOD_EVENTS.

As of version 0.2.4, user events can be created with a custom retention period, using a setting on the event node. If a user event was created with a custom retention period, it will override the server’s default event retention configuration.

Event Loop Protection

The server automatically prevents loops while processing event triggers.

The event loop protection reference explains how this works.

System Events

See the system event reference for a complete list.