---
source_url: https://www.pubnub.com/docs/analytics/decisions/create-business-objects
title: Create a Business Object
updated_at: 2026-09-30T07:20:08.000Z
---

# Create a Business Object

## Documentation index

To discover more PubNub resources:

1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.

Do not assume a path exists, always check the index first.

In this tutorial, you will create a [Business Object](https://www.pubnub.com/docs/analytics/decisions/business-objects.md) in PubNub [Illuminate](https://www.pubnub.com/docs/analytics/decisions/overview.md), 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.

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

:::note 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](https://www.pubnub.com/docs/analytics/decisions.md) or display them on a [Dashboard](https://www.pubnub.com/docs/analytics/decisions/dashboards.md).

## 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](https://admin.pubnub.com/).
* Access to Illuminate. Illuminate includes a two-week free trial. Open the [Admin Portal](https://admin.pubnub.com/), 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](https://www.pubnub.com/docs/analytics/decisions/business-objects.md).

## Create the Business Object

1. In the [Admin Portal](https://admin.pubnub.com/), 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](https://www.pubnub.com/docs/analytics/decisions/business-objects.md#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](https://www.pubnub.com/docs/analytics/decisions.md) or view them on a [Dashboard](https://www.pubnub.com/docs/analytics/decisions/dashboards.md).

Last updated at: 2026-09-30T07:20:08.000Z