Network Events

The 1NCE Data Streamer Service provides a real-time stream of Network Events from your IoT devices and network infrastructure. These Network Events give you comprehensive visibility into device connectivity, location updates, data usage, quota management, and system activities. The exact format of the Network Events depends on the integration used, but this chapter focuses on the JSON Object format delivered by the Data Streamer.

Network Events are categorized into several types:

Network Events - Location updates and network attachments
PDP Context Events - Data session lifecycle
SIM Management Events - SIM activation and status changes
Quota Events - Data and SMS quota management
System Events - VPN and endpoint management

Network Event Structure Overview

All Network Events share a common structure with the following main components:

Generic Properties - Always present in every Network Event
Additional Properties - Optional SIM, IMSI, and endpoint information
Detail Properties - Network Event-specific additional information

Example Network Events

Here are sample Network Events from different categories showing the JSON structure delivered by the Data Streamer:

{
  "id": 12345678,
  "timestamp": "2024-12-13T12:49:57.000Z",
  "event_type": {
    "id": 1,
    "description": "Update location"
  },
  "event_severity": {
    "id": 0,
    "description": "INFO"
  },
  "event_source": {
    "id": 0,
    "description": "Network"
  },
  "organisation": {
    "id": 100018,
    "name": "81013181"
  },
  "alert": false,
  "description": "New location received from VLR for IMSI = '901405105682328', now attached to VLR = '491720215095'",
  "sim": {
    "id": 10000106,
    "iccid": "8988228066605682328",
    "msisdn": "882285105682328"
  },
  "imsi": {
    "id": 100000106,
    "imsi": "901405105682328"
  },
  "endpoint": {
    "id": 100000325,
    "imei": "8697060538230193",
    "name": "8988228066605682328",
    "ip_address": "10.0.0.180"
  },
  "detail": {
    "id": 3,
    "name": "Vodafone",
    "country": {
      "id": 74,
      "mcc": "262",
      "name": "Germany",
      "iso_code": "de",
      "country_code": "49"
    },
    "mnc": [
      {
        "id": 3,
        "mnc": "02"
      }
    ],
    "tapcode": [
      {
        "id": 2,
        "tapcode": "DEUD2"
      }
    ]
  }
}

Generic Properties

Generic Properties are fields that are always included in a Network Event JSON message received via the Data Streamer. These properties provide essential information about every Network Event.

Property	Data Type	Description
`id`	LONG (64 bit)	Unique ID for each Network Event sent. Duplicate received Network Event IDs indicate possible retransmissions.
`timestamp`	TIMESTAMP (UTC)	Timestamp with date and time of the Network Event occurrence in the ISO 8601 format.
`event_type`	JSON Object	Object with an id and a description about the occurred Network Event. See Event Types for a list of all possible values.
`event_severity`	JSON Object	JSON object with an id and a description about the severity of the Network Event. See Event Severity for a list of all possible values.
`event_source`	JSON Object	An id and a description about the source of the Network Event. See Event Source for a list of all possible values.
`organisation`	JSON Object	Object with the ID and the name of the organization. See Event Organization for more information.
`alert`	BOOLEAN	Network Events with a high impact on connectivity operation are flagged as an Alert.
`description`	STRING	String with a human readable description of the Network Event.

Event Types

The different types of Network Events are indicated by the Event Type nested object. This object contains an ID and a short description of the Network Event. The following table lists all possible Event Types that can be received via the Data Streamer.

Event ID	Description
1	Update location
2	Update GPRS location
3	Create PDP Context
4	Update PDP Context
5	Delete PDP Context
8	SIM activation
9	SIM suspension
11	Endpoint blocked
15	Purge location
16	Purge GPRS location
18	Quota Threshold Reached
19	Quota used up
20	SMS Quota Threshold Reached
21	SMS quota used up
29	OpenVPN disconnect
30	OpenVPN authentication
42	Endpoint enabled
43	Endpoint disabled
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
100	Regional Pool Data Quota used up
101	Regional Pool Data Quota Threshold Reached
102	Regional Pool SMS Quota used up
103	Regional Pool SMS Quota Threshold Reached
121	Endpoint deleted

Event Severity

The severity levels of a Network Event indicate what impact the Network Event has on the correct operation of the system. The possible Event Severity values are listed below:

Severity ID	Description
0	INFO
1	WARN
2	WARN
3	ERROR
4	CRITICAL

Event Source

Based on the Event Type, a different originating Event Source might be responsible for triggering the Network Event. The possible sources consisting of an ID and a Description are listed below.

