---
source_url: https://www.pubnub.com/docs/analytics/decisions/overview
title: Illuminate
updated_at: 2026-09-30T07:20:08.000Z
---

# Illuminate

## Documentation index

To discover more PubNub resources:

1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.

Do not assume a path exists, always check the index first.

Illuminate is PubNub's real-time decision engine. You define what data to capture from published messages, build metrics that aggregate that data, write rules that evaluate the metrics, and configure actions that run automatically when a rule fires.

Illuminate has three modules that work in sequence.

| Module | What it does | When to use it |
| --- | --- | --- |
| [Business Objects](https://www.pubnub.com/docs/analytics/decisions/business-objects.md) | Capture data from published messages and compute metrics | Define what Illuminate tracks and how to measure it |
| [Decisions](https://www.pubnub.com/docs/analytics/decisions.md) | Evaluate metrics and trigger automated actions | Act on traffic patterns without manual intervention |
| [Dashboards](https://www.pubnub.com/docs/analytics/decisions/dashboards.md) | Render charts from metrics and Decision activity | Monitor results and trends in real time |

## Business Objects

A Business Object brings data into Illuminate. It defines what to capture from your published messages, where each value comes from in your message payload, and how to aggregate that data into metrics.

Each Business Object has two parts:

* **Data fields** are the values you track. Available field types are Number, String, String (Max), Timestamp, and Derived (Duration). Derived (Duration) calculates the difference between two timestamp fields in the same event. Every new Business Object includes five pre-mapped fields: Channel, User, Message Type, Message, and Publish Timetoken.
* **Metrics** aggregate the captured data. A metric applies a function (Count, Sum, Average, Max, Min, or Count distinct) over a time period, with optional dimension grouping and filtering. Metrics are what Decisions evaluate and what Dashboards display.

A Business Object is inactive until you activate it. Before activation, you must map every data field to a JSON path in your message payload. Activation starts data capture. Once active, you can add metrics but not new data fields.

For field types, mapping categories, JSON path limits, and activation behavior, see [Business Objects](https://www.pubnub.com/docs/analytics/decisions/business-objects.md).

## Decisions

A Decision evaluates metrics and runs actions when conditions are met. It is the automation layer of Illuminate.

Each Decision has three elements:

* **Actions** define what Illuminate does when a rule fires. Available types are Send Message (uses the PubNub Publish API), Webhook, Update User, Update Channel, and Update Membership.
* **Conditions** set the thresholds that trigger actions. Conditions draw from a metric, a Query Builder query, or raw Business Object events as they occur.
* **Rules** combine conditions and actions into rows in the Decision table. You need at least one rule and one active Business Object to activate a Decision.

Illuminate evaluates rules on a configurable frequency. The hit policy controls whether it fires the first matching rule (Single) or all matching rules (Multiple) per evaluation cycle.

You can also limit how often each action runs: always, once per interval, or once per interval per unique condition value.

For action types, condition operators, and rule configuration, see [Decisions](https://www.pubnub.com/docs/analytics/decisions.md).

## Dashboards

A Dashboard is a named container for one or more charts.
Each chart on a Dashboard visualizes a metric from a
[Business Object](https://www.pubnub.com/docs/analytics/decisions/business-objects.md)
.
When the Business Object behind a chart is also used in a
[Decision](https://www.pubnub.com/docs/analytics/decisions.md)
, the chart shows when actions were triggered alongside the metric data.

You can configure each chart's time range, chart type (bar, stacked bar, or line), and width. Chart data reflects your browser's time zone and can be exported as a CSV file.

For chart settings and Dashboard management, see [Dashboards](https://www.pubnub.com/docs/analytics/decisions/dashboards.md).

## How the modules work together

Published messages flow into Business Objects. Business Objects extract data fields and compute metrics over time. Decisions evaluate those metrics and fire actions when conditions are met. Dashboards let you see the metrics, the triggered actions, and their effects in one place.

The typical sequence is:

* Create a Business Object, add and map data fields, then activate it.
* Add metrics to the Business Object.
* Create a Decision that references a metric, a query, or the Business Object's raw events.
* Build a Dashboard to monitor results.

## Availability and access

Illuminate works with any real-time app. Illuminate includes a two-week free trial. After the trial, [contact sales](https://www.pubnub.com/company/contact-sales/) to continue.

To access Illuminate, open the [Admin Portal](https://admin.pubnub.com/). In the sidebar, click **Illuminate**, then choose **Business Objects**, **Decisions**, or **Dashboards**.

If your app does not use the PubNub Publish API, you can send data to Illuminate through the PubNub Fire API. See [External data sources](https://www.pubnub.com/docs/analytics/decisions/external-data-sources.md) for details.

## Illuminate and Functions

Illuminate and [Functions](https://www.pubnub.com/docs/message-processing/serverless/overview.md) both let you act on your message traffic, but they work at different levels.

Functions execute JavaScript on individual message events at the edge. Use Functions when you need to transform, filter, enrich, or route a message while it is in flight.

Illuminate works on aggregated patterns over time. Use it when you need to evaluate trends across your traffic and trigger actions based on computed metrics.

The two are complementary. A Function can enrich a message before it reaches Illuminate. Illuminate then aggregates those values, evaluates conditions, and decides whether to send a discount, update user metadata, or call a webhook.

Last updated at: 2026-09-30T07:20:08.000Z