---
source_url: https://www.pubnub.com/docs/illuminate/business-objects/create-business-object
title: Create Business Object
updated_at: 2026-06-12T11:24:07.061Z
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


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

:::tip 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](#illuminate-for-pubnub-partners) for additional information.
:::

## Use case

For our [use case](https://www.pubnub.com/docs/illuminate/basics#sample-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.

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

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.

##### Check configuration details

Summary of the items and mappings we 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. |

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

[Illuminate: Create and map data fields](https://youtu.be/KepTxFpO3Lo)

#### Step-by-step guide

1. On the Business Objects home page, click Create Business Object. The Create new Business Object modal opens.
2. Enter the name (Game engagement experiment) and an optional description. Click Choose Apps & Keysets to assign at least one app and keyset, which is required to activate the Business Object.
3. Add four separate data fields. Click + Add field. a. By default, the following data fields are automatically added and mapped from PubNub publishes: Channel ($.message.channel), User ($.message.userId), Message Type ($.message.body.type), and Message ($.message.body.text). You can edit the names or the JSON paths, where applicable. b. To add a new data field, click + Add field. Enter a field name (for example, Messages, Purchase Value, Guild Name, or Purchase Item). Then choose its type: Number for Messages and Purchase Value; String for Guild Name and Purchase Item. c. Map the measures to data sources. Click Map. Select message in Category, body in Subcategory, then enter the key in JSON path: chatMessage (Messages), purchaseValue (Purchase Value), guildName (Guild Name), purchasedItem (Purchase Item). d. Save the changes by clicking the Map button.
4. When you’re done, click Save to create the Business Object.

Your Business Object is created. You can [activate](https://www.pubnub.com/docs/illuminate/business-objects/create-business-object#activate-business-object) it or add [metrics](https://www.pubnub.com/docs/illuminate/business-objects/create-business-object#create-metrics) in any order. After activation and at least one metric, create a [Decision](https://www.pubnub.com/docs/illuminate/decisions/create-decision) or a [Dashboard](https://www.pubnub.com/docs/illuminate/dashboards/create-dashboards-and-charts).

:::note Order of steps
You can add metrics even before data fields are mapped.
:::

### Create metrics

Add calculations to your data fields.

:::note Order of steps
You can add metrics before data fields are [mapped](https://www.pubnub.com/docs/illuminate/business-objects/basics#data-mapping).
:::

###### Watch video

[Illuminate: Create metrics](https://youtu.be/Y5_XmhYfoAQ)

###### Step-by-step guide

1. On the Business Objects home page, click the Business Object row. The details view opens.
2. In the Metrics section, click the + Create metric button and the Create metric modal opens.
3. Provide these details for the Message sum metric: a. Enter the metric name (Message sum). b. Select the aggregation Function (Sum). c. Choose Measure Messages. d. Set Period to 30 minutes. e. Select Dimension Guild Name you added as a data field. Dimension selectionTo use a metric as a criterion in decisions or dashboards, select a dimension. 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 (Sum). c. Choose Purchase Value as a Measure. d. Set 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.

![Saved and active Business Object](https://www.pubnub.com/assets/images/complete-and-active-bo-7c64d179ff245dd0d6d1cd7e610a0675.png)

### Activate Business Object

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

:::note Conditions for activating a Business Object
Head to the [Additional details](https://www.pubnub.com/docs/illuminate/business-objects/basics#additional-details) section for details on conditions that must be met to activate a Business Object.
:::

###### Watch video

[Illuminate: Activate Business Object](https://youtu.be/swvWe5j9SCc)

###### Step-by-step guide

Open the Business Object and click **Activate**.

![Saved Business Object](https://www.pubnub.com/assets/images/saved-business-object-b03ff44197ff392ce3e3a0dd04dfa208.png)

After activation, Illuminate captures data until you deactivate or delete the Business Object. To ensure consistent capture, the field structure stays fixed. You can still add metrics.

Captured data remains available for 90 days.

With the Business Object that is configured and active, you can create a [Decision](https://www.pubnub.com/docs/illuminate/decisions/create-decision) or a [Dashboard](https://www.pubnub.com/docs/illuminate/dashboards/create-dashboards-and-charts).

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

![Create Business Object for end customers](https://www.pubnub.com/assets/images/bo-for-end-customers-91e429838c2fd7033270dd6c332b33f1.png)

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](https://www.pubnub.com/docs/portal/partner-portal) in the PubNub Admin Portal and make sure you’ve created the customer in PubNub and assigned a keyset.
* If, after selecting the customer, you don’t see apps or keysets for selection, assign keysets for this customer in the Partner Portal.

## Terms in this document

* **Business Object** - A container for data fields and metrics that defines aggregations and data sources.
* **Data fields** - Data you want Illuminate to track. These can be quantitative (measures), like "Number" or "Timestamp" or qualitative (dimensions) values, like "String" that can be used to categorize and segment data. Data fields can be aggregated and calculated.
* **End Customer** - A customer of a PubNub partner. End customers do not have direct access to the Admin Portal. Instead, they interact with PubNub products—such as Illuminate—through the partner’s portal, where PubNub services are embedded. They can create PubNub objects only within this partner-provided environment.
* **Mapped/Unmapped** - Whether the data source for a data field has been defined or the action has been configured.
* **Metric** - What exactly is evaluated using measures and dimensions (collectively called data fields), as well as aggregation functions.
* **Partner** - A PubNub customer who resells PubNub products, such as Illuminate, to their own customers. Partners have access to the Admin Portal, enabling them to create and manage PubNub objects for themselves or on behalf of their end customers.