Event Object

The following table shows the properties of a generic event. These properties are included in all events:

Property Type Description
id LONG (64 bit integer) A unique numeric identifier of the event. If multiple events with same id are received (e.g., due to transmission errors), these should be treated as duplicates by the receiver.
timestamp TIMESTAMP (UTC) Date/time when this event occurred.
event_type JSON Object Type of the event (see Event Type Object).
description STRING Human readable description of the event
event_severity JSON Object Severity of the event (see Event Severity Object).
alert BOOLEAN Event is a candidate to be alerted to a user.
event_source JSON Object Source of the event (see Event Source Object).
organisation JSON Object Organization associated with the event (see Organization Object).
user Object User details (see User Object).
endpoint JSON Object Device details (see Endpoint Object).
sim JSON Object SIM details (see SIM Object).
imsi JSON Object IMSI details of that SIM (see IMSI Object). In the case of multi-IMSI configuration, events will only show the most recently active IMSI.
detail Object Optional additional information (see Detail Object).

Depending on the event type, some properties don’t apply. For example, network-related events (e.g., a device connected to the network) contain endpoint, SIM, and IMSI data. The detail object will have the mobile network operator (MNO) details but won’t contain user data. Meanwhile, events affecting a user (e.g., authentication issues) will contain user and trusted device data but no network-related data.

Example - SIM data available:

"sim": {"sim_id" : "..."}

Example - SIM data not available:

 "sim": null

Event Type Object

Property Type Description
id INTEGER Unique identifier of the event type.
description STRING Description of the event type.

The following table describes currently available event types (event_type):

ID Description
0 Generic
1 Update location
2 Update GPRS location
3 Create PDP Context
4 Update PDP Context
5 Delete PDP Context
6 User authentication failed
7 Application authentication failed
8 SIM activation
9 SIM suspension
10 SIM deletion
11 Endpoint blocked
12 Organisation blocked
13 Support Access
14 Multi-factor Authentication
15 Purge location
16 Purge GPRS location
17 Self-Signup
18 Quota threshold reached
19 Quota used up
20 SMS quota threshold reached
21 SMS quota used up
22 CloudConnect TGW Resource Share created
23 CloudConnect TGW available
24 CloudConnect VPN breakout available
25 CloudConnect TGW breakout terminated
26 CloudConnect VPN breakout terminated
27 CloudConnect Connection State Changed
28 OpenVPN connect
29 OpenVPN disconnect
30 OpenVPN authentication
31 Organisation updated
32 Billing configuration updated
33 Platform package updated
34 Data plan updated
35 Payment
36 User invited
37 Password reset requested
38 Order submitted
39 Order updated
40 User verification requested
41 User verified
42 Endpoint enabled
43 Endpoint disabled
44 SIM issued
45 SIM factory test
46 User deleted
47 User federation activated
48 SIM registration
49 Device offline
50 SIM Released
51 SIM Assigned
52 Data quota enabled
53 Data quota disabled
54 SMS quota enabled
55 SMS quota disabled
56 Data quota assigned
57 Data quota deleted
58 SMS quota assigned
59 SMS quota deleted
60 Data quota expired
61 SMS quota expired
62 Default inclusive volume updated
63 Monthly order limit threshold reached
64 Monthly order limit reached
65 Endpoint data traffic limit warning
66 SMS MO P2P limit reached
67 User switched workspaces

Event Severity Object

Property Type Description
id INTEGER Unique identifier of the event severity.
description STRING Description of the event severity.

The following table describes currently available event severities (event_severity):

ID Description
0 INFO
1 WARN
2 CRITICAL

Event Source Object

Property Type Description
id INTEGER Unique identifier of the event source.
description STRING Description of the event source.

The following table describes currently available event sources (event_source):

ID Description
0 Network
1 Policy Control
2 API

Organization Object

Property Type Description
id INTEGER Unique identifier of the organization.
name STRING Name of the organization.

User Object

Property Type Description
id INTEGER Unique identifier of the user.
username STRING Username (e.g., email address).
name STRING Actual name of the user.

Endpoint Object

Property Type Description
id INTEGER Unique identifier of the device.
name STRING Configured name of the device.
ip_address STRING IP address assigned to the device.
tags STRING Tags assigned to the device.
imei STRING 16-digit long code indicating the International Mobile Equipment Identity - Software Version.
Differs from a standard IMEI in that the last two numbers identify the software/firmware version.

SIM Object

Property Type Description
iccid STRING Integrated circuit card identifier without the final Luhn checksum digit
msisdn STRING Mobile Station International Subscriber Directory Number (MSISDN).
production_date TIMESTAMP (UTC) Date and time the SIM chip was produced.
id INTEGER Unique identifier of the SIM.

IMSI Object

Property Type Description
id INTEGER Unique identifier of the IMSI.
imsi STRING International Mobile Subscriber Identity (IMSI).
import_date TIMESTAMP (UTC) Date and time the IMSI was provisioned.

Detail Object

Some events may contain additional data added as a nested object called detail. This object includes specific information depending on the event type, event source, and event severity (e.g., the country, details about CloudConnect, trusted device data, etc.).

Events with event type Network (id = 0) may contain detailed information about the mobile network operator (MNO):

Property Type Description
id INTEGER Unique identifier of the MNO.
name STRING Name of the MNO.
country JSON Object Country of the MNO (see Country Object).
pdp_context JSON Object PDP context details (see PDP Context Object).
volume JSON Object Volume consumed in a PDP context (see Volume Object).
tapcode JSON Array List of the MNO tapcodes (see Tapcode Array).
mnc JSON Array List of mobile network codes (MNC) of the MNO (see MNC Array).
session_id STRING Session UUID for correlating PDP context events and usage record objects.

Events with event type API (id = 2) may contain information from the API.

