Rules: a closer look

Rules: a closer look

Introduction.

Rules are one of the main concepts in the ODIN system. They allow a researcher to define the conditions under which questions should be shown to a participant.
Rules can have one or more  filters  attached to them, which add extra constraints on top of the rule's own conditions. For a full breakdown of available filter types, see  Filters: a closer look .
When in doubt, you can always select a rule and read the description of its logic, e.g.:

Rule platforms.

When you create any rule, the ODIN website will ask you to choose a platform. This parameter simply determines where that rule will be registered and evaluated, either on the ODIN server or on the participants' phones.
As you may expect, rules registered on the user's phone tend to be more responsive, since they are locally computed and thus don't require the device to communicate with our servers to work.
Additionally, some types of rules can only be registered on one platform, due to inherent constraints.

Shared parameters.

Each rule has a set of parameters that are specific to it, as well as some shared, predefined ones that apply to all of them, namely:
  • Maximum number of seconds to show the question for: determines for how long a question fired by the given rule is going to remain available for the participant to answer. After this period expires, the question will be considered expired.
  • Groups (comma-separated integers): When you print coupons for a study, you have to add them to one or more _groups. _Using this parameter, you can make rules target such groups. This is useful for cases when you need to differentiate your participants somehow.
  • For instance, imagine you want to show a question once a day, but you want to allow participants to choose if they want to see it in the morning or at night.
  • A way to achieve this would be to create the question, and attach two rules to it: one targeting group 1, the other one targeting group 2. You can then print a coupon into group 1 (if they want to receive the question early), or group 2 (if they prefer to get it at night).
  • You can also change a participant's group(s) at any time, using the Participants page; so you can do more complex things.

Rule catalog (current).

This section reflects the current ODIN rule inventory and naming.
Across many sensor rules, you'll see references like [2*SI]: this means two sensor intervals for the corresponding sensor.

Time rules.

  • Upon recurring time interval (cronRule): asks on a recurring cron schedule. Uses ODIN's cron builder/manual mode. See  Cron expressions .
  • Show group of questions upon recurring time interval (compoundCronRule): same as recurring cron, but fires a bundle of target questions (Compound question type only).
  • Upon random time within a window (randomTimeRule): asks once at a random time within a daily window defined by start hour (hourOfDay) and window length in hours (spanInHours).

Follow-up rules.

  • Upon specific answer to an asked question (follow-up) (questionObserverRule): asks after a delay when a target question receives one of specific choice IDs.
  • Show group of questions upon specific answer to an asked question (compound follow-up) (compoundQuestionObserverRule): like the previous rule, but maps selected choice IDs to bundles of follow-up questions (Compound only).
  • Immediately after showing a specific question (on-show follow-up) (unsetQuestionObserverRule): asks after delay once the referenced question is shown (not answer-dependent).
  • Upon minimum number of trials on a psychometric question (trial-based follow-up) (questionMinNumTrialsObserverRule): asks after delay once the minimum trial count is reached.
  • Upon specific answer to an asked question with negation (follow-up) (questionObserverNegationRule): asks when one set of choices is selected and another set is explicitly not selected.
  • Upon specific answer text found on an asked question (fill-text follow-up) (fillTextContentObserverRule): asks when a fill-text answer contains any configured substring (case-insensitive).
  • Upon a numeric answer compared to a given number (fill-number follow-up) (fillNumberComparisonObserverRule): asks when a numeric answer satisfies the configured comparison operator/value.
  • Upon specific/any answer to an asked end of study question (exit interview follow-up) (endOfStudyChain): asks after end-of-study questions based on selected response IDs.

Other non-sensor rules.

  • Upon discretionary button press (uiObserverRule): creates a mobile app "Report events" button with a custom label and vertical slot position; pressing it triggers the question.
  • Upon given day of study participation (timeSinceEnrollment): asks at a specific hour on the Nth day since consent/registration.
  • Upon end of study (exit interview) (endOfStudy): asks at the study end, at a configured hour.

GPS location rules.

