Event Object

The following table shows the properties in 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 for details
description STRING Human readable description of the event
event_severity JSON Object Severity of the event, see Event Severity Object for details
alert BOOLEAN Event is a candidate to be alerted to an user
event_source JSON Object Source of the event, see Event Source Object for details
organisation JSON Object Organisation associated with the event, see Organisation Object for details
user Object Details of the user, see User Object for details
endpoint JSON Object Details of the Endpoint, see Endpoint Object for details
sim JSON Object Details of the SIM, see SIM Object for details
imsi JSON Object a Details of the IMSI of the SIM, see IMSI Object for details (in case of multi-IMSI configuration, multiple IMSIs may be reported for the same SIM)
detail Object optional additional information, see Detail Object for details

Depending on the event types, some properties do not apply. For e.g. network related events (e.g. endpoint connected to the network) will contain endpoint/SIM/IMSI data and the detail object will have the actual Mobile Network Operator details but will not contain any user data while events affecting a user (e.g. portal 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 Tariff plan updated
34 Usage tariff 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
42 Endpoint disabled

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

Organisation Object

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

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 Endpoint
name STRING Configured name of the endpoint
ip_address STRING IP Address assigned to the Endpoint
tags STRING Tags assigned to the Endpoint
imei STRING International Mobile Equipment Identity (IMEI)

SIM Object

Property Type Description
id INTEGER Unique identifier of the SIM
iccid STRING Integrated Circuit Card identifier (ICCID) without the checksum digit
msisdn STRING MSISDN
production_date TIMESTAMP (UTC) Date/Time when the SIM chip was produced

IMSI Object

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

Detail Object

Some events may contain additional data added as a nested object called detail. It contains specific information depending on the event type, event source and the event severity (e.g. the actual used Mobile Network Operator and country, details about the CloudConnect, the endpoint quota, trusted device data, etc…):

Events with event type Network (id = 0) may contain the detailed information of the actual used Mobile Network Operator:

Property Type Description
id INTEGER Unique identifier of the actual used Mobile Network Operator
name STRING Name of the Mobile Network Operator
country JSON Object Country of the Mobile Network Operator, see Country Object for details
pdp_context JSON Object PDP Context Details, see Tapcode Array for details
volume JSON Object Volume consumed in a PDP Context, see Volume Object for details
tapcode JSON Array List of tapcodes of the actual used Network Operator, see Tapcode Array for details
mnc JSON Array List of Mobile Network Codes of the actual used Network Operator, see MNC Array for details

Events with event type API (id = 2) may contain information available from the API. The following table contains some examples:

Property Type Description
trusted_device JSON Object Trusted device of the user, see Trusted Device Object for details
support_username String Username of the support user
support_user_org JSON Object Organisation of the support user, see Organisation Object for details
target_username String Username of the target user

PDP Context Object

Property Type Description
pdp_context_id INTEGER Unique identifier of this PDP context
tunnel_created TIMESTAMP (UTC) Date/time when the PDP context was created
gtp_version STRING GTP Version (either 1 or 2)
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
region STRING Region where Data Plane is located
breakout_ip STRING IP Address used for Internet Breakout
apn STRING Access Point Name (APN)
nsapi INTEGER Network Service Access Point Identifier (NSAPI)
ue_ip_address STRING IP address assigned to the Endpoint
imeisv STRING IMEISV
mcc STRING Mobile Country Code (MCC)
mnc STRING Mobile Network Code (MNC)
lac INTEGER Location Area Code (LAC)
sac INTEGER Service Area code (SAC)
rac INTEGER Routing Area code (RAC)
ci INTEGER Cell Identification (CI)
rat_type INTEGER Radio Access Type (RAT).

IDs [1-6] correspond to the following values:

1 3G,
2 2G
3 WLAN
4 GAN
5 HSPA+
6 4G

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

MNC Array

Property Type Description
id INTEGER Unique identifier of the Mobile Network Code
mnc STRING Mobile Network Code assigned to the Mobile Network Operator

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 EMnify Event Bus is under active development and is updated for performance and quality improvements regularly so that users of the platform may gain rich insights into event data when using the Event API or the EMnify Data Streamer. Users who have built custom integrations should expect that additional data may be added in future. Mature and tested libraries designed for parsing or reading JSON should be used for such 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.