Create Business Object

Before creating decisions and visualizations, you must define and activate a Business Object — a model of the data you want to process.

Creating Business Objects for customers

If you are a PubNub partner who has embedded Illuminate into your own website as part of your offering, you can create Business Objects for your own use or for your customers (end customers) in the Illuminate section in the Admin Portal. Read Illuminate for PubNub Partners for additional information.

Use case

For our use case, we’ll create a Business Object that captures data such as the guild name, message sent, purchase item, and purchase item value.

We’ll capture that data as data fields — either a numeric measure (message sent and purchase item value) or a qualitative dimension (guild name and purchase item).

This is a sample of the JSON structure we’ll use to map the defined data fields with our app’s data.

[
    { 
        "chatMessage": 1, 
        "guildName": "Rockin Guild", 
        "purchasedItem": "Wood Fort", 
        "purchaseValue": "5", 
        "discountCode": "FORTFREE"
    }, 
    { 
        "chatMessage": 1, 
        "guildName": "Hurrah", 
        "purchasedItem": "Metal Fort", 
        "purchaseValue": "8", 
        "discountCode": "FORTX"
    }, 

show all 17 lines

We’ll later create metrics (one for each measure) to aggregate the data and activate the Business Object at the end to let Illuminate start capturing data.

Here’s the summary of all the items and mappings we will define:

Item	Values	Description
Business Object	Name: Game engagement experiment
Data fields of type Number (measures)	Name: Messages Data mapping: $.message.body.chatMessage Name: Purchase Value Data mapping: $.message.body.purchaseValue	Numeric values from the Publish API we want to track.
Data fields of type String (dimensions)	Name: Guild Name Data mapping: $.message.body.guildName Name: Purchase Item Data mapping: $.message.body.purchasedItem	Qualitative values from the Publish API we want to track.
Metric 1	Name: Message sum	Sum of the number of messages a given guild sends.
Metric 2	Name: Total purchased value	Sum of the value of all items purchased by guild members.

Check configuration details

Steps

Follow the sections to prepare a Business Object — create and map data fields, add metrics, and activate it.

Create and map data fields

Start by defining what data you want to track and how.

Watch video

Step-by-step guide

1. On the Business Objects home page, click the Create Business Object button. The Create new Business Object modal is displayed.

   

2. Provide the name (Game engagement experiment) and optional description, and assign at least one PubNub app and keyset to the Business Object by clicking the Choose Apps & Keysets button.

3. Add four separate data fields by clicking the + Add field button.

   a. Enter a field name (Messages, Purchase Value, Guild Name or Purchase Item) and choose its type (Number for Messages and Purchase Value, and String for Guild Name and Purchase Item).

   b. Map the measures to a data source by clicking the Map button:

   Select message from Category, body from Subcategory, and enter chatMessage (for Messages), purchaseValue (for Purchase Value), guildName (for Guild Name) and purchasedItem (for Purchase Item) in the JSON path text box.

   c. Save the changes by clicking the Map button.

4. When you’re done, click Save to create the Business Object.

   

Now that you have your Business Object created, you can either activate it or add metrics to it — the order doesn’t matter, but both steps are required. Once the Business Object is activated and at least one metric has been created, you can either create a Decision or a Dashboard.

Order of steps

You can add metrics even before data fields are mapped.

Create metrics

Add calculations to your data fields.

Order of steps

You can add metrics before data fields are mapped.

Watch video

Step-by-step guide

1. On the Business Objects home page, click the row with the Business Object to which you want to add the metric. The Business Object details view opens.

   

2. In the Metrics section, click the + Create metric button and the Create metric modal opens.

   

3. Provide the following details for the Message sum metric:

   a. Type in the metric name (Message sum).

   b. Select the aggregation Function to use for the metric (Sum).

   c. Choose Messages as a Measure.

   d. Set the Period to 30 minutes.

   e. Select the Guild Name Dimension you previously added to the Business Object as a data field.

   Dimension selection

   If you don’t select a dimension for your Metric, you won’t be able to use it as a criterion in decisions and dashboards in further steps.

   f. Don’t set any Filters for our use case.

4. When you’re done, click Create.

   

5. Repeat steps 2-4 to create the Total purchased value metric:

   a. Type in the metric name (Total purchased value).

   b. Select the aggregation Function to use for the metric (SUM).

   c. Choose Purchase Value as a Measure.

   d. Set the Period to 30 minutes.

   e. Select the Purchase Item Dimension you previously added to the Business Object as a data field.

   f. Don’t set any Filters.

   

A ready and activated Business Object with metrics looks as follows.

Activate Business Object

To start capturing and storing the data, you must activate the Business Object.

Conditions for activating a Business Object

Head to the Additional details section for details on conditions that must be met to activate a Business Object.

Watch video

Step-by-step guide

To activate a Business Object, open this Business Object and click the Activate button.

From now on, Illuminate will start capturing the requested data until you deactivate or delete the Business Object. You can't add or remove data fields once you've activated a Business Object, but you can add a metric to it.

Data you defined in Business Objects and subsequently captured are housed in a single database for 90 days.

With the Business Object that is configured and active, you can create a Decision or a Dashboard.

Illuminate for PubNub partners

If you’re set up as a PubNub partner, you’ll see a drop-down menu that allows you to select who you’re creating or working on Illuminate for.

• Select your own company name at the top of the drop-down if you’re creating Business Objects for yourself.
• All customers to see which customers have been set up with Illuminate.
• A customer name to see only their Business Objects and start creating or editing only for this one customer.
• All internal and customers for your own Business Objects and those of the customers.

Depending on what you’ve selected from the partner drop-down menu, you’ll see a Customer column that provides information on who a Business Object belongs to – a customer or your own organization.

• If you don’t see a customer in the drop-down menu, go to the Partner Portal section of the PubNub Admin Portal and make sure you’ve created the customer in PubNub and assigned a keyset to them.
• If, after selecting the customer, you don’t see apps or subscribe keys for selection, assign (a) keyset(s) for this customer in the Partner Portal.