Event Records

Get to know the Events provided by the Data Streamer.

The 1NCE Data Streamer Service offers a stream of Event and Usage Records. This chapter will focus on the Event Record specification. The exact format of the events is dependent on the used integration. In this chapter, the focus lies on the JSON Object format. Please note that empty, nested JSON objects are listed as NULL objects. 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.

The following sections will cover the individual parts of the Event Record JSON:

Example Event Records

Let us start with a few Example Event Records in the form of JSON Objects from the Data Streamer. Listed below in the different tabs are some example Event Records for different Event Types. All Examples are in the JSON Format just like it would be delivered by the Data Streamer with the custom HTTP endpoint method. Please note that some fields only include placeholder or example values. Furthermore, some of the fields might be dependent on the used Radio Access Technology and other variables.

01_Update_Location
{
    "imsi": {
        "imsi": "<imsi>",
        "id": 123456,
        "import_date": "2019-01-21T09:36:17Z"
    },
    "event_source": {
        "description": "Network",
        "id": 0
    },
    "organisation": {
        "name": "8100xxxx",
        "id": 1234
    },
    "event_severity": {
        "id": 0,
        "description": "INFO"
    },
    "sim": {
        "msisdn": "<msisdn>",
        "iccid": "<iccid>",
        "id": 1234567,
        "production_date": "2019-01-21T09:36:17Z"
    },
    "description": "New location received from VLR for IMSI='<imsi>', now attached to VLR='<VLR>'.",
    "alert": false,
    "id": 1234567890,
  "user": null,
    "detail": {
        "mnc": [
            {
                "mnc": "20",
                "id": 327
            },
            {
                "mnc": "16",
                "id": 328
            }
        ],
        "tapcode": [
            {
                "tapcode": "NLDDT",
                "id": 470
            },
            {
                "tapcode": "NLDPN",
                "id": 471
            }
        ],
        "name": "T-Mobile",
        "country": {
            "iso_code": "nl",
            "country_code": "31",
            "name": "Netherlands",
            "id": 141,
            "mcc": "204"
        },
        "id": 730
    },
    "endpoint": {
        "tags": null,
        "ip_address": "<ip_address>",
        "name": "<name>",
        "imei": "<imei>",
        "id": 1234567
    },
    "event_type": {
        "id": 1,
        "description": "Update location"
    },
    "timestamp": "2019-01-21T09:36:17Z"
}
02_Update_GPRS_Location
{
    "imsi": {
        "imsi": "<imsi>",
        "id": 12345678,
        "import_date": "2019-01-21T09:36:17Z"
    },
    "event_source": {
        "description": "Network",
        "id": 0
    },
    "organisation": {
        "name": "8100xxxx",
        "id": 1234
    },
    "event_severity": {
        "id": 0,
        "description": "INFO"
    },
    "sim": {
        "msisdn": "<msisdn>",
        "iccid": "<iccid>",
        "id": 12345678,
        "production_date": "2019-01-21T09:36:17Z"
    },
    "description": "New location received from SGSN for IMSI='<imsi>', now attached to SGSN='<SGSN>', IP='<ip_address>', RAT type='E_UTRAN'.",
    "alert": false,
    "id": 1234567,
  "user": null,
    "detail": {
        "mnc": [
            {
                "mnc": "01",
                "id": 2
            }
        ],
        "tapcode": [
            {
                "tapcode": "DEUD1",
                "id": 1
            },
            {
                "tapcode": "DEUK9",
                "id": 851
            }
        ],
        "name": "T-Mobile",
        "country": {
            "iso_code": "de",
            "country_code": "49",
            "name": "Germany",
            "id": 74,
            "mcc": "262"
        },
        "id": 2
    },
    "endpoint": {
        "tags": null,
        "ip_address": "<ip_address>",
        "name": "<name>",
        "imei": "<imei>",
        "id": 123456789
    },
    "event_type": {
        "id": 2,
        "description": "Update GPRS location"
    },
    "timestamp": "2019-01-21T09:36:17Z"
}
03_Create_PDP_Context
{
    "imsi": {
        "imsi": "<imsi>",
        "id": 1234567,
        "import_date": "2019-01-21T09:36:17Z"
    },
    "event_source": {
        "description": "Network",
        "id": 0
    },
    "organisation": {
        "name": "8100xxxx",
        "id": 12345
    },
    "event_severity": {
        "id": 0,
        "description": "INFO"
    },
    "sim": {
        "msisdn": "<msisdn>",
        "iccid": "<iccid>",
        "id": 1234567,
        "production_date": "2019-01-21T09:36:17Z"
    },
    "description": "New PDP Context successfully activated with SGSN CP=<ip_address>, DP=<ip_address>.",
    "alert": false,
    "id": 1234567890,
  "user": null,
    "detail": {
        "pdp_context": {
            "tx_teid_control_plane": 3162410000,
            "sgsn_control_plane_ip_address": "<ip_address>",
            "sac": null,
            "ratezone_id": "2171",
            "rat_type": 2,
            "tunnel_created": "2021-08-09T12:00:27",
            "breakout_ip": "unavailable",
            "tariff_id": "442",
            "mnc": "01",
            "apn": "iot.1nce.net",
            "ue_ip_address": "<ip_address>",
            "gtp_version": 1,
            "rac": null,
            "region": "eu-central-1",
            "tx_teid_data_plane": 2014413000,
            "ggsn_data_plane_ip_address": "<ip_address>",
            "ci": 5559,
            "tariff_profile_id": "129000",
            "pdp_context_id": 110753000,
            "imsi": "901405100000000",
            "operator_id": "2",
            "mcc": "262",
            "imeisv": "863576047850000",
            "sgsn_data_plane_ip_address": "<ip_address>",
            "ggsn_control_plane_ip_address": "<ip_address>",
            "lac": 38701,
            "nsapi": 5,
            "rx_teid": 110750000
        },
        "name": "T-Mobile",
        "id": 2,
        "country": {
            "mcc": "262",
            "iso_code": "de",
            "name": "Germany",
            "id": 74,
            "country_code": "49"
        }
    },
    "endpoint": {
        "tags": null,
        "ip_address": "<ip_address>",
        "name": "<name>",
        "imei": "<imei>",
        "id": 1234567
    },
    "event_type": {
        "id": 3,
        "description": "Create PDP Context"
    },
    "timestamp": "2019-01-21T09:36:17Z"
}
05_Delete_PDP_Context
{
    "imsi": {
        "imsi": "<imsi>",
        "id": 12345678,
        "import_date": "2019-01-21T09:36:17Z"
    },
    "event_source": {
        "description": "Network",
        "id": 0
    },
    "organisation": {
        "name": "8100xxxx",
        "id": 1234
    },
    "event_severity": {
        "id": 0,
        "description": "INFO"
    },
    "sim": {
        "msisdn": "<msisdn>",
        "iccid": "<iccid>",
        "id": 12345678,
        "production_date": "2019-01-21T09:36:17Z"
    },
    "description": "PDP Context deleted.",
    "alert": false,
    "id": 12345678000,
  "user": null, 
    "detail": {
        "pdp_context": {
            "tx_teid_control_plane": 3162419000,
            "sgsn_control_plane_ip_address": "<ip_address>",
            "sac": null,
            "rat_type": 2,
            "tunnel_created": "2021-08-09T12:00:27",
            "breakout_ip": null,
            "mnc": "01",
            "apn": null,
            "ue_ip_address": "<ip_address>",
            "gtp_version": 1,
            "rac": null,
            "region": "eu-central-1",
            "tx_teid_data_plane": 2014410000,
            "ggsn_data_plane_ip_address": "<ip_address>",
            "ci": 5500,
            "pdp_context_id": 110753000,
            "imsi": "901405100000000",
            "mcc": "262",
            "imeisv": "8635760478506578",
            "sgsn_data_plane_ip_address": "<ip_address>",
            "ggsn_control_plane_ip_address": "<ip_address>",
            "lac": 38700,
            "nsapi": 5,
            "rx_teid": 110753000
        },
        "name": "T-Mobile",
        "id": 2,
        "volume": {
            "rx": 0,
            "tx": 0,
            "total": 0
        },
        "country": {
            "mcc": "262",
            "iso_code": "de",
            "name": "Germany",
            "id": 74,
            "country_code": "49"
        }
    },
    "endpoint": {
        "tags": null,
        "ip_address": "<ip_address>",
        "name": "<name>",
        "imei": "<imei>",
        "id": 12345678
    },
    "event_type": {
        "id": 5,
        "description": "Delete PDP Context"
    },
    "timestamp": "2019-01-21T09:36:17Z"
}
08_SIM_Activation
{
    "imsi": {
        "imsi": "<imsi>",
        "id": 1234567,
        "import_date": "2019-01-21T09:36:17Z"
    },
    "event_source": {
        "description": "API",
        "id": 2
    },
    "organisation": {
        "name": "8100xxxx",
        "id": 12345
    },
    "event_severity": {
        "id": 0,
        "description": "INFO"
    },
    "sim": {
        "msisdn": "<msisdn>",
        "iccid": "<iccid>",
        "id": 123456,
        "production_date": "2019-01-21T09:36:17Z"
    },
    "description": "Status of SIM changed from 'Suspended' to 'Activated'",
    "alert": false,
    "id": 1234567890,
  "user": null,
    "endpoint": {
        "tags": null,
        "ip_address": "<ip_address>",
        "name": "<name>",
        "imei": null,
        "id": 123456
    },
    "event_type": {
        "id": 8,
        "description": "SIM activation"
    },
    "timestamp": "2019-01-21T09:36:17Z"
}
16_Purge_GPRS_Location
{
    "imsi": {
        "imsi": "<imsi>",
        "id": 12345678,
        "import_date": "2019-01-21T09:36:17Z"
    },
    "event_source": {
        "description": "Network",
        "id": 0
    },
    "organisation": {
        "name": "8100xxxx",
        "id": 1234
    },
    "event_severity": {
        "id": 0,
        "description": "INFO"
    },
    "sim": {
        "msisdn": "<msisdn>",
        "iccid": "<iccid>",
        "id": 1234567,
        "production_date": "2019-01-21T09:36:17Z"
    },
    "description": "SGSN location information has been purged for IMSI='<imsi>'.",
    "alert": false,
    "id": 12345678,
  "user": null,
    "endpoint": {
        "tags": null,
        "ip_address": "<ip_address>",
        "name": "<name>",
        "imei": "<imei>",
        "id": 12345678
    },
    "event_type": {
        "id": 16,
        "description": "Purge GPRS location"
    },
    "timestamp": "2019-01-21T09:36:17Z"
}
15_Purge_Location
{
    "imsi": {
        "imsi": "<imsi>",
        "id": 12345678,
        "import_date": "2019-01-21T09:36:17Z"
    },
    "event_source": {
        "description": "Network",
        "id": 0
    },
    "organisation": {
        "name": "8100xxxx",
        "id": 1234
    },
    "event_severity": {
        "id": 0,
        "description": "INFO"
    },
    "sim": {
        "msisdn": "<msisdn>",
        "iccid": "<iccid>",
        "id": 1234567,
        "production_date": "2019-01-21T09:36:17Z"
    },
    "description": "VLR location information has been purged for IMSI='<imsi>'.",
    "alert": false,
    "id": 12345678,
  "user": null,
    "endpoint": {
        "tags": null,
        "ip_address": "<ip_address>",
        "name": "<name>",
        "imei": "<imei>",
        "id": 123456
    },
    "event_type": {
        "id": 15,
        "description": "Purge location"
    },
    "timestamp": "2019-01-21T09:36:17Z"
}
18_Threshold_Reached
{
    "imsi": {
        "imsi": "<imsi>",
        "id": 12345678,
        "import_date": "2019-01-21T09:36:17Z"
    },
    "event_source": {
        "description": "Policy Control",
        "id": 1
    },
    "organisation": {
        "name": "8100xxxx",
        "id": 12345
    },
    "event_severity": {
        "id": 1,
        "description": "WARN"
    },
    "sim": {
        "msisdn": "<msisdn>",
        "iccid": "<iccid>",
        "id": 12345678,
        "production_date": "2019-01-21T09:36:17Z"
    },
    "description": "Endpoint quota threshold reached, volume is below 20%.",
    "alert": true,
    "id": 1234567890,
  "user": null,
    "detail": {
        "quota": {
            "threshold_volume": 118.983794,
            "volume": 118.968383,
            "threshold_percentage": 20
        }
    },
    "endpoint": {
        "tags": null,
        "ip_address": "<ip_address>",
        "name": "<name>",
        "imei": "<imei>",
        "id": 12345678
    },
    "event_type": {
        "id": 18,
        "description": "Quota threshold reached"
    },
    "timestamp": "2019-01-21T09:36:17Z"
}
19_Quota_Used_Up
{
    "imsi": {
        "imsi": "<imsi>",
        "id": 1234567,
        "import_date": "2019-01-21T09:36:17Z"
    },
    "event_source": {
        "description": "Policy Control",
        "id": 1
    },
    "organisation": {
        "name": "8100xxxx",
        "id": 1234
    },
    "event_severity": {
        "id": 1,
        "description": "WARN"
    },
    "sim": {
        "msisdn": "<msisdn>",
        "iccid": "<iccid>",
        "id": 1234567,
        "production_date": "2019-01-21T09:36:17Z"
    },
    "description": "Quota volume is completely used up and data access denied for endpoint.",
    "alert": true,
    "id": 1234567890,
  "user": null,
    "detail": {
        "quota": {
            "threshold_volume": 100,
            "volume": "0.015085",
            "threshold_percentage": 20
        }
    },
    "endpoint": {
        "tags": null,
        "ip_address": "<ip_address>",
        "name": "<name>",
        "imei": "<imei>",
        "id": 1234567
    },
    "event_type": {
        "id": 19,
        "description": "Quota used up"
    },
    "timestamp": "2019-01-21T09:36:17Z"
}
09_SIM_Suspension
{
    "imsi": {
        "imsi": "<imsi>",
        "id": 1234567,
        "import_date": "2019-01-21T09:36:17Z"
    },
    "event_source": {
        "description": "API",
        "id": 2
    },
    "organisation": {
        "name": "8100xxxx",
        "id": 1234
    },
    "event_severity": {
        "id": 0,
        "description": "INFO"
    },
    "sim": {
        "msisdn": "<msisdn>",
        "iccid": "<iccid>",
        "id": 12345678,
        "production_date": "2019-01-21T09:36:17Z"
    },
    "description": "Status of SIM changed from 'Activated' to 'Suspended'",
    "alert": false,
    "id": 1234567890,
  "user": null,
    "endpoint": {
        "tags": null,
        "ip_address": "<ip_address>",
        "name": "<name>",
        "imei": "<imei>",
        "id": 123456
    },
    "event_type": {
        "id": 9,
        "description": "SIM suspension"
    },
    "timestamp": "2019-01-21T09:36:17Z"
}
00_SMS_Forwarder
{
    "event_source": {
        "description": "Network",
        "id": 0
    },
    "organisation": {
        "name": "8100xxxx",
        "id": 1234
    },
    "event_severity": {
        "id": 1,
        "description": "WARN"
    },
    "sim": null,
    "imsi": null,
    "detail": null,
    "description": "Unable to dispatch DLR to API Callback URL '<url>' (HTTP code=400), please verify the URL is correct and the application server is accepting requests.",
    "alert": true,
    "id": 1234567890,
    "user": null,
    "endpoint": {
        "tags": null,
        "ip_address": "<ip_address>",
        "name": "<name>",
        "imei": "<imei>",
        "id": 12345678
    },
    "event_type": {
        "id": 0,
        "description": "Generic"
    },
    "timestamp": "2019-01-21T09:36:17Z"
}
00_Disabled_Endpoint
{
    "imsi": {
        "imsi": "<imsi>",
        "id": 12345678,
        "import_date": "2019-01-21T09:36:17Z"
    },
    "event_source": {
        "description": "Policy Control",
        "id": 1
    },
    "organisation": {
        "name": "8100xxxx",
        "id": 1234
    },
    "event_severity": {
        "id": 1,
        "description": "WARN"
    },
    "sim": {
        "msisdn": "<msisdn>",
        "iccid": "<iccid>",
        "id": 123456,
        "production_date": "2019-01-21T09:36:17Z"
    },
    "description": "Disconnecting data access for endpoint, because it has been disabled.",
    "alert": true,
    "id": 1234567890,
  "user": null,
    "endpoint": {
        "tags": null,
        "ip_address": "<ip_address>",
        "name": "<name>",
        "imei": "<imei>",
        "id": 1234567
    },
    "event_type": {
        "id": 0,
        "description": "Generic"
    },
    "timestamp": "2019-01-21T09:36:17Z"
}
00_SMS_API
{
    "event_source": {
        "description": "Network",
        "id": 0
    },
    "organisation": {
        "name": "8100xxxx",
        "id": 12345
    },
    "event_severity": {
        "id": 1,
        "description": "WARN"
    },
    "sim": {
        "msisdn": "<msisdn>",
        "iccid": "<iccid>",
        "id": 1234567,
        "production_date": "2019-01-21T09:36:17Z"
    },
    "description": "SMS to <id> cannot be forwarded, because no API Callback URL defined in service profile.",
    "alert": true,
    "id": 1234567890,
    "user": null,
    "endpoint": {
        "tags": null,
        "ip_address": "<ip_address>",
        "name": "<name>",
        "imei": "<imei>",
        "id": 12345678
    },
    "event_type": {
        "id": 0,
        "description": "Generic"
    },
    "timestamp": "2019-01-21T09:36:17Z"
}

