---
source_url: https://www.pubnub.com/docs/analytics/decisions/business-objects
title: Business Objects
updated_at: 2026-09-30T07:20:08.000Z
---

# Business Objects

## 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.

A Business Object defines what data Illuminate captures from published messages, where each value comes from in your message payload, and how to aggregate that data into metrics. [Decisions](https://www.pubnub.com/docs/analytics/decisions.md) evaluate those metrics. [Dashboards](https://www.pubnub.com/docs/analytics/decisions/dashboards.md) display them as charts.

Each Business Object has two parts:

* **Data fields** are the values Illuminate captures from each published message. Each field has a type that controls how the value is stored and a mapping that points Illuminate to the correct path in your payload.
* **Metrics** aggregate field values over a time window. A Business Object needs at least one metric before it can be used in a Decision or a Dashboard chart.

## Data fields

Field types determine how Illuminate stores and interprets each captured value.

| Field type | What it stores | Use for |
| --- | --- | --- |
| `Number` | Numeric value, such as `1000` or `10.5` | Measuring quantities: purchase amount, points, session duration |
| `String` | Text value | Grouping data into dimensions: delivery zone, user type, game level |
| `String (Max)` | A `String (Max)` field holds text up to 1,000 characters long. A Business Object can include up to 5 `String (Max)` fields. | Chat messages, comments, descriptions |
| `Timestamp` | Date and time, such as `2024-06-14T21:32:27Z` | Marking when an event occurs, calculating elapsed duration |
| `Derived (Duration)` | Difference between two `Timestamp` fields in the same event | Measuring elapsed time between two points in one message |

A Business Object can have up to 100 data fields.

### Pre-mapped fields

Every new Business Object includes five pre-mapped fields: Channel, User, Message Type, Message, and Publish Timetoken. Illuminate maps them automatically to standard PubNub Publish API values.

| Field | JSON path |
| --- | --- |
| Channel | `$.message.channel` |
| User | `$.message.userId` |
| Message Type | `$.message.body.type` |
| Message | `$.message.body.text` |
| Publish Timetoken | `$.timetoken` |

You can rename these fields or update their JSON paths. Publish Timetoken is the only pre-mapped field without a mapping category. It uses the `Timestamp` field type and maps directly to the top-level `$.timetoken` path.

## Data mapping

Mapping connects each data field to a value in your message payload. All fields must be mapped before you can activate a Business Object. After activation, you can update the JSON path for an existing field, but you cannot add new data fields.

Each mapping has three parts:

* **Category** is the data source: `message` for Publish API data, or `user`, `channel`, or `membership` for [App Context](https://www.pubnub.com/docs/data-storage/metadata/overview.md) data.
* **Subcategory** narrows the source within the category. For `message`, choose `meta` or `body`. For `user`, `channel`, or `membership`, choose `custom` or another available attribute.
* **JSON path** is the key or key path within that subcategory. For nested keys, use dot notation: `key.nestedkey`.

For a `Derived (Duration)` field, mapping selects two `Timestamp` fields from the same Business Object rather than a JSON path.

App Context is not required unless you map fields to the `user`, `channel`, or `membership` categories. If you do, enable App Context for the app's keyset in the [Admin Portal](https://admin.pubnub.com/) and turn on the required options. For `membership` mappings, enable Membership Events.

### JSON path limits

JSON path expressions must satisfy these constraints:

* A Business Object JSON path expression supports up to 20 levels of depth.
* A Business Object JSON path expression can be up to 200 characters long.
* Recursive descent (`..`) is not supported
* Wildcards (`*`) are not supported
* Script expressions (`?(@.x > y)`) are not supported

## Metrics

A metric aggregates field values over a time window. Decisions evaluate metrics, and Dashboards display them as charts. You cannot create a Decision or a Dashboard chart without at least one metric on the Business Object they reference.

A metric has a name, a function, a measure, and a period. You can also add a dimension to group results and a filter to narrow the data.

| Component | Description |
| --- | --- |
| **Metric name** | Display name for the metric |
| **Function** | How values are combined: Count, Count distinct, Sum, Average, Max, or Min |
| **Measure** | The data field whose values are aggregated |
| **Period** | The time window for aggregation, such as 1 hour |
| **Dimension** | Optional. A field to group results by |
| **Filter** | Optional. A condition to include or exclude specific values |

You can add metrics before or after activating the Business Object. After activation, you can edit a metric as long as it is not used in an active Decision.

## Activation

Activation starts data capture. To activate a Business Object, two conditions must be met:

* All data fields are mapped.
* At least one app and keyset is assigned to the Business Object.

Once active, Illuminate captures incoming message data against the defined fields. Illuminate keeps a Business Object's captured data for 90 days. After activation:

* You can add metrics and queries.
* You can edit metrics not used in an active Decision.
* You can change the JSON paths for existing data fields.
* You cannot add new data fields.

You can deactivate a Business Object to stop data capture. If you reactivate it later, capture resumes from that point. The data gap between deactivation and reactivation is not backfilled.

Deleting a Business Object is permanent. Deleting a Business Object also permanently deletes its Metrics, Decisions, and Dashboard charts.

## Business Objects in the Admin Portal

The Business Objects home page lists all Business Objects. Each entry shows:

* Activation status
* Number of data fields and how many are mapped
* Number of Decisions using the Business Object
* Number of Dashboards using the Business Object

From the home page, you can activate, deactivate, edit, or delete any Business Object.

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