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: COUNT — Total number of values in a data set (used with dimensions) SUM — Result of adding all of the numbers in a set of values for a given period (used with measures) AVG — Sum of all values that divides them by the number of values for a given period (used with measures) MAX — Maximum value or the largest value in a set of values for a given period (used with measures) MIN — Minimum value or the smallest value in a set of values for a given period (used with measures)
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, which 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, select the Category and Subcategory, and provide the corresponding JSON path keys, where needed.

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.

Real-time apps not powered by PubNub

If PubNub does not power your real-time app, 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.

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