Generic Properties

Generic Properties are fields that are always included in an Event Record JSON message received via the Data Streamer. The following table will list all these properties, their data type, and a short description.

Property

Data Type

Description

id

LONG (64 bit)

Unique ID for each Event Record sent. Duplicate received event IDs indicate possible retransmissions.

timestamp

TIMESTAMP (UTC)

Timestamp with date and time of the event occurrence in the ISO 8601 format.

event_type

JSON Object

Object with an id and a description about the occurred 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 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 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

Events with a high impact on connectivity operation are flagged as an Alert.

description

STRING

String with a human readable description of the event.

Event Types

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

Event 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

Organization 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

Event Severity

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

Severity ID

Description

0

INFO

1

WARNING

2

CRITICAL

Event Source

Based on the Event Type, a different originating Event Source might be responsible for triggering the 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 Event Record 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 ID of the organization.

name

STRING

1NCE Customer ID.

Additional Properties

Event Records 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.

IMSI Object

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

Property

Data Type

Description

id

INTEGER

Unique ID of the IMSI.

imsi

STRING

The International Mobile Subscriber Identity as String.

import_date

TIMESTAMP (UTC)

Timestamp when the IMSI was provisioned in the ISO 8601 format.

SIM Object

Each SIM card has unique properties and parameters. This data is included in the 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.

production_date

TIMESTAMP (UTC)

Timestamp when the SIM was produced in the ISO 8601 format.

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 Event Types, additional information parameters are added in the Detail Properties. A list of the object parameters and fields is listed below.

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.

volume

JSON Object

Object with details about the Volume used. See Volume Object for more information.

Country Object

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

Property

Data Type

Description

country.id

INTEGER

Unique ID of a country.

country.name

STRING

Name of the country.

country.country_code

STRING

Country Code

country.mcc

STRING

Mobile Country Code (MCC)

country.iso_code

STRING

ISO Country Code

PDP Context Object

An Event Record 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

STRING

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 - Softwareversion

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

Volume Object

With each PDP Context, some information about the Data Usage is included in the Volume JSON. The content description of the fields is listed below.

Property

Data Type

Description

volume.rx

DECIMAL(14,6)

Downstream Volume in MegaBytes.

volume.tx

DECIMAL(14,6)

Upstream Volume in MegaBytes.

volume.total

DECIMAL(14,6)

Total Volume Usage.


Did this page help you?