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 and how you want to segment what you're tracking (by adding data fields).
• Where to find and capture the data in your environment (by mapping the required data fields 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 two elements that a Business Object can consist of.

Data fields

Data fields are what you want to track in your application. They can be of two different types:

• Number — numeric data type like 1000 or 10.5. They represent what you want to measure or track. Examples include session duration, amount, or points.
• String — sequence of characters like North Region or VIP User. They represent how you want to group what you're measuring, giving it dimensions. Examples include delivery zone, user type, game level, or key moment.
• Timestamp — data type that indicates date and time, e.g.: 2024-06-14T21:32:27Z. They can be used to calculate duration.
• Derived (Duration) — data type that calculates the difference between two timestamp data types within the same event. You must first add the timestamp data fields so that they are available when creating a derived data field.

To create a Business Object, you must add at least one data field.

For information on how to add a data fields, refer to Create Business Objects.

Metrics

Metrics are aggregations of the data fields you created. They represent calculations you apply to your data fields.

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

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: Count — Total number of rows in a data set or Business Object Count distinct — Total number of unique values in a data set Sum — Result of adding all of the numbers in a set of values for a given period Average — Sum of all values that divides them by the number of values for a given period Max — Maximum value or the largest value in a set of values for a given period Min — Minimum value or the smallest value in a set of values for a given period
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.

Data mapping

Mapping is defining the data source for your data fields.

Once you add a data field to your Business Object, you must define where Illuminate should look for this data. This is required when activating your Business Object, which starts the data capture process.

To define the data source, select the Map button next to each data field (regardless of its type) in your Business Object, select the Category and Subcategory, and provide the corresponding JSON path keys, where needed. For Derived (Duration), select the two timestamps needed to calculate the difference.

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

Enable App Context

If you create Business Objects that link to any App Context data through mapping (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 enabling Membership Events if you want to track them).

To use data found in Publish API, select message from Category and then a Subcategory. If you select meta or body, enter the JSON key in the following JSON path text box. If the keys are nested, enter key.nestedkey.

To use data found in App Context, select user, channel or membership from Category and then a Subcategory. If you select custom, enter the custom data field name in the following JSON path text box.

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))

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 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 data fields 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 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 points
• Activation status

Clicking the Ellipsis (...) button 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.