Decisions

A Decision evaluates data from a Business Object and runs actions when its rules match. You define conditions that compare values against thresholds. Rules combine conditions and actions into rows in the Decision table. When Illuminate evaluates a Decision and every condition in a rule is satisfied, it fires that rule's actions.

Business Objects supply the data. Dashboards display the results. For step-by-step instructions on creating a Decision, see Create Decisions.

Condition sources

Each Decision draws its conditions from exactly one of three sources. You choose the source when you create the Decision.

• Metric. Conditions come from the data fields of an aggregated metric on a Business Object. If the metric applies a function such as Count or Sum, the condition reflects that aggregated value. After you select a Business Object and one of its metrics, Illuminate auto-populates the condition columns from the metric's fields.
• Events. Conditions draw from the raw data fields of a Business Object as each event arrives, rather than from an aggregated metric. After you select a Business Object and the events option, you choose which data fields to use as conditions.
• Query. Conditions come from the fields in a Query Builder query. After you select a query, you choose the data fields from that query to use as conditions.

After activation, the metric, query, or event source used by the Decision cannot be changed.

Conditions

A condition specifies a threshold for a data field. When Illuminate evaluates the Decision, it compares the current value of each field against its threshold. A rule fires when all its conditions are satisfied.

A Decision can have up to 40 conditions.

Condition operators

The operators available depend on the field type. For numeric fields and aggregated metric values:

Operator	Meaning
Equals	The value exactly matches the threshold
Does not equal	The value does not match the threshold
Less than	The value is below the threshold
Less than or equal	The value is at or below the threshold
Greater than	The value is above the threshold
Greater than or equal	The value is at or above the threshold
Inclusive between	The value falls within a range, inclusive of both endpoints

Timestamp conditions

Conditions on Timestamp fields work differently. Illuminate first converts the stored timestamp to a duration using one of two functions:

• Time Since. Calculates how much time has passed since the timestamp when the Decision runs.
• Time Until. Calculates how much time remains until the timestamp when the Decision runs.

The resulting duration is then compared using the same operators as numeric conditions: equals, does not equal, less than, less than or equal, greater than, greater than or equal, or inclusive between. Each operator is available in both the Time Since and Time Until variants.

For example, you can use a timestamp condition to send a reminder 5 minutes before a scheduled appointment, or to follow up 10 minutes after a deadline passes.

Actions

An action defines what Illuminate does when a rule fires. You can add multiple actions to a Decision, and each action runs independently when a matching rule fires.

Five action types are available:

Action type	What it does	Configurable fields
Send Message	Publishes a message to a PubNub channel using the PubNub Publish API	Channel ID, Body, optional Meta
Webhook	Sends an HTTP request to a URL you specify	Payload, Webhook URL, optional Headers (key-value pairs)
Update User	Sets predefined or custom user metadata using PubNub App Context	Key-value metadata fields
Update Channel	Sets predefined or custom channel metadata using PubNub App Context	Key-value metadata fields
Update Membership	Sets predefined or custom membership metadata using PubNub App Context	Key-value metadata fields

All five action types support variables in every configurable field. Each action also has an optional Documentation/Notes section where you can add internal notes for your team.

Variables

