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.

PropertyData TypeDescription
idLONG (64 bit)Unique ID for each Event Record sent. Duplicate received event IDs indicate possible retransmissions.
timestampTIMESTAMP (UTC)Timestamp with date and time of the event occurrence in the ISO 8601 format.
event_typeJSON ObjectObject with an id and a description about the occurred event. See Event Types for a list of all possible values.
event_severityJSON ObjectJSON object with an id and a description about the severity of the event. See Event Severity for a list of all possible values.
event_sourceJSON ObjectAn id and a description about the source of the event. See Event Source for a list of all possible values.
organisationJSON ObjectObject with the ID and the name of the organization. See Event Organization for more information.
alertBOOLEANEvents with a high impact on connectivity operation are flagged as an Alert.
descriptionSTRINGString 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 IDDescription
0Generic
1Update location
2Update GPRS location
3Create PDP Context
4Update PDP Context
5Delete PDP Context
6User authentication failed
7Application authentication failed
8SIM activation
9SIM suspension
10SIM deletion
11Endpoint blocked
12Organization blocked
13Support Access
14Multi-factor Authentication
15Purge Location
16Purge GPRS location
17Self-Signup
18Quota Threshold reached
19Quota used up
20SMS quota threshold reached
21SMS 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 IDDescription
0INFO
1WARNING
2CRITICAL

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.

IDDescription
0Network
1Policy Control
2API

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.

PropertyData TypeDescription
idINTEGERUnique ID of the organization.
nameSTRING1NCE Customer ID.

Additional Properties

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

PropertyData TypeDescription
imsiJSON ObjectInternational Mobile Subscriber Identity, see IMSI Object for more information.
simJSON ObjectSubscriber Identification Module, see SIM Object for more information.
endpointJSON ObjectEndpoint/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.

PropertyData TypeDescription
idINTEGERUnique ID of the IMSI.
imsiSTRINGThe International Mobile Subscriber Identity as String.
import_dateTIMESTAMP (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.

PropertyData TypeDescription
idINTEGERUnique ID of the SIM.
iccidSTRINGIntegrated Circuit Card Identifier of the SIM.
msisdnSTRINGMobile Subscriber ISDN of the SIM Card.
production_dateTIMESTAMP (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.

PropertyData TypeDescription
idINTEGERUnique ID of the Endpoint.
nameSTRINGName of the Endpoint configuration.
ip_addressSTRINGSpecific static IP Address of the SIM card/Endpoint.
tagsSTRINGAny Tags assigned to the Endpoint.
imeiSTRINGInternational 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.

PropertyData TypeDescription
idINTEGERUnique ID for the used mobile network operator.
nameSTRINGName of the mobile network operator.
countryJSON ObjectCountry of the mobile network operator. See Country Object for more information.
pdp_contextJSON ObjectObject with details about the PDP Context. See PDP Context Object for more information.
volumeJSON ObjectObject 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.

PropertyData TypeDescription
country.id INTEGERUnique ID of a country.
country.name STRINGName of the country.
country.country_code STRINGCountry Code
country.mccSTRINGMobile Country Code (MCC)
country.iso_code STRINGISO 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.

PropertyData TypeDescription
pdp_context_idINTEGERID of the PDP Context.
tunnel_createdTIMESTAMP (UTC)Creation time of the PDP Session.
gtp_versionSTRINGGTP Version 1/2
ggsn_control_plane_ip_address STRINGIP Address of GGSN/PGW Control Plane
ggsn_data_plane_ip_addressSTRINGIP Address of GGSN/PGW Data Plane
sgsn_control_plane_ip_addressSTRINGIP Address of SGSN/SGW Control Plane
sgsn_data_plane_ip_addressSTRINGIP Address of SGSN/SGW Data Plane
regionSTRINGRegion of the Data Plane.
breakout_ipSTRINGIP Address used for the Internet Breakout.
apnSTRINGAccess Point Name (APN)
nsapiINTEGERNetwork Service Access Point Identifier (NSAPI)
ue_ip_address STRINGIP address of the device.
imeisvSTRINGInternational Mobile Equipment Identity - Softwareversion
mccSTRINGMobile Country Code (MCC)
mncSTRINGMobile Network Code (MNC)
lacINTEGERLocation Area Code (LAC)
sacINTEGERService Area code (SAC)
racINTEGERRouting Area code (RAC)
ciINTEGERCell Identification (CI)
rat_typeINTEGERRadio 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.

PropertyData TypeDescription
volume.rxDECIMAL(14,6)Downstream Volume in MegaBytes.
volume.txDECIMAL(14,6)Upstream Volume in MegaBytes.
volume.totalDECIMAL(14,6)Total Volume Usage.