Skip to main content

External Evaluation

Alert rules that need more than one series, a time window, or arbitrary maths are evaluated outside dakkio. You supply the logic; dakkio owns the configuration, the schedule, the state machine and the delivery.

Why this exists​

A single-condition rule — "temperature above 30 °C" — is easy to express, and dakkio could evaluate it natively. The rules that actually justify a monitoring platform are not like that.

Consider a rule that verifies temperature control is genuinely working:

Internal temperature stays within a narrow band while external temperature swings widely.

Holding a band is only meaningful if something outside was pushing against it. Expressing that needs:

  • two series compared against each other, not one field against a constant
  • a 48-hour window, re-evaluated hourly
  • a spread calculation on each series
  • a gate: if the external temperature barely moved, the window proves nothing and must produce no verdict at all

That last point is the one that breaks simple rule engines. A mild day where nothing moved is not evidence of success, and reporting it as either "condition met" or "condition not met" would be a lie in both directions.

The same shape recurs across domains with different metrics — pressure differentials, weight change under load, flow against demand — and each one wants slightly different maths. Encoding them all into dakkio would mean a general time-series platform carrying your domain logic, ageing badly as it accumulates.

So the split is inverted: dakkio never does the maths.

The division of labour​

ConcernOwner
Rule definition, parameters, thresholdsdakkio
Evaluation schedule and due-nessdakkio
ARMED / FIRED state and edge detectiondakkio
Webhook dispatch, retry, delivery historydakkio
The mathsyour n8n workflow
Recipient, channel, language, wordingyour application

n8n is the reference evaluator, and the one this documentation walks through — see n8n Integration for a complete working workflow. Nothing about the API is n8n-specific, so a cron job, a Lambda, Make, or your own service works identically; n8n simply means the evaluation logic is a Code node rather than a deployment.

The evaluator never learns who the end user is. Your application never learns when a rule is due. Neither can be replaced without the other noticing, and both can be replaced independently.

The flow​

Step by step​

① Create the rule. Through the API with an admin key. You describe what to read (inputs) and how to judge it (parameters). See Rule Configuration.

② Ask what is due. One call returns every rule across the whole organization whose interval has elapsed — regardless of how many buckets you have. An empty array is the normal outcome; most polls return nothing.

③ Receive a fetch plan. Each rule arrives with its inputs already resolved into query bodies, absolute time bounds included. The evaluator does no clock arithmetic.

④ Fetch the data. Post each input's query object verbatim to the data query endpoint. No translation.

⑤ Compute. This is your code, and dakkio has no opinion about it. Read kind to decide which computation to run and parameters for the constants.

⑥ Submit a verdict. met, not_met, or inconclusive. dakkio applies the state machine — see Evaluation API.

⑦ Delivery. Only the ARMED → FIRED transition produces a webhook. A rule that stays true for six months notifies once. See Webhook Delivery.

⑧ Your application notifies. dakkio sends measurements; you turn them into words.

Two properties worth understanding early​

Edge-triggered. Notifications fire on a change of state, never on a state. This is the difference between "you have an alert" and "you are still in the situation you were told about an hour ago".

Opaque parameters. dakkio stores and returns parameters and never interprets them. For a band rule they hold the boundaries and a variation gate; for yours they hold something else entirely. That opacity is precisely what keeps dakkio out of your domain.

What this costs​

Every rule needs an evaluator running — including trivial ones. A customer who only wants temperature > 30 must still run something. That is a real cost, accepted deliberately: the alternative was shipping the easily-replaceable capability first and the differentiating one never.

Next​