Usage Events

The Bell Data Streamer Service offers a stream of Usage Events. This chapter will focus on the Usage Event specification. In this chapter, the focus lies on the JSON Object format. For other integrations, the format might be different, but the data fields are comparable. Please refer to the setup of the offered integrations to get more information about the specific data formats used.

Usage Event Triggers

Data Connection Events: For an ongoing PDP data connection, at most, one event every 15 minutes if more than 100kB of data was used. This event contains the aggregated usage since the start of the PDP or since the last usage event.

Connection Closure Events: One event on the closure a PDP data connection. This event contains the usage since the last event or the entire aggregated usage if no prior event has been provided for the closed PDP data connection.

SMS Events: For SMS a usage event is provided per individual MO-/MT-SMS send.

The Bell Data Streamer provides two types of events for SMS and Data volume usage.

Usage Events

Data Usage Event

Data Usage events are sent for every Endpoint while the Endpoint is consuming data service. The frequency of Data Usage events depends on platform configuration parameters e.g. an event every 5 minutes and/or every 1 megabyte consumed.

SMS Usage Event

SMS Usage events are sent for every Endpoint while the Endpoint is consuming SMS service. A SMS Usage event is sent for every MO SMS or MT SMS. If SMS submission was rejected by the platform e.g. due to exceeded quota or monthly limit, then the SMS will be not charged and hence no SMS Usage event will be emitted.

Example Usage Events

Let us start with a few Example Usage Events in the form of JSON Objects from the Data Streamer. Please note that some fields only include placeholder or example values.

Data Usage Event Example

  {
    "id": 819948096,
    "operator": {
      "id": 78,
      "name": "Bite GSM",
      "mnc": "05",
      "country": {
        "id": 110,
        "mcc": "247",
        "name": "Latvia"
      }
    },
    "organisation": {
      "id": 100018,
      "name": "81013181"
    },
    "tariff": {
      "id": 369,
      "name": "MVP Phase 2 Tarriff",
      "ratezone": {
        "id": 4,
        "name": "T369.RZ1"
      }
    },
    "traffic_type": {
      "id": 5,
      "description": "Data"
    },
    "endpoint": {
      "id": 100000519,
      "name": "8988228066605682521",
      "ip_address": "10.0.1.118",
      "imei": "3556200910473501"
    },
    "volume": {
      "total": 1.0049019,
      "rx": 1.0049019,
      "tx": 0
    },
    "sim": {
      "id": 10000299,
      "iccid": "8988228066605682521",
      "msisdn": "882285105682521"
    },
    "start_timestamp": "2024-12-15T06:24:47.000Z",
    "end_timestamp": "2024-12-15T06:25:10.000Z",
    "imsi": "901405105682521",
    "imsi_id": 100000299,
    "detail": {
      "pdp_context": {
        "rat_type": 6,
        "ipcan_session_id": "e17b3179-04e0-40e8-b982-0d5f826cea6e"
      }
    }
  }

SMS Usage Event Example

  {
    "id": 8884551,
    "start_timestamp": "2024-12-15T06:27:26Z",
    "end_timestamp": "2024-12-15T06:27:27Z",
    "organisation": {
      "id": 103820,
      "name": "81023262"
    },
    "operator": {
      "id": 77,
      "name": "LMT",
      "mnc": "01",
      "country": {
        "id": 110,
        "mcc": "247",
        "name": "Latvia"
      }
    },
    "tariff": {
      "id": 2703,
      "name": "Tariff 718916841",
      "ratezone": {
        "id": 11428,
        "name": "IoT Cloud Connect Complete"
      }
    },
    "imsi": "901405301000216",
    "imsi_id": 100003437,
    "traffic_type": {
      "id": 6,
      "description": "SMS"
    },
    "endpoint": {
      "id": 100001494,
      "name": "8988228530100000216",
      "imei": "8643510517167031",
      "ip_address": "10.0.0.1"
    },
    "volume": {
      "total": 1,
      "rx": 0,
      "tx": 1
    },
    "sim": {
      "msisdn": "882285301000216",
      "iccid": "8988228530100000216",
      "id": 10003354
    }
  }

