About Business Objects
Business Objects are how you get data into Illuminate. They are containers for the data you want to use for decisioning and visualization within Illuminate.
Business Objects let you define the following:
- What you want to track (by adding measures).
- How you want to segment what you're tracking (by adding dimensions).
- Where to find and capture the data in your environment (by mapping the required measures & dimensions to your backend data through JSON paths).
- How to aggregate the data captured (by creating metrics).
Enable App Context
You can use Illuminate without enabling App Context on your app’s keyset. However, if you create Business Objects in which you link to any App Context data through JSON paths (like channel, user, or membership information), you must enable App Context for the chosen app’s keyset on the Admin Portal and configure all the required options (like enable Membership Events if you want to track them).
Business Objects structure
These are the three elements that a Business Object can consist of.
Measures
Measures are numeric, quantitative values. They represent what you want to track. Examples of measures include session duration, donation amount, or order value.
To create a Business Object, you must add at least one measure or one dimension.
For information on how to add a measure, refer to Create Business Objects.
Dimensions
Contrary to numeric measures, dimensions are qualitative values (like places, products, and people) used to segment data or measures. They represent how you want to slice and dice what you’re tracking. Examples of dimensions include delivery zone, user type, game level, or key moment.
To create a Business Object, you must add at least one dimension or one measure.
For information on how to add a dimension, refer to Create Business Objects.
Metrics
Metrics are aggregations of the measures and dimensions you created. They represent calculations you apply to your measures and dimensions.
Metrics provide larger context to Business Objects, such as the average number of purchases during key moments of a watch party or the total value of sold goods. If you think of a Business Object as a spreadsheet collecting the data, a metric can be compared to a pivot table that aggregates and filters that data.
A metric is required to create a Decision or to visualize on Dashboards through charts.
As part of a metric, you can:
- Choose how to aggregate a given measure (
SUM,MAX, and more). - Count a selected dimension.
- Apply various filters to chosen measures or dimensions.
You can only add metrics to a Business Object that already exists. Each metric has the following elements:
| Item | Description |
|---|---|
| Metric name | A required display name for the metric. |
| Function | The type of measurement for a given metric. Available values include:
|
| Measure | What you’re tracking. You can only add measures that you previously added to the Business Object to which you are adding the metric. |
| Period | Aggregation window or the time period for your function. For example, the average number of purchases by the hour where the period is 30 minutes. |
| Dimension | How you’ve segmented what you’re tracking. You can only select dimensions you previously added to the Business Object to which you are adding the metric. |
| Filter | One or more criteria applied to the data that selectively isolate measure and dimension values according to specific parameters. Filters let you narrow down the data collected by Business Object in measures and dimensions. |
For information on adding metrics, refer to Create Metrics.
Data mapping
Mapping is defining the data source for your measures and dimensions.
Once you add your measure and dimension to your Business Object, you must define where Illuminate should look for this data. This is required when activating your Business Object that starts the data capture process.
To define the data source, select the Map button next to each measure and dimension defined for your Business Object and provide the corresponding JSON paths.
If PubNub powers your real-time applications, Illuminate works with your Publish API and App Context data. This means you can only capture data from your Publish or App Context calls based on the following format.
Publish API
Publish information is part of the message object.
It follows this structure:
{
"message":{ // data from the published message
"body": JSON | message body payload defined by you
"meta": JSON | meta query params defined by you
"userId": string | user ID a.k.a UUID / sender ID
"channel": string | the channel on which the message is published
},
}
To correctly map a measure or dimension, you must provide the message object followed by at least one key from your JSON.
$.message.{obligatory-secondary-field}.{optional-further-fields} // structure
$.message.body.type // example
For example, if you want to capture information about the channels on which messages are published, add a dimension like Channel and map it to $.message.channel.
Real-time apps not powered by PubNub
If your real-time app is not powered by PubNub, your data can be sent using the PubNub Fire API. To map the data, follow the same structure as for the Publish API. For guidance, contact support.
App Context API
Enable App Context
If you create Business Objects in which you link to any App Context data through JSON paths (like channel, user, or membership information), you must enable App Context for the chosen app’s keyset on the Admin Portal and configure all the required options (like enable Membership Events if you want to track trem).
App Context information is part of the user, channel, and membership objects.
It follows this structure:
{
"user": { // data from the sending user metadata, can be null
"externalId": string | user’s external ID
"type": string | user type
"status": string | user status
"custom": JSON | JSON user metadata defined by you
},
"channel":{ // data from the channel the message is sent on, can be null
"name": string | channel name
"type": string | channel type
"status": string | channel status
"custom": JSON | JSON channel metadata defined by you
},
"membership":{ // data from the user's membership to the channel, can be null
"status": string | membership status
To correctly map a measure or dimension, you must provide the user, channel, or membership object followed by at least one key from your JSON.
// User
$.user.{obligatory-secondary-field}.{optional-further-fields} // structure
$.user.type // example
// Channel
$.channel.{obligatory-secondary-field}.{optional-further-fields} // structure
$.channel.custom.details // example
// Membership
$.membership.{obligatory-secondary-field}.{optional-further-fields} // structure
$.membership.status // example
For example, if you want to capture information about the type of a user who published a message, add a dimension like User Type and map it to $.user.type.
Sensitive data
Illuminate captures all data you define with JSON paths and map when creating measures and dimensions for the Business Objects. For this reason, make sure you don’t include any PII data (e-mail address, profile URL, or IP address) in the custom fields of your App Context mappings.
Limits
These are the maximum values/limitations for your JSON path mappings:
- Depth:
20 - Numeric characters:
200 - No recursive descent (
..) - No wildcards (
*) - No script expressions (
?(@.x > y)) - The first two properties must match the required JSON path expression format.
Additional details
To work effectively with Business Objects, mind the following:
- To create and save a Business Object, you must define at least one measure or dimension. However, you must create at least one metric to use the Business Object in a Decision or a chart.
- 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 the measures and dimensions you defined for it must be mapped.
- You can either first activate a Business Object or create a Metric 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.
- You can edit a metric in this Business Object if it’s not used in an active Decision.
- You can still change the JSON paths mapped for measures and dimensions.
- You cannot add any more measures and dimensions 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 points
- Activation status
Clicking the "Actions" menu next to each item in the table lets you activate/deactivate, edit, or delete a Business Object.
Settings
Illuminate lets you edit, activate/deactivate, and remove this Business Object within the selected Business Object view.