The following table shows examples:

Property Type Description
trusted_device JSON Object Trusted device of the user (see Trusted Device Object).
support_username STRING Username of the support user.
support_user_org JSON Object Organization of the support user (see Organization Object).
target_username STRING Username of the target user.

PDP Context Object

The PDP context is a data connection that allows the device to transmit IP data over the network. The PDP context object contains information about the devices’ connection:

Property Type Description
pdp_context_id INTEGER Unique identifier of this PDP context.
tariff_profile_id INTEGER Unique identifier of the tariff profile assigned to the device.
tariff_id INTEGER Unique identifier of the tariff used by the device.
ratezone_id INTEGER Unique identifier of the ratezone used by the device.
operator_id INTEGER Unique identifier of the operator used by the device.
sac INTEGER Service Area Code (SAC).
rac INTEGER Routing Area Code (RAC).
region STRING Region where the data plane is located.
rat_type INTEGER Radio Access Type (RAT). Corresponding IDs listed below.
nsapi INTEGER Network Service Access Point Identifier (NSAPI).
mcc STRING Mobile Country Code (MCC).
mnc STRING Mobile Network Code (MNC).
lac INTEGER Location Area Code (LAC).
ggsn_control_plane_ip_address STRING IP address of the GGSN/PGW control plane.
ggsn_data_plane_ip_address STRING IP address of the GGSN/PGW data plane.
sgsn_control_plane_ip_address STRING IP address of the SGSN/SGW control plane.
sgsn_data_plane_ip_address STRING IP address of the SGSN/SGW data plane.
breakout_ip STRING IP address used for Internet breakout.
ue_ip_address STRING IP address assigned to the device.
imeisv STRING International Mobile Equipment Identity - Software Version (IMEISV).
gtp_version STRING GPRS Tunnelling Protocol (GTP) version. This value is either 1 or 2.
tunnel_created TIMESTAMP (UTC) Date and time the PDP context was created.
ci INTEGER Cell Identification (CI).
apn STRING Access Point Name (APN).
tx_teid_control_plane INTEGER Tunnel Endpoint IDentifier (TEID) of the receiving control plane.
tx_teid_data_plane INTEGER Tunnel Endpoint IDentifier (TEID) of the receiving data plane.
rx_teid INTEGER Tunnel Endpoint IDentifier (TEID) of the sending entity.
imsi STRING International Mobile Subscriber Identity (IMSI). The unique number identifying the active IMSI of the SIM.

Radio Access Type (RAT) IDs correspond to the following values:

ID Value
1 3G
2 2G
3 WLAN
4 GAN
5 HSPA+
6 4G
8 NB-IoT
9 LTE-M
10 5G

Country Object

Property Type Description
id INTEGER Unique identifier of the country.
name STRING Name of country.
country_code STRING Numeric country code.
mcc STRING Mobile Country Code (MCC).
iso_code STRING ISO code.

Volume Object

Property Type Description
volume.rx DECIMAL(14,6) (up to 6 decimal places) Downstream volume in MB.
volume.tx DECIMAL(14,6) (up to 6 decimal places) Upstream volume in MB.
volume.total DECIMAL(14,6) (up to 6 decimal places) Total volume.

Tapcode Array

Property Type Description
id INTEGER Unique identifier of this tapcode.
tapcode STRING Tapcode assigned to the mobile network operator (MNO).

MNC Array

Property Type Description
id INTEGER Unique identifier of the mobile network code (MNC).
mnc STRING MNC assigned to the mobile network operator (MNO).

Trusted Device Object

Property Type Description
id INTEGER Unique identifier of the trusted device.
operating_system STRING Operating system of the trusted device.
browser STRING Browser of the trusted device.
activation_date TIMESTAMP (UTC) Activation date of the trusted device.

Example Event

Sample Event showing PDP context deletion: For more examples, see the Swagger Specification for /api/v1/event

[
  {
    "timestamp": "2015-07-16 12:07:09",
    "alert": true,
    "description": "PDP Context deleted.",
    "id": 69535,
    "event_type":{
      "description": "Delete PDP Context",
      "id": 4
    },
    "event_source": {
      "name": "Network",
      "id": 0
    },
    "event_severity": {
      "description": "INFO",
      "id": 0
    },
    "organisation": {
      "name": "Organisation_Name",
      "id": 2
    },
    "endpoint": {
      "name": "Monitoring201",
      "tags": "Monitoring",
      "ip_address": "10.199.6.39",
      "imei": null,
      "id": 69
    },
    "sim": {
      "iccid": "8988317000000000100",
      "production_date": "2014-12-17 13:26:13",
      "id": 110
    },
    "imsi": {
      "imsi": "901430000000114",
      "import_date": "2014-12-17 13:26:08",
      "id": 110
    }
  }
]

Compatibility Notes

The Event Bus is under active development. It is regularly updated for performance and quality improvements so that users of the platform may gain rich insights into event data when using the Event API or the Data Streamer. Users who have built custom integrations should expect that additional data may be added in the future. Mature and tested libraries designed for parsing or reading JSON should be used for custom integrations to ensure compatibility.

Event Data Properties

Data Types are referred to in the following sections to assist with integration or database schemas. They should be interpreted as follows:

Type Description
INTEGER An integer value usually used for entity IDs, will not exceed 32-bit values.
LONG (64 bit integer) For event IDs, a long value should be expected.
BOOLEAN true or false
STRING A string value enclosed in " " double quotation characters.
DECIMAL(14,6) Used for data volume measurements (volume.total, volume.tx, volume.rx) with 6 decimal places.
DECIMAL(14,10) Cost calculation (cost property) may have up to 10 decimal places.
TIMESTAMP Timestamp property in UTC enclosed in " double quotation characters.