Usage Data Properties

These are the main properties of a Usage Event that help to identify the endpoint and provide an insight into the volume used.

Property	Data Type	Description
`id`	LONG (64-bit integer)	Unique ID for each Usage Event sent. Duplicate received event IDs indicate possible retransmissions.
`cost`	DECIMAL(14,10)	Does not reflect the real world cost, 1:1 translation of usage. (Legacy field, may not be present in newer events)
`currency`	JSON Object	Currency object with information about the cost currency. (Legacy field, may not be present in newer events)
`start_timestamp`	TIMESTAMP (UTC)	Timestamp with date and time of the usage start in the ISO 8601 format.
`end_timestamp`	TIMESTAMP (UTC)	Timestamp with date and time of the usage end in the ISO 8601 format.
`volume`	JSON Object	Object with the exact volume used as part of the Usage Event. See Volume for more information.
`imsi`	STRING	The International Mobile Subscriber Identity as String.
`organisation`	JSON Object	Object with the ID and the name of the organization. See Event Organization for more information.
`operator`	JSON Object	Operator information, see Operator for more information.
`sim`	JSON Object	Subscriber Identification Module, see SIM for more information.
`tariff`	JSON Object	Tariff details, see Tariff for more information.
`traffic_type`	JSON Object	Type of traffic of the Usage Event, see Traffic Type for more information.
`endpoint`	JSON Object	Endpoint/Device information object, see Endpoint for more information.
`detail`	JSON Object	Additional details specific to the usage type, see Detail for more information.

Object Specifications

Currency Object

The cost object is set as a 1:1 relation to the used volume. It does not reflect the real world cost. This is a legacy field and may not be present in newer usage events.

| Property | Data Type         | Description                                          |
| :------- | :---------------- | :--------------------------------------------------- |
| `id`     | INTEGER           | Unique identifier of the currency of indicated cost. |
| `symbol` | UTF-8 Char STRING | Symbol of the currency as UTF-8 Char.                |
| `code`   | ISO 4217 STRING   | Currency Code in ISO format.                         |

Organisation Object

Information about the organization of the SIM that generated the volume usage event.

| Property | Data Type | Description                            |
| :------- | :-------- | :------------------------------------- |
| `id`     | INTEGER   | Unique identifier of the organisation. |
| `name`   | STRING    | Bell Customer ID.                      |

SIM Object

Details about the SIM that is responsible for the volume usage.

| Property          | Data Type       | Description                                                                |
| :---------------- | :-------------- | :------------------------------------------------------------------------- |
| `id`              | INTEGER         | Unique ID of the SIM.                                                      |
| `iccid`           | STRING          | Integrated Circuit Card Identifier of the SIM.                             |
| `msisdn`          | STRING          | Mobile Subscriber ISDN of the SIM Card.                                    |
| `production_date` | TIMESTAMP (UTC) | Timestamp when the SIM was produced in the ISO 8601 format. (Legacy field) |

Operator Object

Operator the SIM was attached to when the usage was generated.