ID	Description
0	Network
1	Policy Control
2	API

Event Organization

Each Network Event includes information about the originating organization. This helps to identify the organization in the use case of multiple Data Streamer for sub organizations. The JSON property fields of this object are listed below.

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

Additional Properties

Network Events that directly relate to SIMs, Endpoints, or Users might include some of the following optional properties.

Property	Data Type	Description
`imsi`	JSON Object	International Mobile Subscriber Identity, see IMSI Object for more information.
`sim`	JSON Object	Subscriber Identification Module, see SIM Object for more information.
`endpoint`	JSON Object	Endpoint/Device information object, see Endpoint Object for more information.
`user`	STRING	User identifier if the Network Event was triggered by a specific user action.

IMSI Object

The International Mobile Subscriber Identity is used to identify each device with a SIM. The following parameters are included in a Network Event.

Property	Data Type	Description
`id`	INTEGER	Unique ID of the IMSI.
`imsi`	STRING	The International Mobile Subscriber Identity as String.

SIM Object

Each SIM card has unique properties and parameters. This data is included in the Network Event stream. A list of the available data fields is shown below.

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.

Endpoint Object

As a SIM is placed inside a device, some information about this endpoint is transferred via the mobile network. This information is useful to identify the specific device type and certain connection parameters. A list of all Endpoint Objects is listed below.

Property	Data Type	Description
`id`	INTEGER	Unique ID of the Endpoint.
`name`	STRING	Name of the Endpoint configuration.
`ip_address`	STRING	Specific static IP Address of the SIM card/Endpoint.
`tags`	STRING	Any Tags assigned to the Endpoint.
`imei`	STRING	International mobile equipment identity of the Endpoint/Device with the SIM.

Detail Properties

For certain Network Event Types, additional information parameters are added in the Detail Properties. The content varies based on the Network Event Type and provides specific context for that Network Event category.

Network Detail Properties

Network Events include operator and country information in their detail properties.

Property	Data Type	Description
`id`	INTEGER	Unique ID for the 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 more information.
`mnc`	ARRAY	Array of Mobile Network Code objects with id and mnc fields.
`tapcode`	ARRAY	Array of TAP code objects with id and tapcode fields.

PDP Context Detail Properties

PDP Context Events include comprehensive information about the data session in their detail properties.

Property	Data Type	Description
`id`	INTEGER	Unique ID for the 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 more information.
`pdp_context`	JSON Object	Object with details about the PDP Context. See PDP Context Object for more information.

Quota Detail Properties

Quota Events include quota information and optionally regional pool details.

Property	Data Type	Description
`quota`	JSON Object	Object with details about the quota. See Quota Object for more information.
`regional_pool`	JSON Object	Object with regional pool information (for regional pool Network Events).

VPN Detail Properties

VPN Events include client and connection information.

Property	Data Type	Description
`vpn_id`	INTEGER	OSS VPN ID
`region`	STRING	AWS region code
`client`	JSON Object	Object with version, private_ip, and public_ip fields

Country Object

A nested JSON object inside the Detail Properties contains more information about the country where the SIM Network Event took place. The fields of the Country JSON are listed below.

Property	Data Type	Description
`id`	INTEGER	Unique ID of a country.
`name`	STRING	Name of the country.
`country_code`	STRING	Country Code
`mcc`	STRING	Mobile Country Code (MCC)
`iso_code`	STRING	ISO Country Code

PDP Context Object

A Network Event for a PDP Context includes a wide range of additional information in the Detail Properties. The individual fields are listed below.