To use these, your study must have GPS enabled.
  • Upon arrival at specified location (onArrival_GPS): triggers on transition from outside radius to inside radius (with [2*SI] stability conditions).
  • Upon departure from specified location (onDeparture_GPS): triggers on transition from inside radius to outside radius (with [2*SI] stability conditions).
  • While at specified location (whileAt_GPS): repeats every configured seconds while participant remains inside radius (after entry stabilization).
  • While NOT at specified location (whileNotAt_GPS): repeats every configured seconds while participant remains outside radius (after exit stabilization).
  • Upon arrival at any of the specified locations (onArrival_Multilocation_GPS): arrival behavior over a configured set of scheduled locations.
  • Upon departure from any of the specified locations (onDeparture_Multilocation_GPS): departure behavior over a configured set of scheduled locations.

Multilocation GPS input.

Multi-location GPS rules use a JSON-backed locations payload in the rule form (historically commonly prepared from CSV-style rows of latitude/longitude/radius/schedule).
Practical constraints remain the same:
  • Latitude must be between -90 and 90.
  • Longitude must be between -180 and 180.
  • Radius is in meters.
  • Scheduled windows determine when each location is considered active.
Helpful tools:
  • Radius visualization:  Draw a circle with a radius on a map 
  • Cron tooling:  Crontab.guru 

Proximity rules (participant-to-participant).

These families share the same behavior shape: transition-based rules (onArrival, onDeparture) and sustained-state rules (whileAt, whileNotAt), with NEAR defined as either Bluetooth-detectable or RSSI threshold.

Bluetooth category (ProximityBluetooth).

  • Upon forming/joining a group of participants (onArrival_Bluetooth)
  • Upon someone leaving a group of participants (onDeparture_Bluetooth)

BLE category (ProximityBLE).

  • Upon forming/joining a group of participants (onArrival_BLE)
  • Upon someone leaving a group of participants (onDeparture_BLE)

Beacon proximity rules (ProximityBeacon).

Beacon rules target beacon minor values plus NEAR definition.
  • Upon being in the proximity of beacon device(s) (onArrival_Beacon)
  • Upon leaving beacon device(s) (onDeparture_Beacon)
  • While in the proximity of beacon device(s) (whileAt_Beacon)
  • While NOT in the proximity of beacon device(s) (whileNotAt_Beacon)

Activity recognition rules (ActivityRecognition).

Supported activities include driving, biking, on foot, running, still, and walking.
  • Upon starting specified activity (onArrival_Activity)
  • Upon finishing specified activity (onDeparture_Activity)
  • While doing specified activity (whileAt_Activity)
  • While NOT doing specified activity (whileNotAt_Activity)

Empatica E4 rules (EmpaticaE4).

These rules react to GSR compared against a moving average in the configured lookback period.
  • Upon GSR above average (onArrival_EmpaticaE4)
  • Upon GSR below average (onDeparture_EmpaticaE4)
  • While GSR is above average (whileAt_EmpaticaE4)
  • While GSR is below average (whileNotAt_EmpaticaE4)

Data Analysis rules.

ODIN supports external forecast consumers through two linked rule types:
  • Forecasting rule (forecasting): marks a numeric/NPS question for periodic external analysis. Optional configuration JSON and optional expected output keys can be provided.
  • Upon specified forecast result (forecasting_reaction): evaluates periodic comparisons between two forecast-output fields from a target forecasting rule, and triggers the question when the condition is met.
The usual integration flow:
    Attach forecasting to forecast-enabled questions.
    Use  Data Analysis API  in your consumer to pull data and push forecasts.
    Attach forecasting_reaction to trigger questions from forecast comparisons.
 [configexample.json (2KB)] 

Platform and behavior notes by rule family.

  • FE only examples: uiObserverRule, randomTimeRule, beacon rules, several follow-up specializations.
  • FE + BE examples: cronRule, core GPS point rules, BLE/Bluetooth participant proximity, activity, some sensor families.
  • BE only: forecasting, forecasting_reaction.
  • Compound-only rule targets: compoundQuestionObserverRule, compoundCronRule.
  • Rules that do not ignore group IDs or max answer time by default: almost all editable rules.
  • Special exception: forecasting ignores both group IDs and max answer time and is not user-editable once defined.