Skip to main content

Trigger Rules & Scheduled Jobs

Overview​

A trigger rule is a "when X happens, do Y" rule that connects real events in the system to the actions the business wants to take.

  • Sources include an attribute changing value, a form submission, a campaign link click, a new friend adding the account, or a scheduled point in time.
  • Actions include sending a message, adding the user to an audience, switching the rich menu, or resuming a workflow from the node where it paused.

Actions that need to wait are not executed immediately. They are queued into scheduled_action until their due time. Rules that run on a schedule rely on scheduled_trigger_execution to guarantee that a given cycle is never executed twice.

Core Data Structure​

trigger_rule — the rule itself​

Holds the definition of each rule, keeping the source side and the action side cleanly separated.

GroupColumnsNotes
Sourcesource_type, source_configEvent type plus its parameters as JSONB
Actionaction_type, action_configAction type plus its parameters as JSONB
Rate controlenabled, frequency, cooldown_secondsfrequency defaults to once_per_hour
Workflow bindingworkflow_id, workflow_node_pathUsed when the rule is part of a workflow
Scopeline_oa_id, organization_idIsolates data per channel and organization

The table uses soft deletes via deleted_date and carries indexes on (line_oa_id, organization_id) and (deleted_date) so that fetching the live rules of a channel stays cheap.

trigger_log — execution history​

Records every evaluation and execution of a rule. Its primary key is a BIGINT because of the volume involved.

  • Back-references: trigger_rule_id, audience_id, user_id (LINE userId), trigger_on
  • Stores the action_type and action_config as they were at that moment, so history stays auditable even after the rule is edited
  • Outcome: status (defaults to success) and error_message
  • The (trigger_rule_id, created_date DESC) index backs the per-rule history screen

scheduled_action — the deferred work queue​

Holds work created by a rule but not yet due.

  • Job data: trigger_rule_id (nullable), user_id, action_type, action_config, source_config
  • Timing: execute_at, expires_at, executed_at
  • State: status (defaults to pending) and retry_count
  • workflow_id and workflow_node_path let a workflow resume from where it paused

The indexes map directly onto the access patterns: idx_scheduled_action_pending (execute_at) picks up due work, idx_scheduled_action_processing (updated_at) serves the reaper that sweeps up jobs stuck in processing, and idx_scheduled_action_user (user_id, trigger_rule_id) checks whether a user already has pending work from the same rule.

scheduled_trigger_execution — one row per scheduled cycle​

Each row represents a single cycle of a time-based rule. The core of the table is the unique constraint (trigger_rule_id, scheduled_at), named uq_scheduled_trigger_execution: even when several workers race to run the same cycle, only one of them can insert the row and proceed.

The table also tracks the state and statistics of the cycle through started_at, completed_at, status (defaults to processing), total_users, processed_users, failed_users and error_message.

  • prisma/schema.prisma:1340 — the TriggerRule model
  • prisma/schema.prisma:1369 — the TriggerLog model
  • prisma/schema.prisma:1494 — the ScheduledAction model
  • prisma/schema.prisma:1520 — the ScheduledTriggerExecution model
  • manual-sql/1.notify_attribute_change.sql, manual-sql/2.notify_attribute_change.sql, manual-sql/3.bank.sql, manual-sql/4.sql, manual-sql/5.sql — the pg_notify triggers that act as rule sources
  • schema-dumps/2026-07-24/schema.sql:3077, :3038, :2706, :2751

Connections to Other Services​

  • worker-go is the heart of this domain. Its pg-listener consumes the attribute_changed, form_submitted, campaign_click, friend_track_event_inserted and booking_event events, evaluates the matching rules, writes trigger_log, and creates or executes scheduled_action entries.
  • cms-api-go owns rule authoring through its trigger-rule module, along with the execution-history screens.
  • Connects to Workflow, pg_notify & Event Outbox, Audience and Link Tracking.