Property	Data Type	Description
`pdp_context_id`	INTEGER	ID of the PDP Context
`tunnel_created`	TIMESTAMP (UTC)	Creation time of the PDP Session
`gtp_version`	INTEGER	GTP Version 1/2
`ggsn_control_plane_ip_address`	STRING	IP Address of GGSN/PGW Control Plane
`ggsn_data_plane_ip_address`	STRING	IP Address of GGSN/PGW Data Plane
`sgsn_control_plane_ip_address`	STRING	IP Address of SGSN/SGW Control Plane
`sgsn_data_plane_ip_address`	STRING	IP Address of SGSN/SGW Data Plane
`region`	STRING	Region of the Data Plane
`breakout_ip`	STRING	IP Address used for the Internet Breakout
`apn`	STRING	Access Point Name (APN)
`nsapi`	INTEGER	Network Service Access Point Identifier (NSAPI)
`ue_ip_address`	STRING	IP address of the device
`imeisv`	STRING	International Mobile Equipment Identity - Software version
`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) 1 - 3G 2 - 2G 5 - HSPA+ 6 - LTE 8 - NB-IoT 9 - CAT-M
`gtp_v1_uli`	JSON Object	GTP V1 User Location Information with lac, ci, sac, rac fields
`gtp_v2_uli`	JSON Object	GTP V2 User Location Information with cgi, sai, rai, tac, eci, lac, menbi, emenbi fields
`tx_teid_data_plane`	INTEGER	PGW/GGSN TEID user_plane
`tx_teid_control_plane`	INTEGER	PGW/GGSN TEID control_plane
`rx_teid`	INTEGER	Received Tunnel Endpoint Identifier
`tariff_id`	STRING	Tariff identifier
`operator_id`	STRING	Operator identifier
`ratezone_id`	STRING	Rate zone identifier
`ipcan_session_id`	STRING	IP-CAN session identifier

Quota Object

Quota Events include detailed information about quota status and usage. The content description of the fields is listed below.

Property	Data Type	Description
`id`	INTEGER	Unique quota identifier
`volume`	DECIMAL	Remaining volume (can be negative if exceeded)
`total_volume`	DECIMAL	Total allocated volume
`accumulated_total_volume`	DECIMAL	Sum of all quota allocations
`last_volume_added`	DECIMAL	Most recent quota addition
`service`	STRING	Service type: "data" or "sms"
`threshold`	JSON Object	Object with volume and percentage fields for threshold settings
`threshold_percentage`	INTEGER	Percentage threshold (0-100)
`threshold_volume`	DECIMAL	Calculated threshold volume
`expiry_date`	TIMESTAMP (UTC)	When the quota expires
`created_at`	TIMESTAMP (UTC)	When the quota was created
`status`	JSON Object	Object with id and description for quota status

Network Event Categories

Network Events are organized into the following functional categories:

Network Events

Network Events track device location changes and network attachments.

Update Location (ID: 1)

Sent when endpoint changes CS (Circuit Switched) network location
Includes VLR attachment information

Update GPRS Location (ID: 2)

Sent when endpoint changes PS (Packet Switched) network location
Includes SGSN attachment information

Purge Location (ID: 15)

Sent when CS network location information is cleaned up

Purge GPRS Location (ID: 16)

Sent when PS network location information is cleaned up

PDP Context Events

PDP Context Events track the lifecycle of data sessions.

Create PDP Context (ID: 3)

Sent when endpoint establishes a data session
Includes comprehensive PDP context details
Also sent for IMEI lock violations

Update PDP Context (ID: 4)

Sent when data session is updated
Includes updated PDP context information

Delete PDP Context (ID: 5)

Sent when data session is terminated
Includes final PDP context state

SIM Management Events

SIM Management Events track SIM lifecycle and status changes.

SIM Activation (ID: 8)

Sent when SIM status changes to activated

SIM Suspension (ID: 9)

Sent when SIM status changes to suspended/disabled

Endpoint Enabled (ID: 42)

Sent when endpoint status is set to enabled

Endpoint Disabled (ID: 43)

Sent when endpoint status is set to disabled

Endpoint Blocked (ID: 11)

Sent when endpoint is blocked (e.g., monthly limit exceeded)

Endpoint Deleted (ID: 121)

Sent when endpoint is deleted from organization

Quota Events

Quota Events track data and SMS quota management and usage.

Data Quota Events

Data quota enabled/disabled (ID: 52/53)
Data quota assigned/deleted (ID: 56/57)
Data quota expired (ID: 60)
Quota threshold reached (ID: 18)
Quota used up (ID: 19)

SMS Quota Events

SMS quota enabled/disabled (ID: 54/55)
SMS quota assigned/deleted (ID: 58/59)
SMS quota expired (ID: 61)
SMS quota threshold reached (ID: 20)
SMS quota used up (ID: 21)

Regional Pool Events

Regional pool data/SMS quota used up (ID: 100/102)
Regional pool data/SMS quota threshold reached (ID: 101/103)

System Events

System Events track infrastructure and service activities.

VPN Events

OpenVPN authentication (ID: 30)
OpenVPN disconnect (ID: 29)

These Network Events include VPN client details and connection information.

Network Event Processing

When processing Network Events from the Data Streamer:

Check Network Event ID: Use the unique id field to detect retransmissions
Monitor Alerts: Pay attention to Network Events where alert is true
Filter by Severity: Use event_severity to focus on critical issues
Track Organizations: Use organisation to separate multi-tenant scenarios
Parse Detail Properties: Extract Network Event-specific information from the detail object based on Network Event type