Create a Business Object

In this tutorial, you will create a Business Object in PubNub Illuminate, add and map data fields to a message payload, add two metrics, and activate the Business Object to start capturing data.

What you will build

By the end of this tutorial, you will have an active Business Object called "Game engagement experiment". It captures four values from each published message: chat message count, guild name, purchase item, and purchase value. It computes two metrics over 30-minute windows: total chat message count per guild and total purchase value per item.

The example payload this Business Object reads from has this shape.

{
    "chatMessage": 1,
    "guildName": "Rockin Guild",
    "purchasedItem": "Wood Fort",
    "purchaseValue": "5"
}

Numeric strings

purchaseValue is a string in the payload ("5"), but the corresponding data field uses the Number type. Illuminate converts numeric strings to numbers automatically during ingestion.

Once active, you can use these metrics in a Decision or display them on a Dashboard.

Before you start

To follow this tutorial, confirm you have:

• A PubNub account with at least one app and keyset. If you do not have one, create one in the Admin Portal.
• Access to Illuminate. Illuminate includes a two-week free trial. Open the Admin Portal, click Illuminate in the sidebar, and confirm you can see Business Objects.

For field types, mapping categories, JSON path rules, and activation behavior, see Business Objects.

Create the Business Object

1. In the Admin Portal, go to Illuminate > Business Objects.
2. Click Create Business Object.
3. Enter Game engagement experiment as the name. Add an optional description.
4. Click Choose Apps & Keysets and assign at least one app and keyset.
5. Click Save.

Illuminate creates the Business Object and opens the details view. The default fields are already mapped, so you do not need to map them. See Pre-mapped fields for their names and JSON paths.

Add data fields

Next, add four fields to capture the values from your payload.

1. Click + Add field. Enter Messages as the field name, select Number as the type, and click Save.
2. Click + Add field. Enter Purchase Value as the field name, select Number as the type, and click Save.
3. Click + Add field. Enter Guild Name as the field name, select String as the type, and click Save.
4. Click + Add field. Enter Purchase Item as the field name, select String as the type, and click Save.

Each new field shows "Unmapped" until you complete the next step.

Map data fields

Mapping tells Illuminate where to find each field value in the message payload. Each field row has a Map button. Clicking it opens a three-field form: Category, Subcategory, and JSON path. Clicking Map in the form saves the mapping.

1. Click Map next to Messages.
2. Set Category to message.
3. Set Subcategory to body.
4. Enter chatMessage in JSON path.
5. Click Map to save.

The field now shows "Mapped". Repeat for the remaining three fields using these values:

• Purchase Value: Category message, Subcategory body, JSON path purchaseValue
• Guild Name: Category message, Subcategory body, JSON path guildName
• Purchase Item: Category message, Subcategory body, JSON path purchasedItem

After mapping all four, all nine fields show "Mapped" (the four you added plus the five defaults). If any field still shows "Unmapped", click its Map button and complete the mapping.

Add metrics

A metric aggregates field values over a time window. You will add two metrics to the Business Object.

Message sum

1. In the Metrics section, click + Create metric.
2. Enter Message sum as the metric name.
3. Set Function to Sum.
4. Set Measure to Messages.
5. Set Period to 30 minutes.
6. Set Dimension to Guild Name.
7. Leave Filter blank.
8. Click Create.

Total purchased value

1. Click + Create metric.
2. Enter Total purchased value as the metric name.
3. Set Function to Sum.
4. Set Measure to Purchase Value.
5. Set Period to 30 minutes.
6. Set Dimension to Purchase Item.
7. Leave Filter blank.
8. Click Create.

Your Business Object now has two metrics.

Activate

Activation starts data capture. Before activating, confirm all four custom fields show "Mapped" and at least one app and keyset is assigned.

1. Click Activate.

Illuminate begins capturing incoming message data and computing metrics. You can add more metrics after activation, but you cannot add new data fields.

What you built

You created "Game engagement experiment", a Business Object that captures chat message counts, purchase values, guild names, and purchase items from published message payloads. You mapped all four custom fields to the message.body category, added a Sum metric for chat message count per guild and a Sum metric for purchase value per item (each over 30 minutes), and activated the Business Object. Illuminate now computes these metrics as messages arrive. Use them in a Decision or view them on a Dashboard.