---
source_url: https://www.pubnub.com/docs/illuminate/business-objects/basics
title: About Business Objects
updated_at: 2026-05-21T15:45:39.399Z
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# About Business Objects

Business Objects bring data into Illuminate. They store data you use for decision‑making and visualization.

Business Objects let you define the following:

* What to track and how to segment it (add [data fields](https://www.pubnub.com/docs/illuminate/business-objects/basics#data-fields)).
* Where to capture the data (use [mapping](https://www.pubnub.com/docs/illuminate/business-objects/basics#data-mapping) to point fields to your backend with JSON paths).
* How to aggregate the captured data (create [metrics](https://www.pubnub.com/docs/illuminate/business-objects/basics#metrics)).
* How to use the captured data in one of the [predefined queries in Query Builder](https://www.pubnub.com/docs/illuminate/business-objects/query-builder).

:::note Configure App Context
You can use Illuminate without enabling [App Context](https://www.pubnub.com/docs/general/metadata/basics). If you link to [App Context data through JSON paths](#data-mapping) (channel, user, or membership), enable App Context for the app’s keyset in the [Admin Portal](https://admin.pubnub.com/) and turn on required options (for example, Membership Events).
:::

## Business Objects structure

A Business Object has two elements: Data fields and metrics.

### Data fields

Data fields are what you track in your application and can have the following types:

* `Number` — numeric data like `1000` or `10.5`. Use to measure values (session duration, amount, points).
* `String` — text like `North Region` or `VIP User`. Use to group measurements (dimensions), such as delivery zone, user type, game level, or key moment.
* `String (Max)` — 1000-character text data fields. Use for chat message fields, comments, or descriptions.
* `Timestamp` — date and time, for example `2024-06-14T21:32:27Z`. Use timestamps to calculate duration.
* `Derived (Duration)` — the difference between two timestamp fields in the same event. Add the timestamp fields before you create a derived field.

The maximum number of data fields per Business Object is 100.

For details on how to add data fields, see [Create Business Objects](https://www.pubnub.com/docs/illuminate/business-objects/create-business-object).

### Metrics

Once you define data fields, create metrics to aggregate them. Metrics are the calculations you apply to your data.

Metrics add context, such as average purchases during a watch party or total value sold. If a Business Object is a spreadsheet of raw data, a metric is like a pivot table that aggregates and filters it.

A metric is required to create a [Decision](https://www.pubnub.com/docs/illuminate/decisions/create-decision) or to visualize on [Dashboards](https://www.pubnub.com/docs/illuminate/dashboards/create-dashboards-and-charts) through charts.

As part of a metric, you can:

* Choose how to aggregate your data (`Sum`, `Max`, and more).
* Select a data field for which you want to group by or count.
* Apply various filters to chosen data fields.

Add metrics only to an existing Business Object. Then define these elements:

| Item | Description |
| --- | --- |
| **Metric name** | A required display name for the metric. |
| **Function** | The measurement type. Values include: Count — number of rows, Count distinct — number of unique values, Sum — sum of values, Average — average of values, Max — maximum value, Min — minimum value |
| **Measure** | What you want to aggregate. |
| **Period** | Aggregation window or the time period for your metric. For example, the average number of purchases by the hour where the period is `1 hour`. |
| **Dimension** | How you'd like to group the data in your metric. |
| **Filter** | The data you want to include in or exclude from your metric. |

For information on adding metrics, refer to [Create Metrics](https://www.pubnub.com/docs/illuminate/business-objects/create-business-object#create-metrics).

## Data mapping

Mapping defines the data source for your data fields.

After you add a field, define where Illuminate finds it. Map fields before activation. Activation starts data capture.

To define the source, click **Map** next to each field, choose **Category** and **Subcategory**, and enter the **JSON path** as needed. For `Derived (Duration)`, select the two timestamps to calculate the difference.

![Map button](https://www.pubnub.com/assets/images/map-button-39d98b9e3e1142f00461a2ad42f08d23.png)

If PubNub powers your real‑time apps, Illuminate works with your Publish API and App Context data.

###### Define time ranges with publish timetokens

Illuminate can use the publish timetoken (`PUBLISH_TIMETOKEN`) as a time boundary when calculating derived duration fields. This lets you measure elapsed time between a custom timestamp in your message payload and the moment PubNub received the publish, without sending a separate clock value. See the [Illuminate Admin API](https://www.pubnub.com/docs/admin-api/illuminate-introduction) for `TimeDiffParams` configuration.

:::note Configure App Context
If you link to [App Context](https://www.pubnub.com/docs/general/metadata/basics) data through mapping (channel, user, or membership), enable App Context for the app’s keyset in the [Admin Portal](https://admin.pubnub.com/) and turn on required options (for example, Membership Events).
:::

###### Map membership data into Business Objects

When you select `membership` as the data mapping category, Illuminate captures membership events (created, updated, deleted) as they occur. This lets you build metrics around user-channel relationships, such as membership growth per channel or churn rates across user segments. Enable **Membership Events** in the [App Context configuration](https://www.pubnub.com/docs/general/metadata/basics#configuration) to generate the events that Illuminate maps.

To use data from Publish API, select `message` in **Category**, then a **Subcategory**. If you select `meta` or `body`, enter the JSON key in **JSON path**. For nested keys, enter `key.nestedkey`.

![Publish API](https://www.pubnub.com/assets/images/publish-api-4a1669edab01c11a8d45eb8f2a296c18.png)

To use data from App Context, select `user`, `channel`, or `membership` in **Category**, then a **Subcategory**. If you select `custom`, enter the custom data field name in **JSON path**.

![App Context API](https://www.pubnub.com/assets/images/app-context-api-89191f18576cba129af1000fcf5127f8.png)

###### Attribute analytics to users with User ID mapping

When you map a data field to the `user` category, Illuminate captures the [User ID](https://www.pubnub.com/docs/general/setup/users-and-devices) from each event. The default `$.message.userId` field is pre-mapped on every new Business Object. Use this to build metrics grouped by user, such as message volume per user or engagement rates across user segments. You can also map [App Context user metadata](https://www.pubnub.com/docs/general/metadata/users-metadata) custom fields to enrich your analytics with stored user attributes.

###### Aggregate metrics by channel with Business Objects

When you map a data field to the `channel` category, Illuminate captures the channel identifier from each event. Use this to build metrics grouped by channel, such as message volume per channel or engagement rates across channel patterns. For background on how channels are structured and named, see [Channel Basics](https://www.pubnub.com/docs/general/channels/overview) and [Channel Naming Conventions](https://www.pubnub.com/docs/general/channels/channel-naming).

### Limits

JSON path mapping limits:

* Depth: `20`
* Numeric characters: `200`
* No recursive descent (`..`)
* No wildcards (`*`)
* No script expressions (`?(@.x > y)`)

## Additional details

To work effectively with Business Objects, mind the following:

* To create and save a Business Object, you must define at least one data field. However, you must create at least one metric to use the Business Object in a chart. Once saved, you can create a metric and/or a query.
* For a Business Object to start capturing and storing the data based on the information provided, you must activate it. To activate a Business Object, all data fields must be [mapped](https://www.pubnub.com/docs/illuminate/business-objects/basics#data-mapping) and you must have at least one app & keyset selected.
* You can either first activate a Business Object or create a Metric or a Query for it — the order doesn't matter.
* Once you activate the Business Object: Illuminate starts capturing the defined data., You can add a metric to it or create a query., You can edit a metric in this Business Object if it's not used in an active Decision., You can edit a query that sources data from this Business Object if it's not used in an active Decision., You can still change the JSON paths mapped for data fields., You cannot add any more data fields to this Business Object.
* You can deactivate the Business Object if you no longer need it. When you deactivate a Business Object, the data defined in it is no longer captured. If you reactivate the Business Object, the data will start flowing anew, but you must account for the data gap between the deactivation and reactivation periods.
* When you delete the Business Object, it's permanent, and you cannot undo this action. Any Decisions and charts within Dashboards that use this deleted Business Object will get automatically deleted.

## Home page

The **Business Objects** home page provides the list of all created Business Objects along with the following information:

* Number of dashboards a Business Object is used in
* Number of decisions a Business Object is used in
* Number of mapped and unmapped data fields
* Activation status

Click the Ellipsis (...) next to an item to activate/deactivate, edit, or delete a Business Object.

![Business Objects home page list with counts and actions menu](https://www.pubnub.com/assets/images/business-objects-home-page-92b431097b3fb0b83d2b71072b315bae.png)

## Settings

In the selected Business Object view, you can edit, activate/deactivate, or remove the Business Object.

![Business Object settings panel with edit and activation controls](https://www.pubnub.com/assets/images/business-object-settings-e9a40081a5c8ffd4add849251a3f8329.png)