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:
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 |
Note: Event history is stored for 30 days.
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. |