Business Objects

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 evaluate those metrics. Dashboards 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 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 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.