| Property  | Data Type   | Description                                                                      |
| :-------- | :---------- | :------------------------------------------------------------------------------- |
| `id`      | INTEGER     | Unique identifier of visited operator.                                           |
| `mnc`     | STRING      | Mobile Network Code of the roaming operator.                                     |
| `name`    | STRING      | Name of the roaming mobile operator.                                             |
| `country` | JSON Object | Country information object, see [Country](#country-object) for more information. |

Country Object

Country of the device with the Bell SIM where the usage was generated.

| Property | Data Type | Description                           |
| :------- | :-------- | :------------------------------------ |
| `id`     | INTEGER   | Unique identifier of visited country. |
| `mcc`    | STRING    | Mobile Country Code of the operator.  |
| `name`   | STRING    | Name of visited country.              |

Tariff Object

Specific tariff assigned to the Bell SIM.

| Property   | Data Type   | Description                                                                         |
| :--------- | :---------- | :---------------------------------------------------------------------------------- |
| `id`       | INTEGER     | Unique identifier of applied tariff.                                                |
| `name`     | STRING      | Name of the applied tariff.                                                         |
| `ratezone` | JSON Object | Ratezone information object, see [Ratezone](#ratezone-object) for more information. |

Ratezone Object

The ratezone in which the SIM generated the indicated usage.

| Property | Data Type | Description                            |
| :------- | :-------- | :------------------------------------- |
| `id`     | INTEGER   | Unique identifier of applied Ratezone. |
| `name`   | STRING    | Name of the Ratezone.                  |

Traffic Type Object

Identifies what kind of traffic was used and is shown in the Usage Event. This could either be Data or SMS.

| Property | Data Type | Description                                          |
| :------- | :-------- | :--------------------------------------------------- |
| `id`     | INTEGER   | Unique identifier of traffic type. 5 = Data, 6 = SMS |
| `name`   | STRING    | Name of traffic type either "Data" or "SMS".         |

Endpoint Object

Details about the endpoint/device with the Bell SIM that generated the usage.

| Property     | Data Type | Description                                  |
| :----------- | :-------- | :------------------------------------------- |
| `id`         | INTEGER   | Unique identifier of traffic type.           |
| `tags`       | STRING    | User-defined tags set for this endpoint.     |
| `ip_address` | STRING    | The IP address assigned to this endpoint.    |
| `imei`       | STRING    | The IMEI of the endpoint hardware.           |
| `name`       | STRING    | The user-defined name set for this endpoint. |
| `balance`    | STRING    | (Legacy field, may not be present)           |

Volume Object

Exact volume, either data in MegaBytes or number of SMS used by the SIM.

| Property | Data Type     | Description                                                                                                                        |
| :------- | :------------ | :--------------------------------------------------------------------------------------------------------------------------------- |
| `total`  | DECIMAL(14,6) | Total traffic consumed, sum of `tx` and `rx`.                                                                                      |
| `tx`     | DECIMAL(14,6) | **Dependent on Traffic Type:** Upstream traffic (MiB - Binary unit based) send by the endpoint. **or** Number of sent MO-SMS       |
| `rx`     | DECIMAL(14,6) | **Dependent on Traffic Type:** Downstream traffic (MiB - Binary unit based) received by the endpoint. **or** Number of sent MT-SMS |

Detail Object

Additional details specific to the usage type. This object may contain different information depending on the type of usage event.

**For Data Usage Events:**

| Property      | Data Type   | Description                                   |
| :------------ | :---------- | :-------------------------------------------- |
| `pdp_context` | JSON Object | PDP context information for data connections. |

**PDP Context Object:**

| Property           | Data Type | Description                                        |
| :----------------- | :-------- | :------------------------------------------------- |
| `rat_type`         | INTEGER   | Radio Access Technology type identifier.           |
| `ipcan_session_id` | STRING    | IP-CAN session identifier for the data connection. |

Usage Event Triggers​

Usage Events​

Data Usage Event​

SMS Usage Event​

Example Usage Events​

Usage Data Properties​

Object Specifications​

Currency Object​

Organisation Object​

SIM Object​

Operator Object​

Country Object​

Tariff Object​

Ratezone Object​

Traffic Type Object​

Endpoint Object​

Volume Object​

Detail Object​

Usage Event Triggers

Usage Events

Data Usage Event

SMS Usage Event

Example Usage Events

Usage Data Properties

Object Specifications

Currency Object

Organisation Object

SIM Object

Operator Object

Country Object

Tariff Object

Ratezone Object

Traffic Type Object

Endpoint Object

Volume Object

Detail Object