Rule engine extensions (new conditions, complex actions)

Last updated: May 19, 2026

Rule engine extensions (new conditions, complex actions)

The Rules Engine extensions add advanced primitives beyond the base set: trend operators (compare current vs prior period), day-parting (schedule by day-of-week + hour-of-day), daily_at_time schedule, projected spend pacing, and cross-platform rules (behind ENABLE_CROSS_PLATFORM_RULES flag — span Meta + Google + TikTok + LinkedIn + Taboola).

Who is this for

Users beyond basic rules who need:

  • Drift detection (catch performance change vs absolute thresholds)

  • Time-of-day control (run rule only at specific hours)

  • Cross-platform comparisons (single rule across all platforms)

Extension 1: trend operators

Two new operators that compare current time_range to the immediately preceding equal-length period.

Operator

Meaning

Example

increased_pct

rose by ≥ N% vs prior period

cpa increased_pct 30 / last_3d → CPA up 30%+ in last 3 days vs the 3 days before

decreased_pct

fell by ≥ N% vs prior period

roas decreased_pct 25 / last_7d → ROAS dropped 25%+ vs prior week

Why useful: absolute thresholds catch "is metric bad now?". Trend operators catch "is metric getting worse fast?" — earlier signal.

Worked example (alert on CPA drift):

condition_logic: OR
- metric: cpa, operator: gt, value: 50, time_range: last_3d        # absolute alarm
- metric: cpa, operator: increased_pct, value: 30, time_range: last_3d  # trend alarm
actions: [notify_only]

Fires on either condition. Catches both "CPA is bad" and "CPA is getting worse fast".

Extension 2: day-parting

DayPartingConfig lets a daily_at_time schedule run only on specific days + hours.

Fields:

  • days_of_week: array of 0-6 (Sunday=0)

  • hours_of_day: array of 0-23

  • timezone: IANA timezone string (e.g. "Europe/Rome")

  • type: "day_parting"

Preset schedules:

Preset

Days

Hours

work

Mon-Fri (1-5)

9-18

night

All days (0-6)

22-5 (wraps midnight)

clear

none (disabled)

none

Use case: rule that should run only during business hours when team can react ("notify on spend > 80% only Mon-Fri 9-18 — outside that window, nothing to do anyway").

Extension 3: daily_at_time schedule

Schedule type alongside interval. Runs at HH:MM on chosen days. Configured via DayPartingConfig.

Differences vs interval:

Aspect

interval

daily_at_time

Cadence

every N min

once per day per matching slot

Min cadence

15 min

1 day

Use case

continuous monitoring

end-of-day kill, start-of-week scale

Example: "Every weekday morning at 09:00, pause adsets that consumed > 90% of yesterday's budget by midnight." Runs once daily at the chosen time.

Extension 4: projected_spend_pct (spend pacing)

Multi-platform metric tracking budget depletion rate (not just current consumption).

Use case: detect ad sets that are pacing to exceed daily budget hours before they actually do.

Example:

metric: projected_spend_pct, operator: gt, value: 110, time_range: today
actions: [notify_only]

Fires when current pace projects > 110% of daily budget by end-of-day (extrapolation from current hour's spend velocity).

Earlier signal than budget_spent_pct gt 100 (which fires after budget is already exceeded).

Extension 5: cross-platform rules

Behind the ENABLE_CROSS_PLATFORM_RULES feature flag. Backed by apps/backend/src/routes/api/analytics/cross-platform-rules.route.ts + cross-platform-rule-evaluator.service.ts.

What's different:

  • Single rule evaluates entities across multiple platforms simultaneously (Meta + Google + TikTok + LinkedIn + Taboola)

  • Uses a separate (smaller) metric set: 7 metrics (spend, spend_pct, impressions, clicks, ctr, cpc, cpm, purchases, purchase_value, roas, cpa)

  • 5 operators (subset): greater_than, less_than, greater_or_equal, less_or_equal, equal

  • Templates: 6 pre-built in cross-platform-rule-templates.ts

  • Endpoint: POST /api/v1/analytics/rules/from-template to instantiate

Use cases:

  • "If TikTok CPA > Meta CPA × 1.5, alert" (cross-platform performance comparison)

  • "If Google spend > 60% of total cross-platform spend today, alert" (channel concentration)

  • Multi-platform budget pacing in one rule

Requires admin to enable the feature flag at workspace or org level.

Extension 6: alert creator dialog

UI helper for creating cross-platform rules from templates with schedule overrides:

  • interval_minutes: 15-1440 (15 min to 24 h)

  • cooldown_minutes: 60-10080 (1 h to 1 week)

  • max_executions_per_day: 1-10

Quick-launch path for cross-platform alerts without full rule builder.

Combining extensions

Extensions can combine:

  • Cross-platform rule with trend operators (detect cross-platform CPA drift)

  • daily_at_time schedule with projected_spend_pct (morning check of full-day projection)

  • Day-parting on a cross-platform alert rule

Each combination is recorded in the rule's validation schema (TypeBox).

Compatibility

Extensions are additive — base rules continue to work unchanged. Existing rules that don't use extensions are unaffected.

If the ENABLE_CROSS_PLATFORM_RULES flag is off: cross-platform rule creation fails with a clear error. Other extensions (trend operators, day-parting, daily_at_time, projected_spend_pct) are available regardless.

Common mistakes

  • Trend operator + short time_range: 1-day windows have too much noise for trend comparison; use last_3d+

  • Day-parting timezone mismatch: confirm workspace timezone before saving

  • Cross-platform rule on platforms with very different metric definitions: e.g. video metrics differ between Meta and TikTok; cross-platform CTR comparison can mislead

  • projected_spend_pct early in day: pacing prediction is less reliable in the first 1-2 hours; consider a daily_at_time schedule after 10 AM

Related