Variables let you inject dynamic values into action fields at the time a rule fires. To add a variable, type ${ in any action field. Select a suggestion from the list, or type ${VariableName} to create a new one.

Two variable sources are available:

• Condition variables. The data fields from the Decision's source (metric, query, or events) are available as variables. For event-based Decisions, all data fields from the Business Object are available.
• Static variables. Variables you define and assign fixed values to within each rule row in the Decision table.

For example, the body "Welcome to ${levelName}, enter discount code ${discountCode} within the first 5 minutes to buy ${purchaseItem}." uses condition variables alongside static variables. levelName might come from a condition field. discountCode and purchaseItem might be static values set per rule.

Action execution limit

Each action has an execution limit that controls how often it can fire, even when its rule continues to match. Three options are available:

Option	Behavior
Always (default)	The action fires every time the rule matches during an evaluation cycle
Once per interval	The action fires once within a specified time interval, regardless of how many times the rule matches in that period
Once per interval per condition	The action fires once per unique condition value within a specified time interval. If three distinct users match the rule in one interval, the action fires three times, once per user.
Once per interval per condition group	The action fires once per unique combination of all condition values within a specified time interval. If the same user matches two different condition combinations, the action fires twice.

The limit resets when you deactivate the Decision. After a reset, past executions are not counted. You can also reset the limit manually while the Decision is active by clicking Reset limit.

Rules

A rule is one row in the Decision table. It pairs a set of conditions with a set of actions. When Illuminate evaluates the Decision and all conditions in a row are satisfied, it fires the actions in that row.

You can save a Decision without any rules. At least one rule is required before you can activate the Decision.

Rule configuration settings

Each Decision has four settings that apply to all its rules:

Setting	Description
Hit policy	Controls which rules run when multiple rules match in the same evaluation cycle. Single fires only the first matching rule in order. Multiple fires all matching rules.
Aggregation window	Auto-populated from the metric's Period. Shows how often the metric function runs over the data fields.
Evaluation frequency	How often Illuminate checks the rules in this Decision. This is the lookback window. On each evaluation, Illuminate checks current metric values or events against every rule.
Conditions	The threshold columns in the Decision table. See Conditions for the maximum.

Rules run in the order they appear in the Decision table. To change that order, open the Decision in edit mode and use Move up or Move down from the ellipsis menu next to each rule.

Activation

To activate a Decision, two requirements must be met:

• The Decision has at least one action and one rule.
• The Business Object referenced by the Decision is active.

When activating, you can choose to run the Decision until it is manually deactivated, or set specific start and end dates. Illuminate uses your browser's time zone for activation dates.

Once active, rules evaluate on the configured frequency and actions fire when conditions match.

After activation:

• You can edit rule values in the Decision table.
• You can add new rules and new actions.
• You can edit the Decision configuration, including hit policy and evaluation frequency.
• The metric, query, or event source the Decision uses cannot be changed.
• You can add the Decision to a Dashboard.

To stop evaluation and prevent further action executions, deactivate the Decision.

Action history

The Action history page shows the 50 most recent action executions for a Decision. Use it to confirm that actions are running and to diagnose failures.

Action history is accessible from three places:

• The ellipsis menu on each Decision chart in a Dashboard
• The ellipsis menu on a Decision on the Decisions home page
• The ellipsis menu in the Decision table when viewing a Decision

Each row in the Action history table shows:

• The action status (success or failure)
• The trigger value that caused the rule to fire
• The failure reason, if the action did not succeed

You can filter the table by any column value, such as status, trigger value, or failure reason. Expanding a row shows the full condition breakdown: the condition name, the threshold, and the actual value that triggered the action.

For example, Max of Minutes waiting ≥ 1 (6) means the condition name is Max of Minutes waiting, the threshold is ≥ 1, and the value that triggered the action was 6.

Action failure reasons

An action can fail for one of these reasons:

• Action configuration is invalid
• HTTP timeout error during dispatch
• Publish action was unsuccessful
• App Context action was unsuccessful
• Webhook action was unsuccessful
• The response status code is not 2xx

The Decisions home page

The Decisions home page lists all Decisions for your keyset. Each entry shows:

• Type. Whether the Decision is based on events, a metric, or a query.
• Business Object. The data source for the Decision.
• Actions. The number of actions currently enabled, compared to the total number of actions added.
• Status. Whether the Decision is active or inactive.
• Updated. The date of the last change and the user who made it.
• Created. The date the Decision was created and the user who created it.

From the home page, use the ellipsis menu on any Decision to edit its configuration or rules, view action history, activate or deactivate it, or delete it.